让剧本成为游戏中的声音

VoiceDirector 是 Unreal 编辑器中的对话制作工具。你提供台词，选择声音或导入录音，试听后决定哪一版用于游戏。最终产物是 Unreal 标准音频资源 SoundWave。设置对话绑定后，也可以创建 DialogueWave。

台词是剧本中的一条记录；语言变体是这条台词的某种语言版本；录音版本（take）是该变体的一次录制或生成。可以保留多个版本，同时继续使用游戏中原来的音频。

第一次创建 Unreal 项目

1. 打开 Epic Games Launcher > Unreal Engine > Library，启动 UE 5.5、5.6、5.7 或 5.8。
2. 在项目浏览器中选择 Games > Third Person，再选 Blueprint 和 Desktop。Blueprint（蓝图）是通过连接节点编写的可视化程序，本指南无需编写 C++。
3. 填写项目名称，选择有空余空间的文件夹，点击 Create，等待编辑器加载。

添加 VoiceDirector

使用与你的 Unreal 版本匹配的 Windows x64 插件构建。通过 Fab 安装时，在 Launcher 库中将插件添加到对应引擎版本。安装到项目时，先关闭编辑器，再把完整插件文件夹放到 YourProject/Plugins/VoiceDirector/。没有 Plugins 就新建它。

YourProject/Plugins/VoiceDirector/VoiceDirector.uplugin

不要再嵌套一层 VoiceDirector。纯蓝图项目需要已编译的包及随附的构建文件。只有源代码的包需要 C++ 编译器并自行构建。

1. 重新打开项目，进入 Edit > Plugins，搜索 VoiceDirector 并启用。
2. 按提示重启编辑器。
3. 打开 Tools > VoiceDirector。

本教程使用随附录音，无需先配置 Kokoro 或 ElevenLabs。

1. 打开 Settings，把 Output Content folder (/Game/...) 设为 /Game/VoiceDirector/Audio，点击 Save Output Folder。/Game 指项目的 Content 目录，不是 Windows 磁盘。
2. 将两个示例文件下载到容易找到的文件夹。
3. 在 Lines > Import script 中，把 Import SourceId 设为 MyScript，点击 Import CSV 并选择示例 CSV。
4. 检查预览，点击 Apply Import。本教程不要勾选 Full snapshot。
5. 选中 L-001 的 en 变体。点击 Import WAV，选择示例录音。
6. 必要时点击 Select take，再点 Play。你会听到 “Keep your voice down.”。Stop 停止试听。
7. 点击 Approve take 批准录音。
8. 进入 Publish，或点击 Review publishing。点击 Refresh Preview，勾选新 SoundWave 的行，再点 Apply Selected Approved。
9. 用 Ctrl + Space 打开 Content Drawer，进入 Content > VoiceDirector > Audio。接着学习在游戏中播放。

在电子表格或文本编辑器中编写台词，导出为逗号分隔的 UTF-8 CSV。

LineId,CharacterId,Culture,Text,Context
L-001,rowan,en,Keep your voice down.,At the city gate

进入 Lines > Import script，填写稳定的 Import SourceId，点击 Import CSV。检查 Added / Changed / Archived / Unchanged，再点 Apply Import。仅查看预览不会修改台词。

重新导入时使用相同的 SourceId 和 LineId，可保留标识和历史录音。同一来源中 LineId/Culture 必须唯一。一个 LineId 可以有多个语言版本，角色应保持一致。

含逗号的单元格用双引号包围，内部引号写两次："他说 ""等等。"""。表格软件通常会自动处理。分号分隔的文件需要重新导出为逗号分隔。限制：16 MiB、10,000 行。

DataTable 是 Unreal 内的表格资源。直接选择它，无需手写 JSON 或另存 CSV。

1. 在 Settings > Script DataTable 中选择资源。
2. 将列映射到 LineId、CharacterId、Culture、Text，以及可选的 Context、SpokenText。支持 String、Name、Text。@RowName 可把行名作为 LineId。
3. 来源自动根据 DataTable 资源路径确定。点击 Preview DataTable Import。
4. 在 Lines 检查变更，点击 Apply Import。

从零创建表格

在 Content Browser 中创建 Blueprint Structure，加入 String 字段 LineId、CharacterId、Culture 和 Text 字段 Text、Context、SpokenText。保存后创建 Data Table，选择该结构作为行类型，添加行并填写示例值。最多 10,000 行。

