配置文件与运行上下文

1. 当前配置主线

当前配置链路由三部分组成：

settings：传给 create_app_context(...) 的共享设置映射
标准 INI：lol_audio_unpack.config.ini 负责读写
AppContext：只消费已经解析好的共享配置

2. 配置读写

导入路径：lol_audio_unpack.config。公开入口见 Python API。

2.1 schema 层

共享配置 schema 位于：

src/lol_audio_unpack/config/schema.py

这里维护：

SettingKey
ConfigSection
SharedSettingField
CommandConfigField
SHARED_SETTING_FIELDS
SHARED_FIELDS_BY_KEY
SHARED_FIELDS_BY_INI_KEY
SHARED_FIELDS_BY_CLI_ATTR
SUPPORTED_SETTING_KEYS
DEFAULT_SHARED_SETTINGS
COMMAND_CONFIG_FIELDS
CONTEXT_OPTION_ATTRS
build_settings(args)

build_settings(args) 会从 argparse namespace 中提取共享配置字段，产出 create_app_context(...) 可直接消费的 dict[str, Any]。

2.2 INI 层

标准 INI 读写位于：

src/lol_audio_unpack/config/ini.py

当前公开 helper：

python

def resolve_default_path(
    *,
    dev_mode: bool = False,
    runtime_paths: RuntimePaths | None = None,
) -> Path


def load_settings(
    config_file: StrPath,
    *,
    require_exists: bool = True,
) -> dict[str, str]


def write_settings(
    config_file: StrPath,
    settings: dict[str, Any],
) -> None


def load_command_config(
    config_file: StrPath,
    *,
    command: str | None,
    require_exists: bool = True,
) -> dict[str, Any]


def write_command_config(
    config_file: StrPath,
    *,
    command: str,
    values: dict[str, Any],
) -> None

默认文件名：

lol-audio-unpack.ini
lol-audio-unpack.dev.ini

3. 运行时默认路径

resolve_default_path(...) 基于 detect_runtime_paths() 的 config_root 选择默认配置目录：

也就是说：

源码运行界面/控制台时，默认配置文件落在当前启动目录
打包运行界面时，默认配置文件落在可执行文件同目录

4. 标准 INI 结构

标准 section：

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

当前支持的命令字段：

[targets]：champions、maps
[runtime]：max_workers
[update]：enable、force、skip_events
[extract]：enable
[wav]：enable、wav_workers、wav_timeout、wav_retries、wav_format、wav_group_by_event
[mapping]：enable、integrate_data

[wav] wav_format 设置采样格式，转码统一输出 WAV。默认 pcm16 表示 16 位整数 PCM； pcm24 / pcm32 表示 24 / 32 位整数 PCM，float 表示 32 位浮点， auto 沿用解码器默认的输出采样格式。配置字段名保持为 wav_format。

界面读取 [app] 共享设置、[wav] 转码默认值与 [gui] 界面偏好，任务动作由执行中心选择。控制台启用 -c 时，动作列表由动作 section 的 enable 决定，转码选项同样读取 [wav]。

5. 共享设置字段

常用共享设置 key：

GAME_PATH
OUTPUT_PATH
GAME_REGION
EXCLUDE_TYPE
GROUP_BY_TYPE
WWISER_PATH
VGMSTREAM_PATH
LOBBY_AUDIO

当前默认值：

GAME_REGION = "zh_CN"
EXCLUDE_TYPE = "SFX,MUSIC"
GROUP_BY_TYPE = False
LOBBY_AUDIO = True：默认附带选人语音、禁用语音及选人音效；INI 使用 [app] lobby_audio = false 关闭，控制台使用 --no-lobby-audio。

上述语言默认值用于未显式提供参数的控制台/API。界面首次配置保持“请选择”，只在发现唯一有效语言时自动选中；主动留空会持久化，刷新不重新填充。显式空语言不能执行源处理任务。

