# dsh-voice-say

把「用某个音色、按某种情绪说一句话」做成 DSH 里可安装的一个插件。

两条通道，同一组主参数：

| 通道 | 引擎 | 需要什么 |
| --- | --- | --- |
| `local` | Breeze TTS 2（一个 exe + 一个 gguf） | 一份本地模型，免费离线，Vulkan / CPU 都行 |
| `cloud` | 任意 OpenAI 风格 TTS（BreezeBlue 等） | `apiKey` + `voiceId`，一次 HTTP |

## 核心：调声音不靠调快慢

```
instructions    自然语言写情绪、语气、停顿 —— 怎么说话
guidanceScale   模型听不听这段指令（1.0 = 不额外施加，>2 容易发毛）
```

语速、音高这类硬参数**不是**主要手段。想让它慢一点、冷一点、带点哽咽，
正确做法是把话写进 `instructions`，然后决定要不要把 `guidanceScale` 拉高一点。

两条通道怎么映射：

| 插件参数 | 本地（breeze-cli） | 云端（HTTP） |
| --- | --- | --- |
| `instructions` | `--instruction` | `instructions` |
| `guidanceScale` | `--cfg-scale` | `guidance_scale`（可改成 `cfg_scale`） |

## 风格：不用自己想词

自己写 instructions 最难的是「想不出词」。所以内置 18 个风格，点一下就填好：

| id | 风格 | 建议强度 | 一句话 |
| --- | --- | --- | --- |
| `tsundere` | 😤 傲娇 | 1.45 | 嘴上不饶人，明明在意却装作无所谓 |
| `aloof` | 🧊 高冷 | 1.40 | 情绪和音量都压下去，懒得解释 |
| `coquettish` | 🥺 撒娇 | 1.40 | 尾音上扬拖长，带鼻音，在讨反应 |
| `gentle` | 🌙 温柔 | 1.20 | 轻声细语，句尾软下来 |
| `genki` | ⚡ 元气 | 1.30 | 语速偏快，音色明亮 |
| `lazy` | 🛋️ 慵懒 | 1.35 | 懒散拖音，像刚睡醒 |
| `tired` | 😮‍💨 疲惫 | 1.35 | 沙哑、气息不足，偶尔叹气 |
| `choked` | 💧 哽咽 | 1.50 | 忍着哭，气息不稳，句子中间断一下 |
| `perfunctory` | 😐 敷衍 | 1.40 | 只给最短回应，明显没兴趣 |
| `angry` | 🔥 生气 | 1.50 | 压着火，字咬得重，但不喊 |
| `shy` | 😳 害羞 | 1.45 | 越来越小声，像不敢说完 |
| `whisper` | 🤫 耳语 | 1.50 | 气声，贴着耳朵说 |
| `broadcast` | 🎙️ 正经播报 | 1.15 | 播音腔，吐字清晰，无个人情绪 |
| `aggrieved` | 🥲 委屈 | 1.45 | 拖尾音带鼻音，像刚被欺负 |
| `mysterious` | 🌫️ 神秘低语 | 1.50 | 压低声线，很慢，句尾下坠 |
| `excited` | ✨ 兴奋 | 1.35 | 音调高、快，亮得忍不住笑 |
| `coaxing` | 🫧 哄人 | 1.25 | 放软放慢，一句一句哄，带笑意 |
| `deadpan` | 🫥 面瘫 | 1.35 | 完全平，像在念清单 |

**可以叠加**：选「傲娇 + 高冷」= 两段描述按顺序拼成一条 `--instruction`，
建议强度取其中最大值，之后还能自己拉 `guidanceScale` 微调。

设置页里点风格 → 下面实时显示**实际会发给引擎的那段 instructions**；
不爽就再往 `instructions` 框里补一句自己的话（傲娇 + 高冷 + 「最后一句压下去」）。

工具侧一样：`voice_say { text, styles: ["tsundere","aloof"] }`，
`voice_styles` 列出全部风格（可带 `query` 过滤）。

## 读音导演：先断句，再念

引擎念的是**标点**。同一句「我不要」，写成 `我不要。` 和 `我不要……` 是两个意思；
而 TTS 自己不知道她此刻是什么心情、刚才在跟谁聊什么。所以在合成之前，多加了一道：

```
台词 → 读音导演（和 QQ 同一个大脑）→ 打好标点的台词 → Breeze / 云端 → 音频
```

