用自然语言设计原创角色的声音：导入人物设定，查看模型推演的声线提示词，生成试听，并保存喜欢的声音用于后续台词。
Chinese-first local voice studio: turn character profiles into editable voice prompts, generate previews, and reuse saved reference voices with new dialogue.
把“这个角色听起来应该是什么样”变成可试听、可保存、可复用的角色声音。
TimbreForge 不是单独的 TTS 调用示例，而是一套围绕角色声线资产组织的本地工作流：角色设定会生成可编辑的声音描述，试听结果进入角色库，参考音频可以波形裁剪、串联和复用，后续台词始终从同一张角色卡继续生成。
- 想做原创角色、游戏 NPC、有声小说或短视频角色声音。
- 希望参考音频、逐字稿和声音设定留在本机。
- 正在使用或准备使用 Qwen3-TTS，也希望保留 CosyVoice / IndexTTS 等后端入口。
- 不想每次生成都重新填写一套零散参数，而是希望先建立角色卡再持续复用。
当前版本：0.6.0a1 · Alpha。语言模型与语音模型需另行配置；本仓库仅包含源码、文档、测试和版本清单。
| 功能 | 使用方式 |
|---|---|
| 角色设定 → 声线推演 | 粘贴设定，或导入 Word .docx、TXT、Markdown、JSON；本地语言模型给出声音特征、依据、待确认项、完整提示词和试听台词。 |
| 一句话生成 | 只输入声音描述，自动选择设备、模型采样配置和随机种子；试听后可直接保存到角色库。 |
| 角色库与角色卡 | 统一保存原始音频、标准音频、逐字稿、结构化 VoiceRecipe、模型版本、随机种子、来源、处理历史与 Clone Prompt 状态；支持复制、导出和重新导入。 |
| 参考音频修整 | 去首尾静音、基础降噪、去点击声、EQ、压缩与响度标准化；四个预设，原始音频永不覆盖，每次处理都有参数与输入/输出哈希。 |
| Clone Prompt 缓存 | 复用 Qwen 条件张量；音频、逐字稿、模型版本、克隆模式或处理链变化时自动失效并回退到普通克隆。 |
| 声线微调与 A/B | 每次只改变一个表达维度生成 4–8 个候选，A/B 试听，选中后保存为角色新版本并重建 Clone Prompt。 |
| 文字生成与长文本 | 从角色库选择角色生成台词；长文本按段落/句子切分、逐段生成、检查漏句与异常后淡化拼接。 |
| 自动评估 | 固定八类测试文本，记录 CER/WER、说话人相似度、时长、语速、静音、峰值/LUFS、削波、音色漂移与人工评分，同时给出平均值与最差候选。 |
| 模型管理 | 登记本机已有模型目录与版本，切换、检查与回滚；新模型通过统一适配器接入，不自动下载。 |
| 进阶设计与多角色创作 | 手动采样参数、候选 A/B、直接保存任一候选、脚本逐句生成、人工选择后导出分轨与混合轨。 |
| 资源管理 | 重型任务统一排队、串行执行；失败或取消时释放子进程、临时文件与空闲模型；按页面缓存、历史预览、空闲模型顺序释放内存。 |
| 高级训练（离线） | 数据集切分与质量筛选、外部 LoRA/Adapter 训练任务、检查点原子发布、评估、模型登记与回滚；不作为普通生成流程的一部分。 |
flowchart LR
A[导入角色设定] --> B[本地模型推演]
B --> C[查看并编辑声线配方]
C --> D[生成试听与挑选]
D --> E[保存角色声线]
E --> F[音频修整]
F --> G[声线微调候选]
G --> H[长文本与角色复用]
Windows 用户可以直接双击 安装并启动声线工作室.cmd。它会自动创建 .venv、安装界面依赖、生成本机配置并打开工作室；模型权重仍需按本机显卡和许可证单独准备。开发者可使用 tools/build_windows_bundle.ps1 生成可分发 ZIP。
需要 Python 3.11 或 3.12。以下以 Windows PowerShell 为例：
git clone https://github.com/zdd3143/timbreforge.git
cd timbreforge
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install ".[ui]"
Copy-Item timbreforge.example.toml timbreforge.local.tomlLinux 可用 source .venv/bin/activate 激活环境，再复制示例配置。Windows 是当前真实模型验收环境；其他平台仍需验证对应 CUDA 与模型运行环境。
编辑 timbreforge.local.toml，填写模型 Python 和完整模型快照路径。工作室环境与模型环境分开，不要把模型权重放进 Git 仓库。
| 用途 | 模型 | 对应配置 |
|---|---|---|
| 角色设定推演 | Qwen/Qwen3-1.7B |
[planner] python / model |
| 描述生成声音 | Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign |
[qwen] python / design_model |
| 克隆、保存角色后换台词 | Qwen/Qwen3-TTS-12Hz-0.6B-Base |
[qwen] python / base_model |
角色推演是可选功能；只用一句话生成时不需要语言模型。IndexTTS/ComfyUI、CosyVoice3 和评分器也是可选后端。
模型版本和已验收运行环境见 VoiceDesign 配置、角色推演配置及 后端说明。语音模型基线为 qwen-tts==0.1.1；实际 PyTorch/CUDA 需按机器单独安装并验证。软件启动不会自动下载模型。
python -m timbreforge.launcher --check
python -m timbreforge.launcher也可以在已安装依赖的环境中双击 启动声线工作室.cmd。默认打开 本地工作室。端口被占用时可使用 --port 7862；--no-browser 只启动服务。
首次使用可从「简化版 · 一句话生成」开始；已有角色资料时，使用「角色设定 → 声线推演」。满意的试听保存后会进入统一「角色库」，之后在「创建角色 / 声线微调 / 文字生成 / 长文本生成」中始终从角色库选择角色卡。参考音频的波形裁剪、确认另存和多片段串联集中在「参考音频助手」；参考克隆和角色复用也合并在同一入口。角色卡可试听、复制、导出和重新导入；高级训练与模型切换在「模型管理 / 高级训练」页，不参与普通生成流程。完整上手指南
在「参考克隆 / 表演指令」上传 30 秒以内的参考音频，填写准确完整转录和新台词，使用默认 Qwen Base 后端生成。Qwen Base 的表演指令应留空；IndexTTS 与 CosyVoice 的指令能力和参数语义不同。
工作室按需启动独立模型进程，结束后退出。同一输出目录下的工作室与命令行共用资源锁；调用前释放本机闲置 ComfyUI/IndexTTS 模型缓存。不会强制关闭其它应用或中断已有任务。长台词分段可能影响语气衔接，需要试听确认。内存策略与故障排查
已在 RTX 4060 Laptop 8 GB 上验证本地角色推演、VoiceDesign、Qwen Base 克隆及浏览器生成。一次两段克隆输出 25.36 秒音频，PyTorch 峰值显存约 2.60 GiB，结束后整卡显存回到运行前水平。这是单次实测，不是最低配置或音质保证。本机验收记录
- 按示例配置，输出保存在
.local-data/outputs/，角色与声线库保存在.local-data/characters/。备份时应同时保留音频和元数据。 - 角色目录结构：
character.json、原始reference.wav、audio/（当前标准音频与压缩预览）、prompts/（可重建的 Clone Prompt）。删除角色会清理整个目录。 - 生成记录在
outputs/generation/，调音会话在outputs/tuning/，任务记录在outputs/jobs/，模型注册表在models/registry.json。 .gitignore排除本机配置、录音、模型、缓存和生成结果；仓库和安装包不分发这些资产。- 声线推演是创作建议。声音贴合度、文字准确性和身份一致性需要试听确认；保存角色不是训练或微调模型。
- 使用参考声音前应确认使用权和说话者授权，不用于冒充、欺诈或侵权。界面面向本机可信用户，不提供公网多用户鉴权。声音权利与安全
仅安装 CPU 核心可使用 python -m pip install .；核心依赖为 NumPy 和 SoundFile，界面为可选 Gradio extra。
python -m timbreforge capabilities
python -m timbreforge --config timbreforge.local.toml generate --backend qwen3 --task clone --reference authorized-reference.wav --ref-text "参考音频实际说出的完整内容。" --text "新的台词。" --confirm-rights
python -m unittest discover -s tests -p "test_*.py" -v
python tools/release_check.py
python tools/backend_audit.pyauthorized-reference.wav 是占位路径。测试使用临时合成采样和模拟后端；真实模型推理不纳入核心 CI。仓库提供 Windows/Linux、Python 3.11/3.12 的 CI 矩阵，结果以实际工作流为准。
另保留独立实验合成器 timbreforge-synth 和旧数据集检索 timbreforge-voicegen。实验合成器生成程序化音色，并非自然语音 TTS；它们不属于角色声线主流程。
- 配置说明 · 使用指南 · 多角色创作
- 角色库与角色卡 · 音频修整 · Clone Prompt 缓存 · 社区适配器
- VoiceRecipe 配方 · 微调、长文本与评估
- 模型管理与 Voice Conversion · 离线训练
- 角色推演与导入 · 声音设计 · 参考音频助手
- 公开角色示例 · AutoDL 部署
- 测试说明 · 发布检查 · 更新记录 · 0.6.0a1 实施报告
- 贡献指南 · 安全报告
缺陷报告请附复现步骤、版本、系统和脱敏错误信息；不要上传私人录音、密钥或本机配置。
原创项目代码采用 Apache-2.0。模型、第三方库、数据、录音及声音权利分别适用各自条款，见 第三方说明。