SadTalker 安装部署指南macOS / Windows / WSL / Docker 多平台环境搭建实战【免费下载链接】SadTalker[CVPR 2023] SadTalkerLearning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalkerSadTalkerCVPR 2023是一个基于单张人像图片与驱动音频生成说话人头视频的开源项目其安装方式覆盖 Linux、macOS、Windows、WSL 与 Docker 等多种环境。本文以 docs/install.md 为主线结合仓库内的 webui.sh、webui.bat、launcher.py、requirements.txt、cog.yaml 与 scripts/download_models.sh 等真实文件系统讲解各平台的安装步骤、依赖说明、模型下载与安装验证方法帮助你在自己的机器上完整跑通 SadTalker。一、安装前的环境准备无论使用哪种平台SadTalker 的本地运行都依赖以下几项基础组件组件用途备注Python 3.8运行推理代码官方 conda 方案固定使用python3.8launcher.py 中校验 Python 版本Windows 下支持 3.10其他平台支持 3.7~3.11git克隆仓库、webui.sh自更新webui.sh 默认使用系统gitffmpeg音视频解码/编码音频读取与视频合成均依赖 ffmpeg建议安装为系统命令conda可选创建隔离 Python 环境Linux/macOS 官方方案使用 Anaconda关于依赖清单的两个文件仓库根目录同时存在两个依赖清单用途不同requirements.txtWindows Native 与 macOS 手动安装时使用包含numpy1.23.4、face_alignment1.3.5、librosa0.9.2、kornia0.6.8、gfpgan、facexlib、gradio、safetensors等。req.txtwebui.sh/webui.bat自动安装时使用由 launcher.py 依据平台选择非 Windows 用req.txtWindows 用requirements.txt其内部将 librosa 升级为0.10.0.post2、numpy 降为1.21.6并锁定llvmlite0.38.1、numba0.55.1。两者都包含TTS之外的全部推理依赖Coqui TTS 仅用于本地 Gradio 演示的文字转语音功能属于可选安装项。二、Linux / Unix 安装conda 方案Linux/Unix 是 SadTalker 官方文档README.md的主推安装路径步骤如下安装 Anaconda、Python 与git克隆仓库、创建并激活 conda 环境然后安装依赖git clone https://gitcode.com/GitHub_Trending/sa/SadTalker.git cd SadTalker conda create -n sadtalker python3.8 conda activate sadtalker pip install torch1.12.1cu113 torchvision0.13.1cu113 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113 conda install ffmpeg pip install -r requirements.txt ### Coqui TTS 对 gradio demo 可选需要时执行 ### pip install TTS其中 PyTorch 使用 CUDA 11.3 构建版本cu113是当前仓库各配置文件如 cog.yaml 中cuda: 11.3验证过的组合。若机器无 NVIDIA GPU可将 torch 安装命令替换为 CPU 版本参考下文 macOS 一节。三、macOS 安装docs/install.md 给出的 macOS 方案已在M1 MacmacOS 13.3上测试通过命令如下git clone https://gitcode.com/GitHub_Trending/sa/SadTalker.git cd SadTalker conda create -n sadtalker python3.8 conda activate sadtalker # install pytorch 2.0 pip install torch torchvision torchaudio conda install ffmpeg pip install -r requirements.txt pip install dlib # macOS needs to install the original dlib.需要特别说明的两点PyTorch 安装文档注释写的是 install pytorch 2.0直接pip install torch torchvision torchaudio会拉取当前可用的最新稳定版Apple Silicon 上默认是支持 MPS 的构建。这与 Linux 的 CUDA 固定版本不同原因在于 macOS 没有 CUDA直接安装默认构建即可。仓库的 webui.sh 也体现了这一点当检测到darwin系统时会将TORCH_COMMAND设置为pip install torch1.12.1 torchvision0.13.1即不带 CUDA 后缀的 CPU 构建。dlib 必须安装原始包pip install dlib安装的是官方原始 dlib而非dlib-bin。这是因为 macOS 上某些预编译的dlib-bin存在兼容性问题人脸关键点提取src/face3d/util/detect_lm68.py 所依赖的 68 点检测需要原版 dlib 才能正常工作。Linux 上的 Docker 镜像则相反使用dlib-bin19.24.1见 cog.yaml。四、Windows Native原生 Windows安装Windows 原生环境的要点是确保ffmpeg已加入系统%PATH%docs/install.md 建议参考安装教程或使用 scoop 安装否则后续音频/视频处理会报错。完整步骤README.md安装 Python 3.8勾选 Add Python to PATH安装git手动安装或通过 Scoopscoop install git安装ffmpeg并加入 PATH或scoop install ffmpeg克隆仓库git clone https://gitcode.com/GitHub_Trending/sa/SadTalker.git按本文第七节下载预训练模型与 GFPGAN 权重以普通用户身份非管理员双击运行start.bat会自动启动一个 Gradio 驱动的 WebUI 演示界面。仓库当前提供的一键脚本是 webui.bat其逻辑为若不存在venv目录则用python -m venv venv创建虚拟环境然后调用venv\Scripts\activate.bat激活最后执行Launcher.py完成依赖安装并启动 WebUI。由于 Windows 下Launcher.py会选择 requirements.txt 作为依赖清单launcher.py首次运行安装耗时较长属于正常现象。五、Windows WSL 安装在 WSLWindows Subsystem for Linux中安装时docs/install.md 给出的关键环境变量是export LD_LIBRARY_PATH/usr/lib/wsl/lib:$LD_LIBRARY_PATH该路径对应 WSL 与 Windows 共享 GPUDirectML / WSLg所需的库目录。设置好该变量后再按上文 Linux/Unix 一节的 conda 流程继续安装即可。此外webui.sh在 WSL 中也同样适用它依赖lspci探测 GPU见 webui.sh。六、Docker 安装社区维护者 thegenerativegeneration 在 Docker Hub 上发布了可直接使用的 SadTalker 镜像镜像名wawa9000/sadtalker。使用方式docs/install.mddocker run --gpus all --rm -v $(pwd):/host_dir wawa9000/sadtalker \ --driven_audio /host_dir/deyu.wav \ --source_image /host_dir/image.jpg \ --expression_scale 1.0 \ --still \ --result_dir /host_dir命令说明--gpus all启用宿主机全部 GPU需配合 NVIDIA Container Toolkit-v $(pwd):/host_dir将当前目录挂载进容器输入音频、图片与输出目录都在/host_dir下映射--still开启全身/原图动画模式对应 inference.py 的--still参数--result_dir /host_dir生成结果直接写回宿主机当前目录。对于希望自建镜像的用户仓库提供了 cog.yaml它声明了 CUDA 11.3、Python 3.8、系统包ffmpeg/libgl1-mesa-glx/libglib2.0-0以及全部 Python 依赖含torch1.12.1、dlib-bin19.24.1、gfpgan1.3.8等并在构建时预下载 face-alignment 所需的s3fd与2DFAN4模型缓存。Linux 下手动部署时若缺少libgl1-mesa-glx、libglib2.0-0这两个系统库人脸检测facexlib阶段可能报 GL/GLib 相关错误可参照该文件安装。七、下载预训练模型安装后的必经步骤模型权重不属于代码仓库需要单独下载。最快捷的方式是执行仓库自带的下载脚本Linux/macOSbash scripts/download_models.shscripts/download_models.sh 会完成以下工作创建./checkpoints目录下载新版打包权重mapping_00109-model.pth.tar、mapping_00229-model.pth.tarMappingNetfull/全身模式与 crop 模式分别使用SadTalker_V0.0.2_256.safetensors、SadTalker_V0.0.2_512.safetensors256 与 512 分辨率的打包模型创建./gfpgan/weights目录下载人脸增强与检测权重alignment_WFLW_4HG.pth、detection_Resnet50_Final.pthfacexlib 人脸检测/对齐、GFPGANv1.4.pth人脸增强、parsing_parsenet.pth人脸解析。如果脚本下载不便也可从 README 提供的Google Drive / GitHub Releases / 百度云盘提取码sadt手动下载 checkpoint 与 GFPGAN 离线补丁包gfpgan/目录携带后推理时不触发额外下载。新版权重说明README.mdModelDescriptioncheckpoints/mapping_00229-model.pth.tarSadTalker 中预训练的 MappingNetcrop 模式checkpoints/mapping_00109-model.pth.tarSadTalker 中预训练的 MappingNetfull 模式checkpoints/SadTalker_V0.0.2_256.safetensors旧版打包权重256 人脸渲染checkpoints/SadTalker_V0.0.2_512.safetensors旧版打包权重512 人脸渲染gfpgan/weightsfacexlib 与 gfpgan 使用的人脸检测与增强模型模型目录的解析逻辑见 src/utils/init_path.py当checkpoints目录下存在*.safetensors文件时优先使用 safetensors 打包权重否则回退到旧版pth权重wav2lip.pth、auido2pose_00140-model.pth、auido2exp_00300-model.pth、facevid2vid_00189-model.pth.tar、epoch_20.pth此时会打印 WARNING: ... You may need to download it manually。此外preprocess为full时使用mapping_00109与facerender_still.yaml否则使用mapping_00229与facerender.yamlsrc/config/facerender_still.yaml。八、安装验证启动 WebUI 与 CLI方式一一键脚本启动 WebUI推荐Windows双击webui.bat脚本自动创建venv并安装依赖后启动Linux / macOS运行bash webui.sh。webui.sh 的完整流程包括macOS 下自动切换 CPU 版 torch 命令、检查git/python3/venv是否存在、创建并激活venv最终执行launcher.py。launcher.py 的prepare_environment()会先按TORCH_COMMAND环境变量默认 CUDA 11.3 版 torch安装 torch/torchvision再安装req.txtWindows 为requirements.txt非 Windows 平台还会自动尝试安装TTS。由于launcher.py会关闭 Gradio 遥测GRADIO_ANALYTICS_ENABLEDFalse见 launcher.py日常使用不受影响。方式二直接运行 Gradio Demo## 如需文字转语音请先手动安装 TTSpip install TTS python app_sadtalker.py这与 launcher.py 调用的app_sadtalker.sadtalker_demo()是同一个 Gradio 应用效果与官方 Hugging Face 在线 Demo 一致。方式三CLI 命令行推理安装并下载模型后可用 inference.py 做端到端验证python inference.py --driven_audio audio.wav \ --source_image video.mp4 or picture.png \ --enhancer gfpgan结果默认保存在results/$SOME_TIMESTAMP/*.mp4inference.py 以时间戳建目录最后移动为results/时间戳.mp4。核心命令行参数inference.py参数默认值说明--driven_audio./examples/driven_audio/bus_chinese.wav驱动音频路径--source_image./examples/source_image/full_body_1.png源图片或视频路径--checkpoint_dir./checkpoints权重目录--result_dir./results输出目录--pose_style0姿态风格取值 [0, 46)--size256人脸渲染尺寸对应 256/512 权重--expression_scale1.0表情幅度系数--enhancerNone人脸增强器gfpgan/RestoreFormer--background_enhancerNone背景增强器realesrgan--stillFalse全身/原图动画模式--preprocesscrop预处理方式crop/extcrop/resize/full/extfull--old_versionFalse使用旧版 pth 权重而非 safetensors--cpuFalseCPU 推理全身动画示例python inference.py --driven_audio audio.wav \ --source_image video.mp4 or picture.png \ --result_dir a file to store results \ --still \ --preprocess full \ --enhancer gfpgan九、常见问题与延伸阅读安装或运行中遇到问题先查阅 docs/FAQ.md 再提交 issue各参数调节与最佳实践分辨率、enhancer、姿态风格等详见 docs/best_practice.md若需将 SadTalker 作为 stable-diffusion-webui 扩展安装参见 docs/webui_extension.md版本更新历史见 docs/changlelog.md使用须知本仓库采用 Apache 2.0 许可推理完全离线运行不收集任何个人信息请勿将其用于伪造、诈骗或侵犯他人肖像权等非法用途详见 README.md 免责声明。【免费下载链接】SadTalker[CVPR 2023] SadTalkerLearning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SadTalker 安装部署指南：macOS / Windows / WSL / Docker 多平台环境搭建实战
SadTalker 安装部署指南macOS / Windows / WSL / Docker 多平台环境搭建实战【免费下载链接】SadTalker[CVPR 2023] SadTalkerLearning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalkerSadTalkerCVPR 2023是一个基于单张人像图片与驱动音频生成说话人头视频的开源项目其安装方式覆盖 Linux、macOS、Windows、WSL 与 Docker 等多种环境。本文以 docs/install.md 为主线结合仓库内的 webui.sh、webui.bat、launcher.py、requirements.txt、cog.yaml 与 scripts/download_models.sh 等真实文件系统讲解各平台的安装步骤、依赖说明、模型下载与安装验证方法帮助你在自己的机器上完整跑通 SadTalker。一、安装前的环境准备无论使用哪种平台SadTalker 的本地运行都依赖以下几项基础组件组件用途备注Python 3.8运行推理代码官方 conda 方案固定使用python3.8launcher.py 中校验 Python 版本Windows 下支持 3.10其他平台支持 3.7~3.11git克隆仓库、webui.sh自更新webui.sh 默认使用系统gitffmpeg音视频解码/编码音频读取与视频合成均依赖 ffmpeg建议安装为系统命令conda可选创建隔离 Python 环境Linux/macOS 官方方案使用 Anaconda关于依赖清单的两个文件仓库根目录同时存在两个依赖清单用途不同requirements.txtWindows Native 与 macOS 手动安装时使用包含numpy1.23.4、face_alignment1.3.5、librosa0.9.2、kornia0.6.8、gfpgan、facexlib、gradio、safetensors等。req.txtwebui.sh/webui.bat自动安装时使用由 launcher.py 依据平台选择非 Windows 用req.txtWindows 用requirements.txt其内部将 librosa 升级为0.10.0.post2、numpy 降为1.21.6并锁定llvmlite0.38.1、numba0.55.1。两者都包含TTS之外的全部推理依赖Coqui TTS 仅用于本地 Gradio 演示的文字转语音功能属于可选安装项。二、Linux / Unix 安装conda 方案Linux/Unix 是 SadTalker 官方文档README.md的主推安装路径步骤如下安装 Anaconda、Python 与git克隆仓库、创建并激活 conda 环境然后安装依赖git clone https://gitcode.com/GitHub_Trending/sa/SadTalker.git cd SadTalker conda create -n sadtalker python3.8 conda activate sadtalker pip install torch1.12.1cu113 torchvision0.13.1cu113 torchaudio0.12.1 --extra-index-url https://download.pytorch.org/whl/cu113 conda install ffmpeg pip install -r requirements.txt ### Coqui TTS 对 gradio demo 可选需要时执行 ### pip install TTS其中 PyTorch 使用 CUDA 11.3 构建版本cu113是当前仓库各配置文件如 cog.yaml 中cuda: 11.3验证过的组合。若机器无 NVIDIA GPU可将 torch 安装命令替换为 CPU 版本参考下文 macOS 一节。三、macOS 安装docs/install.md 给出的 macOS 方案已在M1 MacmacOS 13.3上测试通过命令如下git clone https://gitcode.com/GitHub_Trending/sa/SadTalker.git cd SadTalker conda create -n sadtalker python3.8 conda activate sadtalker # install pytorch 2.0 pip install torch torchvision torchaudio conda install ffmpeg pip install -r requirements.txt pip install dlib # macOS needs to install the original dlib.需要特别说明的两点PyTorch 安装文档注释写的是 install pytorch 2.0直接pip install torch torchvision torchaudio会拉取当前可用的最新稳定版Apple Silicon 上默认是支持 MPS 的构建。这与 Linux 的 CUDA 固定版本不同原因在于 macOS 没有 CUDA直接安装默认构建即可。仓库的 webui.sh 也体现了这一点当检测到darwin系统时会将TORCH_COMMAND设置为pip install torch1.12.1 torchvision0.13.1即不带 CUDA 后缀的 CPU 构建。dlib 必须安装原始包pip install dlib安装的是官方原始 dlib而非dlib-bin。这是因为 macOS 上某些预编译的dlib-bin存在兼容性问题人脸关键点提取src/face3d/util/detect_lm68.py 所依赖的 68 点检测需要原版 dlib 才能正常工作。Linux 上的 Docker 镜像则相反使用dlib-bin19.24.1见 cog.yaml。四、Windows Native原生 Windows安装Windows 原生环境的要点是确保ffmpeg已加入系统%PATH%docs/install.md 建议参考安装教程或使用 scoop 安装否则后续音频/视频处理会报错。完整步骤README.md安装 Python 3.8勾选 Add Python to PATH安装git手动安装或通过 Scoopscoop install git安装ffmpeg并加入 PATH或scoop install ffmpeg克隆仓库git clone https://gitcode.com/GitHub_Trending/sa/SadTalker.git按本文第七节下载预训练模型与 GFPGAN 权重以普通用户身份非管理员双击运行start.bat会自动启动一个 Gradio 驱动的 WebUI 演示界面。仓库当前提供的一键脚本是 webui.bat其逻辑为若不存在venv目录则用python -m venv venv创建虚拟环境然后调用venv\Scripts\activate.bat激活最后执行Launcher.py完成依赖安装并启动 WebUI。由于 Windows 下Launcher.py会选择 requirements.txt 作为依赖清单launcher.py首次运行安装耗时较长属于正常现象。五、Windows WSL 安装在 WSLWindows Subsystem for Linux中安装时docs/install.md 给出的关键环境变量是export LD_LIBRARY_PATH/usr/lib/wsl/lib:$LD_LIBRARY_PATH该路径对应 WSL 与 Windows 共享 GPUDirectML / WSLg所需的库目录。设置好该变量后再按上文 Linux/Unix 一节的 conda 流程继续安装即可。此外webui.sh在 WSL 中也同样适用它依赖lspci探测 GPU见 webui.sh。六、Docker 安装社区维护者 thegenerativegeneration 在 Docker Hub 上发布了可直接使用的 SadTalker 镜像镜像名wawa9000/sadtalker。使用方式docs/install.mddocker run --gpus all --rm -v $(pwd):/host_dir wawa9000/sadtalker \ --driven_audio /host_dir/deyu.wav \ --source_image /host_dir/image.jpg \ --expression_scale 1.0 \ --still \ --result_dir /host_dir命令说明--gpus all启用宿主机全部 GPU需配合 NVIDIA Container Toolkit-v $(pwd):/host_dir将当前目录挂载进容器输入音频、图片与输出目录都在/host_dir下映射--still开启全身/原图动画模式对应 inference.py 的--still参数--result_dir /host_dir生成结果直接写回宿主机当前目录。对于希望自建镜像的用户仓库提供了 cog.yaml它声明了 CUDA 11.3、Python 3.8、系统包ffmpeg/libgl1-mesa-glx/libglib2.0-0以及全部 Python 依赖含torch1.12.1、dlib-bin19.24.1、gfpgan1.3.8等并在构建时预下载 face-alignment 所需的s3fd与2DFAN4模型缓存。Linux 下手动部署时若缺少libgl1-mesa-glx、libglib2.0-0这两个系统库人脸检测facexlib阶段可能报 GL/GLib 相关错误可参照该文件安装。七、下载预训练模型安装后的必经步骤模型权重不属于代码仓库需要单独下载。最快捷的方式是执行仓库自带的下载脚本Linux/macOSbash scripts/download_models.shscripts/download_models.sh 会完成以下工作创建./checkpoints目录下载新版打包权重mapping_00109-model.pth.tar、mapping_00229-model.pth.tarMappingNetfull/全身模式与 crop 模式分别使用SadTalker_V0.0.2_256.safetensors、SadTalker_V0.0.2_512.safetensors256 与 512 分辨率的打包模型创建./gfpgan/weights目录下载人脸增强与检测权重alignment_WFLW_4HG.pth、detection_Resnet50_Final.pthfacexlib 人脸检测/对齐、GFPGANv1.4.pth人脸增强、parsing_parsenet.pth人脸解析。如果脚本下载不便也可从 README 提供的Google Drive / GitHub Releases / 百度云盘提取码sadt手动下载 checkpoint 与 GFPGAN 离线补丁包gfpgan/目录携带后推理时不触发额外下载。新版权重说明README.mdModelDescriptioncheckpoints/mapping_00229-model.pth.tarSadTalker 中预训练的 MappingNetcrop 模式checkpoints/mapping_00109-model.pth.tarSadTalker 中预训练的 MappingNetfull 模式checkpoints/SadTalker_V0.0.2_256.safetensors旧版打包权重256 人脸渲染checkpoints/SadTalker_V0.0.2_512.safetensors旧版打包权重512 人脸渲染gfpgan/weightsfacexlib 与 gfpgan 使用的人脸检测与增强模型模型目录的解析逻辑见 src/utils/init_path.py当checkpoints目录下存在*.safetensors文件时优先使用 safetensors 打包权重否则回退到旧版pth权重wav2lip.pth、auido2pose_00140-model.pth、auido2exp_00300-model.pth、facevid2vid_00189-model.pth.tar、epoch_20.pth此时会打印 WARNING: ... You may need to download it manually。此外preprocess为full时使用mapping_00109与facerender_still.yaml否则使用mapping_00229与facerender.yamlsrc/config/facerender_still.yaml。八、安装验证启动 WebUI 与 CLI方式一一键脚本启动 WebUI推荐Windows双击webui.bat脚本自动创建venv并安装依赖后启动Linux / macOS运行bash webui.sh。webui.sh 的完整流程包括macOS 下自动切换 CPU 版 torch 命令、检查git/python3/venv是否存在、创建并激活venv最终执行launcher.py。launcher.py 的prepare_environment()会先按TORCH_COMMAND环境变量默认 CUDA 11.3 版 torch安装 torch/torchvision再安装req.txtWindows 为requirements.txt非 Windows 平台还会自动尝试安装TTS。由于launcher.py会关闭 Gradio 遥测GRADIO_ANALYTICS_ENABLEDFalse见 launcher.py日常使用不受影响。方式二直接运行 Gradio Demo## 如需文字转语音请先手动安装 TTSpip install TTS python app_sadtalker.py这与 launcher.py 调用的app_sadtalker.sadtalker_demo()是同一个 Gradio 应用效果与官方 Hugging Face 在线 Demo 一致。方式三CLI 命令行推理安装并下载模型后可用 inference.py 做端到端验证python inference.py --driven_audio audio.wav \ --source_image video.mp4 or picture.png \ --enhancer gfpgan结果默认保存在results/$SOME_TIMESTAMP/*.mp4inference.py 以时间戳建目录最后移动为results/时间戳.mp4。核心命令行参数inference.py参数默认值说明--driven_audio./examples/driven_audio/bus_chinese.wav驱动音频路径--source_image./examples/source_image/full_body_1.png源图片或视频路径--checkpoint_dir./checkpoints权重目录--result_dir./results输出目录--pose_style0姿态风格取值 [0, 46)--size256人脸渲染尺寸对应 256/512 权重--expression_scale1.0表情幅度系数--enhancerNone人脸增强器gfpgan/RestoreFormer--background_enhancerNone背景增强器realesrgan--stillFalse全身/原图动画模式--preprocesscrop预处理方式crop/extcrop/resize/full/extfull--old_versionFalse使用旧版 pth 权重而非 safetensors--cpuFalseCPU 推理全身动画示例python inference.py --driven_audio audio.wav \ --source_image video.mp4 or picture.png \ --result_dir a file to store results \ --still \ --preprocess full \ --enhancer gfpgan九、常见问题与延伸阅读安装或运行中遇到问题先查阅 docs/FAQ.md 再提交 issue各参数调节与最佳实践分辨率、enhancer、姿态风格等详见 docs/best_practice.md若需将 SadTalker 作为 stable-diffusion-webui 扩展安装参见 docs/webui_extension.md版本更新历史见 docs/changlelog.md使用须知本仓库采用 Apache 2.0 许可推理完全离线运行不收集任何个人信息请勿将其用于伪造、诈骗或侵犯他人肖像权等非法用途详见 README.md 免责声明。【免费下载链接】SadTalker[CVPR 2023] SadTalkerLearning Realistic 3D Motion Coefficients for Stylized Audio-Driven Single Image Talking Face Animation项目地址: https://gitcode.com/GitHub_Trending/sa/SadTalker创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
使用与优惠攻略)
