# KING--WANGCHAO

**Repository Path**: software-engineering-pre-project/king--wangchao

## Basic Information

- **Project Name**: KING--WANGCHAO
- **Description**: 重构tts文字转语音系统

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-28
- **Last Updated**: 2025-11-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 Coqui TTS 的中文真人化语音合成服务

支持真人化语音生成与流式播放状态监控。

## 快速开始

### 启动服务

```bash
# 克隆项目
git clone <your-repo>
cd ChineseTTS

# 使用 uv 安装依赖
uv sync

# 启动 TTS 服务
python -m ChineseTTS.main
```

服务运行在 `http://localhost:30704`，访问 `/docs` 查看 API 文档。

## API 接口

### 📡 SSE 流式状态监控

**URL:** `GET /stream/status/{session_id}`

建立 SSE 连接接收实时播放进度。

**事件格式（与 llm_chat 统一）**

| 事件   | 数据格式                                                                 | 说明                           |
|--------|--------------------------------------------------------------------------|--------------------------------|
| start  | `{"status": "connected", "timestamp": str, "session_id": str}`           | 连接建立                       |
| message| `{"type": "playing/completed", "progress": str, "timestamp": str, "session_id": str}` | 播放状态                       |
| ping   | `{"status": "ping", "timestamp": str, "session_id": str}`                | 心跳（5 秒）                  |
| end    | `{"status": "completed", "timestamp": str, "session_id": str}`           | 会话结束                       |
| error  | `{"code": int, "message": str, "timestamp": str, "session_id": str}`     | 错误                           |

> ⚠️ `message` 事件类型（重要）

- `type: "playing"`：语音播放中（实时进度，如 “第 1/2 段”）
  - 用于实时显示给用户，不要发送给其他模块
- `type: "completed"`：语音播放完成（最终状态）✅
  - 语音合成 + 播放的完整结果，这个才是要反馈给其他模块的内容

### 🎤 触发语音合成

**开始合成**

**URL:** `POST /tts/trigger/{session_id}`

**请求体:**
```json
{
  "text": "需要转换的中文文本"
}
```

## 前端调用流程

### 初始化阶段

1. 生成唯一 `session_id`（使用 `crypto.randomUUID()` 或 `uuid` 库）
2. 建立 SSE 连接：`GET /stream/status/{session_id}`
3. 监听 `start` 事件确认连接成功

### 合成播放阶段

用户输入文本并提交  
↓  
调用 `POST /tts/trigger/{session_id}`（携带文本）  
↓  
语音合成中  
↓  
收到 `type: "playing"` 事件 → 实时显示播放进度（灰色 / 提示状态）  
↓  
语音播放完成  
↓  
收到 `type: "completed"` 事件 → 显示播放完成状态（黑色 / 确认状态）

### 调用其他模块阶段

收到 `type: "completed"` 事件  
↓  
确认语音播放完成  
↓  
调用其他服务（如内容分发）  
```json
{
  "content": "合成的语音内容描述",
  "thread_id": session_id  // 使用同一个 ID
}
```
↓  
接收其他服务响应 → 执行后续逻辑

## 关键要点

✅ **DO（应该做的）**

- 只在收到 `type: "completed"` 时反馈结果给其他模块
- 使用同一个 `session_id`
  - TTS 的 `session_id` = 其他模块的 `thread_id`，方便追踪完整流程
- 区分显示状态
  - `playing`：灰色 / 虚化显示（实时进度反馈）
  - `completed`：黑色 / 加粗显示（确认完成状态）

❌ **DON'T（不应该做的）**

- 不要发送 `type: "playing"` 给其他模块
- 不要忽略 `completed` 事件
  - `playing` 只是过程，`completed` 才是合成 + 播放的最终状态

## 数据流向图

用户输入文本  
↓  
TTS 服务  
↓  
`playing` 事件（实时进度，无结果） → 前端显示（灰色）  
↓  
`completed` 事件（播放完成，最终状态） → 前端显示（黑色）  
↓  
↓  
确认合成完成  
↓  
其他业务模块  
↓  
后续业务逻辑

## 事件处理伪代码

```javascript
// 1. 建立 SSE 连接
eventSource = new EventSource(`/stream/status/${session_id}`)

// 2. 监听 message 事件
eventSource.addEventListener('message', (event) => {
    const data = JSON.parse(event.data)
    
    if (data.type === 'playing') {
        // 实时显示播放进度（灰色）
        showProgressText(data.progress)
    }
    else if (data.type === 'completed') {
        // 显示播放完成状态（黑色）
        showCompletedStatus(data.progress)
        
        // ✅ 调用其他业务模块
        callOtherService({
            content: "语音合成完成",
            thread_id: session_id
        })
    }
})

// 3. 触发 TTS 合成
function onSubmitText(text) {
    fetch(`/tts/trigger/${session_id}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text })
    })
}
```

## 与其他模块的对接

### TTS 的 completed 输出

```json
{
  "type": "completed",
  "progress": "第2/2段",
  "timestamp": "2025-11-22T15:30:00",
  "session_id": "def-456"
}
```

发送给其他模块（如业务分发服务）

```bash
POST /service/distribute
Content-Type: application/json

{
  "content": "语音合成已完成",
  "thread_id": "def-456"  // ← 同一个 session_id
}
```

## 测试

### 后端测试

```bash
# 使用测试客户端
uv run python -m ChineseTTS.client
```

### 前端测试流程

1. 输入测试文本并提交
2. 观察实时进度显示（`playing` 状态）
3. 等待播放完成，确认显示 `completed` 状态
4. 验证其他模块收到了完成通知

## 常见问题

**Q: 什么时候调用其他业务模块？**  
A: 收到 `type: "completed"` 的 `message` 事件时。

**Q: `playing` 事件有什么用？**  
A: 给用户实时反馈，让用户知道语音正在合成 / 播放。不发送给其他模块。

**Q: 多次合成怎么处理？**  
A:
第一次合成 → `completed1` → 发给其他模块（`thread_id: xxx`）  
第二次合成 → `completed2` → 发给其他模块（`thread_id: xxx`）  
使用同一个 `thread_id`，其他模块会关联同一会话的操作。

**Q: 如何判断语音合成完成？**  
A: 收到 `type: "completed"` 事件就代表本次语音合成 + 播放已完成。

## 技术支持

- TTS 模块问题：联系后端同学
- 其他模块集成：参考对应模块的 README
- 问题反馈：提 Issue 或联系开发团队