说明文档
Speech-X
一个仓库中包含两种模式 — 共享相同的 conda 环境、模型和 LiveKit 服务器。
| 页面 | 模式 | 功能说明 |
|---|---|---|
/ |
数字人 | 文本/语音 → Kokoro TTS → MuseTalk 唇形同步 → LiveKit 视频 |
/voice |
语音代理 | 语音 → faster-whisper → Llama → Kokoro TTS → LiveKit 音频 |
系统架构
浏览器 (React + LiveKit SDK)
│
├── / → FastAPI 服务器 (端口 8767) → Kokoro TTS + MuseTalk + LiveKit 发布者
└── /voice → LiveKit Agent 工作进程 → ASR → LLM → TTS + Token 服务器 (端口 3000)
共享基础设施 (始终运行):
┌─────────────────────────────────────────────────────────────────────┐
│ LiveKit 服务器 :7880 │ llama-server :8080 │ Vite 开发服务器 :5173 │
└─────────────────────────────────────────────────────────────────────┘
前置条件
- NVIDIA GPU (RTX 4060 8GB 或更高配置)
- Conda
- Docker
- Node.js 18+
- llama.cpp —
llama-server需在 PATH 中
环境配置
完整的分步指南请参阅
setup/setup.md,或运行自动化脚本:bash setup/setup.sh # Linux / macOS .\setup\setup.ps1 # Windows (PowerShell)
恢复 conda 环境
# 在仓库根目录执行
conda env create -f environment.yml
conda activate avatar
前端依赖
cd frontend
npm install
运行方式
四个进程需同时运行。请打开四个终端窗口。
终端 1 — LiveKit 服务器 (Docker,两个页面共用)
docker run --rm -d \
--name livekit-server \
-p 7880:7880 -p 7881:7881 -p 7882:7882/udp \
livekit/livekit-server:latest \
--dev --bind 0.0.0.0 --node-ip 127.0.0.1
稍后停止服务:
docker stop livekit-server
终端 2 — llama-server (两个页面共用)
llama-server \
-m backend/models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
-c 2048 -ngl 32 --port 8080
终端 3 — 后端 (根据所需页面选择)
用于 / (数字人页面 — MuseTalk 唇形同步):
conda activate avatar
cd backend
python api/server.py
# 运行在 http://localhost:8767
用于 /voice (语音代理页面 — ASR → LLM → TTS):
conda activate avatar
cd backend
python agent.py dev
# Token 服务器运行在 http://localhost:3000
# LiveKit 工作进程连接到 ws://localhost:7880
如需同时使用两个页面,可在不同终端中同时运行两个服务。
终端 4 — 前端
cd frontend
npm run dev
# 打开 http://localhost:5173
http://localhost:5173/— 数字人唇形同步页面http://localhost:5173/voice— 语音代理页面
数字人形象
预置三个已预计算的数字人形象:sophy (默认)、harry_1、christine。
如需创建新形象,在激活 avatar 环境后,从仓库根目录运行一次 setup/avatar_creation.py:
conda activate avatar
# 从肖像图片创建 (复制为 50 帧)
python setup/avatar_creation.py --image frontend/public/Sophy.png --name sophy
# 从说话头像视频创建
python setup/avatar_creation.py --video /path/to/talking_head.mp4 --name harry_1
# 批量创建 — 先编辑 setup/avatars_config.yml
python setup/avatar_creation.py --config setup/avatars_config.yml
输出文件写入 backend/avatars/<name>/:latents.pt、coords.pkl、mask_coords.pkl、full_imgs/、mask/、avator_info.json。
运行时切换数字人形象:
SPEECHX_AVATAR=harry_1 python api/server.py
| 参数 | 默认值 | 说明 |
|---|---|---|
--name |
必填 | 数字人文件夹名称 |
--frames |
50 |
--image 模式的帧数 |
--bbox-shift |
5 |
垂直边界框偏移 (如裁剪不准可调整) |
--device |
cuda |
cuda 或 cpu |
--overwrite |
关闭 | 跳过重新创建确认提示 |
环境变量
复制并根据需要调整 (两个后端都会从 shell 环境变量或 backend/ 目录下的 .env 文件读取):
# LiveKit
LIVEKIT_URL=ws://localhost:7880
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret
# llama-server
LLAMA_SERVER_URL=http://localhost:8080/v1
# TTS 音色 (语音代理页面)
DEFAULT_VOICE=af_sarah # 查看 backend/agent/config.py 获取所有选项
# ASR 模型大小 (语音代理页面)
ASR_MODEL_SIZE=tiny # tiny | base | small
# 数字人页面服务器
SPEECH_TO_VIDEO_HOST=0.0.0.0
SPEECH_TO_VIDEO_PORT=8767
项目结构
speech_to_video/
├── environment.yml # Conda 环境导出 (跨平台,无构建字符串)
├── README.md
├── setup/
│ ├── setup.md # 分步安装指南
│ ├── setup.sh # 自动化安装脚本
│ └── setup.ps1 # 自动化安装脚本
├── docs/
│ ├── avatar_gen_README.md # 语音代理架构说明
│ └── avatar_gen_phase_2.md# MuseTalk 集成第二阶段计划
├── backend/
│ ├── config.py # 数字人页面配置
│ ├── requirements.txt # Pip 依赖 (在 conda 环境内安装)
│ ├── api/
│ │ ├── server.py # 数字人页面 FastAPI 服务器 (:8767)
│ │ └── pipeline.py # MuseTalk 流程编排器
│ ├── agent.py # 语音页面 LiveKit 工作进程入口
│ ├── agent/
│ │ ├── config.py # 语音代理配置 (音色、模型路径)
│ │ ├── asr.py # faster-whisper 语音识别
│ │ ├── llm.py # llama-server HTTP 客户端
│ │ └── tts.py # kokoro-onnx TTS;修复 int32→float32 速度 bug (0.5.x)
│ ├── tts/
│ │ └── kokoro_tts.py # 数字人页面 Kokoro TTS
│ ├── musetalk/ # MuseTalk 推理
│ ├── models/ # 所有模型权重
│ │ ├── kokoro/
│ │ ├── musetalkV15/
│ │ ├── sd-vae/
│ │ ├── whisper/
│ │ └── Llama-3.2-3B-Instruct-Q4_K_M.gguf
│ └── avatars/ # 预计算的数字人资源
│ ├── christine/
│ ├── harry_1/
│ └── sophy/
└── frontend/
└── src/
├── App.tsx # 数字人页面
├── pages/
│ └── VoicePage.tsx # 语音代理页面
└── index.css
可用音色 (语音代理页面)
| 音色 ID | 说明 |
|---|---|
af_sarah |
女声,清晰专业 |
af_bella |
女声,温暖亲切 |
af_heart |
女声,富有情感和表现力 |
am_michael |
男声,专业权威 |
am_fen |
男声,深沉共鸣 |
bf_emma |
女声,英式口音 |
bm_george |
男声,英式口音 |
故障排除
Kokoro ONNX int32 速度张量错误
已在 backend/tts/kokoro_tts.py 和 backend/agent/tts.py 中通过 _patched_create_audio 猴子补丁修复。需要 kokoro-onnx>=0.5.0。
启动时出现 ModuleNotFoundError
请先激活 conda 环境:conda activate avatar
LiveKit 连接错误
请验证 backend/config.py 和 backend/agent/config.py 中的 API 密钥是否一致:
LIVEKIT_API_KEY = \"devkey\"
LIVEKIT_API_SECRET = \"secret\"
找不到 llama-server
从 llama.cpp releases 下载并添加到 PATH。
Windows:下载 llama-...-win-cuda-cu12.x.x-x64.zip,解压后将文件夹添加到 PATH。
显存不足 (数字人页面)
在 backend/config.py 中减小批处理大小:
FRAMES_PER_CHUNK = 2 # 默认为 8
端口被占用
# 查找并终止进程
lsof -i :8767 # 数字人页面后端
lsof -i :3000 # 语音代理 Token 服务器
lsof -i :8080 # llama-server
agkavin/Avatar-Speech
作者 agkavin
创建时间: 2026-03-10 02:58:05+00:00
更新时间: 2026-03-20 04:44:40+00:00
在 Hugging Face 上查看