导演看三样东西，全部从本机真实数据里取，不看摘要、不猜：

| 它看什么 | 从哪儿取 |
| --- | --- |
| 人设 | dsh-life 的 `identity.json`（名字、九项人格参数、原则） |
| 此刻情绪 | 情感引擎的 `params.json`（某个会话的七情当前值 / 上限、语言指纹） |
| 当时情节 | QQ 桥接的 `social-v2.json`（这个会话最近几条消息、正在聊的话题、上次被什么叫醒） |

然后它只做一件事：**重排标点与停顿**——哪儿断句、哪儿留一口气、结尾是句号还是省略号。

**硬约束**：字词一个都不许改。

- 模型输出会先跟原文逐字核对（只比汉字/字母/数字，标点不计）。
- 不一致就先重试一次（明确要求「只许动标点」）。
- 还是不一致，就走**盖章法**：把它想出来的标点剥下来，原封不动盖回原文的词上——标点是它的，字还是原字。
- 再不行就作废，**退回原文照念**。合成永远不会因为导演而失败或卡死（有超时）。

设置页里「试算标点」只算不合成，「看上下文」能看到导演手里到底有什么料（不发模型请求）。

```
voice_direct { text: "你不要再这样了，我真的会难过的。", styles: ["choked"] }
→ 原句  你不要再这样了，我真的会难过的。
→ 处理  你不要……再这样了。我真的……会难过的。
→ 说明  用两处省略号把话断开，让气卡在「再这样」和「会难过」前面……
→ 情绪  哽咽压抑
```

## 导演台开在 DeepSeek 窗口里（0.6.0）

导演不必自己拿 key 直连模型。默认走 **DSH 里的专用会话**：插件会在 DeepSeek 窗口里建一个标题叫
`读音导演 · dsh-voice-say` 的会话，之后每次「这句怎么念」都在那个窗口里问 —— 你能在 GUI 里看见它想了什么、
为什么这么断句，也能随时进去插一句改方向。

```
设置页点「试算标点」
   → 插件找到 DSH（桥接里记着的 baseUrl）→ 用本机会话密钥签一个 Cookie
   → session/prompt：把「规则 + 人设 + 七情 + 最近聊天 + 这句台词」发进那个会话
   → session/page 轮询，等这一轮说完 → 拿回 JSON（render / notes / emotion）
   → 过四道保底（逐字核对 → 重试 → 盖章法 → 退回原文）→ 交给引擎念
```

为什么这样更省心：

- **不碰 key**：用宿主自己的 provider / 模型 / 凭据，插件里没有任何密钥。
- **看得见**：导演的每次判断都留在那个会话里，是对话历史也是日志。
- **不重复开窗**：会话 id 存在 `config.json` 的 `director.sessionId`，只有会话没了才新建。
- **有退路**：DSH 连不上（或你把 `director.transport` 设成 `api`）就退回直连模型 API，合成照常出声。

设置页那张卡里能看到：通道、导演窗口（会话 id）、DSH 地址与来源、会话是否就绪；右上角 **「换一个导演窗口」**
会清掉会话 id，下一次合成自动在 DeepSeek 里新开一个。

```
GET  /api/voice-say/direct/session          → 看现在开着哪个窗口
POST /api/voice-say/direct/session {reset:true} → 清掉，下次新建
```


## QQ 里的声音 = 设置页试听（0.5.0）

以前群里发出去的语音和这里试听**不是一个嗓子**，三个原因叠在一起：

1. **音源不同**：QQ 那边桥接固定用自己那份参考音频（`audio/大肥鱼.mp3` 裁 12 秒）克隆；
   而设置页如果没选音色，`--voice` / `--ref-audio` 都不传，引擎走的是**内置默认说话人**。
2. **参数不同**：试听带着 `--instruction` + `--cfg-scale`，QQ 那条 `cfgScale: 1` 什么都不传。
3. **最后一道**：QQ 语音条要过 SILK 编码（网关做的），低码率会削高频、声音发闷——这条躲不掉，谁发都一样。

现在反过来：**QQ 那边先问插件**。桥接每次要发语音，先 `POST /api/voice-say/voice-plan` 拿一份「这句怎么念」：

```
台词 ─┐
      ├─ 读音导演 → 打好标点的台词（spoken）
      ├─ 风格 → instructions + guidanceScale
      └─ 音色 → voice（默认音色）或 refAudio（自定义参考音频）
                     ↓
        Breeze / 云端 → 音频 → SILK → QQ
```

