# 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类型定义

---