企业官网建设流程全解析

Pixelle-Video 声音克隆实战指南：基于参考音频与 Index-TTS 工作流的完整配置

【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video

声音克隆（Voice Cloning）是 Pixelle-Video 中让短视频配音"拥有专属音色"的核心能力：只需一段 10～30 秒的参考音频，即可让 TTS 合成语音在音色、语气上贴近参考人声。本文围绕 docs/zh/tutorials/voice-cloning.md 的完整使用流程，结合仓库中 TTS 服务源码、ComfyUI 工作流定义与 REST API 实现，讲解参考音频的准备规范、启用声音克隆的配置与操作步骤、不同 TTS 工作流的克隆能力差异，以及常见坑位的排查思路。读完本文，你将能独立完成"准备参考音频 → 选择克隆工作流 → 预览效果 → 生成带专属音色的视频"的完整链路。

一、声音克隆在 Pixelle-Video 中的定位

Pixelle-Video 是一套 AI 全自动短视频引擎，TTS（语音合成）是其生成口播、旁白的关键环节。声音克隆属于 TTS 能力的一个进阶分支：不是在所有 TTS 工作流上都可用，而是依赖底层工作流是否内置"参考音频（reference audio）"输入节点。

从 TTSService 的源码可以看到，语音合成统一走pixelle_video.tts(text=..., workflow=..., ref_audio=...)这一入口，它支持两种推理模式：

• local 模式：调用本地 Edge TTS，免 API Key，但不支持声音克隆；
• comfyui 模式：将text、voice、speed以及ref_audio等参数注入指定工作流执行，声音克隆正是通过给工作流传入参考音频实现。

因此在动手之前，务必先确认你选择的 TTS 工作流是否包含参考音频输入，否则"克隆"不会生效。

二、准备参考音频：格式、时长与音质要求

根据原文档，参考音频需满足以下三个基本条件：

1. 文件格式：MP3 / WAV / FLAC 均可，推荐使用 WAV（无损、兼容性最好）；
2. 建议时长：10～30 秒；
3. 音质要求：避免背景噪音，人声清晰。

从工作流定义可以印证参考音频的"载体形态"：selfhost/tts_index2.json 中使用VHS_LoadAudioUpload节点加载参考音频（reference_audio），该节点支持上传音频文件并指定start_time与duration（0 表示读取完整文件）。这意味着：

• 参考音频可以是本地文件路径，也可以是上传后返回的路径（见下文 API 一节）；
• 若参考音频较长，可在工作流节点中通过start_time/duration截取最干净的人声片段用于克隆。

实操建议（结合源码逻辑）：录制或剪辑时尽量保证单一人声、无背景音乐、无回声，长度落在 10～30 秒区间；过短会导致音色特征提取不充分，过长则引入多余噪声。参考音频的路径需要在后续步骤中提供给工作流，建议将音频文件放在项目可访问的路径下，并记录好相对路径。

三、启用声音克隆的完整步骤

原文档给出了四步操作流程，下面逐一步骤结合界面与配置展开：

步骤 1：在语音设置中选择支持声音克隆的 TTS 工作流（如 Index-TTS）

Pixelle-Video 的 TTS 工作流按运行环境分为两类目录：

• workflows/runninghub/：云端 RunningHub 工作流，需在 config.example.yaml 中配置runninghub_api_key；
• workflows/selfhost/：本地 ComfyUI 工作流，需在 config.example.yaml 中配置comfyui_url（默认http://127.0.0.1:8188）。

仓库内置的 TTS 工作流包括：

其中 selfhost/tts_index2.json 的IndexTTS2BaseNode节点包含reference_audio输入，正是声音克隆能力的实现载体；而 selfhost/tts_edge.json 的EdgeTTS节点只有text、voice、speed、pitch输入，不含参考音频节点，因此不支持克隆。

默认工作流通过配置文件指定，config.example.yaml 中：

comfyui: tts: default_workflow: selfhost/tts_edge.json # TTS workflow to use

需要启用声音克隆时，应将默认工作流改为selfhost/tts_index2.json（本地）或runninghub/tts_index2.json（云端），或在调用时显式传入workflow参数。

步骤 2：上传参考音频文件

参考音频通过 TTS 请求中的ref_audio字段传入。在 REST API 层，TTSSynthesizeRequest 定义了该字段：

ref_audio: Optional[str] = Field( None, description="Reference audio path for voice cloning (optional). Can be a local file path or URL." )

即ref_audio支持本地文件路径或URL两种形式，由 tts.py 原样透传给 TTS 服务，最终注入工作流的reference_audio节点。

若通过 Web UI 操作，对应"上传参考音频文件"的交互；若通过 API 调用，则直接指定音频路径，见下文第四节的完整请求示例。

步骤 3：使用「预览语音」测试效果

合成前先用预览功能验证克隆效果。在 tts.py 的POST /tts/synthesize接口中，合成成功后会自动调用 get_audio_duration 返回音频时长：

{ "success": true, "message": "Success", "audio_path": "output/xxxx.mp3", "duration": 12.34 }

预览的核心价值在于：快速验证参考音频是否被正确识别、克隆音色是否符合预期，而无需等待完整视频渲染。若预览音色偏差较大，应回到步骤 2 更换或重录参考音频。

步骤 4：生成视频

确认预览效果后，即可在视频生成流程中复用该 TTS 工作流与参考音频，让最终成片使用克隆音色。至此，"参考音频 → 克隆音色 → 视频配音"的链路闭环。

四、通过 REST API 使用声音克隆（源码级示例）

