Arknights Voice Mod Guide

明日方舟语音 Mod 配置说明

这份文档面向语音 Mod 作者，说明 mod.ini 的字段含义、自动映射规则、 手动映射写法，以及常见问题排查方式。当前 wav 替换分支仅支持 .wav 文件。

推荐结论

• 能用 CN_001.wav 这种标准命名时，优先标准命名。
• 文件名和游戏 key 不一致时，用 [map] 显式映射。
• 发布给别人时，尽量只用相对路径，不用绝对路径。

注意事项

• 当前解析器按 INI 风格处理，不是完整 TOML。
• audio_root 是兼容旧字段，仍然有效。
• 自动映射依据的是“文件名主干”，不是文件内容。

1. 推荐目录结构

你的Mod文件夹/
├─ mod.ini
└─ wav/
   ├─ CN_001.wav
   ├─ CN_002.wav
   └─ CN_003.wav

如果文件名和游戏语音 key 不一致，也可以这样组织：

你的Mod文件夹/
├─ mod.ini
└─ wav/
   ├─ CN_001_重录版.wav
   ├─ 阿米娅_问候.wav
   └─ custom/
      └─ CN_003_alt.wav

2. 最常用配置模板

[mod]
type = audio
asset_root = Audio/Sound_Beta_2
voice_group = Voice_CN
character = char_002_amiya
audio_root = wav
auto_map_by_stem = true

[map]
CN_001 = CN_001.wav
CN_002 = CN_002.wav
CN_003 = CN_003.wav

3. 字段说明

type

固定写 audio，表示这是语音替换配置。

asset_root

游戏语音资源根路径。当前通常写 Audio/Sound_Beta_2。 最终完整资源键会拼成： Audio/Sound_Beta_2/Voice_CN/char_xxx/语音名。

voice_group

语音语言分组，必须与游戏资源目录一致。常见值包括 Voice_CN（中文）、Voice（日文）、Voice_EN（英文）。

character

角色语音目录名，例如 char_002_amiya、 char_103_angel。这里必须和游戏资源中的目录完全一致。

audio_root

音频文件扫描目录。它是兼容旧写法的字段，当前仍然有效，作用等同于 wav_root / scan_root。 通常写 wav，表示扫描当前 Mod 目录下的 wav 文件夹。

auto_map_by_stem

是否按文件名自动映射。开启后，会递归扫描 audio_root 下所有 .wav 文件，并按“文件名主干”自动建立映射。

[map]

手动映射表。左边是游戏中的语音 key，右边是实际使用的 wav 文件名或路径。 当文件名和 key 不一致时，应该优先使用这里进行显式绑定。

4. 自动映射规则

当 auto_map_by_stem = true 时，程序会递归扫描 audio_root 下所有 .wav 文件。

示例 A：标准命名

wav/CN_001.wav

会自动映射到：

Audio/Sound_Beta_2/Voice_CN/char_002_amiya/CN_001

示例 B：非标准命名

wav/CN_001_30000.wav

自动映射到的是：

Audio/Sound_Beta_2/Voice_CN/char_002_amiya/CN_001_30000

而不是：

Audio/Sound_Beta_2/Voice_CN/char_002_amiya/CN_001

5. 手动映射示例

[mod]
type = audio
asset_root = Audio/Sound_Beta_2
voice_group = Voice_CN
character = char_002_amiya
audio_root = wav
auto_map_by_stem = true

[map]
CN_001 = CN_001_30000.wav
CN_002 = 阿米娅_问候.wav
CN_003 = custom/CN_003_alt.wav

上面这份配置的意思是：

• 把游戏里的 CN_001 替换成 CN_001_30000.wav。
• 把 CN_002 替换成 阿米娅_问候.wav。
• 把 CN_003 替换成 wav/custom/CN_003_alt.wav。

6. 路径写法说明

[map] 右边支持以下几种写法：

• 相对于 audio_root 的路径，例如 CN_001.wav、custom/CN_003.wav。
• 相对于 Mod 根目录的路径，例如 wav/CN_001.wav。
• 绝对路径，例如 C:\VoiceMods\CN_001.wav。

7. 推荐写法

最稳妥的方案是：文件放在 wav/ 下，文件名直接使用游戏语音 key，并在 [map] 中显式列出关键项。

你的Mod文件夹/
├─ mod.ini
└─ wav/
   ├─ CN_001.wav
   ├─ CN_002.wav
   ├─ CN_003.wav
   └─ CN_004.wav

8. 常见问题

Q：文件放进 wav 目录了，为什么没有生效？

A：先检查文件名主干是否和游戏语音 key 完全一致。如果不一致，请在 [map] 里手动写映射。

Q：为什么 mp3 / ogg 不生效？

A：当前 wav 替换分支只支持 .wav 文件。

Q：audio_root 可以不写 wav 吗？

A：可以。它只是扫描目录名，你也可以写成 voice、audio 或其他目录。

Q：auto_map_by_stem = false 时会怎样？

A：不会自动扫描文件名建立映射，只有 [map] 中手动写明的条目才会生效。

Q：我已经能自动映射了，还需要写 [map] 吗？

A：不是必须，但推荐给关键语音写上。这样配置更直观，也能避免以后改名或关闭自动映射后失效。

9. 最稳妥模板

[mod]
type = audio
asset_root = Audio/Sound_Beta_2
voice_group = Voice_CN
character = char_002_amiya
audio_root = wav
auto_map_by_stem = false

[map]
CN_001 = CN_001.wav
CN_002 = CN_002.wav
CN_003 = CN_003.wav

这种写法最明确，最不容易因为自动映射规则而产生误解。