控制台参数参考

当前入口：

• unpack：对应 lol_audio_unpack.cli.cli:main
• mapping：同样对应 lol_audio_unpack.cli.cli:main，但默认以 mapping 模式启动
• python -m lol_audio_unpack：薄壳转发到同一套控制台主入口
• Windows 独立包 LolAudioUnpack-CLI.exe：提供相同动作，映射使用 LolAudioUnpack-CLI.exe mapping ...；使用说明见 控制台独立包。

控制台的相对输入、输出和工具路径均以调用终端的当前目录为起点，打包后也不切换到 EXE 所在目录。 默认输出为当前目录的 output/；不带路径的 -c 读取当前目录的 config/lol-audio-unpack.ini。

1. 基础命令

uv run unpack <ACTION...> [OPTIONS]

单独运行映射命令时，也可以直接使用：

uv run mapping [OPTIONS]

模块入口仍可用：

python -m lol_audio_unpack <ACTION...> [OPTIONS]

2. 配置来源语义

控制台当前只有两种模式：

2.1 命令参数模式

• 不带 -c/--config-file
• 仅使用内建默认值 + 本次命令显式参数
• 不再隐式读取 .lol.env 或系统 LOL_*

示例：

uv run unpack update extract \
  --champions Annie,Ahri \
  --game-path "D:/Games/Tencent/WeGameApps/英雄联盟" \
  --output-path "./output"

2.2 配置文件模式

• 带 -c 或 --config-file
• -c 不带路径：读取当前目录下的 config/lol-audio-unpack.ini
• -c <PATH>：读取指定 INI 配置文件
• 启用 -c 后，只允许提供配置文件路径；动作与参数都从配置文件读取
• 这条规则对全部控制台参数都生效，包括 --dev、--force、--max-workers
• 如果要切换到其他 profile（例如 lol-audio-unpack.dev.ini），请直接写显式 -c <PATH>

默认配置文件名：

• 默认：lol-audio-unpack.ini
• dev 配置：请显式传入 -c ./lol-audio-unpack.dev.ini

配置文件结构：

• [app]：共享配置
• [targets]：多个动作共享的实体范围
• [runtime]：多个动作共享的通用执行参数
• [update]：update 动作参数
• [extract]：extract 动作参数
• [wav]：独立 WAV 转码 stage 开关与细节参数
• [mapping]：mapping 动作参数

其中：

• 界面读取 [app] 共享设置、[wav] 转码默认值与 [gui] 界面偏好，动作由执行中心选择
• 控制台的 -c 模式读取共享设置、目标、运行参数和各动作分组，界面/控制台共用 WAV 输出规则

示例配置文件中的约定：

• 未注释的项：通常是必填或最重要的项
• 注释掉的项：表示默认值示例，不写就沿用默认值

示例：

uv run unpack -c
uv run unpack -c ./config/custom.ini

3. 共享配置参数

以下参数属于“共享配置”，只允许在纯控制台模式下显式传入：

• --game-path PATH
• --output-path PATH
• --game-region REGION
• --exclude-type TYPES
• --wwiser-path PATH
• --group-by-type / --no-group-by-type
• --no-lobby-audio：关闭默认附带的大厅音频（选人语音、禁用语音和选人音效）。三种文件统一输出到英雄的 lobby/，不受 --exclude-type 的 VO/SFX 筛选影响。

音频类型筛选

--exclude-type 接受 VO、SFX、MUSIC 的逗号分隔列表，默认 SFX,MUSIC。 --exclude-type= 显式传入空值，取消类型过滤。筛选示例见 控制台音频筛选，具体分组见 音频类型。

大厅音频与旧键

项目	行为
[app] lobby_audio	默认 true，设为 false 关闭
旧控制台 --with-bp-vo / --no-with-bp-vo	提示新用法并退出；默认包含时删除旧参数，关闭改用 --no-lobby-audio
旧 INI with_bp_vo	自动迁移为 lobby_audio，保留原值、注释与其他配置；新旧并存时以新键为准，无法写回时提示手动修改
获取与保存	更新时预取到 manifest，英雄解包时硬链接到 lobby/；缓存缺失时按英雄补齐
内容库	大厅 OGG 不进入 WEM 内容库

通用参数

• -c, --config-file [PATH]
• --max-workers N
• -l, --log-level
• --dev
• --enable-league-tools-log

注意：

• --max-workers 在 -c 模式下应写入 [runtime]
• -l, --log-level、--dev、--enable-league-tools-log 仍然只支持纯控制台显式传入
• 一旦启用 -c，它们都不能再作为手工控制台参数追加

4. 动作与参数

