SadTalker 安装教程：3 条命令跑通第一段口型视频
【免费下载链接】SadTalker[CVPR 2023] SadTalker：Learning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalker
SadTalker 能把一张静态人像和一段音频，合成为会说话的人像视频：口型、点头、表情都跟着语音走。这篇教程带你完成 SadTalker 安装与 SadTalker 配置——先三步跑通第一次推理拿到正反馈，再按平台排坑、按硬件做选型，最后用一份自检清单确认部署成功。
一、三步跑通：先拿一个能播放的结果
1. 克隆代码
打开终端，克隆仓库并进入目录：
git clone https://gitcode.com/GitHub_Trending/sa/SadTalker.git cd SadTalker2. 建环境、装依赖
用 conda 建一个独立环境，别往现有环境里塞：
conda create -n sadtalker python=3.8 -y conda activate sadtalker pip install torch torchvision torchaudio conda install ffmpeg pip install -r requirements.txt依赖其实就三块，装的时候心里有数：
| 依赖 | 装它的理由 |
|---|---|
| torch / torchvision / torchaudio | 推理引擎，N 卡机器直接装默认包即可 |
| ffmpeg | 解码音频、拼接结果视频，缺它必报错 |
| requirements.txt | 一条命令装下 numpy、librosa、face_alignment、kornia、gfpgan、gradio 等 |
| dlib | 仅 macOS 需要，用于人脸关键点检测 |
3. 下载模型
bash scripts/download_models.sh脚本 scripts/download_models.sh 会把文件放进两个位置：
checkpoints/：256 与 512 两档人脸渲染模型（.safetensors），外加两个 mapping 网络gfpgan/weights/：GFPGAN 人脸增强用的 4 个权重文件
模型总量约 3GB。网络中断也没关系，直接重跑脚本，已下载的文件会被跳过。
4. 跑第一次推理
python inference.py不传任何参数时，inference.py 会用仓库自带的示例：音频examples/driven_audio/bus_chinese.wav，人像examples/source_image/full_body_1.png，也就是下面这张图：
跑完后终端会打印一行The generated video is named: ./results/xxxx.mp4，视频就在results/目录。看到嘴型跟着语音动，SadTalker 安装就算成了。
二、分平台差异：各平台特有的坑
⚠️ Windows：ffmpeg 不在 PATH 里
Windows 上最常见的翻车是ffmpeg is not recognized as an internal or external command——ffmpeg 装了但没进系统 PATH。
- 原生 Windows：用 scoop 或官方二进制安装 ffmpeg，把它的
bin目录加进%PATH% - 用 WSL 的话：先执行
export LD_LIBRARY_PATH=/usr/lib/wsl/lib:$LD_LIBRARY_PATH，再走第一节的流程
改完 PATH 要重开终端。验证方法：
ffmpeg -version能打印出版本号就通过了。
Linux：基本无坑
Linux 上照抄第一节命令即可，两点注意：
conda install ffmpeg最省事；走系统源装的也行，前提是新终端里ffmpeg命令能直接执行- Python 建议用 3.8，高小版本一般也能跑，但 3.8 的依赖冲突最少
macOS：M 芯片上 dlib 的坑
官方在 M1（macOS 13.3）上有成功记录，流程与 Linux 相同，只需补一步。如果启动后立刻崩溃、报Illegal Hardware Instruction，通常是 dlib 与当前芯片架构不匹配。重新装一次即可：
pip install dlib装完用python -c "import dlib"验证，不报错再跑推理。
三、选型指南：你应该怎么选
跑通之后，剩下三个问题：256 还是 512、GPU 还是 CPU、显存不够怎么办。
256 vs 512
--size决定加载哪个模型：init_path.py 按 size 去checkpoints/里找SadTalker_V0.0.2_<size>.safetensors并加载。
- 第一次跑、只想验证环境：
--size 256（默认值），快、省显存 - 效果满意后要出正式片：
--size 512，细节明显更细 - 成片要放大观看：512 之外再挂
--enhancer gfpgan做一次人脸增强（依赖第三步下载的 gfpgan 权重）
GPU vs CPU
设备是自动选的：有 CUDA 且你没传--cpu就走 GPU，否则回落到 CPU。纯 CPU 跑 10 秒音频要等几分钟，把 CPU 当"能跑"方案，别当"好用"方案。
你应该怎么选
| 你的情况 | 建议 | 参数 |
|---|---|---|
| 首次运行，任何硬件 | 256 + GPU | python inference.py |
| 显存 6GB 左右，要出精修片 | 512 + 降 batch | --size 512 --batch_size 1 |
| 完全没 N 卡 | 256 + CPU，音频剪短点 | --cpu --size 256 |
| 全身图、要做头身联动 | still 模式 | --preprocess full --still |
显存不足时怎么调参数
SadTalker 显存不足的报错长这样：RuntimeError: CUDA out of memory。按顺序做三件事：
--batch_size 1（默认是 2）--size 256- 还爆，就限制 PyTorch 的显存切分粒度再跑：
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:128 python inference.py --size 256 --batch_size 1Windows 下把export换成set。
四、自检清单：验证 SadTalker 配置已生效
复制这段，逐条执行：
python -c "import torch; print('torch', torch.__version__, '| cuda', torch.cuda.is_available())" ffmpeg -version ls checkpoints gfpgan/weights预期输出：
- 第一行：
torch 2.x | cuda True；纯 CPU 机器显示False属正常 - 第二行：ffmpeg 的版本横幅；提示找不到命令就回第二节对应平台处理
- 第三行：
checkpoints/4 个文件（2 个 .safetensors + 2 个 mapping），gfpgan/weights/4 个 .pth
最后跑一遍python inference.py，看到The generated video is named:并把results/里的视频点开——脸会随音频说话，SadTalker 配置就全部生效了。
五、高频排错：现象 → 原因 → 动作
1. SadTalker CUDA 报错：CUDA out of memory
- 现象：渲染阶段中途崩溃
- 原因：512 分辨率或 batch 偏大，显存不够
- 动作：降到 256、
--batch_size 1，仍爆则按第三节导PYTORCH_CUDA_ALLOC_CONF
2.ffmpeg is not recognized/No such file or directory: 'ffmpeg'
- 现象：视频拼接阶段崩溃
- 原因：ffmpeg 未安装，或不在 PATH
- 动作：装 ffmpeg 并进 PATH，用
ffmpeg -version验证
3.FileNotFoundError: .../similarity_Lm3D_all.mat
- 现象：3DMM 特征提取阶段崩溃
- 原因：模型没下全，或目录结构不对
- 动作：重跑
bash scripts/download_models.sh，核对checkpoints/内容
4.ModuleNotFoundError: No module named 'ai'
- 现象：启动即崩，报错看着很怪
- 原因：模型文件损坏或下载不完整（常见于 checkpoint 大小不对）
- 动作：删掉对应模型文件，重新执行下载脚本并核对大小
5. Mac M1/M2：Illegal Hardware Instruction
- 现象：进程秒崩
- 原因：dlib 与当前芯片架构不兼容
- 动作：
pip install dlib重装一次
6. 音频解码错误：Invalid data found when processing input
- 现象：加载音频阶段崩溃
- 原因：音频格式不支持
- 动作：输入只支持 wav / mp3，其他格式先用 ffmpeg 转成 wav 再喂进去
六、下一步
到这里，SadTalker 安装与配置就算完成：环境、依赖、模型、推理全链路都通了。把--driven_audio和--source_image换成你自己的音频和照片，就能生成第一段口型视频；想控制表情强度或用参考视频驱动眨眼神态，参考 docs/best_practice.md，更多输入素材在 examples/ 目录里。
【免费下载链接】SadTalker[CVPR 2023] SadTalker：Learning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalker
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
