# 配置文档

## 1. 多音色管理

### 音色档案

每个档案包含：名称、描述、标签、类型（内置/克隆）、状态（启用/停用）、底层
TTS 音色、样本列表、训练版本、当前版本、最近训练时间、试听记录。

- 新建：管理面板「音色管理 → 新建音色」，或 `voice.profile.create` / `voice_profile_create`。
- 重命名/描述/标签：卡片上的“重命名”，或 `voice.profile.update`。
- 停用：停止该音色被选为默认/临时音色；全局默认不能停用。
- 删除：仅克隆音色可删；会删除样本、版本试听与相关音频。内置音色只能停用。
- 设为默认：必须已训练且启用；全局只有一个默认。

### 样本

- 支持 wav / mp3 / m4a / flac / ogg / opus，单个 ≤ 60MB。
- 上传后自动解码为 24kHz 单声道 WAV，并做质量检测：
  时长、音量、削波、静音比例、F0、谱质心、质量分、问题列表。
- 长音频（>25 秒）默认按静音切片，也可对单条样本点“切片”。
- 追加样本后档案进入“需重新训练”状态；旧版本仍可用。

### 训练与版本

- 训练异步执行；面板 1.5 秒轮询显示 `training.progress/status/error`。
- 每次训练生成不可变版本 `v1`、`v2`……，记录样本 ID、训练时间、模型参数、
  相似度、试听音频。
- 训练使用样本的加权 F0/谱质心/亮度估计音高与音色，样本越多：
  - 转换强度越高（0.48 → 0.96）；
  - 音高/共振峰估计更稳定；
  - 试听相似度通常更高。
- 回滚：版本列表点“回滚”，或 `voice.profile.rollback`；不会删除新版本。
- 训练失败：`training.status=failed`，`training.error` 写入原因；再点训练即可重试。
  训练失败不影响普通对话，也不影响旧版本。

## 2. 按需语音回复（默认）与始终回复

- **默认不自动启动语音**。`autoReply=false`、`intentReply=true`。
- 按需模式：只有用户消息包含“唱/说/语音/朗读/念/翻唱/配音/播报/用某个声音”等明确要求时，
  本轮助手最终文本才会合成语音；其他普通对话不生成语音。
- 如果模型已经调用 `voice.speak` / `voice.cover.run` 并写入了语音，本轮不会再重复生成。
- 「语音设置 → 始终语音回复」对应 `voice.reply.toggle` / `voice_reply_toggle`：
  开启后每条助手最终回复都合成语音；关闭即回到按需模式。
- 语音回复时省略过程：系统提示要求模型不要描述工具名、参数、训练/分离/换声/混音/编码、
  队列、日志或路径；只留一句极简确认或直接让语音出现。
- “自动播放”是客户端行为：新语音消息出现时尝试 `audio.play()`；浏览器策略可能拦截，
  此时播放器保留播放按钮。
- 全局默认切换后，新回复使用新音色；旧消息仍显示生成时的音色名。
- 右键语音播放器 →「转文字」：TTS 回复读取生成时的原始文本（准确）；翻唱/其他音频
  使用 Windows 本地 SAPI 识别（可能不完全准确），结果可复制。

## 3. 情感设置

支持七种情感：平静、开心、温柔、严肃、安慰、兴奋、低落。

| 参数 | 范围 | 说明 |
|---|---|---|
| 情感强度 | 0~1 | 映射到音高、语速、亮度、颤音、停顿的强度 |
| 语速 | 0.75~1.3 | 全局倍率，叠加情感语速 |
| 音量 | 0~1.5 | 映射到 SAPI 音量与后处理增益 |
| 跨轮情绪 | 开/关 | 当前轮没有情感信号时沿用最近 20 分钟的情绪 |
| 默认情感 | 七选一 | 无信号且无跨轮状态时使用 |
| 自动播放 | 开/关 | 对话内是否自动播放新语音 |
| 回复字数上限 | 80~1200 | 自动语音最多朗读的字数，避免超长回复 |

- 情感分析是本地规则 + 标点/表情信号，不调用云端，不重写原文；只改变 TTS 韵律。
- 手动指定：`voice.speak` 的 `emotion`，或试听时的情感标签。
- 重置：设置面板“重置情绪”，或 `voice.settings.update` 的 `reset_emotion: true`。

## 4. 翻唱流程

```text
原唱文件（缓存路径 / URL / 本地上传）
  → ffmpeg 解码 44.1kHz 立体声
  → 人声分离（STFT 中置软掩码，保留左右声道伴奏与低频）
  → 音色转换（音高/共振峰/亮度/颤音，按所选音色模型）
  → 混音（默认清唱+伴奏：主唱 1.45 / 伴奏 1.0；`mode=mix` 时 1.25 / 1.35）
  → 输出 cover.mp3 + cover.wav + preview.mp3
  → 默认直出语音回复到当前会话
```