执行前确认目录设置： --group-by-type 决定新解包 WEM 的类型层位置，WAV 镜像实际 WEM 路径； --wav-group-by-event 仅控制 WAV 的事件分类和独立默认根。两者都不搬动或整理已有文件。

4.1 动作列表

可以顺序提供多个动作：

uv run unpack update extract wav mapping --champions Annie,Ahri --game-path "./game" --output-path "./output"

实际执行顺序固定为：

1. update
2. extract
3. wav
4. mapping

因此只要同次命令里包含 update 或 wav，运行时也会按上述顺序统一编排。 事件分类 WAV 会在本轮已选择的映射步骤结束后交付，能使用本轮新映射；未选映射则只读取已有映射。

4.2 共享实体选择

• --champions [IDs|ALIASES]
• --maps [IDs]

它们会对本次命令中出现的所有动作同时生效。

列表同时支持英文逗号和中文逗号，例如 --champions "1，103,555"，会先统一分隔符、去除空白和重复项。 英雄继续支持纯 ID 或纯 alias，不混用两者；负数不承担“不处理”或“全部”的含义。

未知 ID 会列出并以退出码 2 停止，不询问、不自动跳过。需要修改参数后重新运行。 存在性检查只依赖实体目录；update 取得基础 game data 后可检查 ID，再进入 BIN 和资源处理。 既有本地源检查可能更早发现未知选择；资源文件缺失、损坏和解析失败仍按原阶段边界报告。

在 -c 模式下，应写入 [targets]：

[targets]
champions = Annie,Ahri
maps =

4.3 通用执行参数

• --max-workers N

在 -c 模式下，应写入 [runtime]：

[runtime]
max_workers = 4

4.4 update

• -f, --force
• --skip-events

在 -c 模式下，上述参数应写入 [update]：

[update]
enable = true
force = false
skip_events = false

4.5 extract

extract 动作当前没有独立的专属控制台参数，主要复用共享目标与运行时参数。

在 -c 模式下：

• [extract] 使用 enable = true|false 决定是否执行解包阶段

示例：

[extract]
enable = true

4.6 wav

• --wav-workers N
• --wav-timeout SECONDS
• --wav-retries N
• --wav-format {auto,pcm16,pcm24,pcm32,float}
• --wav-group-by-event / --no-wav-group-by-event（默认关闭，仅 WAV 有效）

转码统一输出 WAV；--wav-format 设置采样格式，默认值为 pcm16。

参数值	采样格式
auto	沿用解码器默认的输出采样格式
pcm16	16 位整数 PCM（默认）
pcm24	24 位整数 PCM
pcm32	32 位整数 PCM
float	32 位浮点

PCM 选项中的数字表示位深。32 位整数与 32 位浮点使用不同的数值表示方式； 这些选项不改变文件容器，也不设置采样率。

在 -c 模式下：

• [wav] 负责 enable、wav_workers、wav_timeout、wav_retries、wav_format、wav_group_by_event

示例：

[wav]
enable = true
wav_workers = 2
wav_timeout = 5
wav_retries = 3
wav_format = pcm16
wav_group_by_event = false

按事件输出完整目录的例子：

uv run unpack extract wav mapping --champions Annie --wav-group-by-event --game-path "./game" --output-path "./output"

输出模式	英雄示例路径
普通默认	output/wavs/<版本>/<语言>/champions/<英雄>/<皮肤>/VO/<ID>.wav
开启事件分类且映射可用	output/wavs_by_event/<版本>/<语言>/champions/<英雄>/<皮肤>/VO/<事件名>/<ID>.wav

• 类型分组保留实际 VO/SFX/MUSIC 层位置，WEM 目录与原始 ID 不变。
• 无可用映射时保留普通 wavs；有映射但音频未关联时，进入“未关联事件”。不同版本、语言的映射不能互用，旧仅 ID 映射不用于猜测路径。
• 事件副本是独立文件，可复制、压缩和分发；切换参数不整理、删除或迁移已有 WAV。

上述选项用于消费应用 audios 树的 wav 动作；独立 convert-wem 消费用户指定的外部文件， 没有版本/实体映射上下文，继续按其输入路径镜像转换。

说明：

• 当动作列表包含 wav 时，控制台会执行一个独立的 WAV 转码 stage。
• WAV 转码 stage 消费当前版本/语言的 audios/<version>/<region> 输出树，按内容与转换方案复用已完成 WAV；需要转换的内容通过共用批处理生成镜像 WAV。

4.7 mapping

• --integrate-data / --no-integrate-data

在 -c 模式下，应写入 [mapping]：

[mapping]
enable = true
integrate_data = true

5. 执行与校验规则

除主动作外，还提供两个独立命令，必须放在参数首位，不能与主动作组合，也不读取 -c：