插件也提供编辑器导入行类型 VoiceDirectorScriptRow。打包游戏本身需要的表格应使用你自己的运行时结构。发布后的 SoundWave 是普通游戏资源。

声音来自 Kokoro 或 ElevenLabs 的现有目录。分配将声音绑定到 CharacterId + Culture，并不会创建新声音模型。

1. 按后续章节配置服务商。
2. 在 Voices 选择服务商，点击 Check Connection / List Voices。这只读取目录，不生成语音。
3. 填写剧本里的 CharacterId 和 Culture，选择 Voice、Model，调整可用参数，点击 Save Voice Assignment。
4. 回到 Lines，选择一个变体，点击 Generate new take。

示例：rowan、en、Kokoro 声音 af_heart、模型 kokoro。声音必须支持目标语言。导入 WAV 无需声音分配。更改分配只影响后续生成，旧录音保留原始设置。

放大截图 ↗

Kokoro-FastAPI 独立运行在本机或可访问的服务器上。VoiceDirector 不安装或启动它。为依赖和模型预留磁盘空间。

1. 按照 Kokoro-FastAPI v0.9.0 官方安装说明操作。Windows CPU 方式需要安装前置组件、下载模型，再在后端目录运行 .start-cpu.ps1。
2. 等待服务及模型加载。本地默认安装可在浏览器打开 http://127.0.0.1:8880/docs 检查连接。
3. 在 Settings 把 Kokoro-FastAPI base URL 设为 http://127.0.0.1:8880/v1，点击 Save Settings。
4. 在 Voices 加载目录。可先使用 af_heart、kokoro、英语 en、速度 1.0。

Kokoro 速度范围为 0.5-2.0。支持语言取决于模型和声音。可以导入俄语文本与 WAV，但此 Kokoro 集成不生成俄语语音，需要其他合适来源。

需要你自己的 ElevenLabs 账号、额度和具有权限的密钥。生成消耗账号额度，大批量生成前请查看当前价格。

1. 在账号中打开 Developers > API Keys。创建密钥，启用 Voices: Read 和 Text to Speech: Access。若限制模型访问，允许所需模型。
2. 在 Windows 开始菜单搜索编辑账户的环境变量。在用户变量中点击新建，名称填 VOICEDIRECTOR_ELEVENLABS_KEY，值填密钥，确认各窗口。
3. 完全退出 Unreal 和 Epic Games Launcher，包括系统托盘进程，再重新启动，使其继承变量。
4. 在 Voices 选择 ElevenLabs，点击 Check Connection / List Voices，选择账号可用的声音和模型。
5. 保存分配，先生成一句短台词并试听。

插件请求 pcm_24000 并将 PCM 响应封装成 WAV。能读取目录不代表账号具有此格式的生成权限。速度范围 0.7-1.2；风格和 speaker boost 仅在模型支持时可用。

现有密钥可通过 More Actions (...) > Edit 修改，参见官方密钥指南。权限、额度或区域访问错误应先向服务商解决，再重试。

1. 在 Lines 选择变体，用 Ctrl 或 Shift 多选。
2. 单个变体点击 Generate new take，多个点击 Generate selected。确认前检查服务商、请求数、字符数和费用估算。
3. 在 Jobs 查看进度。Pause 暂停新请求，Resume 继续，Cancel 停止剩余队列。
4. Completed 后点击 Open take，会在 Lines 打开对应录音并清除隐藏它的筛选。

完成的录音仍需试听、批准和发布。错误诊断可以复制。每批最多 1,000 个变体，每次 TTS 请求最多 5,000 字符。

放大截图 ↗

审核面板显示录音文本、来源、时间、时长和由真实 WAV 计算的波形。切换台词即可查看该台词的历史。

使用 Select take、Play、Stop，满意后点击 Approve take。所有版本仍可比较。波形显示按可读性缩放，比较音量请实际聆听。

导入自己的录音

选择一个变体，点击 Import WAV。要求 little-endian RIFF WAV，16 位 PCM、24 或 48 kHz、单声道或立体声，最大 64 MiB。MP3、浮点 WAV 和 24 位 PCM 必须先转换。

More line actions 提供锁定、翻译审核、保留稳定 ID 的重命名和对话绑定。替换批准版本前先解锁。相同输入再次生成时，勾选 Create another take even if input matches。

