# 3D 数字人语音聊天系统

这个项目提供一个浏览器侧渲染的 3D 数字人语音交互原型：

- 浏览器通过 WebRTC 上传麦克风音频，并接收服务端回传的 AI 语音。
- 浏览器通过 WebSocket 订阅字幕和口型/头部控制数据。
- 服务端执行 VAD -> ASR -> DeepSeek LLM -> TTS，并把音频特征转换为驱动 3D 数字人的控制帧。

当前形态更接近单机演示和研发验证环境，不是已经拆分完毕的生产化架构。

## 当前架构

语音链路：

```text
Browser Mic
  -> WebRTC audio upstream
  -> FastAPI / aiortc
  -> VAD
  -> ASR
  -> LLM
  -> TTS
  -> WebRTC audio downstream
  -> browser audio playback
```

控制链路：

```text
LLM reply text / TTS audio
  -> AvatarService
  -> /ws/animation
  -> browser animation buffer
  -> VRM or GLTF morph targets / head bones
```

字幕链路：

```text
ASR text / LLM segmented reply
  -> /ws/subtitles
  -> browser message panel
```

## 关键目录

- [main.py](main.py): FastAPI 入口，聚合 WebRTC、WebSocket、健康状态和文本对话接口。
- [core/pipeline.py](core/pipeline.py): 语音/文本对话流水线，负责 ASR、LLM、TTS 编排。
- [core/state_machine.py](core/state_machine.py): 简单会话状态机，处理用户说话、思考、数字人说话之间的切换。
- [services/asr.py](services/asr.py): ASR 封装，优先使用 FunASR，失败时进入降级模式。
- [services/llm.py](services/llm.py): 在线 LLM 封装，默认兼容 DeepSeek OpenAI-style API。
- [services/tts.py](services/tts.py): TTS 封装，优先使用 Kokoro，失败时返回静音兜底。
- [services/vad.py](services/vad.py): VAD 封装，基于 silero-vad。
- [services/avatar.py](services/avatar.py): 把音频转换成 blendshape 和头部控制帧。
- [web/app.js](web/app.js): 浏览器端 3D 舞台、WebRTC 建连、字幕和动画消费逻辑。
- [scripts](scripts): 启动、证书生成、巡检和服务管理脚本。

## 快速启动

安装依赖：

```bash
pip install -r requirements.txt
```

准备环境变量，至少包括：

```bash
export LLM_API_KEY="..."
export LLM_BASE_URL="https://api.deepseek.com/v1"
export LLM_MODEL="deepseek-chat"
```

本地启动：

```bash
python main.py
```

或使用脚本：

```bash
bash scripts/start-public.sh
```

启动后访问：

- `http://127.0.0.1:8080/`
- `http://127.0.0.1:8080/health`

如果浏览器与服务端跨机器访问，麦克风采集通常需要 HTTPS。可以先生成自签证书：

```bash
bash scripts/gen-self-signed-cert.sh
```

再在环境变量或 `.env` 中配置 `SSL_CERTFILE` 和 `SSL_KEYFILE`。

## 核心接口

- `GET /`: 前端页面。
- `POST /webrtc/offer`: 建立 WebRTC 音频连接。
- `POST /chat/text`: 文本输入链路，跳过 ASR/VAD。
- `POST /chat/reset`: 清空上下文和运行时状态。
- `GET /health`: 返回后端运行指标和组件健康状态。
- `GET /meta`: 返回 STUN、HTTPS、端口和动画协议配置。
- `GET /events`: Server-Sent Events 运行状态流。
- `WS /ws/subtitles`: 字幕流。
- `WS /ws/animation`: 数字人控制流。
- `GET /avatar/schema`: 当前控制协议 schema。

## 后续开发建议

优先阅读 [docs/development-guide.md](docs/development-guide.md)。这个文档说明了：

- 语音与文本两条链路的完整时序。
- 前后端之间的协议约定。
- 当前实现的边界和适合继续扩展的位置。
- 已知的工程化约束。