于是三样东西对齐了：**标点、语气、嗓子**。想让它彻底一致，只要在设置页做一件事：

- 「自定义参考音频」传一段音频 → 存成 `<数据根>/ref/ref-24k.wav`，QQ 发语音就用它当 `--ref-audio`；
- 或者上传成音色再「设为默认」（音色同样是从你那段音频编出来的）。

两样都没设，才回落到桥接自带的克隆。桥接侧开关：`socialV2.voice.followPlugin`（`false` = 临时不跟插件）、
`socialV2.voice.pluginBaseUrl`（默认取 `dsh.baseUrl`）。桥接失败/超时一律 null 回落老路，不会把消息卡死。

## 装

```bash
dsh plugin --profile <profile> add dsh-voice-say
```

或者手工：把包目录加进 profile 的 `dsh.profile.bundles`，重启 DSH。
装好以后在 **设置 → 语音合成** 里就能用。

本地通道要先有一份 Breeze TTS 2：`breeze-cli.exe` + `*.gguf`。
插件会自己按常见位置探测（`D:/dprz/breeze-tts2`、`$BREEZE_ROOT`、`$BREEZE_CLI`、`$BREEZE_MODEL`），
探不到就在设置页里手填。

## 用

七个工具：

| 工具 | 干什么 |
| --- | --- |
| `voice_say` | 合成一句话（`text` / `provider` / `voice` / `styles` / `instructions` / `guidanceScale` / `seed` / `direct` / `scope`） |
| `voice_preview` | 合成一小段试听，听当前风格与参数的效果 |
| `voice_direct` | 只算标点不合成：看看导演会把这句话断成什么样 |
| `voice_styles` | 列出 18 个风格（`query` 可过滤），叠加时把 id 传给 `styles` |
| `voice_list` | 列已保存音色，顺便报引擎是否就位 |
| `voice_add` | 把一段音频存成音色（`name` + `text` 逐字转写 + `audio`） |
| `voice_delete` | 删一个音色 |

设置页里还能**上传本地音频**（浏览器选文件 → base64 上传 → 落盘 → 编码成 `voices/<name>.breeze`），
以及直接播放试听片段。

## 上传音色时只有一条硬要求

`ref_text` 必须是那段音频里**一字不差的转写**。引擎靠它对齐音色，写错整条音色就歪了。
另外：5~15 秒、安静环境、单人说话最稳；带混响或背景音乐会把噪点一起克隆进去。

## 配置

配置合并顺序：插件 patch 的 `config` ← 被 `<dataRoot>/config.json` 覆盖
（设置页写的是后者，改完立刻生效，不用动 profile）。

| 键 | 默认 | 说明 |
| --- | --- | --- |
| `provider` | `local` | `local` / `cloud` |
| `instructions` | 一句傲娇味的默认值 | 怎么说话；用风格时它就是「补充」 |
| `styles` | `[]` | 选中的风格 id 数组（可多个，按顺序拼） |
| `guidanceScale` | `1` | 1.0~3.0，1.0 = 不额外施加 |
| `seed` | `42` | 换种子 = 换一种演绎 |
| `maxChars` | `300` | 单次合成字数上限 |
| `defaultVoice` | 空 | 不指定就用 `instructions` 现场设计嗓音 |
| `refAudio` | 空 | 自定义参考音频的 24k wav 路径（界面「就用这段当嗓子」会写它）；没音色时用它克隆 |
| `refText` | 空 | 上面那段音频的逐字转写 |
| `cli` / `model` | 自动探测 | breeze-cli.exe 与 .gguf |
| `voicesDir` / `inboxDir` | 自动探测 | 音色目录 / 上传暂存目录 |
| `device` / `gpuIndex` | `vulkan` / `1` | 多显卡机器要钉住独显 |
| `ffmpeg` | 自动探测 | 非 wav 的参考音频要它转码 |
| `cloudBaseUrl` / `cloudApiKey` | 空 | 云端通道 |
| `cloudVoiceId` / `cloudModel` | 空 / `breeze-tts-2` | 云端音色与模型名 |
| `cloudStyle` | `json` | `json` = OpenAI 风格；`form` = breeze-server 原生表单 |
| `cloudGuidanceField` | `guidance_scale` | 有的服务叫 `cfg_scale` |
| `timeoutMs` | `600000` | 单次合成超时 |
| `director.enabled` | `true` | 合成前要不要先过读音导演 |
| `director.transport` | `dsh` | `dsh` = 在 DeepSeek 窗口里的专用会话里想；`api` = 直连模型 API |
| `director.dshBaseUrl` | 自动 | DSH 地址；不填就用 QQ 桥接记着的 `dsh.baseUrl` |
| `director.sessionId` | 自动 | 那个导演窗口的 id，第一次合成时建好写进来；清空 = 下次重开 |
| `director.sessionTitle` | `读音导演 · dsh-voice-say` | 新开会话用的标题（一眼能在 GUI 里认出来） |
| `director.sessionCwd` | 工作区 | 会话的工作目录 |
| `director.sessionTimeoutMs` | `60000` | 在会话里等一轮说完的上限 |
| `director.baseUrl` / `director.model` | `https://ai.xyclub.top/v1` / `deepseek-v4.1-flash` | 走 `api` 通道时用的模型（和 QQ 同一个） |
| `director.apiKey` / `apiKeyEnv` | 空 / `DPSK_API_KEY` | `api` 通道的 key，优先用它，其次环境变量，其次 `~/.dsh/.credentials.yaml` |
| `director.scope` | 自动 | 钉住某个会话的剧情与情绪（`group:xxx` / `private:xxx`） |
| `director.timeoutMs` | `20000` | `api` 通道超时就退回原文照念 |
| `lifeHome` / `emotionHome` / `bridgeState` | 自动探测 | 人设 / 情绪 / 剧情三份数据的目录 |

