VoiceForge

VoiceForge 是一个“脚本 -> 语音 -> 节奏 -> 场景协议 -> 视频渲染”的自动化引擎。

它当前同时支持两条输出链路：

• 旧协议：manifest.json + MoviePy 草稿/终版渲染
• 新协议：project.json + scenes/scene_xxx/ Scene Package + Remotion 预览/渲染

仓库内已经包含：

• 多个 TTS provider
• 多个 TTA provider
• Scene Package Protocol
• Background / SFX Protocol
• Remotion 双协议运行时

功能概览

• 从 script.json 读取逐句脚本
• 调用 TTS 生成逐句语音
• 提取 timing / phoneme / beat
• 自动构建 scene / shot 包
• 可选生成场景级 BGM、Ambient、SFX
• 导出 audio_layers.json / audio_mix_plan.json / scene_mix.wav
• 用 MoviePy 或 Remotion 渲染视频
• 提供 scene/project 级 QC

环境要求

• Python >= 3.11
• Node.js >= 18
• npm 或 pnpm

推荐在 Linux / WSL / macOS 下运行。部分 TTS/TTA provider 依赖 GPU、PyTorch、ffmpeg 或额外系统库。

安装

1. 安装 Python 依赖

最小安装：

pip install -e .

开发安装：

pip install -e ".[dev]"

如果你需要完整能力：

pip install -e ".[all]"

可选依赖说明：

• .[tts]：TTS provider 相关依赖
• .[tta]：TTA provider 相关依赖
• .[video]：MoviePy 渲染相关依赖
• .[audio]：音频处理相关依赖
• .[dev]：pytest / ruff 等开发工具

2. 安装 Remotion 依赖

cd voiceforge-remotion
npm install
cd ..

模型目录约定

本项目约定所有模型放在本地 models/ 目录，不依赖运行时从 HuggingFace 自动下载。

关键约束：

• 模型路径通过 _resolve_model_path(model_id) 解析
• HF_HOME 会被锁定到 models/.hf-home
• 推荐目录形式：models/org/model-name

例如：

models/
  .hf-home/
  hexgrad/
    Kokoro-82M/
  coqui/
    XTTS-v2/

快速开始

1. 准备脚本文件

创建 examples/script.json：

{
  "title": "AI 语音视频演示",
  "language": "zh",
  "lines": [
    {
      "id": "S1",
      "text": "欢迎来到 VoiceForge。",
      "keywords": ["VoiceForge"],
      "emotion": "neutral",
      "speaker": "narrator"
    },
    {
      "id": "S2",
      "text": "它可以把脚本自动转换成带节奏的视频数据。",
      "keywords": ["脚本", "视频"],
      "emotion": "emphasis",
      "speaker": "narrator"
    },
    {
      "id": "S3",
      "text": "你还可以把输出交给 Remotion 做精细预览和渲染。",
      "keywords": ["Remotion", "渲染"],
      "emotion": "conclusion",
      "speaker": "narrator"
    }
  ]
}

2. 查看系统信息

voiceforge info

这个命令会显示：

• VoiceForge 版本
• 当前 registry 中可用的 TTS provider
• 当前 registry 中可用的 TTA provider
• provider 是否检测到本地模型目录

3. 只导出数据

voiceforge export examples/script.json -o output --tts kokoro

这个命令不会渲染视频，只会输出供 Remotion 或后续检查使用的数据文件。

4. 启动 Remotion 预览

voiceforge preview examples/script.json -o output --tts kokoro

或者在导出后手动打开：

cd voiceforge-remotion
npx remotion studio

5. 直接跑完整流水线

voiceforge run examples/script.json -o output --tts kokoro

如果你只想执行到导出阶段：

voiceforge run examples/script.json -o output --backend export-only

输入脚本格式

script.json 结构由 script.py 定义：

{
  "title": "项目标题",
  "language": "zh",
  "lines": [
    {
      "id": "S1",
      "text": "一句话内容",
      "keywords": ["关键词1", "关键词2"],
      "emotion": "neutral",
      "speaker": "default"
    }
  ]
}

字段说明：

• title：项目标题
• language：脚本语言，默认 zh
• lines[].id：句子 ID，建议唯一
• lines[].text：句子正文
• lines[].keywords：关键词列表
• lines[].emotion：neutral | emphasis | question | conclusion
• lines[].speaker：说话人标签

注意事项：

• 每行 text 不能为空
• 每行长度不能超过配置中的 max_sentence_length
• char_count 会自动计算，一般不需要手动写

配置文件

VoiceForge 支持通过 YAML 或 JSON 配置文件覆盖默认配置。

加载逻辑位于 loader.py，支持：

• .yaml
• .yml
• .json

示例 voiceforge.yaml：

fps: 30
width: 1920
height: 1080
max_sentence_length: 28
max_scene_duration: 8.0
safe_area_margin: 60
inter_sentence_gap: 0.3

tts:
  provider: kokoro
  voice: null
  language: zh
  speed: 1.0
  fallback_providers:
    - xtts

tta:
  provider: stable_audio
  bgm_prompt: "light modern tech background music"
  bgm_volume: 0.15
  ambient_prompt: "soft office room tone"
  per_scene_bgm: true
  sfx_prompts:
    whoosh: "clean UI whoosh"
    click: "light interface click"
  mix_policy:
    voice_target_lufs: -16
    bgm_target_lufs: -28
    ambient_target_lufs: -30
    sfx_peak_dbfs: -8
    peak_limit_dbfs: -1
    normalize_final_mix: true
    ducking:
      enabled: true
      voice_primary_reduction_db: 10
      attack_ms: 80
      release_ms: 220

