ComfyUI-LatentSyncWrapper 1.6

支持我的工作

如果您觉得这个项目对您有帮助，请考虑请我喝杯咖啡：

适用于 Windows 和 WSL 2.0 的 ComfyUI 非官方 LatentSync 1.6 实现。

此节点利用字节跳动的 LatentSync 1.6 模型，在 ComfyUI 中提供先进的口型同步功能。它允许您将视频中的嘴唇与音频输入进行同步，具有更高的清晰度和分辨率，解决了先前版本中存在的模糊问题。

⚠️ 重要升级通知 ⚠️

如果您已安装旧版本的 ComfyUI-LatentSyncWrapper，必须在安装 1.6 版本之前将其完全移除：

1. 完全停止 ComfyUI
2. 删除整个文件夹：ComfyUI/custom_nodes/ComfyUI-LatentSyncWrapper/
3. 全新安装：按照以下安装步骤进行 1.6 的全新安装
4. 切勿尝试更新——由于重大更改，1.6 版本需要完全重新安装。

未移除旧版本会导致冲突，从而无法正常运行。

最新变更：

2025年6月14日——更新至 LatentSync 1.6，采用 512×512 分辨率训练，显著提升了牙齿和嘴唇生成的清晰度与细节。

2025年4月29日——为避免 GPU 内存分配问题，帧数据现在会在转换为 uint8 格式之前被移动到 CPU 上。这一改动使得生成更长视频时不会出现 OOM 错误。

LatentSync 1.6 有哪些新特性？

1. 增强的分辨率训练：LatentSync 1.6 基于 512×512 分辨率的视频进行训练，以解决 LatentSync 1.5 中报告的模糊问题。
2. 视觉质量提升：显著减少了 1.5 版本中常见的牙齿和嘴唇模糊现象。
3. 向后兼容性：当前代码同时兼容 LatentSync 1.5 和 1.6，只需更换检查点即可。
4. 模型架构不变：模型结构和训练策略未作更改，仅提升了训练数据的分辨率。
5. 性能保持：1.5 版本的所有改进均得以保留：
   • 时间层改进：修正后的实现显著提升了时间一致性。
   • 更好的中文语言支持：通过额外的训练数据，提升了对中文视频的处理效果。
   • 降低显存需求：优化后可在 20GB 显存（RTX 3090 兼容）上运行。
   • 代码优化：原生 PyTorch FlashAttention-2 实现，无需 xFormers 依赖。

先决条件

在安装此节点之前，您必须按顺序安装以下内容：

1. 已安装并可正常运行的 ComfyUI。

2. 系统中已安装 FFmpeg：

   • Windows：从 这里 下载，并将其添加到系统 PATH 中。

安装

注意：可通过 Google Drive 获取完整的预配置检查点包（推荐），或者您可以从 HuggingFace 仓库单独下载模型。

请务必确认所有先决条件均已安装并正常运行后再继续安装。

1. 将此仓库克隆到您的 ComfyUI custom_nodes 目录中：

cd ComfyUI/custom_nodes
git clone https://github.com/ShmuelRonen/ComfyUI-LatentSyncWrapper.git
cd ComfyUI-LatentSyncWrapper
pip install -r requirements.txt

必需依赖项

diffusers>=0.32.2
transformers
huggingface-hub
omegaconf
einops
opencv-python
mediapipe
face-alignment
decord
ffmpeg-python
safetensors
soundfile
DeepCache

需要手动下载模型

重要提示：LatentSync 1.6 需要手动下载模型，因为 LatentSync 1.6 模型托管在一个私有的 HuggingFace 仓库中，无法自动访问。您必须在首次使用前下载以下模型：

手动单独下载

1. VAE 模型下载

在您的 checkpoints 目录下创建一个 vae 文件夹，并下载 VAE 模型：

# 创建 vae 目录
mkdir checkpoints/vae

手动下载步骤：

1. 访问：https://huggingface.co/stabilityai/sd-vae-ft-mse/tree/main
2. 仅下载以下两个文件：
   • diffusion_pytorch_model.safetensors
   • config.json
3. 将它们放入 checkpoints/vae/ 文件夹中（位于扩展目录内）。

2. LatentSync 1.6 检查点下载

下载主要的 LatentSync 1.6 模型：