旧 [app] with_bp_vo 在配置加载时自动迁移为 lobby_audio 并保留原值。新旧键同时存在时保留新键；迁移无法写回时告警并继续兼容读取。Python 配置字段和设置键统一为 lobby_audio / LOBBY_AUDIO，旧 Python 名称不保留别名。

6. 上下文构建

python

def create_app_context(
    *,
    settings: Mapping[str, Any] | None = None,
    force_reload: bool = False,
    dev_mode: bool = False,
    runtime_cache: dict[str, Any] | None = None,
    allow_empty_language: bool = False,
) -> AppContext

python

def setup_app(
    dev_mode: bool = False,
    log_level: str = "INFO",
    **kwargs,
) -> AppContext

create_app_context(...) 负责：
- 标准化共享配置
- 构建 AppConfig
- 在任何输出初始化前验证本地数据源基础结构
- 派生 AppPaths
- 产出 AppContext
setup_app(...) 在此基础上额外完成日志初始化

7. 路径派生结果

create_app_context(...) 会派生以下路径根：

audios
wavs
temps
logs
cache
hashes
reports
manifest
game_version
Game/DATA/FINAL/Champions
Game/DATA/FINAL/Maps/Shipping
LeagueClient/Plugins/rcp-be-lol-game-data

game_path 可以指向已安装客户端，也可以指向外部工具准备的等价目录。两者必须满足同一个已准备本地数据源合同，程序不提供下载或网络回退。

路径规则	说明
版本产物	`ctx.version_path(kind, version)` 加入版本和规范化语言
示例	`ctx.version_path("manifest", "16.18")` 返回 `manifest/16.18/zh_CN`
`kind`	使用 `manifest`、`audio`、`wav`、`wav_event`、`hash`、`report` 等 `AppPaths` 前缀
英语与空语言	`default` 规范化为 `en_US`；界面空语言使用只读 `_unselected`，不能执行源任务

用户文件位置见统一输出目录，硬链接、完整搬迁与旧目录迁移见资源库 API。

8. 配置示例

界面的“提前准备数据”保存在独立偏好分组，默认关闭：

ini

[gui]
prepare_data_on_startup = false

关闭时启动仅准备基础英雄/地图目录，解包或映射任务按所选目标补齐资源；开启后，在启动或游戏版本、路径、区域变化时自动补齐普通英雄/地图的资源与事件缓存。普通准备复用同版本缓存，显式“前置强制更新”才强制重建。该偏好不进入 AppContext 共享设置，也不改变控制台的显式动作语义；运行任务期间开关与其他运行时配置一起锁定。

[wav] wav_group_by_event 对应基础设置中的“按事件分类输出”，默认关闭，控制台同步提供 --wav-group-by-event / --no-wav-group-by-event。界面兼容读取旧 [gui] 同名键，新字段优先，保存时迁移到 [wav]。例如：

ini

[wav]
enable = true
wav_group_by_event = true

参数生效： 在创建新的 WAV 转码或批量导出任务时冻结，不重建共享数据或整理旧文件。 Python 使用 WavOutputOptions(group_by_event=True)。

输出情况	布局
普通默认根	`wavs`
可分类默认根	`wavs_by_event`；保留版本、语言、实体目录、原始 ID，在文件前增加事件层
无可用精确映射	回到普通根
映射可用但音频未关联	事件根的“未关联事件”
手动导出	使用所选根，不额外加 `wavs` 或 `wavs_by_event`

交付时序： 界面与控制台共用延后交付入口，等本轮已选映射步骤完成后分类，不隐式启用映射。独立 Python WAV 调用消费当时已有映射；需等待后续映射时，用 app.defer_wav_output(opts) 包住转码与映射，再调用 app.finish_wav_output(output)。

解包前应同时确认 [app] group_by_type：它决定新 WEM 的类型层位置，WAV 镜像实际 WEM 目录。两项设置均不重排已有输出。跨事件的 WAV 使用独立副本，用户自行整理、打包与分发。