## HTTP

全部只认本机同源（`127.0.0.1` / `localhost` / `[::1]`）。

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/voice-say/status` | 状态：引擎、音色、云端、导演、默认参数 |
| GET | `/api/voice-say/styles` | 18 个风格 + 当前选中的 |
| GET | `/api/voice-say/direct/context` | 导演手里有什么料（人设 / 情绪 / 剧情），不发模型请求 |
| POST | `/api/voice-say/direct` | 只算标点：`{text,styles,instructions,scope}` |
| POST | `/api/voice-say/direct/cache` | 清掉导演的标点缓存 |
| GET | `/api/voice-say/direct/session` | 看导演窗口开在哪个会话、DSH 是否连得上 |
| POST | `/api/voice-say/direct/session` | `{reset:true}` 清掉会话 id（下次合成自动新开）；`{sessionId}` 指定窗口 |
| POST | `/api/voice-say/config` | 改配置（写进 `config.json`） |
| GET | `/api/voice-say/voices` | 列音色 |
| POST | `/api/voice-say/voices` | 上传音色：`{name,text,description,filename,data}`（`data` 为 base64）或 `{name,text,src}` |
| POST | `/api/voice-say/voices/delete` | `{name}` |
| POST | `/api/voice-say/voices/default` | `{name}` 设成默认音色（空串=取消），QQ 发语音也用它 |
| POST | `/api/voice-say/ref` | 自定义参考音频：`{filename,data}`（base64）或 `{src,text}`；`{clear:true}` 清掉 |
| POST | `/api/voice-say/voice-plan` | 只出「这句怎么念」：`{text,styles,instructions,scope,direct}` → `spoken/instructions/guidanceScale/voice/refAudio` |
| POST | `/api/voice-say/synth` | 合成：`{text,provider,voice,styles,instructions,guidanceScale,seed,direct,scope}` |
| POST | `/api/voice-say/preview` | 试听（同上，`text` 可省） |
| POST | `/api/voice-say/cloud/test` | 云端连通性（真发一次极短合成） |
| GET | `/api/voice-say/audio?name=` | 取回合成出来的音频 |

## 已知限制

- 本地通道每次合成都起一个进程、加载一次模型，第一声比云端慢；连续多句时云端更划算。
- 引擎本身没有语速数值参数，`speed` 之类的硬参数在这里**故意不做**。
- `guidanceScale` 超过 2 之后音质会发毛，只在嗓音明显不听指令时才往上顶。
- 音色目录与 QQ 桥接共用时，这里存好的音色在群里可以直接用。
- 读音导演多花 2~3 秒（一次 `chat/completions`），并且**不生成新内容**：它只分配标点。
  真要改字，是主对话那边的事，不是这里。
- 导演看的是「本机最近一段对话」，如果你要念的台词跟那段剧情无关，把 `director.scope` 钉到对的会话，或者干脆 `direct:false`。

## License

MIT