# 从 HuggingFace 下载 LatentSync 1.6 模型
# 访问：https://huggingface.co/ByteDance/LatentSync-1.6/tree/main
# 将该仓库中的所有文件下载到 checkpoints/ 文件夹中

手动下载步骤：

1. 确保您有权访问私有的 HuggingFace 仓库。
2. 访问：https://huggingface.co/ByteDance/LatentSync-1.6/tree/main
3. 下载该仓库中的所有文件。
4. 将其直接放置在 checkpoints/ 文件夹中。

检查点目录结构

下载模型后（无论采用哪种方式），您的检查点目录结构应如下所示：

./checkpoints/
|-- .cache/
|-- auxiliary/
|-- vae/
|   |-- config.json
|   `-- diffusion_pytorch_model.safetensors
|-- whisper/
|   `-- tiny.pt
|-- config.json
|-- latentsync_unet.pt  (~5GB)
|-- stable_syncnet.pt   (~1.6GB)

请确保所有这些文件都存在，以保证正常运行。主要模型文件包括：

• vae/diffusion_pytorch_model.safetensors：用于编码/解码的 Stable Diffusion VAE 模型。
• vae/config.json：VAE 配置文件。
• latentsync_unet.pt：在 512×512 分辨率下训练的主 LatentSync 1.6 模型。
• stable_syncnet.pt：用于口型同步监督的 SyncNet 模型。
• whisper/tiny.pt：用于音频处理的 Whisper 模型。

使用方法

1. 使用 AceNodes 视频加载器选择输入视频文件。
2. 使用 ComfyUI 音频加载器加载音频文件。
3. （可选）设置种子值以获得可重复的结果。
4. （可选）调整 lips_expression 参数以控制嘴唇运动的强度。
5. （可选）修改 inference_steps 参数以平衡质量和速度。
6. 连接到 LatentSync1.6 节点。
7. 运行工作流。

处理后的视频将保存在 ComfyUI 的输出目录中。

节点参数：

• video_path: 输入视频文件的路径
• audio: 来自 AceNodes 音频加载器的音频输入
• seed: 用于获得可复现结果的随机种子（默认值：1247）
• lips_expression: 控制嘴唇动作的表现力（默认值：1.5）
  • 值较高（2.0–3.0）：嘴唇动作更明显，更适合富有表现力的讲话
  • 值较低（1.0–1.5）：嘴唇动作更细腻，更适合平静的讲话
  • 该参数会影响模型的指导尺度，在自然度和唇形同步精度之间取得平衡
• inference_steps: 推理过程中去噪步骤的数量（默认值：20）
  • 值较高（30–50）：生成结果质量更好，但处理速度较慢
  • 值较低（10–15）：处理速度更快，但可能质量稍低
  • 默认值20通常能在质量和速度之间取得良好平衡

获得更好效果的建议：

• 提升至 512×512 分辨率：与 1.5 版本相比，LatentSync 1.6 能提供更加清晰的牙齿和嘴唇细节
• 对于需要清晰嘴唇动作的演讲或演示，可尝试将 lips_expression 参数调高至 2.0–2.5
• 对于日常对话，使用默认值 1.5 通常效果不错
• 如果发现嘴唇动作不自然或过于夸张，可适当降低 lips_expression 的值
• 不同语言和说话习惯可能需要不同的参数设置才能达到最佳效果
• 若追求更高质量且有充足时间，可将 inference_steps 提升至 30–50
• 对于快速预览或非关键性应用，可将 inference_steps 降至 10–15

已知限制

• 最适合清晰的正面人脸视频
• 目前不支持动漫或卡通风格的人脸
• 视频帧率应为 25 FPS（系统会自动转换）
• 整个视频中必须始终可见人脸
• 需手动下载模型：LatentSync 1.6 的模型托管在私有的 HuggingFace 仓库中，但也可通过 Google Drive 获取完整包
• 单独下载模型需要访问 ByteDance/LatentSync-1.6 的 HuggingFace 仓库

致谢

本项目基于以下内容进行非官方实现：

• 字节跳动研究院的 LatentSync 1.6
• ComfyUI

许可证

本项目采用 Apache License 2.0 许可证授权——详情请参阅 LICENSE 文件。

ComfyUI-LatentSyncWrapper 快速上手指南

