何时使用
用户想要根据一张肖像照片和一段音频文件创建说话头像/数字人视频（口播视频、数字人生成、照片说话）。触发关键词："生成口播视频"、"make this photo talk"、"照片说话"、"数字人视频"、"sadtalker"、"talking head"、"avatar video from photo"。仅适用于macOS（Apple Silicon 或 Intel）。
操作步骤
- 定位脚本：它们位于此SKILL.md所在的同一目录中。使用以下命令找到它们：
ls "$(dirname <此SKILL.md的路径>)"— 你会看到 setup.sh 和 generate.sh 与该文件并存。 - 检查先决条件：ffmpeg、conda环境sadtalker、~/SadTalker/checkpoints/。如果缺少任何内容，请运行 setup.sh（仅首次运行，约需15分钟，下载约2.5GB）。
- 确认用户已提供肖像照片（.jpg/.png）和语音音频文件（.wav/.mp3）。如果音频是其他格式，请先用ffmpeg转换。
- 运行生成：
bash generate.sh <照片> <音频> [--enhancer gfpgan] [--still] [--preprocess full|resize|crop]。此命令底层调用conda run -n sadtalker python inference.py。 - 输出文件为.mp4格式，位于 ~/SadTalker/results/<时间戳>/ 目录下。使用
open <路径>（macOS）打开。将路径报告给用户。
常见陷阱
- conda环境中Python必须是3.10版本。3.8缺少Apple Silicon的wheel包，3.11及以上版本没有scikit-image==0.19.3的wheel包。
- 8GB内存：运行前请关闭Chrome/IDE等应用。SadTalker在Mac上仅使用CPU运行——无GPU加速路径。
- dlib必须在Mac上单独安装：
conda run -n sadtalker pip install dlib——这是M1 Mac上最常见的错误。 - 安装torch时不要带CUDA后缀：直接使用
pip install torch torchvision torchaudio。如果 torch.version 包含 '+cu'，请重新安装。 - 使用brew安装ffmpeg，不要用conda。conda的ffmpeg有时缺少所需的编解码器。
- 首次运行会下载约2GB的检查点文件。在中国，请先设置环境变量
HF_ENDPOINT=https://hf-mirror.com。 - GFPGAN增强器（
--enhancer gfpgan）会大约使处理时间翻倍。快速预览时可跳过。 - --still模式在与 --preprocess full 结合使用时，期望源照片为全身照。
- 音频必须是.wav或.mp3格式。其他格式会报错'Header missing'。使用ffmpeg转换：
ffmpeg -i input.m4a output.wav。
验证步骤
- conda run -n sadtalker python -c 'import torch; print(torch.version)' — 输出中必须不包含 '+cu'
- ls ~/SadTalker/checkpoints/ — 必须包含 audio2exp_00300-model.pth、audio2pose_00140-model.pth、epoch_20.pth 以及其他 .pth 文件
- conda run -n sadtalker python -c 'import dlib; print("ok")' — 必须打印 'ok'（无 Illegal Hardware Instruction 错误）
- 冒烟测试：cd ~/SadTalker && conda run -n sadtalker python inference.py --driven_audio examples/driven_audio/bus_chinese.wav --source_image examples/source_image/full_body_1.png — 应在 results/ 目录下生成输出文件