- 默认音色：全局默认；可在翻唱页临时选择其他已训练音色，不改变全局默认。
- 混音模式：默认 `mode=clean`（清唱+伴奏）——主唱提升、共振峰拉回中性、转换强度上限 0.88，
  原唱人声在伴奏侧完全抵消；`mode=mix` 保留旧版均衡混音。界面/工具不传时也用 clean。
- 整句截取：片段翻唱传 `start_time` / `end_time`（秒），`end_time` 必须落在歌词句末；
  引擎会按该窗口重新截取，不再从预先剪好的片段里二次切割。`end_time` 至少比
  `start_time` 大 0.1 秒；宁可多留 0.1~0.3 秒尾音，也不要切在字中间。
- 音色差异：内置「温柔女声」接近 SAPI 原声，翻唱时会自动 +2.2 半音、提亮共振峰、强度提升到 1，
  避免听起来像原唱；其他档案使用自身模型且强度至少 0.9。想更明显可改用「沉稳男声/明亮少年」。
- 对话显示：语音回复与翻唱统一为微信式语音气泡，按时长自适应宽度；右键可转文字。
- 队列：单 worker 顺序执行；UI 显示排队/阶段/进度/日志。
- 失败：状态 `failed`，`error` + 日志 + 红色提示；点“重试”复用参数创建新任务。
- 导出：任务完成后可导出 MP3/WAV；API `voice.cover.export`。
- 直出：`deliver` 默认 true。翻唱可能在原回合结束后完成，插件会安全地开一个
  新的助手步骤/回合写入会话，刷新后仍可见、可播放。
- 时长/大小限制：服务端不限；如果未来会话层限制，保留 `preview.mp3`（前 20 秒）
  与完整文件导出，直出逻辑不取消。

## 5. 音乐缓存对接

标准入口：

- `POST /plugins/dsh-voice-unified/api/music/bind-cache` `{ "directory": "..." }`
- `voice.music.bindCache` / `voice_music_bind_cache`
- `POST /plugins/dsh-voice-unified/api/music/use-current` `{ "url": "...", "songName": "..." }`
  把音乐插件当前播放流下载到本地缓存。
- `voice.cover.run` 接受：
  - `source_path`：缓存文件绝对路径（优先）
  - `source_url`：音乐插件音频 URL
  - `song_name`：按名称在已扫描缓存中查找

默认扫描目录：

```text
~/.dsh/music-cache
~/.dsh/music/cache
%LOCALAPPDATA%\dsh-music\cache
~/Music/DSH
```

插件会对已存在目录做监听（Windows recursive watch），新文件 0.8 秒内进入索引。
缓存管理面板可查看文件列表并选用。

没有缓存时的提示：
- 完全无缓存：`NO_CACHE_FILE` —— “未找到音乐缓存文件。请先在音乐插件中缓存歌曲，
  或在翻唱页手动选择本地音频。”
- 有缓存但按名称找不到：`CACHE_NOT_FOUND` —— 明确的歌曲名提示。

> 当前 dsh-music 版本多数情况下在浏览器内流式播放、不强制落盘。此时用
> “从音乐插件当前曲目”按钮（`/music/use-current`）把当前流写入本地缓存，或直接
> 上传本地音频；翻唱接口本身按标准路径/URL 接收。

## 6. 直出语音回复设置

- 自动回复：语音设置页开关；`voice.reply.toggle`。
- 自动播放：语音设置页开关；浏览器策略拦截时手动点播放。
- 翻唱直出：翻唱页“完成后直出语音回复”开关；默认开启。
- 手动直出：`voice.speak({deliver:true})` 或 `/api/synthesize`。
- 输出格式：默认 mp3；可在设置中切 wav（改 `replyFormat`）。

## 8. 界面入口与面板拖动

- 已移除左下角可移动的「声音」悬浮图标；不再占用界面。
- 打开方式：
  - 「设置 → 声音」区块里的“打开声音管理面板”；
  - 或快捷键 **Ctrl+Shift+V**（macOS 为 Cmd+Shift+V）。
- 管理面板可按住标题栏拖动；第一次拖动会把居中面板切换为自由浮动，位置写入
  `dsh-voice-unified.panel.pos.v1`。
- 面板标题栏右侧「十字准星」按钮恢复默认位置；双击标题栏空白处也可重置面板位置。
- 拖动后不会触发误点击（4px 阈值）。
- 窄屏（<720px）面板自动全屏，不启用面板拖动。
- 窗口缩放时位置自动夹回可视区域。

## 9. 环境变量

| 变量 | 默认 | 作用 |
|---|---|---|
| `DSH_VOICE_HOME` | `~/.dsh/dsh-voice-unified` | 数据根目录 |
| `DSH_VOICE_PYTHON` | DSH 运行时 Python | DSP 解释器 |
| `DSH_VOICE_FFMPEG` | 插件 `bin/ffmpeg.exe` | ffmpeg 路径 |
| `DSH_VOICE_DOTTED_TOOLS` | 未设置 | 设为 `1` 时额外注册点号工具名；仅限工具名语法允许点号的宿主/提供方 |
| `DSH_PORT` | 51386 | 音乐流本地下载 origin |