lol_audio_unpack

一个极简、高效的英雄联盟音频提取工具。

---

主要功能

• 全面支持: 能够提取英雄和地图的所有音频类型（VO语音, SFX音效, MUSIC音乐）。
• 不包含: 游戏大厅内的英雄选择/禁用语音。
• 数据纯粹: 输出的音频文件为原始的 .wem 格式，文件名保留其在游戏数据中的ID，不进行重命名或分类。
• 事件信息: 数据更新时会包含音频事件信息，但目前解包功能不支持按事件对音频进行分类。

对于需要按事件分类或进行自动转码的用户，请关注后续版本或使用其他配套工具。

---

• 介绍
• 使用方法
• 设计哲学
• 性能参考
• 后续处理：音频转码
• 维护者
• 感谢
• 许可证

介绍

提取联盟客户端中的英雄和地图音频文件，专注于提供原始、未处理的音频数据。

使用方法

1. 克隆仓库:

   git clone https://github.com/Virace/lol_audio_unpack.git
   cd lol_audio_unpack

2. 安装依赖:

   • 方式一: 使用 uv (推荐)

     # uv 会自动创建虚拟环境
     uv sync

   • 方式二: 使用 pip

     pip install .

3. 编写配置文件: 在项目根目录创建 .lol.env 或 .lol.env.dev 文件。详见配置文件。

4. 运行脚本: 所有命令都需要在项目根目录执行。

   • 方式一: 使用 uv (推荐)

     # --- 数据更新 ---
     # 首次运行或游戏更新后，需要更新数据
     
     # 更新所有数据 (英雄和地图)
     uv run unpack --update
     
     # 或，只更新所有英雄的数据
     uv run unpack --update-champions
     
     # 或，只更新指定ID的英雄 (例如：1,103,555)
     uv run unpack --update-champions 1,103,555
     
     # 或，只更新所有地图的数据
     uv run unpack --update-maps
     
     # 或，只更新指定ID的地图 (例如：11,12)
     uv run unpack --update-maps 11,12
     
     # 快速更新模式 (跳过事件数据处理，大幅提升速度)
     uv run unpack --update --skip-events
     
     # --- 音频解包 ---
     # 解包所有音频 (英雄和地图)，使用默认4线程
     uv run unpack --extract
     
     # 或，使用8个线程解包所有音频
     uv run unpack --extract --max-workers 8
     
     # 或，只解包所有英雄的音频
     uv run unpack --extract-champions
     
     # 或，只解包指定ID的英雄
     uv run unpack --extract-champions 555,222
     
     # 或，只解包所有地图的音频
     uv run unpack --extract-maps
     
     # 或，只解包指定ID的地图
     uv run unpack --extract-maps 11,12
     
     # update和extract可以一起使用
     uv run unpack --update --extract --skip-events

   • 方式二: 使用 python -m (传统方式)

     # --- 数据更新 ---
     python -m lol_audio_unpack --update
     python -m lol_audio_unpack --update-champions 1,103,555
     python -m lol_audio_unpack --update-maps 11,12
     python -m lol_audio_unpack --update --skip-events
     
     # --- 音频解包 ---
     python -m lol_audio_unpack --extract
     python -m lol_audio_unpack --extract-champions 555
     python -m lol_audio_unpack --extract-maps 11

   注意：在单独更新地图数据时候，如果使用了下列命令，则去重失效

   # 地图去重依赖于地图ID为0的Common数据，所以如果想正确处理地图数据，建议无论你单独处理哪个地图数据都带上 "0"
   lol_audio_unpack --update-maps 11,12
   

配置文件

项目将从根目录下的 .lol.env 文件加载配置。如果存在 .lol.env.dev 文件，则会优先加载后者（开发模式）。

所有配置项也可以通过环境变量提供（例如 export LOL_GAME_PATH=/path/to/game），这在CI/CD环境中非常有用。

# 游戏客户端根目录 (例如: D:\Games\League of Legends)
LOL_GAME_PATH=''

# 游戏语言区域 (例如: zh_CN, en_US, ko_KR)
LOL_GAME_REGION='zh_CN'

# 数据输出目录
LOL_OUTPUT_PATH=''

# 排除的音频类型 (VO: 语音, SFX: 特效, MUSIC: 音乐), 使用英文逗号
分割, 留空则全部解包
LOL_EXCLUDE_TYPE='SFX,MUSIC'

设计哲学

• 速度优先: 通过简化的处理流程和优化的文件I/O，最大化解包效率。
• 数据纯粹: 不对文件进行任何形式的重命名或分类。文件名即ID，保留了数据的原始性，方便后续工具进行二次处理。
• 责任分离: 核心解包功能与音频转码等后处理步骤完全解耦。本工具只做一件事：快速解包。

性能参考

在典型的开发环境 (SSD, 多核CPU)下，测试数据如下：

• 解包: 使用4线程解包全部英雄语音，耗时约 15 秒。
• 转码: 将所有解包后的 .wem 文件转码为 .wav，耗时约 15 分钟。

后续处理：音频转码

本工具输出的音频文件为 .wem 格式。为了方便播放和使用，你可能需要将它们转换为 .mp3 或 .wav 等常见格式。

我们现在提供了一个魔改版的 vgmstream-cli 工具，它支持以下增强功能：

1. 目录递归处理：可以直接指定包含 .wem 文件的目录，工具会自动递归扫描并处理所有文件。
2. 增强的输出路径通配符：
   • ?p: 代表源文件的完整路径（包含最后的路径分隔符）。
   • ?b: 代表源文件的基础名称（不含扩展名）。
3. 源文件删除选项：通过 -Y 参数可以在转换成功后删除源文件。⚠️ 注意：这是一个危险操作，请谨慎使用！

使用方法

• 命令行直接调用: 假设你的音频文件位于 D:/audios 目录下：

  # 将所有 .wem 文件转换为 .wav 格式，并保持原始目录结构
  .\vgmstream-cli.exe -o "?p?b.wav" "D:/audios"
  
  # 转换并删除原始的 .wem 文件（谨慎使用！）
  .\vgmstream-cli.exe -o "?p?b.wav" "D:/audios" -Y

• 使用测试脚本进行批量转码: 项目提供了一个测试脚本，可以方便地进行批量转码并验证结果。

  python tests/test_transcode.py

  注意: 脚本中的 vgmstream-cli.exe 路径是硬编码的。如果你的路径不同，请直接修改 tests/test_transcode.py 文件中的路径。

你可以从 Virace/vgmstream-cli-build 下载最新版本的魔改工具。

注意: 如果你准备将所有提取的英雄语音转码为WAV格式，请确保有足够的硬盘空间。15.14版本所有VO相关WEM音频总共大小接近3G，转码后文件大小接近40G。

这种方式将转码与核心逻辑分离，让你可以自由选择是否需要以及如何进行格式转换。

维护者

Virace

• blog: 孤独的未知数

感谢

• @Morilli, bnk-extract

• @Pupix, lol-file-parser

• @CommunityDragon, CDTB

• @vgmstream, vgmstream

• 以及JetBrains提供开发环境支持

  

许可证

GPLv3