除了 Web UI，Pixelle-Video 提供完整的 REST API。启用声音克隆的请求示例如下（对应 tts.py 中给出的官方示例）：

{ "text": "Hello, this is a cloned voice", "workflow": "runninghub/tts_index2.json", "ref_audio": "path/to/reference.wav" }

请求字段说明：

需要注意的两点（来自 tts.py 的兼容逻辑）：

• voice_id仅在未指定workflow时才会被当作voice参数使用，且会输出 deprecation 警告，新代码不应依赖它；
• ref_audio只在workflow本身支持参考音频节点时才会生效——若给tts_edge.json传ref_audio，该参数会被透传但 Edge 工作流中没有对应节点消费它，克隆不会发生。

响应体TTSSynthesizeResponse（见 api/schemas/tts.py）返回合成音频路径与时长，可用于后续视频合成流程。

五、工作流层面的实现原理：参考音频如何驱动克隆

声音克隆能否生效，取决于工作流图中是否存在"参考音频 → 合成模型"的连线。以 selfhost/tts_index2.json 为例，其关键结构为：

{ "5": { "inputs": { "text": ["3", 0], "mode": "Auto", "temperature": 0.8, "top_p": 0.9, "top_k": 30, "num_beams": 3, "repetition_penalty": 10, "max_mel_tokens": 1815, "max_tokens_per_sentence": 120, "reference_audio": ["12", 0] }, "class_type": "IndexTTS2BaseNode" }, "12": { "inputs": { "audio": "小裴钱.wav", "start_time": 0, "duration": 0 }, "class_type": "VHS_LoadAudioUpload" } }

要点拆解：

• IndexTTS2BaseNode：Index-TTS 系列模型的工作流入口节点，其reference_audio输入即"音色参考"；
• VHS_LoadAudioUpload：负责加载上传的音频文件，可通过start_time/duration截取片段；audio字段在 tts_service.py 中会被请求参数覆盖，即你传入的ref_audio路径会替换这里的默认值；
• SaveAudioMP3：将合成结果保存为 MP3，filename_prefix为audio/ComfyUI。

在服务层，TTSService.call会根据推理模式路由：local 模式直接调用 Edge TTS（edge_tts，含 5 次指数退避重试与并发限流）；comfyui 模式则调用 ComfyBaseService._resolve_workflow 解析工作流，再通过共享 ComfyKit 实例执行并解析返回的音频文件（tts_service.py 依次检查result.audios、result.files、result.outputs中的音频扩展名）。若工作流返回的是 URL 且指定了output_path，服务会自动下载到本地。

六、注意事项与常见坑位

原文档明确指出三点限制，结合源码可进一步给出排查建议：

1. 不是所有 TTS 工作流都支持声音克隆判断标准是工作流是否包含参考音频输入节点。Edge 系列工作流（runninghub/tts_edge.json、selfhost/tts_edge.json）的节点只有text/voice/speed/pitch，不支持克隆；Index-TTS 系列（tts_index2.json）支持。选择工作流前可先打开对应 JSON 检查是否存在reference_audio输入。

2. 参考音频质量会影响克隆效果背景噪音、多说话人混音、压缩过度的低码率音频都会污染音色特征提取。建议使用 10～30 秒、单一人声、无背景音乐的高质量片段；必要时用start_time/duration截取最干净的段落。

3. Edge-TTS 不支持声音克隆在 pixelle_video/utils/tts_util.py 的本地 Edge TTS 实现中，参数仅有voice（音色 ID）、rate、volume、pitch，其音色由微软云端预置角色决定，无法通过参考音频自定义。本地模式（inference_mode="local"）同样无法克隆。

其他实操提醒：

• 本地 ComfyUI 模式运行tts_index2.json前，需确认 ComfyUI 已安装 Index-TTS 相关自定义节点（IndexTTS2BaseNode、VHS_LoadAudioUpload、SaveAudioMP3等），否则工作流执行会失败；
• RunningHub 云端模式无需本地节点，但需在配置中填入有效的runninghub_api_key，并注意 config.example.yaml 中runninghub_concurrent_limit（默认 1）的并发限制；
• 合成失败时可查看服务日志：本地模式关注 Edge TTS 的 401/NoAudioReceived 重试信息，工作流模式关注 tts_service.py 打印的result.audios / result.files / result.outputs诊断信息，据此判断是工作流节点缺失还是音频解析失败。

七、小结

声音克隆在 Pixelle-Video 中的完整链路可概括为：

1. 准备：10～30 秒、无噪、单人声的 MP3/WAV/FLAC 参考音频；
2. 选型：在语音设置或 API 中指定支持克隆的 TTS 工作流（如tts_index2.json），Edge-TTS 与本地模式不支持克隆；
3. 注入：通过ref_audio字段传入参考音频路径（本地或 URL），工作流的reference_audio节点消费该输入；
4. 验证：用「预览语音」/POST /tts/synthesize检查合成音频的audio_path与duration，确认音色符合预期；
5. 成片：在视频生成流程中复用该工作流与参考音频，产出带专属音色的短视频。

如需进一步了解 TTS 工作流的配置项（default_workflow、runninghub_api_key、comfyui_url等），可查阅 config.example.yaml 与 docs/zh/getting-started/configuration.md；更完整的声音克隆进阶教程（多说话人、情感控制等）已在规划中，可先基于本仓库的 Index-TTS 工作流自行探索采样参数（temperature、top_p、num_beams等）对克隆音色的影响。

【免费下载链接】Pixelle-Video🚀 AI 全自动短视频引擎 | AI Fully Automated Short Video Engine项目地址: https://gitcode.com/GitHub_Trending/pi/Pixelle-Video