放大截图 ↗

只有发布才会更改游戏使用的资源。导入、生成和批准本身保留原音频。

1. 打开 Publish > Refresh Preview。
2. 检查路径与操作：Create 创建、Update 更新、Conflict 需要处理。
3. 勾选目标已批准行及所需的基础 SoundWave 或对话依赖。
4. 点击 Apply Selected Approved 并查看结果。Copy 复制路径。

外部修改、未保存或只读资源不会被直接覆盖。解决冲突后刷新预览。发布过期但已批准的版本需要明确启用 stale takes 选项；先对比录音和文字。

放大截图 ↗

1. 打开关卡，在主工具栏选择 Blueprints > Open Level Blueprint。
2. 找到 Event BeginPlay，没有时右键图表并搜索添加。
3. 从白色执行引脚拖出连线，搜索并创建 Play Sound 2D。
4. 在 Sound 字段选择发布后的 SoundWave。
5. 点击 Compile，保存蓝图和关卡，回到编辑器点击 Play。

台词将在关卡开始时播放。空间中的角色语音可使用 Unreal 位置音频节点和自己的对话逻辑。在游戏中引用资源，使其包含在打包内容中。

运行时播放无需编辑器模块、密钥或 TTS 服务。参见 Epic 的 Play Sound 2D 文档。

翻译行保留 LineId、CharacterId，修改 Culture：例如 L-001,rowan,en 和 L-001,rowan,fr。翻译、对应声音和录音由你提供。

默认源语言是 en。基础 SoundWave 与新的本地化版本一起发布。本地化资源使用 Unreal 的 /Game/L10N/<culture>/... 结构。游戏引用基础资源，由当前活动文化选择本地化。

在 Project Settings > Packaging 包含所需文化和国际化数据。只修改编辑器界面语言不会配置游戏对话语言。

DialogueWave

创建说话者和可选听者的 DialogueVoice 资源。在 More line actions 中选择 Dialogue speaker、听者和稳定的 Context key，再点 Save Dialogue Context。将必需的 SoundWave、DialogueWave 一起发布。

DialogueVoice 是对话元数据，不是声音模型。每个 LineId 对应一个上下文；其他上下文使用不同台词 ID。

1. 准备剧本，点击 Settings > Export Actor Manifest CSV。
2. 将清单发给演员，保留 ID 和规定的 WAV 文件名，并要求支持的录音格式。
3. 用 Choose Actor Manifest 选择原始清单，用 Choose Returned WAV Folder 选择返回的录音目录。
4. 点击 Preview Actor Matching，检查就绪、缺失和歧义匹配，先修正文件。
5. 选中就绪行，点击 Import Selected Actor WAVs，然后试听、批准并发布。

录音保留原清单的台词。如果录制期间剧本发生变化，录音可能被标记为过期；请比较实际说出的内容。

Settings 包含 Kokoro URL、输出、DataTable、演员工具和队列限制。Save Settings 保存连接及生成设置，Save Output Folder 保存输出目录。

可以限制请求和字符数量。美元估算需手动填写每 1,000 字符价格。价格 -1 表示未知；美元预算 -1 表示无金额上限。启用金额上限但价格未知时，云生成会被阻止，直到可以估算。

这些是本地编辑器偏好设置，正常操作不需要编辑 JSON。

放大截图 ↗

备份整个项目，包括：

一个 SoundWave 无法恢复全部历史。同一项目只能由一个编辑器写入。只读实例恢复写入时，关闭另一编辑器并重启当前编辑器。不要删除仍由进程使用的写锁。

中断生成后查看 Jobs。结果未知的已发送请求不会自动重试；先查看服务商历史。

在 Publish 中使用检测到的 Review interrupted publication，或点击 Restore From Publish Journal，选择本项目 Saved/VoiceDirector/Publish/<batch>/Journal.json。阅读确认提示。恢复解决前保留日志和备份。外部修改会产生冲突，新建资源也可能留在磁盘供检查。需要帮助时保留项目副本并联系支持。

联系 nexusforgeuesupport@gmail.com，提供 VoiceDirector 和 Unreal 版本、服务商、复现步骤、错误文本及相关选项卡截图。

不要发送 API 密钥。可分享的小型台词或录音示例比整个私人项目更有用。调查恢复问题前保留备份。