gui.md

桌面应用使用说明

基于 PySide6 的 CosyVoice 语音合成界面，覆盖音色选择、全部合成参数调节、多音字纠音、AI 风格指令生成、试听与自动命名输出。所有网络调用走后台线程，界面不冻结。

本应用聚焦语音合成；声音复刻（创建音色）请用核心库 voice_clone 或 python main.py clone。

启动

python run_gui.py

需先安装 PySide6（pip install PySide6 或 pip install -e ".[gui]"）。

界面布局

左右分栏：

• 左侧：凭据（API Key / 地域 / 代理）、音色与合成模型、合成文本、输出文件。
• 右侧：参数面板，分「韵律 / 风格指令 / 多音字 / 高级」四个 Tab。
• 底部：试听、打开目录、开始合成。

操作流程

1. 配置凭据并拉取音色

1. 填入 API Key（北京/新加坡地域 Key 不通用，注意与「地域」一致）。
2. 如直连百炼下载失败（DNS 解析错误），在 代理 框填 127.0.0.1:7890 之类的地址。
3. 点 拉取音色，列表来自 list_voices。选中某音色会自动带出它的 target_model 作为合成模型（仍可手动改；改成不匹配的模型会由 API 报错提示）。

也可不拉列表，直接在音色框手输公共音色名（如 longanyang）。

2. 输入文本并调参

右侧四个 Tab：

韵律

参数	说明
音频格式	wav / mp3 / opus / pcm
采样率	常用 24000 Hz
音量 / 语速 / 音调	滑块调节

风格指令

• 手写 instruction（方言 / 情感 / 角色等，如「以清静、空灵的语气朗读」）。
• 点 AI 生成：调用 Qwen 按文本情感写约 30 字风格指令，可再编辑。
• 语种提示：辅助多语种判定。

多音字（按词纠音 hot_fix，详见下节）

• AI 扫描多音字：调用 Qwen 结合上下文识别多音字并注音，失败时回退本地词典。
• 批量导入：粘贴形如 {"乐": "le4", "差": "ci1"} 的内容并入纠音表（可带 corrections= 前缀）。
• 复制：把纠音表 + 替换表导出为 dict 文本到剪贴板（与批量导入互逆）。
• AI 模型 / 深度思考：选择 Qwen 模型；深度思考默认关闭（扫描更快，需更准时再勾选，仅思考型模型有效）。
• 纠音表（词/字 → 拼音）：见下节规则。
• 文本替换表（原文 → 替换为）：生僻字替换为同音常用字，如 佁 → 以。

高级

• 固定随机种子（可复现）、启用 SSML、返回字级时间戳、过滤 Markdown 标记。
• 开头补静默：合成后用 ffmpeg 在开头补一段静默（需系统已装 ffmpeg；未装则回退为不补并提示）。

3. 输出与合成

• 自动命名（默认开启）：每次合成按「文本前缀_时间戳」生成文件名（取文本前 8 个有效字符 + 年月日_时分秒，落到 data/），避免反复合成互相覆盖。例：床前明月光疑是地_20260530_162651.mp3。扩展名跟随当前音频格式。
• 取消勾选「自动命名」可手动指定路径（启用「浏览…」）。
• 点 开始合成，完成后可 试听（再点为停止）或 打开目录。

多音字纠音规则（重点）

hot_fix 是按词匹配，不是按字全局替换：

• 拼音用带声调数字的 TONE3 格式：声调 1–4，轻声用 5，ü 写作 v。例：le4、cen1、de5、nv3。
• 多字词的拼音用空格分隔：至于 → zhi4 yu2。
• 同一个字在不同上下文读音不同时，用「包含该字的词」区分，而不是填孤立的字：
  • 至于顿丘 中「于」读 yú → 填词条 至于 → zhi4 yu2
  • 于嗟鸠兮 中「于」读 xū → 填词条 于嗟 → xu1 jie1
• 全文读音一致的字，可只填单字（如 乐 → le4）。
• cosyvoice-v2 不支持 hot_fix：选该模型时多音字 Tab 会被禁用。

常见问题

现象	原因 / 处理
合成成功但下载失败（getaddrinfo failed）	直连百炼 OSS 域名失败，在「代理」框填代理后重试（音频 URL 24h 内有效）
试听无声 / 补静默不生效	试听依赖 QtMultimedia（PySide6 Addons）；补静默依赖系统 ffmpeg，检查是否在 PATH
提示模型与音色不匹配（418）	合成模型须与复刻音色的 target_model 一致
多音字 Tab 不可用	当前模型不支持 hot_fix（如 cosyvoice-v2），换支持的模型