使用方式：

voiceforge export examples/script.json -c voiceforge.yaml -o output

CLI 使用教程

voiceforge info

查看系统版本、provider 注册和本地模型探测结果：

voiceforge info

voiceforge export

只导出数据，不渲染视频：

voiceforge export examples/script.json -o output --tts kokoro

常用参数：

• --config, -c：配置文件路径
• --output, -o：输出目录
• --tts：TTS provider 名称
• --precision, -p：模型精度，如 fp32、fp16、bf16、int8、int4
• --verbose, -v：打印详细日志

voiceforge run

完整流水线执行：

voiceforge run examples/script.json -o output --tts kokoro

后端控制：

voiceforge run examples/script.json --backend export-only
voiceforge run examples/script.json --backend auto
voiceforge run examples/script.json --backend moviepy

说明：

• export-only：只导出数据
• auto：默认行为
• moviepy：走 MoviePy 渲染链

voiceforge preview

导出数据后直接启动 Remotion Studio：

voiceforge preview examples/script.json -o output

voiceforge export-scene

重新跑导出流程，但只查看某个场景包：

voiceforge export-scene examples/script.json --scene scene_001 -o output

voiceforge scene-info

查看单个场景包信息：

voiceforge scene-info output/scenes/scene_001/scene.json

voiceforge check-scene

对单场景执行 QC：

voiceforge check-scene output/scenes/scene_001/scene.json

主要覆盖：

• Scene timing 一致性
• shot 覆盖
• beat 范围
• background / sfx / mix policy 检查

voiceforge check-project

对 project.json 和所有场景包执行 QC：

voiceforge check-project output/project.json

voiceforge check

对旧协议 manifest.json 执行 QC：

voiceforge check output/manifest.json

voiceforge preview-scene

只聚焦某个 scene 启动 Remotion 预览：

voiceforge preview-scene output/scenes/scene_001/scene.json

voiceforge render-final

先做 QC，通过后渲染终版：

voiceforge render-final output/manifest.json -o output

如果 QC 不通过，这个命令会直接失败，不会输出终版视频。

输出目录说明

典型输出结构如下：

output/
  manifest.json
  project.json
  timing_track.json
  beats.json
  phonemes.json
  audio/
    voice_mix.wav
    bgm.wav
    segments/
      S1.wav
      S2.wav
  scenes/
    scene_001/
      scene.json
      audio.wav
      scene_mix.wav
      beats.json
      phonemes.json
      subtitle_tokens.json
      audio_layers.json
      audio_mix_plan.json
      background/
        bgm_main.wav
        ambient_main.wav
      sfx/
        click.wav
        whoosh.wav
      shots/
        1-1.json
        1-2.json

关键文件说明：

• manifest.json：旧协议主入口
• project.json：新协议整片入口
• scene.json：单场景包
• audio_layers.json：声明式音频层
• audio_mix_plan.json：编译后的执行计划
• scene_mix.wav：Python 侧预混结果

推荐工作流

工作流 A：数据导出 + Remotion 预览

适合调镜头、看字幕、看 beat、看 scene package。

voiceforge export examples/script.json -c voiceforge.yaml -o output
voiceforge check-project output/project.json
voiceforge preview-scene output/scenes/scene_001/scene.json

工作流 B：完整自动化输出

适合快速出草稿。

voiceforge run examples/script.json -c voiceforge.yaml -o output

工作流 C：终版渲染前校验

适合成片前最后一轮检查。

voiceforge export examples/script.json -c voiceforge.yaml -o output
voiceforge check output/manifest.json
voiceforge check-project output/project.json
voiceforge render-final output/manifest.json -o output

TTS / TTA Provider

当前 provider registry 定义在 provider_factory.py。

当前 TTS provider：

• kokoro
• xtts
• qwen3
• fish
• chatterbox
• f5tts
• mms
• vibevoice
• indic_parler
• higgs
• dia

当前 TTA provider：

• stable_audio
• bark
• audiocraft
• audioldm2

查看实际可用情况请以：

voiceforge info

为准。

Remotion 渲染说明

Remotion 工程位于 voiceforge-remotion/。

安装依赖后可直接运行：

cd voiceforge-remotion
npm run studio

或者：

npx remotion studio

内置脚本：

npm run render:draft
npm run render:final

注意：

• Remotion 消费的是导出的 public 静态文件路径
• preview / preview-scene 命令会帮你准备对应 props
• 新协议优先读取 project.json / scene.json / audio_mix_plan.json

常见问题

1. voiceforge info 里 Local = N

说明 provider 对应模型目录没有在 models/ 下被检测到。先确认模型是否已放到本地约定路径。

2. Script validation failed 或 Sentence too long

说明输入脚本不符合 script_parser.py 的约束。

处理方式：

• 缩短单句长度
• 确保 text 非空
• 确保 JSON 结构合法

3. preview-scene / preview 找不到 voiceforge-remotion/

请先安装前端依赖：

cd voiceforge-remotion
npm install

4. 只想看数据，不想渲染视频

使用：

voiceforge export examples/script.json -o output

5. 终版渲染失败

先执行：

voiceforge check output/manifest.json
voiceforge check-project output/project.json

确认 QC 通过后再执行 render-final。

开发与测试

运行测试：

python -m pytest

运行指定测试：

python -m pytest tests/core/test_pipeline_audio_protocol.py -q
python -m pytest tests/core/test_quality_checker_audio.py -q

运行 lint：

ruff check src tests

版本

当前版本：2.0.0

定义位置见 init.py。