ComfyUI-LatentSyncWrapper 是 ByteDance LatentSync 1.6 模型的非官方 ComfyUI 实现节点，专为 Windows 和 WSL 2.0 设计。它能够将视频唇形与音频输入进行高精度同步，显著提升了牙齿和嘴唇的清晰度，解决了旧版本的模糊问题。

⚠️ 重要升级提示 如果您之前安装过旧版本，必须完全卸载后才能安装 1.6 版：

1. 彻底停止 ComfyUI。
2. 删除整个文件夹：ComfyUI/custom_nodes/ComfyUI-LatentSyncWrapper/。
3. 按照下方步骤重新进行全新安装。切勿直接更新，否则会导致冲突。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

1. ComfyUI: 已安装并可正常运行。
2. FFmpeg: 必须安装在系统中并配置到环境变量 PATH。
   • Windows 用户: 推荐从 GitHub Releases 下载 ffmpeg-master-latest-win64-gpl.zip，解压后将 bin 目录路径添加到系统环境变量 Path 中。
3. 硬件要求: 建议显存至少 20GB (如 RTX 3090)，优化后可在较低显存下运行较长视频。

安装步骤

1. 克隆仓库与安装依赖

打开终端（CMD 或 PowerShell），进入 ComfyUI 的 custom_nodes 目录执行以下命令：

cd ComfyUI/custom_nodes
git clone https://github.com/ShmuelRonen/ComfyUI-LatentSyncWrapper.git
cd ComfyUI-LatentSyncWrapper
pip install -r requirements.txt

注：国内用户若遇到 pip 下载慢的问题，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 参数加速。

2. 手动下载模型文件

由于 LatentSync 1.6 模型托管在受限的 HuggingFace 仓库，必须手动下载模型文件并放置到指定目录。

请在 ComfyUI-LatentSyncWrapper 目录下创建 checkpoints 文件夹，并按以下结构存放文件：

A. 下载 VAE 模型

1. 创建目录：mkdir checkpoints/vae
2. 访问地址：https://huggingface.co/stabilityai/sd-vae-ft-mse/tree/main
3. 下载以下两个文件并放入 checkpoints/vae/：
   • diffusion_pytorch_model.safetensors
   • config.json

B. 下载 LatentSync 1.6 主模型

1. 访问地址：https://huggingface.co/ByteDance/LatentSync-1.6/tree/main
   • 注意：您可能需要登录 HuggingFace 并同意相关协议才能访问。
2. 下载该仓库下的所有文件。
3. 将文件直接放入 checkpoints/ 根目录（不要嵌套子文件夹）。

✅ 最终目录结构检查

安装完成后，您的目录结构应如下所示：

ComfyUI-LatentSyncWrapper/
└── checkpoints/
    ├── vae/
    │   ├── config.json
    │   └── diffusion_pytorch_model.safetensors
    ├── whisper/
    │   └── tiny.pt (通常包含在主模型包中，若无需单独下载)
    ├── config.json
    ├── latentsync_unet.pt      (~5GB)
    └── stable_syncnet.pt       (~1.6GB)

基本使用

安装完成并重启 ComfyUI 后，即可在工作流中使用该节点。

最简单工作流示例

1. 加载视频: 使用 AceNodes Video Loader (或其他兼容的视频加载节点) 加载输入视频。
   • 建议: 视频最好为正面清晰人脸，帧率会自动转换为 25 FPS。
2. 加载音频: 使用 ComfyUI 自带的音频加载节点加载对应的音频文件。
3. 添加核心节点: 双击搜索并添加 LatentSync1.6 节点。
4. 连接线路:
   • 将视频输出连接到节点的 video_path 输入。
   • 将音频输出连接到节点的 audio 输入。
5. 调整参数 (可选):
   • seed: 随机种子，默认 1247。
   • lips_expression: 唇形表现力强度。
     • 1.0-1.5: 适合平静对话，动作自然 subtle。
     • 2.0-3.0: 适合演讲或激情表达，口型幅度更大。
   • inference_steps: 推理步数，默认 20。
     • 提高至 30-50 可获得更高质量但速度变慢。
     • 降低至 10-15 可加快预览速度。
6. 运行: 点击 "Queue Prompt" 开始生成。

生成的对口型视频将自动保存在 ComfyUI 的 output 目录中。