8.1 已安装客户端

python

from lol_audio_unpack.app import create_app_context

ctx = create_app_context(
    settings={
        "GAME_PATH": "/path/to/League of Legends",
        "OUTPUT_PATH": "./output",
        "GAME_REGION": "zh_CN",
    }
)

8.2 外部准备目录

python

from lol_audio_unpack.app import create_app_context

ctx = create_app_context(
    settings={
        "GAME_PATH": "/path/to/prepared/lol-client",
        "OUTPUT_PATH": "./out",
        "GAME_REGION": "zh_CN",
        "WWISER_PATH": "./wwiser.pyz",
    }
)

旧版 source_mode、remote_* 与 cleanup_remote INI 项会作为未知配置记录警告并被忽略，不会改变 game_path 的本地消费语义。

8.3 直接读写 INI

python

from lol_audio_unpack.config import load_settings, resolve_default_path, write_settings

config_file = resolve_default_path()
write_settings(
    config_file,
    {
        "GAME_PATH": "/path/to/League of Legends",
        "OUTPUT_PATH": "./output",
        "GROUP_BY_TYPE": True,
    },
)
settings = load_settings(config_file)

外部工具选择与启动预检

[app] wwiser_path 和 vgmstream_path 留空分别使用内置 NativeHIRC、pyvgmstream；填写路径明确选择该外部工具。界面旧 [gui] vgmstream_path 在首次保存时写入共享字段，新共享字段（包括空值）优先。清除仅移除配置，不删除文件；任务使用创建时的快照。

后端检查与恢复	行为
启动预检	只探测本次后端，实际调用随包小 WEM/BNK；失败不静默回退
界面预检失败	可确认仅本次改用内置并复检，或取消
控制台/API 预检失败	直接返回失败
文件转换重试	重试完整任务，保持后端与参数，不重复预检；耗尽后记失败并继续其他文件
界面任务结束	不提供失败项手动重试入口

最大尝试次数包含首次，默认 3，至少 1。以下入口使用相同语义：

控制台：--wav-retries。
INI：[wav] wav_retries。
Python：WavOutputOptions.max_retries。
界面：“最大尝试次数”同步读写该 INI 字段，在创建任务与导出时冻结；保存不移除此键。

Windows 打包程序运行外部 wwiser.pyz 时，需要 PATH 中有可启动的 python；内置 NativeHIRC 不需要另装 Python。外部工具由用户自行准备，应用不自动下载。

发布包可在不启动界面、不加载用户配置的情况下执行真实样本自检：

powershell

.\LolAudioUnpack.exe --check-tools .\check-results\report.json --check-cancel `
  --wwiser-path C:\Tools\wwiser.pyz --vgmstream-path C:\Tools\vgmstream-cli.exe

省略外部路径则只检查两项内置后端。报告包含实际样本调用结果、耗时和取消后的子进程情况；所选检查全部成功（以及启用时取消成功）才返回退出码 0。该命令保留报告和探测材料，不能替代正式界面的人工验收。

配置文件与运行上下文 ​

1. 当前配置主线 ​

2. 配置读写 ​

2.1 schema 层 ​

2.2 INI 层 ​

3. 运行时默认路径 ​

4. 标准 INI 结构 ​

5. 共享设置字段 ​

6. 上下文构建 ​

7. 路径派生结果 ​

8. 配置示例 ​

8.1 已安装客户端 ​

8.2 外部准备目录 ​

8.3 直接读写 INI ​

外部工具选择与启动预检 ​

配置文件与运行上下文

1. 当前配置主线

2. 配置读写

2.1 schema 层

2.2 INI 层

3. 运行时默认路径

4. 标准 INI 结构

5. 共享设置字段

6. 上下文构建

7. 路径派生结果

8. 配置示例

8.1 已安装客户端

8.2 外部准备目录

8.3 直接读写 INI

外部工具选择与启动预检