MuseTalk：腾讯音乐 Lyra Lab 实时口型同步模型｜部署与使用全指南

MuseTalk —— 腾讯音乐 Lyra Lab 出品的实时高保真音频驱动视频口型同步模型

适用场景：给已有视频/照片中的人物换配音口型、配合 MuseV 生成的虚拟人视频完成口型对齐、离线批量配音成片；仓库同时提供普通推理、实时推理与 Gradio 网页 Demo 三套入口。本节命令与参数均以官方 README、官方仓库脚本（scripts/inference.py、scripts/realtime_inference.py、app.py、inference.sh、download_weights.sh、download_weights.bat、requirements.txt、configs/inference/*.yaml）为准。

项目定位与基本信息

官方图片

图 07-1 MuseTalk 模型结构（README "Model" 章节原图）

• 来源 URL：https://github.com/user-attachments/assets/02f4a214-1bdd-4326-983c-e70b478accba（README ![Model Structure](...) 原始链接，跟随 302 重定向下载）
• 下载方式：curl -L -o 07_musetalk_model_structure.png "<上述 URL>"；2026-10-25 下载后 file 校验：PNG image data, 1934 x 646, 8-bit/color RGBA，大小 410,486 字节（>20KB）。

图 07-2 Gradio Demo 参数面板（README "Gradio Demo" 章节引用图 assets/figs/gradio_2.png）

• 来源 URL：https://raw.githubusercontent.com/TMElyralab/MuseTalk/main/assets/figs/gradio_2.png
• 下载方式：curl -L -o 07_musetalk_gradio_params.png "<上述 URL>"；2026-10-25 下载后 file 校验：PNG image data, 1781 x 1066, 8-bit/color RGBA，大小 75,170 字节（>20KB）。

说明：仓库另一张 assets/figs/gradio.png（硬件耗时对比图）下载后仅 13,911 字节，未达到本节 ">20KB" 的交付要求，故未引用；本地亦未保留。

环境要求

最详细部署步骤（WSL2 Ubuntu 24.04 / Windows 10-11 双视角）

环境搭建（README Installation 原文命令）

视角 A：WSL2 Ubuntu 24.04 / Linux

# 1. 创建官方推荐环境
conda create -n MuseTalk python==3.10
conda activate MuseTalk

# 2. 安装 PyTorch 2.0.1（README Option 1：pip cu118 wheel）
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118
# README Option 2（conda 方式，二选一即可）：
# conda install pytorch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 pytorch-cuda=11.8 -c pytorch -c nvidia

# 3. 拉取源码
git clone https://github.com/TMElyralab/MuseTalk.git
cd MuseTalk

# 4. 安装其余 Python 依赖（README 原文命令）
pip install -r requirements.txt

# 5. 安装 MMLab 生态（README 原文命令）
pip install --no-cache-dir -U openmim
mim install mmengine
mim install "mmcv==2.0.1"
mim install "mmdet==3.1.0"
mim install "mmpose==1.1.0"

# 6. 安装 ffmpeg（README Quickstart Prerequisites：Linux 用系统包管理器）
sudo apt-get update && sudo apt-get install -y ffmpeg
ffmpeg -version    # 确认命令在 PATH 中

视角 B：Windows 10/11 原生

# 1. conda 环境（与 Linux 一致）
conda create -n MuseTalk python==3.10
conda activate MuseTalk

# 2. PyTorch（README 同一组 pip 命令，Windows 下直接可用）
pip install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118

# 3. 源码与依赖
git clone https://github.com/TMElyralab/MuseTalk.git
cd MuseTalk
pip install -r requirements.txt
pip install --no-cache-dir -U openmim
mim install mmengine
mim install "mmcv==2.0.1"
mim install "mmdet==3.1.0"
mim install "mmpose==1.1.0"

ffmpeg 安装（README "Setup FFmpeg" 原文）：

1. 下载 ffmpeg-static 构建包：https://github.com/BtbN/FFmpeg-Builds/releases（curl 200 核验）。
2. Linux：解压后设置环境变量 export FFMPEG_PATH=/path/to/ffmpeg，README 示例 export FFMPEG_PATH=/musetalk/ffmpeg-4.4-amd64-static。
3. Windows：将 ffmpeg-xxx\bin 目录加入系统 PATH；命令行运行 ffmpeg -version 能输出版本信息即配置成功；也可以在推理命令中用 --ffmpeg_path 参数指定实际 bin 目录（README Windows 推理命令即采用该方式）。

下载权重（两种官方方式）

方式一：官方下载脚本（推荐，脚本内置国内 HF 镜像）

方式二：手动下载（README "Option 2: Manual Download" 原文清单）

1. MuseTalk 训练权重：https://huggingface.co/TMElyralab/MuseTalk/tree/main
2. 其他组件权重： - sd-vae-ft-mse：https://huggingface.co/stabilityai/sd-vae-ft-mse/tree/main（curl 200） - whisper-tiny：https://huggingface.co/openai/whisper-tiny/tree/main（curl 200） - dwpose：https://huggingface.co/yzd-v/DWPose/tree/main（curl 200） - syncnet：https://huggingface.co/ByteDance/LatentSync/tree/main（curl 200） - face-parse-bisent 79999_iter.pth：https://drive.google.com/file/d/154JgKpzCPW82qINcVieuPH3fZ2e0P812/view?pli=1 - resnet18：https://download.pytorch.org/models/resnet18-5c106cde.pth（curl 实测 46,827,520 字节）

权重目录结构（README 原文树形清单，必须按此组织到 models/ 下）：

./models/
├── musetalk
│   ├── musetalk.json
│   └── pytorch_model.bin
├── musetalkV15
│   ├── musetalk.json
│   └── unet.pth
├── syncnet
│   └── latentsync_syncnet.pt
├── dwpose
│   └── dw-ll_ucoco_384.pth
├── face-parse-bisent
│   ├── 79999_iter.pth
│   └── resnet18-5c106cde.pth
├── sd-vae
│   ├── config.json
│   └── diffusion_pytorch_model.bin
└── whisper
    ├── config.json
    ├── pytorch_model.bin
    └── preprocessor_config.json

权重文件清单与实测体积（2026-10-25 HTTP HEAD Content-Length 实测）

国内加速：download_weights.sh / download_weights.bat 已把 HF_ENDPOINT 指向 https://hf-mirror.com（curl 200 核验）；手动下载时也可在各 HF URL 前替换域名 huggingface.co → hf-mirror.com。

关键配置文件修改（以官方 YAML 原文为准，web_fetch 核验）

普通推理配置 configs/inference/test.yaml（当前 main 分支原文）：

task_0:
 video_path: "data/video/yongen.mp4"
 audio_path: "data/audio/yongen.wav"

task_1:
 video_path: "data/video/yongen.mp4"
 audio_path: "data/audio/eng.wav"
 bbox_shift: -7

实时推理配置 configs/inference/realtime.yaml（当前 main 分支原文）：

avator_1:
 preparation: True # your can set it to False if you want to use the existing avator, it will save time
 bbox_shift: 5
 video_path: "data/video/yongen.mp4"
 audio_clips:
     audio_0: "data/audio/yongen.wav"
     audio_1: "data/audio/eng.wav"

README 补充：为获得最佳效果，输入视频建议 25fps（与训练时一致）；帧率偏低的视频可先插帧，或用 ffmpeg 转成 25fps。

启动与推理命令

普通推理（Normal Inference，README Quickstart 原文）

Linux：

# MuseTalk 1.5（README 推荐）
sh inference.sh v1.5 normal
# MuseTalk 1.0
sh inference.sh v1.0 normal

Windows（README 原文命令，路径分隔符为反斜杠；--ffmpeg_path 指向实际 ffmpeg bin 目录）：

REM MuseTalk 1.5（推荐）
python -m scripts.inference --inference_config configs\inference\test.yaml --result_dir results\test --unet_model_path models\musetalkV15\unet.pth --unet_config models\musetalkV15\musetalk.json --version v15 --ffmpeg_path ffmpeg-master-latest-win64-gpl-shared\bin

REM MuseTalk 1.0：相应改为 models\musetalk、pytorch_model.bin、--version v1

实时推理（Real-time Inference，README Quickstart 原文）

Linux：

# MuseTalk 1.5（推荐）
sh inference.sh v1.5 realtime
# MuseTalk 1.0
sh inference.sh v1.0 realtime

Windows（README 原文命令）：

REM MuseTalk 1.5（推荐）
python -m scripts.realtime_inference --inference_config configs\inference\realtime.yaml --result_dir results\realtime --unet_model_path models\musetalkV15\unet.pth --unet_config models\musetalkV15\musetalk.json --version v15 --fps 25 --ffmpeg_path ffmpeg-master-latest-win64-gpl-shared\bin

REM MuseTalk 1.0：相应改为 models\musetalk、pytorch_model.bin、--version v1

inference.sh 脚本事实（web_fetch 核验）：normal → scripts.inference + configs/inference/test.yaml + results/test；realtime → scripts.realtime_inference + configs/inference/realtime.yaml + results/realtime，并附加 --fps 25；v1.0 对应 --version v1 与 models/musetalk/pytorch_model.bin，v1.5 对应 --version v15 与 models/musetalkV15/unet.pth。

Gradio 网页 Demo（README "Gradio Demo" 原文命令；Windows / Linux 通用）：

# 可去掉 --use_float16 换取更好画质，但会增加显存占用与推理时间（README 原文说明）
python app.py --use_float16 --ffmpeg_path ffmpeg-master-latest-win64-gpl-shared\bin

app.py 参数（源码 argparse 核验）：--ip 默认 127.0.0.1，--port 默认 7860，--share（创建公开链接），--use_float16，--ffmpeg_path 默认 Windows 路径 ffmpeg-master-latest-win64-gpl-shared\bin。启动后浏览器访问 http://127.0.0.1:7860。

使用方法

方式一：Gradio 网页 Demo（README "Gradio Demo" 章节 + app.py 界面定义）

1. 启动 python app.py --use_float16 --ffmpeg_path <ffmpeg bin 目录>。
2. 左侧面板：Drving Audio（app.py 源码原始标签，即 Driving Audio）上传驱动音频；Reference Video 上传参考视频（app.py 的 check_video 会自动把视频转成 25fps）。
3. 参数区： - BBox_shift value, px（bbox_shift，默认 0，仅 v1.0 可调；Demo 固定使用 v15） - Extra Margin（滑块 0–40，默认 10，决定下颌区域可动范围） - Parsing Mode（jaw / raw，默认 jaw） - Left Cheek Width / Right Cheek Width（滑块 20–160，默认 90；jaw 模式下决定左右脸颊编辑范围）
4. 先点 "1. Test Inpainting" 仅生成第一帧用于微调口型参数，减少成片面部瑕疵（README 建议：为节省推理时间，可先生成第一帧调试最佳参数）。
5. 参数满意后点 "2. Generate"，右侧输出口型同步视频。

方式二：命令行普通推理（离线批量配音）

1. 编辑 configs/inference/test.yaml，把 video_path / audio_path 换成自己的素材；可写多个 task_* 任务。
2. 执行 07.4.5 节普通推理命令。
3. 输出目录：results/test/v15/<视频名>_<音频名>.mp4（scripts/inference.py 命名规则：output_basename = f"{input_basename}_{audio_basename}"，先帧序列 + 临时视频，再用 ffmpeg 合并输入音频）。

方式三：命令行实时推理

1. 首次为新数字人准备素材：configs/inference/realtime.yaml 中 preparation: True，填写 video_path 与 audio_clips。
2. 执行 07.4.5 节实时推理命令；首次会做人脸检测、坐标提取、VAE latent 等准备工作并缓存：v15 为 results/v15/avatars/<avatar_id>/，v1 为 results/avatars/<avatar_id>/（scripts/realtime_inference.py 源码路径规则）。
3. 后续复用同一形象：将 preparation 改为 False，跳过准备阶段。
4. 可选跳过图片保存以测速：

python -m scripts.realtime_inference --inference_config configs/inference/realtime.yaml --skip_save_images

（README "For faster generation without saving images" 原文命令）

普通推理参数说明表（来源：scripts/inference.py 源码 argparse，逐项核验默认值）

实时推理参数补充（来源：scripts/realtime_inference.py 源码 argparse）

端到端示例（输入 → 命令 → 输出，使用仓库自带示例素材）

1. 输入素材（仓库内置，已核验可达）： - 视频：data/video/yongen.mp4（https://raw.githubusercontent.com/TMElyralab/MuseTalk/main/data/video/yongen.mp4，HTTP HEAD 实测 1,870,923 字节） - 音频：data/audio/yongen.wav（https://raw.githubusercontent.com/TMElyralab/MuseTalk/main/data/audio/yongen.wav，实测 1,536,078 字节）
2. 配置：保持 configs/inference/test.yaml 中 task_0 默认值不变（即上述两个文件）。
3. 命令（Linux / WSL2）：

conda activate MuseTalk
cd MuseTalk
sh inference.sh v1.5 normal

4. 处理过程：ffmpeg 抽帧 → Whisper 提取音频特征 → 人脸关键点与 bbox 检测（坐标缓存为 .pkl）→ VAE 编码 latent → UNet 逐 batch 推理 → 解码贴回原画面 → ffmpeg 合成 yongen_yongen.mp4 并合并音频。
5. 输出：results/test/v15/yongen_yongen.mp4（scripts/inference.py 输出命名规则）。
6. Windows 等价命令：

python -m scripts.inference --inference_config configs\inference\test.yaml --result_dir results\test --unet_model_path models\musetalkV15\unet.pth --unet_config models\musetalkV15\musetalk.json --version v15 --ffmpeg_path <实际 ffmpeg bin 目录>

常见坑（现象 + 原因 + 解决，依据官方 README 与源码）

本节来源清单