命令	输入与输出
export-json --champions ID 或 export-json --maps ID	按一个实体 ID 定位已有映射；--output-path 为数据根，默认 ./output；--game-region 默认 zh_CN；多版本用 --game-version 选择；--json-output FILE.json 保存文件，省略则 stdout 为完整 JSON
convert-wem --input WEM... 或 convert-wem --input-list FILE.txt	读取明确 WEM 文件，UTF-8 清单每行一个路径，相对条目基于清单目录；两种输入可合用；--output-path 为 WAV 目标，默认 ./output/wavs

映射导出 JSON

export-json 不初始化客户端、不自动运行 mapping；缺失时提示 update mapping。 仅有一个匹配版本时自动选择；普通和整合映射都存在时取最近生成的一份，同时间优先整合版。 完整 JSON 保留原字段，整数对象键转为字符串；诊断始终写入 stderr。

映射类型	事件字段
整合英雄映射	data.skins[].events.<类别>.mapping
整合地图映射	data.map.events.<类别>.mapping
普通映射	skins 或 map 中按子实体和类别组织

事件值为 WEM ID 列表，事件与音频可能为多对多关系。已解包时映射可能包含 audioPaths； 只有 ID 时，可在对应版本、语言和实体的 audios 目录按 <WEM ID>.wem 查找。

查找内容	入口或关键词
装备音效	地图 0 的 ITEMS_Global
英雄与装备交互台词	对应英雄语音
装备事件	ID 或内部名称，如心之钢 3084、中娅 Zhonyas
标记提示音	PING

英文前缀可能命中其他变体，以完整事件名和本地资源为准。中文名称与 ID 可参考腾讯 装备资料 items.js，版本可能与本地客户端不同。

独立 WEM 转码

独立转码配置	规则
共用参数	使用既有 WAV 批处理，支持 --wav-workers、--wav-format、--wav-timeout、--wav-retries、--vgmstream-path，默认值与主流程一致
路径	默认镜像共同父目录，跨卷使用 volume-N 子目录；--input-root 可固定镜像根
已有 WAV	默认跳过，--overwrite 覆盖
报告	写入目标下 reports/

两个独立命令沿用第 7 节退出码，示例见 控制台使用说明。

清单支持 UTF-8 BOM、空行和包围路径的双引号；不展开通配符，重复文件只处理一次。 清单内相对路径以清单目录为起点，命令行路径以当前终端目录为起点。 帮助和重定向输出均使用 UTF-8。主流程中的 manifest、hashes、audios 与 cache 可复用， 删除后相应步骤需重做；各阶段需使用相同输出根、版本和语言。

主动作校验

• 纯控制台模式下，必须提供至少一个动作：update / extract / wav / mapping
• -c 模式下，必须在配置文件里启用至少一个动作
• --wav* 仅允许和 wav 动作一起使用
• --integrate-data 仅允许和 mapping 一起使用
• game_path 必须满足已准备本地数据源的共享结构；缺失或损坏会在输出初始化前失败
• 程序不会下载资源，也不会在本地文件缺失时回退到网络来源

6. 已准备本地目录示例

外部工具准备的目录与已安装客户端使用同一命令：

uv run unpack update extract \
  --game-path "/path/to/prepared/lol-client" \
  --output-path "./output" \
  --game-region zh_CN \
  --champions 1,103,555

配置文件模式只需填写同一个 game_path：

[app]
game_path = /path/to/prepared/lol-client
output_path = ./output

完整结构与迁移说明见 已准备本地数据源合同。

7. 退出语义

控制台顶层根据同一个 RunResult 统一决定主结论与进程退出码；dispatch/runtime 不会在深层直接退出：

结果	退出码	含义
success	0	全部已尝试阶段成功，或合法 no-op
partial	3	有成功产物，也有实体或阶段失败
failed	1	已尝试工作全部失败，或发生运行期全局失败
input / usage	2	参数、配置或目标解析不满足约束
cancelled	130	用户中断；未开始的后续阶段不会执行

update 的共享数据、持久化或全局准备失败会阻断依赖阶段。extract partial 时，WAV 只接收 success/partial 且 artifacts 非空的实体目标；mapping 不依赖 extract 产物时仍会继续。日志样本摘要用于诊断， 不再作为退出状态的事实来源。

外部转码与重试

参数或流程	规则
--vgmstream-path	指定外部 vgmstream-cli，空路径使用内置后端
输出采样格式	两后端都输出 WAV，支持 auto、pcm16、pcm24、pcm32、float
并发与超时	沿用 --wav-workers、--wav-timeout
预检	均使用真实样本；失败直接退出，不询问或自动切换
--wav-retries N	文件最大尝试次数含首次，默认 3，至少 1
重试边界	内外后端共用，保持参数与后端，不重复预检；耗尽次数保留失败诊断