16 KiB
16 KiB
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 对话编辑器（表格式）
表格列：
- 序号（支持拖拽手柄）
- 角色选择（下拉菜单）
- 文本输入（文本框，支持多行）
- 指令覆盖（可选，点击展开）
- 状态指示器（pending/processing/completed/failed）
- 操作按钮：
- 删除行
- 单条重试（失败时显示）
- 查看详情
交互特性：
- 支持拖拽排序
- 快捷键：
- 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 音色库工作流程
- 用户创建音色（选择类型，输入参数）
- 系统生成示例音频（用于预览）
- 保存到音色库
- 用户可以预览、编辑、删除音色
- 创建角色时从音色库选择
5.2 角色创建工作流程
- 用户创建角色（输入名称）
- 选择音色（从音色库或预定义）
- 输入默认控制指令
- 设置个性化显示（颜色、头像）
- 设置默认TTS参数（可选）
- 保存角色
5.3 对话编辑和生成工作流程
编辑阶段：
- 创建新对话（输入标题）
- 添加对话行：
- 选择角色
- 输入文本
- 可选：覆盖控制指令
- 可选：覆盖TTS参数
- 拖拽调整顺序
- 实时保存草稿
生成阶段：
顺序生成模式：
- 用户点击"开始生成"
- 系统按序处理每条对话行：
- 标记为 processing
- 调用 TTS API（根据角色配置和覆盖参数）
- 生成音频文件
- 标记为 completed 或 failed
- 实时更新前端进度
- 用户可以：
- 实时查看进度和结果
- 暂停/继续生成
- 取消生成
- 遇到失败项：
- 显示错误信息
- 提示用户选择：重试/跳过/取消
- 全部完成后：
- 显示统计信息（成功/失败）
- 提供"合并音频"选项
批量生成模式：
- 用户点击"批量生成"
- 系统创建后台任务
- 后台按序处理每条对话行
- 遇到失败项自动跳过
- 完成后通知用户
- 用户查看结果，对失败项进行单条重试
5.4 音频合并工作流程
- 生成完成后，用户点击"合并音频"
- 系统读取所有成功的音频片段
- 应用智能间隔策略：
- 根据文本长度计算间隔
- 根据情感变化调整间隔（可选）
- 默认间隔：0.5-1秒
- 拼接所有音频片段
- 保存合并后的完整音频
- 提供下载链接
5.5 错误处理和重试机制
错误类型：
- 文本验证失败
- 模型推理失败
- GPU内存不足
- 音频生成失败
处理策略：
- 显示详细错误信息
- 提供单条重试按钮
- 记录重试次数
- 顺序生成：手动干预（重试/跳过/取消）
- 批量生成：自动跳过失败项，记录错误
5.6 历史记录管理
查看历史：
- 列表显示所有对话项目
- 显示状态、轮数、创建时间
- 支持搜索和筛选
编辑和重新生成：
- 打开历史对话
- 编辑对话行（文本、角色、指令）
- 选择重新生成：
- 单条重新生成
- 全部重新生成
- 从某一行开始重新生成
- 保持已成功的音频，只生成修改的部分
复制为模板：
- 选择已有对话
- 点击"复制为新对话"
- 系统创建新对话，复制所有对话行
- 清除生成状态和音频路径
- 用户可以修改后重新生成
导出功能：
- 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类型定义