555 lines
16 KiB
Markdown
555 lines
16 KiB
Markdown
# Qwen3-TTS 多人对话功能需求文档
|
||
|
||
## 1. 功能概述
|
||
|
||
在现有 Qwen3-TTS WebUI 基础上，新增多人对话功能，支持音色复用，实现生动自然的多轮次、多角色、长篇章对话生成。
|
||
|
||
## 2. 核心需求
|
||
|
||
### 2.1 音色复用机制
|
||
- 用户可将 Qwen3-TTS 创建的音色进行持久存储
|
||
- 支持重复调用已保存的音色
|
||
- 生成多轮次多角色对话
|
||
- 保持音色的一致性和自然度
|
||
|
||
## 3. 数据模型设计
|
||
|
||
### 3.1 音色库（VoiceLibrary）
|
||
音色库用于持久化存储和管理用户创建的音色。
|
||
|
||
**核心属性：**
|
||
- 音色ID（唯一标识）
|
||
- 音色名称（用户自定义）
|
||
- 音色描述（可选）
|
||
- 音色类型：CustomVoice / VoiceDesign / VoiceClone
|
||
- 音色数据：
|
||
- CustomVoice: speaker名称
|
||
- VoiceDesign: instruct指令
|
||
- VoiceClone: 缓存的x_vector引用
|
||
- 标签/分组（支持多标签）
|
||
- 示例音频路径（用于预览）
|
||
- 创建时间
|
||
- 最后使用时间
|
||
- 使用次数统计
|
||
- 用户ID（用户隔离）
|
||
|
||
**功能要求：**
|
||
- 基础CRUD操作（创建、读取、更新、删除）
|
||
- 音色预览：生成并播放示例音频
|
||
- 标签/分组管理：支持按标签筛选和搜索
|
||
- 支持批量操作（批量删除、批量导出）
|
||
|
||
### 3.2 角色（Character）
|
||
角色代表对话中的发言人，绑定音色和控制指令。
|
||
|
||
**核心属性：**
|
||
- 角色ID
|
||
- 角色名称
|
||
- 绑定音色（引用音色库ID 或 使用预定义音色）
|
||
- 默认控制指令（instruct）
|
||
- 角色描述/标签
|
||
- 个性化显示：
|
||
- 头像/图标
|
||
- 颜色标记（用于在对话中区分）
|
||
- 默认TTS参数：
|
||
- language
|
||
- max_new_tokens
|
||
- temperature
|
||
- top_k
|
||
- top_p
|
||
- repetition_penalty
|
||
- 创建时间
|
||
- 最后使用时间
|
||
- 用户ID（用户隔离）
|
||
|
||
**功能要求：**
|
||
- 基础CRUD操作
|
||
- 快速创建（从音色库选择音色）
|
||
- 删除前检查：如果角色被对话使用，需提示确认
|
||
- 支持预览：使用角色设置生成示例音频
|
||
|
||
### 3.3 对话项目（Dialogue）
|
||
对话项目是多轮对话的容器。
|
||
|
||
**核心属性：**
|
||
- 对话ID
|
||
- 对话标题
|
||
- 对话状态：
|
||
- draft（草稿）
|
||
- generating（生成中）
|
||
- completed（已完成）
|
||
- failed（失败）
|
||
- partial（部分成功）
|
||
- 生成模式：
|
||
- sequential（顺序生成）
|
||
- batch（批量生成）
|
||
- 音频合并配置：
|
||
- 是否自动合并
|
||
- 间隔策略：intelligent（智能间隔）
|
||
- 合并后的音频路径
|
||
- 对话轮数统计
|
||
- 成功/失败数量统计
|
||
- 创建时间
|
||
- 更新时间
|
||
- 完成时间
|
||
- 用户ID（用户隔离）
|
||
|
||
**功能要求：**
|
||
- 创建新对话
|
||
- 编辑对话（标题、设置）
|
||
- 删除对话（级联删除所有对话行）
|
||
- 复制对话（作为模板）
|
||
- 导出对话：
|
||
- JSON格式（完整数据）
|
||
- CSV格式（角色、文本、指令）
|
||
- SRT字幕格式（时间轴 + 文本）
|
||
- 音频文件（分段或合并）
|
||
|
||
### 3.4 对话行（DialogueLine）
|
||
对话行是单条对话内容。
|
||
|
||
**核心属性：**
|
||
- 对话行ID
|
||
- 所属对话ID（外键）
|
||
- 排序序号（支持拖拽调整）
|
||
- 关联角色ID（外键）
|
||
- 文本内容（1-1000字符）
|
||
- 控制指令覆盖（可选，覆盖角色默认指令）
|
||
- TTS参数覆盖（可选）：
|
||
- language
|
||
- max_new_tokens
|
||
- temperature
|
||
- top_k
|
||
- top_p
|
||
- repetition_penalty
|
||
- 生成状态：
|
||
- pending（待生成）
|
||
- processing（生成中）
|
||
- completed（已完成）
|
||
- failed（失败）
|
||
- 输出音频路径
|
||
- 音频时长（秒）
|
||
- 错误信息
|
||
- 重试次数
|
||
- 创建时间
|
||
- 完成时间
|
||
|
||
**功能要求：**
|
||
- 添加对话行
|
||
- 编辑对话行（文本、角色、指令）
|
||
- 删除对话行
|
||
- 拖拽排序
|
||
- 单条重试（失败时）
|
||
- 查看详细错误信息
|
||
|
||
## 4. 用户界面设计
|
||
|
||
### 4.1 页面布局
|
||
**独立页面**：`/dialogues` 路由
|
||
|
||
**整体布局：**
|
||
```
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ Navbar (全局导航) │
|
||
├─────────────────┬─────────────────────┬──────────────────┤
|
||
│ 左侧边栏 │ 中间主内容区 │ 右侧面板(可折叠) │
|
||
│ - 对话历史列表 │ - 对话编辑器 │ - 角色管理 │
|
||
│ - 新建对话按钮 │ - 表格式编辑 │ - 音色库管理 │
|
||
│ - 搜索/筛选 │ - 生成控制面板 │ │
|
||
│ │ - 音频播放器 │ │
|
||
└─────────────────┴─────────────────────┴──────────────────┘
|
||
```
|
||
|
||
### 4.2 对话编辑器（表格式）
|
||
**表格列：**
|
||
1. 序号（支持拖拽手柄）
|
||
2. 角色选择（下拉菜单）
|
||
3. 文本输入（文本框，支持多行）
|
||
4. 指令覆盖（可选，点击展开）
|
||
5. 状态指示器（pending/processing/completed/failed）
|
||
6. 操作按钮：
|
||
- 删除行
|
||
- 单条重试（失败时显示）
|
||
- 查看详情
|
||
|
||
**交互特性：**
|
||
- 支持拖拽排序
|
||
- 快捷键：
|
||
- Enter: 添加新行
|
||
- Ctrl+D: 删除当前行
|
||
- Ctrl+↑/↓: 上下移动行
|
||
- 实时保存（防丢失）
|
||
|
||
### 4.3 生成控制面板
|
||
**生成模式选择：**
|
||
- 顺序生成：按序生成，实时显示进度
|
||
- 批量生成：一次性提交，后台处理
|
||
|
||
**生成控制按钮：**
|
||
- 开始生成
|
||
- 暂停/继续（顺序模式）
|
||
- 取消生成
|
||
- 合并音频（生成完成后）
|
||
|
||
**进度显示：**
|
||
- 总体进度条
|
||
- 当前生成的对话行高亮
|
||
- 成功/失败数量统计
|
||
- 预计剩余时间（顺序模式）
|
||
|
||
### 4.4 音色库管理界面
|
||
**列表视图：**
|
||
- 卡片式布局
|
||
- 显示：名称、类型、标签、创建时间
|
||
- 操作：编辑、删除、预览、复制
|
||
|
||
**创建/编辑表单：**
|
||
- 音色名称（必填）
|
||
- 音色类型选择（CustomVoice/VoiceDesign/VoiceClone）
|
||
- 类型特定参数：
|
||
- CustomVoice: 选择speaker
|
||
- VoiceDesign: 输入instruct
|
||
- VoiceClone: 上传参考音频
|
||
- 音色描述（可选）
|
||
- 标签（多选或自定义）
|
||
- 生成示例音频（用于预览）
|
||
|
||
**预览功能：**
|
||
- 点击预览按钮，使用默认文本生成示例音频
|
||
- 播放示例音频
|
||
|
||
### 4.5 角色管理界面
|
||
**列表视图：**
|
||
- 表格或卡片式
|
||
- 显示：头像/颜色、名称、绑定音色、标签
|
||
- 操作：编辑、删除、预览
|
||
|
||
**创建/编辑表单：**
|
||
- 角色名称（必填）
|
||
- 选择音色（从音色库或预定义）
|
||
- 默认控制指令（多行文本框）
|
||
- 个性化显示：
|
||
- 颜色选择器
|
||
- 头像上传（可选）
|
||
- 默认TTS参数（高级选项，可折叠）
|
||
- 角色描述/标签
|
||
|
||
### 4.6 对话历史列表
|
||
**显示内容：**
|
||
- 对话标题
|
||
- 状态标签（draft/generating/completed/failed/partial）
|
||
- 对话轮数
|
||
- 创建时间
|
||
- 最后更新时间
|
||
|
||
**操作：**
|
||
- 打开编辑
|
||
- 复制为新对话
|
||
- 导出
|
||
- 删除
|
||
|
||
**筛选和搜索：**
|
||
- 按状态筛选
|
||
- 按创建时间排序
|
||
- 关键词搜索（标题）
|
||
|
||
## 5. 核心功能流程
|
||
|
||
### 5.1 音色库工作流程
|
||
1. 用户创建音色（选择类型，输入参数）
|
||
2. 系统生成示例音频（用于预览）
|
||
3. 保存到音色库
|
||
4. 用户可以预览、编辑、删除音色
|
||
5. 创建角色时从音色库选择
|
||
|
||
### 5.2 角色创建工作流程
|
||
1. 用户创建角色（输入名称）
|
||
2. 选择音色（从音色库或预定义）
|
||
3. 输入默认控制指令
|
||
4. 设置个性化显示（颜色、头像）
|
||
5. 设置默认TTS参数（可选）
|
||
6. 保存角色
|
||
|
||
### 5.3 对话编辑和生成工作流程
|
||
|
||
**编辑阶段：**
|
||
1. 创建新对话（输入标题）
|
||
2. 添加对话行：
|
||
- 选择角色
|
||
- 输入文本
|
||
- 可选：覆盖控制指令
|
||
- 可选：覆盖TTS参数
|
||
3. 拖拽调整顺序
|
||
4. 实时保存草稿
|
||
|
||
**生成阶段：**
|
||
|
||
**顺序生成模式：**
|
||
1. 用户点击"开始生成"
|
||
2. 系统按序处理每条对话行：
|
||
- 标记为 processing
|
||
- 调用 TTS API（根据角色配置和覆盖参数）
|
||
- 生成音频文件
|
||
- 标记为 completed 或 failed
|
||
- 实时更新前端进度
|
||
3. 用户可以：
|
||
- 实时查看进度和结果
|
||
- 暂停/继续生成
|
||
- 取消生成
|
||
4. 遇到失败项：
|
||
- 显示错误信息
|
||
- 提示用户选择：重试/跳过/取消
|
||
5. 全部完成后：
|
||
- 显示统计信息（成功/失败）
|
||
- 提供"合并音频"选项
|
||
|
||
**批量生成模式：**
|
||
1. 用户点击"批量生成"
|
||
2. 系统创建后台任务
|
||
3. 后台按序处理每条对话行
|
||
4. 遇到失败项自动跳过
|
||
5. 完成后通知用户
|
||
6. 用户查看结果，对失败项进行单条重试
|
||
|
||
### 5.4 音频合并工作流程
|
||
1. 生成完成后，用户点击"合并音频"
|
||
2. 系统读取所有成功的音频片段
|
||
3. 应用智能间隔策略：
|
||
- 根据文本长度计算间隔
|
||
- 根据情感变化调整间隔（可选）
|
||
- 默认间隔：0.5-1秒
|
||
4. 拼接所有音频片段
|
||
5. 保存合并后的完整音频
|
||
6. 提供下载链接
|
||
|
||
### 5.5 错误处理和重试机制
|
||
**错误类型：**
|
||
- 文本验证失败
|
||
- 模型推理失败
|
||
- GPU内存不足
|
||
- 音频生成失败
|
||
|
||
**处理策略：**
|
||
1. 显示详细错误信息
|
||
2. 提供单条重试按钮
|
||
3. 记录重试次数
|
||
4. 顺序生成：手动干预（重试/跳过/取消）
|
||
5. 批量生成：自动跳过失败项，记录错误
|
||
|
||
### 5.6 历史记录管理
|
||
**查看历史：**
|
||
- 列表显示所有对话项目
|
||
- 显示状态、轮数、创建时间
|
||
- 支持搜索和筛选
|
||
|
||
**编辑和重新生成：**
|
||
1. 打开历史对话
|
||
2. 编辑对话行（文本、角色、指令）
|
||
3. 选择重新生成：
|
||
- 单条重新生成
|
||
- 全部重新生成
|
||
- 从某一行开始重新生成
|
||
4. 保持已成功的音频，只生成修改的部分
|
||
|
||
**复制为模板：**
|
||
1. 选择已有对话
|
||
2. 点击"复制为新对话"
|
||
3. 系统创建新对话，复制所有对话行
|
||
4. 清除生成状态和音频路径
|
||
5. 用户可以修改后重新生成
|
||
|
||
**导出功能：**
|
||
- JSON格式：完整数据（角色、文本、指令、参数）
|
||
- CSV格式：角色,文本,指令（用于批量导入）
|
||
- SRT字幕格式：时间轴 + 角色 + 文本
|
||
- 音频文件：打包所有音频（分段或合并）
|
||
|
||
## 6. 技术规格
|
||
|
||
### 6.1 数据权限
|
||
- 所有数据（音色库、角色、对话）按用户隔离
|
||
- 每个用户只能访问自己创建的数据
|
||
- 与现有 Job 系统的权限模型保持一致
|
||
|
||
### 6.2 性能限制
|
||
- 单个对话支持 1-200 轮对话
|
||
- 音频文件命名：`dialogue_{dialogue_id}_line_{line_id}_{timestamp}.wav`
|
||
- 合并音频命名：`dialogue_{dialogue_id}_merged_{timestamp}.wav`
|
||
- 存储路径：`./outputs/dialogues/`
|
||
|
||
### 6.3 音频处理
|
||
**智能间隔计算：**
|
||
```
|
||
基础间隔：0.5秒
|
||
调整因子：
|
||
- 短文本（<20字符）：-0.2秒
|
||
- 长文本（>100字符）：+0.3秒
|
||
- 同一角色连续对话：-0.1秒
|
||
- 不同角色切换：+0.1秒
|
||
- 最小间隔：0.3秒
|
||
- 最大间隔：2.0秒
|
||
```
|
||
|
||
**音频拼接：**
|
||
- 使用 pydub 或 ffmpeg
|
||
- 保持采样率一致（24000 Hz）
|
||
- 无缝拼接（避免爆音）
|
||
|
||
### 6.4 并发控制
|
||
- 同一用户同时只能有一个对话在生成中
|
||
- 顺序生成：支持暂停/继续/取消
|
||
- 批量生成：后台异步处理，不阻塞前端
|
||
|
||
### 6.5 缓存机制
|
||
- 复用现有的 VoiceCacheManager
|
||
- 对于 VoiceClone 类型的音色，缓存 x_vector
|
||
- 减少重复的特征提取操作
|
||
|
||
## 7. 用户示例参考
|
||
|
||
用户提供的对话示例格式：
|
||
|
||
**角色定义（控制指令）：**
|
||
```
|
||
"旁白": "声音特征沉稳、客观、略带叙事感的女播音腔，普通话标准，语速适中，带有轻微的环境氛围渲染，语调平缓但富有感染力，在关键情节时稍作停顿，增强画面感。情感冷静旁观，偶尔带一丝微妙的反讽"
|
||
|
||
"小林": "25岁男性上班族，声音清亮但时常犹豫，语速时快时慢，紧张时会轻微结巴。情绪波动明显，从低声呢喃到突然激动再到自我怀疑的叹气。肢体语言丰富，经常无意识的小动作"
|
||
|
||
"御姐": "模拟成熟性感的御姐音色，声音略带磁性且沉稳，语速不快不慢，语调充满自信和一丝挑逗，尾音可以稍微拖长并上扬，给人一种游刃有余的掌控感。"
|
||
```
|
||
|
||
**对话格式：**
|
||
```
|
||
旁白: 小林今天第三次走神了。酒吧昏黄的灯光晃得他心跳加速，而吧台对面那个红唇微扬的女人，正用指尖轻轻摩挲着酒杯边缘。
|
||
御姐: 小弟弟，有兴趣陪姐姐喝一杯吗？
|
||
小林: 啊？我、我……我其实不太会喝酒……
|
||
旁白: 他的手指无意识地抠着杯沿，喉结上下滚动，像被什么无形的东西掐住了呼吸。
|
||
御姐: 不会喝？那正好——姐姐教你。这杯莫吉托，甜得刚好，就像你刚才偷看我的眼神。
|
||
小林: 我、我没偷看！……好吧，看了一眼。就一眼！
|
||
...
|
||
```
|
||
|
||
**系统支持：**
|
||
- 用户可以导入此类格式的文本（纯文本解析）
|
||
- 系统自动识别角色名和对话内容
|
||
- 自动创建角色（如果不存在）
|
||
- 生成对话行
|
||
|
||
## 8. 非功能性需求
|
||
|
||
### 8.1 性能要求
|
||
- 对话列表加载时间 < 1秒
|
||
- 单条对话生成平均时间：根据模型推理速度
|
||
- 音频合并时间 < 5秒（200条以内）
|
||
- 支持 1000+ 对话项目不卡顿
|
||
|
||
### 8.2 可用性要求
|
||
- 直观的表格编辑界面
|
||
- 实时保存，防止数据丢失
|
||
- 清晰的状态指示和错误提示
|
||
- 支持键盘快捷键
|
||
- 响应式设计，支持大屏编辑
|
||
|
||
### 8.3 可扩展性
|
||
- 未来支持更多生成模式（并行生成）
|
||
- 支持更多导出格式
|
||
- 支持批量导入对话脚本
|
||
- 支持对话版本控制（可选）
|
||
|
||
### 8.4 兼容性
|
||
- 与现有系统无缝集成
|
||
- 复用现有认证、任务队列、缓存机制
|
||
- 不影响现有功能
|
||
|
||
## 9. 实现优先级
|
||
|
||
### 9.1 必需功能（首期实现）
|
||
- [ ] 音色库基础CRUD
|
||
- [ ] 角色管理（创建、编辑、删除）
|
||
- [ ] 对话编辑器（表格式，拖拽排序）
|
||
- [ ] 顺序生成 + 实时进度显示
|
||
- [ ] 分段音频生成
|
||
- [ ] 音频合并（智能间隔）
|
||
- [ ] 对话历史列表
|
||
- [ ] 单条重试机制
|
||
- [ ] 错误显示和手动干预
|
||
|
||
### 9.2 重要功能（后续补充）
|
||
- [ ] 批量生成模式
|
||
- [ ] 音色预览功能
|
||
- [ ] 标签/分组管理
|
||
- [ ] 编辑和重新生成
|
||
- [ ] 复制为模板
|
||
- [ ] 导出功能（JSON/CSV/SRT）
|
||
|
||
### 9.3 可选功能（未来扩展）
|
||
- [ ] 纯文本导入解析
|
||
- [ ] 内置对话模板
|
||
- [ ] 批量导入对话
|
||
- [ ] 对话版本控制
|
||
- [ ] 音色分享功能
|
||
- [ ] 协作编辑
|
||
|
||
## 10. 验收标准
|
||
|
||
### 10.1 功能验收
|
||
- [ ] 用户可以创建和管理音色库
|
||
- [ ] 用户可以创建和管理角色
|
||
- [ ] 用户可以使用表格编辑器创建对话
|
||
- [ ] 用户可以选择顺序生成模式，实时查看进度
|
||
- [ ] 系统能够正确处理失败项（显示错误、支持重试）
|
||
- [ ] 用户可以合并音频，生成完整对话音频
|
||
- [ ] 用户可以查看历史对话，并进行编辑/重生成
|
||
- [ ] 所有数据按用户隔离，权限正确
|
||
|
||
### 10.2 性能验收
|
||
- [ ] 支持至少 200 轮对话的编辑和生成
|
||
- [ ] 对话列表加载流畅（< 1秒）
|
||
- [ ] 音频合并速度快（< 5秒）
|
||
|
||
### 10.3 用户体验验收
|
||
- [ ] 界面直观，易于操作
|
||
- [ ] 实时保存，数据不丢失
|
||
- [ ] 错误提示清晰，易于理解
|
||
- [ ] 支持键盘快捷键，提高效率
|
||
|
||
## 11. 项目背景信息
|
||
|
||
### 11.1 现有架构
|
||
- 前端：React 19 + TypeScript + Vite + Tailwind CSS + Shadcn/ui
|
||
- 后端：FastAPI + SQLAlchemy + SQLite
|
||
- 认证：JWT
|
||
- 任务处理：FastAPI BackgroundTasks + APScheduler
|
||
|
||
### 11.2 现有数据模型
|
||
- User（用户）
|
||
- Job（任务）
|
||
- VoiceCache（音色缓存）
|
||
|
||
### 11.3 现有功能
|
||
- CustomVoice：使用预定义音色合成
|
||
- VoiceDesign：使用风格描述合成
|
||
- VoiceClone：克隆参考音色合成
|
||
- 用户管理（超管功能）
|
||
- 任务历史记录
|
||
- 音色缓存管理
|
||
|
||
### 11.4 主要文件路径
|
||
**后端：**
|
||
- `/home/bdim/Documents/github/Qwen3-TTS/qwen3-tts-backend/`
|
||
- `main.py` - 应用入口
|
||
- `db/models.py` - 数据模型
|
||
- `db/crud.py` - 数据库操作
|
||
- `api/` - API路由
|
||
- `core/` - 核心功能模块
|
||
|
||
**前端：**
|
||
- `/home/bdim/Documents/github/Qwen3-TTS/qwen3-tts-frontend/`
|
||
- `src/pages/` - 页面组件
|
||
- `src/components/` - 可复用组件
|
||
- `src/contexts/` - 状态管理
|
||
- `src/lib/api.ts` - API客户端
|
||
- `src/types/` - TypeScript类型定义
|
||
|
||
---
|