AIIA Nodes for ComfyUI

欢迎来到 AIIA Nodes for ComfyUI 仓库！这是一个旨在为 ComfyUI 提供一系列强大、直观且高度可定制的节点的集合。这些节点专注于简化复杂的工作流，并为创意工作者提供最大的灵活性。

本节点套件致力于解决 ComfyUI 工作流中的核心痛点。

🚀 全新旗舰节点：AIIA 媒体浏览器 🚀

还在费力地翻找 output 文件夹，或者对着一堆时间戳命名的文件猜内容吗？

我们隆重推出 AIIA 媒体浏览器——一个完全集成在 ComfyUI 内部的、功能完备的媒体文件管理中心。它的诞生，旨在彻底改变你管理和使用生成结果的方式，让整个过程变得高效、直观且充满乐趣。

✨ 为何选择 AIIA 浏览器？

告别猜测： 无需离开 ComfyUI 即可即时预览图片、视频和音频。
为性能而生： 专为处理包含数千乃至数万个文件的海量输出文件夹而设计，极致流畅，拒绝卡顿。
精美且直观： 拥有现代化的用户界面，与 ComfyUI 原生主题无缝融合，宛若天生。

核心亮点

1. 强大的核心功能

一键加载工作流: 直接从浏览器中加载任何图片、视频或工作流文件，瞬间恢复你的创作环境。
直接下载文件: 无需再打开系统文件夹，一键下载你需要的任何文件。
内容丰富的工具提示 (Tooltip): 将鼠标悬停在任何文件或文件夹上，即可看到包含详细元数据（尺寸、时长、日期等）的浮窗，甚至还能 直接在浮窗里预览图片、视频和音频！
高级排序与筛选: 按 名称、日期、大小、类型、尺寸或时长 对文件进行排序，并可选择隐藏文件夹，总能快速找到你想要的。

2. 顶级的界面与用户体验

双视图模式： 可在经典的 图标视图（支持缩放）和信息详尽的 列表视图 之间一键切换。
沉浸式全屏查看器： 双击文件即可进入一个独立的媒体查看器。支持视频/音频播放、用于快速导航的胶片缩略图，并提供多种导航方式（鼠标滑动、滚轮、键盘方向键和长按按钮）。
全键盘导航： 为高级用户设计，你可以完全通过键盘在文件夹之间穿梭、选择文件、打开预览、显示/隐藏工具提示，实现真正的“效率流”操作。
交互式路径与面包屑导航： 通过可点击的面包屑轻松跳转目录，或直接输入路径进行导航。

3. 无与伦比的性能与技术

高性能后端： 基于 Python 的异步后端，利用 ffmpeg 和 Pillow 进行即时的缩略图与视频海报生成。
智能缓存： 所有缩略图和元数据都会被智能缓存。浏览器仅在文件发生变化时才重新生成，确保后续加载瞬间完成。
懒加载与虚拟滚动： 我们在图标视图中使用 IntersectionObserver，在列表视图中实现 完全虚拟滚动。这意味着浏览器永远只渲染屏幕上可见的内容，即使面对上万个文件也能保持极低的内存占用和零延迟。
无阻塞元数据分析： 在列表视图中，浏览器会在后台批量分析视频时长、尺寸等元数据，并以进度条显示，完全不阻塞UI操作。

4. 灵活的自定义选项

在设置面板中，你可以根据习惯隐藏文件夹侧边栏，或开关视频预览功能。所有设置都会被自动保存。

🚀 核心设计理念：为大规模生成而生

本节点套件的另一个核心设计初衷，是为了攻克困扰许多用户的技术难题，特别是解决在生成长视频或处理大量图像帧时常见的内存不足（OOM）问题。

🌟 告别OOM：为处理海量帧而生

处理成百上千张高清图像帧时，轻易就会耗尽 VRAM 和系统内存，导致工作流中断。AIIA 节点通过 增量式处理（Incremental Processing） 的策略从根本上解决了这个问题。

v1.9.21+ 内存优化

自 v1.9.21 起，AIIA Body Sway 和 AIIA Video Combine 节点实现了激进的内存管理策略：

分批处理：每次只处理 50 帧，处理完立即释放中间变量。
逐帧释放：每帧转换后立即 del 并定期 gc.collect()。
GPU 内存同步释放：处理前移至 CPU 并调用 torch.cuda.empty_cache()。

这意味着即使处理 1500+ 帧的高分辨率视频（如 1288×1920），也能在合理的内存占用下完成，无需磁盘中转。

两种工作模式

我们提供了两种工作模式，以适应不同场景：

内存模式 (推荐): 直接将上游节点的 IMAGE 张量输入。v1.9.21+ 的优化使其可处理数千帧而不 OOM。
磁盘模式: 对于极端长序列或内存受限环境，仍可通过 frames_directory 从磁盘流式读取帧。

🔧 强大且可扩展的预设系统

通过简单的 JSON 文件，您可以完全自定义视频和音频的编码参数，并将其保存为可复用的格式预设。这使得高级用户可以轻松实现复杂的 FFmpeg 配置，而无需修改任何代码。

🛠️ 安装与先决条件

1. 安装 FFmpeg (视频与浏览器节点强依赖)

视频合并节点和媒体浏览器的视频功能依赖 ffmpeg 和 ffprobe。

访问 FFmpeg 官网下载并安装。
强烈建议将 FFmpeg 的 bin 目录添加到您系统的 PATH 环境变量中。
在终端中运行 ffmpeg -version 和 ffprobe -version 来验证安装。

2. 安装 SoX (VibeVoice 变速不变调必须)

VibeVoice 节点的 speed 参数依赖系统级 sox 命令。

Ubuntu/Debian: sudo apt-get update && sudo apt-get install -y libsox-dev sox
macOS: brew install sox
Windows: 下载 SoX 编译版并将目录添加到 PATH。

3. 安装 NeMo 模型 (音频AI节点必须)

音频处理节点（如说话人日志）依赖 NeMo 模型。

在 ComfyUI 的 models 目录下，创建一个名为 nemo_models 的子目录。最终路径应为 ComfyUI/models/nemo_models/。
从 NVIDIA NeMo 目录下载所需的 .nemo 模型文件。
- 基础模型: diar_sortformer_4spk-v1.nemo
- 流式模型 (v2.1): diar_streaming_sortformer_4spk-v2.1.nemo
将下载的 .nemo 文件放入 ComfyUI/models/nemo_models/ 目录中。

使用 huggingface-cli 下载 (推荐): nvidia/nemo-models 仓库很大，建议直接下载指定文件：

# 进入 ComfyUI/models 目录
cd ComfyUI/models
mkdir -p nemo_models

# 下载基础模型
hf download nvidia/nemo-models diar_sortformer_4spk-v1.nemo --local-dir nemo_models

# 下载流式模型
hf download nvidia/nemo-models diar_streaming_sortformer_4spk-v2.1.nemo --local-dir nemo_models

4. 安装本节点套件

进入 ComfyUI 的自定义节点目录，然后克隆本仓库：

cd ComfyUI/custom_nodes/
git clone https://github.com/havvk/ComfyUI_AIIA.git

最后，重启 ComfyUI。

✨ 可用节点

1. 媒体管理 (Media Management)

AIIA 媒体浏览器

安装并重启后，一个 "AIIA Browser" 按钮会出现在 ComfyUI 主菜单中。
点击即可启动浏览器。
尽情探索你的 output 目录吧！

2. 视频生成与合成 (Video Generation & Compositing)

2.1 视频合并 (AIIA, 图像或目录)

这是一个功能强大且高度可定制的视频合并节点，是您工作流中处理视频生成的终极解决方案。

核心亮点:

内存高效: 通过 frames_directory 输入，可以处理几乎无限数量的图像帧，完美解决了 OOM 问题。
直接张量输入: 接受上游节点的 IMAGE 张量，方便快速迭代和测试。
全面的音频控制: 支持 AUDIO 张量和外部文件，并提供对编解码器和码率的精细控制。
智能自动配置: auto 模式能自动应用格式预设中的音频参数，并能自动检测源文件的码率。
安全清理帧目录 (v1.11.1 New): cleanup_frames 开关（默认关闭）。开启后，视频合成成功时自动删除输入的 frames_directory。
- 防误删机制: 仅删除包含 .aiia_temp 标记文件的目录（由 AIIA 上游节点自动写入），用户自己提供的素材目录永远不会被误删。
- 合成失败时不执行任何删除操作，确保帧文件安全。

2.2 FLOAT 影片生成 (内存与磁盘模式)

这组节点封装了先进的 FLOAT 模型，能够根据参考图像和音频生成高质量的口型同步影片。我们提供了两种模式，以应对不同长度的生成需求。

1. Float Process (AIIA In-Memory)

用途: 用于生成短片、快速预览或直接与其他内存节点（如视频合并的 images 输入）连接。
输出: IMAGE 张量。
优势: 速度快，流程无缝。
限制: 受限于您的 VRAM 和系统内存大小，不适合生成长视频。

2. Float Process (AIIA To-Disk for Long Audio)

用途: 专门用于长音频的影片生成，是解决OOM问题的关键。
输出: STRING (包含所有生成帧的目录路径) 和 INT (帧总数)。
优势: 在解码过程中，节点以小批量方式处理帧并逐帧保存到磁盘，内存占用极低，可以处理任意长度的音频。
工作流: 此节点的输出目录可以直接作为 视频合并节点 的 frames_directory 输入，构建一个完整的、内存高效的 talking head 视频生成管线。

2.3 PersonaLive 视频驱动 (AIIA Integrated)

这组节点基于强大的 PersonaLive 模型，专为生成高质量的 Talking Head 视频而设计。我们将原版代码完全重构并集成到 ComfyUI 中，通过特有的分块处理和磁盘流式技术，彻底解决了长视频生成时的显存和内存溢出 (OOM) 问题。

1. PersonaLive Checkpoint Loader

用途: 加载所有必要的模型权重（Base Model, VAE, PersonaLive Weights）。
功能: 首次运行时会自动从 HuggingFace 下载所需模型，无需手动配置。

2. PersonaLive Photo Sampler (AIIA In-Memory)

用途: 标准生成模式，适合短视频或中等长度视频。
输出: IMAGE 张量（所有生成的帧）。
机制: 节点会自动将长视频切分为多个 Chunk 进行推理，每推理完一个 Chunk 就会清空显存，从而允许你在有限的显存下生成较长的视频。

3. PersonaLive Photo Sampler (AIIA To-Disk for Long Video)

用途: 专门用于超长视频生成。这是解决系统内存（System RAM）OOM 的终极方案。
输出: STRING (包含生成帧的目录路径) 和 INT (帧数)。
最佳实践: 将此节点的输出目录直接连接到 AIIA Video Combine 节点，即可实现从生成到合成的全流程 OOM-Safe。

2.4 EchoMimic V3 (AIIA Integrated)

这组节点集成了最新的 EchoMimic V3 (1.3B Parameters) 模型，它是目前开源界效果最惊艳的 Talking Head 解决方案之一。

特点:

多模态驱动: 支持 Audio Only (仅音频驱动) 和 Audio + Reference Pose (音频+参考姿态) 驱动。
自然度极高: 相比 float 等早期模型，V3 在头部运动、表情微表情的自然度上有巨大提升。
ComfyUI 原生: 我们将其封装为标准的 Loader 和 Sampler 节点，支持流式生成和内存优化。

1. EchoMimic V3 Loader

用途: 加载模型权重 (Transformer, VAE, Wav2Vec, etc.)。
参数:
- model_subfolder: 模型子目录名 (默认 Wan2.1-Fun-V1.1-1.3B-InP)。
- device: 指定运行设备 (CUDA)。

2. EchoMimic V3 Sampler

用途: 执行推理生成。
输入:
- ref_image: 参考人物图片 (建议 1:1 比例，如 768x768)。
- ref_audio: 驱动音频。
参数:
- cfg: 视觉引导系数 (默认 4.0)。
- audio_cfg: 音频引导系数 (默认 2.9)。
- enable_teacache: True (默认)。开启后生成速度提升 1.5 倍以上，且质量无损。
- keep_model_loaded: True (默认)。即使显存占用增加，也强制将模型保留在 GPU 上，显著减少多段视频生成时的加载时间。
- negative_prompt: 已内置优化过的 眼部修复 (Eye Correction) 提示词，有效防止翻白眼和眼神飘忽。

🚀 性能优化 (Performance):

Flash Attention 2: 强烈推荐安装。检测到时会自动启用，大幅提升推理速度。
TeaCache: 默认启用。通过缓存部分 Transformer 层计算，大幅加速生成。
Full GPU Mode: 默认启用。适合显存充足 (24GB+) 用户，享受极致流畅的生成体验。

🛠️ 模型下载指南 (Manual Download Guide)

由于 EchoMimic V3 模型较大且组件较多，目前不支持自动下载，请按以下步骤手动准备模型。

目标目录: ComfyUI/models/EchoMimicV3/

目录结构:

ComfyUI/models/EchoMimicV3/
├── Wan2.1-Fun-V1.1-1.3B-InP/     <-- 主模型目录
│   ├── transformer/
│   │   ├── config.json
│   │   └── diffusion_pytorch_model.safetensors
│   ├── vae/
│   │   ├── config.json
│   │   └── diffusion_pytorch_model.safetensors
│   ├── text_encoder/
│   ├── tokenizer/
│   ├── image_encoder/
│   └── scheduler/
└── wav2vec2-base-960h/           <-- 音频编码器 (必需)
    ├── config.json
    ├── pytorch_model.bin
    └── ...

下载地址:

主模型 (EchoMimicV3):
- HuggingFace: BadToBest/EchoMimicV3
- 下载命令 (推荐):
```
hf download BadToBest/EchoMimicV3 --local-dir models/EchoMimicV3/EchoMimicV3
```
- 注意：此模型包含 EchoMimic 特有的 Transformer 权重，是生成嘴型的核心。
底模 (Wan2.1-Fun-V1.1-1.3B-InP):
- HuggingFace: alibaba-pai/Wan2.1-Fun-V1.1-1.3B-InP
- 下载命令:
```
hf download alibaba-pai/Wan2.1-Fun-V1.1-1.3B-InP --local-dir models/EchoMimicV3/Wan2.1-Fun-V1.1-1.3B-InP
```
- 注意：作为 fallback 来源，提供 VAE、Text Encoder 和 Image Encoder权重。

音频编码器 (wav2vec2-base-960h):

HuggingFace: facebook/wav2vec2-base-960h

下载命令:

hf download facebook/wav2vec2-base-960h --local-dir models/EchoMimicV3/wav2vec2-base-960h

环境依赖:

请确保安装了 requirements.txt 中的依赖，如 diffusers>=0.30.1。节点加载时会尝试自动引用，但如果报错缺包，请手动安装。

2.5 Ditto Talking Head (AIIA Integrated)

这组节点集成了 Ditto 数字人模型。我们采用了 PyTorch 原生实现，避免了复杂的 TensorRT 编译过程，让用户能够“开箱即用”地生成高质量的 Talking Head 视频。

特点:

PyTorch Native: 无需安装 TensorRT，兼容性更好。
In-Memory Pipeline: 针对 ComfyUI 优化的内存内处理流程，无需生成中间视频文件。
自动模型管理: 支持自动下载模型权重。

1. AIIA Ditto Loader

用途: 下载并加载 Ditto 模型 (约 1.2GB)。
参数:
- model_name: 模型名称 (默认 ditto-talkinghead)。
- device: 运行设备 (CUDA/CPU)。

2. AIIA Ditto Sampler

用途: 执行推理生成。
输入:
- pipe: 来自 Loader 的模型管道。
- ref_image: 参考人物图片 (建议正方形，人脸居中)。
- audio: 驱动音频。
- fps: 建议 25 (Ditto 针对 25FPS 训练)。即使输入其他值，目前内部逻辑也会优先保证 25FPS 的同步率。
输出: IMAGE (视频帧), AUDIO。
高级参数 (Advanced Parameters):
- seed: 随机种子 (Random Seed)。
  - 控制扩散模型的噪声生成。
  - 关键作用: 在长语音生成中，当触发“静音重置”时，种子会被重置，从而确保每一句话的生成条件都与第一句话完全一致，彻底消除“长语音嘴型漂移”和“对口型不准”的问题。
- crop_scale: (默认 2.3) 面部工作区视野 (Face Context Scale)。
  - 注意: 此参数不会改变输出视频的分辨率，它决定了模型“看”到了多少人脸周围的内容。
  - 数值越大 (如 2.5): 广角视野。模型能覆盖更多头发、脖子和背景。
    - ✅ 优点：适合头部运动幅度大的场景，不容易出框。
    - ❌ 缺点：在固定的推理画布中，人脸占比变小，生成的五官细节（如牙齿、眼神）可能会变糊。
  - 数值越小 (如 2.0): 特写视野。模型聚焦于面部核心区域。
    - ✅ 优点：人脸占比大，五官细节极其清晰锐利。
    - ❌ 缺点：容易裁掉下巴或额头，头部大幅运动时可能会出现“断头”或伪影。
  - 推荐值:
    - 标准场景: 2.3
    - 大动态/全身/半身: 2.5 (牺牲细节换稳定性)
    - 大头照/证件照: 2.0 (追求极致细节)
- emo: (默认 Neutral) 表情控制。可选 Angry, Happy, Sad 等。
- drive_eye: (默认 True) 是否驱动眼睛。关闭后眼睛将保持参考图状态(或微动)，适合原图眼神较好的情况。
- chk_eye_blink: (已废弃，请使用 blink_mode)。
- blink_mode: (默认 Natural) 眨眼模式控制。
  - Natural: 拟人化随机眨眼。
    - 基础频率：90-150帧/次 (约 3.6s - 6.0s)。
  - Slow: 慢速沉稳眨眼 (120-200帧/次)。
  - Fast: 快速频繁眨眼 (10-40帧/次)。
  - None: 彻底关闭眨眼。
- blink_amp: (v1.9.1 New) 眨眼幅度控制。
  - 1.0 (默认): 标准闭眼幅度。
  - < 1.0 (推荐 0.8): 适合男性角色或眼睛较小的人物，避免“用力挤眼”的感觉。
  - > 1.0: 加深闭眼力度。
- mouth_amp: (v1.9.1 New) 嘴型幅度控制。
  - 1.0 (默认): 标准嘴部开合幅度。
  - > 1.0 (推荐 1.1-1.2): 适合大声说话或需要更夸张表情的场景，增强口型辨识度。
  - < 1.0: 适合轻声细语。
- relax_on_silence: (默认 True) 静音归位 (Relax Face on Silence)。
  - 结合下方的 silence_release 参数，针对静音片段进行平滑过渡（慢速闭合），避免“紧绷抿嘴”。
  - 智能预测 (Predictive Logic): 自动识别短停顿（如逗号）与长静音（如句号）。短停顿不触发闭嘴动画，由模型自由发挥；长静音则触发优雅的慢速闭合。
  - 防止累积误差 (Drift Correction):
    - 精密网格对齐 (Exact Onset Alignment): 将模型的时间步长精确对齐到语音的开始（Onset），而不是固定的处理块。
    - 状态重置 (State & RNG Reset): 在长静音后，强制重置模型状态和随机种子，确保每一句话的生成质量一致，彻底消除“长语音嘴型漂移”。
- silence_release: (v1.9.2 New) 静音闭嘴速度 (Adsr Release Control)。
  - Natural (0.8s) [默认]:
    - 自然平衡模式。适合大多数常速对话。
    - 触发阈值: >0.88s。
  - Fast (0.5s):
    - 快速响应模式。适合语速极快、充满激情的演讲。
    - 触发阈值: >0.56s。
  - Deep (1.3s):
    - 深沉模式。适合朗诵、讲故事或情感类内容。超长尾韵，极度平滑。
    - 触发阈值: >1.4s。
- ref_threshold: (默认 0.005) 静音检测相对阈值 (Relative Silence Threshold)。
  - 现在的阈值是基于全段音频峰值音量的比例 (例如 0.005 = 0.5% 的峰值音量)。
  - 这意味着无论音频整体是大声还是小声，系统都能自动适应，准确捕捉微弱的语音片段。
  - 只有低于此比例的音量才会被视为静音。
- smo_k_d: (默认 3) 运动平滑系数。数值越大动作越柔和，可抑制面部抖动。
- hd_rot_p / y / r: 头部旋转微调 (Pitch/Yaw/Roll)。
- speech_pitch: (v1.10.0 New) 说话时俯仰角补偿 (Speech Pitch Offset)。
  - 用于修正"说话时头抬得太高"或"需要低头说话"的场景。此偏移量仅在说话期间生效，并随语音强度平滑切入切出。
  - 正值 (+) = 低头 (Look Down)。例如 5.0 表示说话时微微低头。
  - 负值 (-) = 抬头 (Look Up)。
- mouth_smoothing: (v1.9.5 New) 嘴型惯性平滑 (Mouth Motion Inertia)。
  - 防止模型输出的嘴型瞬间开合（如爆破音时），增加物理惯性感。
  - None (Raw): 无平滑，模型原始输出。追求极致对口型，容忍偶尔快速开合。
  - Light (0.3): 轻微平滑，推荐快语速使用。
  - Normal (0.5) [默认]: 适中平滑，常规对话推荐。
  - Heavy (0.7): 强力平滑，适合低质量音频或模型输出抖动严重的情况。
- save_to_disk: (v1.9.24 New) OOM 安全模式 (OOM-Safe Mode)。
  - Memory (Default): 传统模式，所有帧保存在内存中。适合短视频（<1000帧）。
  - Disk (OOM-Safe): 长视频推荐。边生成边保存到磁盘，无 OOM 风险。
  - 选择 Disk 模式时，frames_dir 输出会包含帧保存路径，可直接连接 AIIA Video Combine 节点的 frames_directory 输入。
  - ⚠️ Disk 模式下 images 输出为占位符，请使用 frames_dir 连接后续节点。
输出:
- images: 生成的视频帧序列（Memory 模式）或占位符（Disk 模式）。
- audio: 透传的音频。
- frames_dir: (v1.9.24 New) Disk 模式下的帧保存路径。Memory 模式下为空字符串。

🛠️ 模型下载指南 (Manual Download Guide)

如果自动下载失败，请手动下载模型并放入 ComfyUI/models/ditto/ 目录。

目标目录结构:

ComfyUI/models/ditto/
├── ditto_pytorch/
│   ├── audio2motion.pth
│   ├── ...
└── ditto_cfg/
    ├── v0.4_hubert_cfg_pytorch.pkl
    ├── ...

下载地址:

HuggingFace: digital-avatar/ditto-talkinghead

下载命令:

# 进入 models 目录
cd ComfyUI/models

# 下载模型 (直接下载到 ditto 目录，避免多层嵌套)
hf download digital-avatar/ditto-talkinghead --local-dir ditto

2.6 身体微动后处理 (Body Sway Post-Processing)

这个轻量级后处理节点可以为 Ditto 等 Talking Head 模型的输出添加模拟的身体晃动效果，让人物看起来更加自然、有呼吸感。

工作原理:

通过裁切平移 + 轻微旋转模拟人体站立或坐着时的自然重心漂移和呼吸起伏。
使用多频正弦波叠加（基于黄金比例）生成平滑、有机的运动轨迹。
纯裁切方式，不放大图像，保持原始画质。

AIIA Body Sway 节点

输入:
- images (可选): 来自 Ditto 等节点的视频帧张量 (Memory 模式)
- frames_directory (可选, v1.9.25 New): 帧目录路径 (Disk 模式，连接 Ditto 的 frames_dir 输出)
参数:
- crop_ratio: (默认 0.99) 输出尺寸占输入的比例。
  - 0.99 = 保留 99%，晃动幅度较小 (推荐)
  - 0.98 = 保留 98%，晃动幅度中等
  - 支持三位小数 (如 0.995)
- rotation_amplitude: (默认 0.1) 最大旋转角度 (度)。
- smoothness: (默认 0.02) Perlin 噪声平滑度。数值越小，运动越缓慢。
- seed: 控制随机轨迹。
输出:
- images: 应用了微动效果的帧 (Memory 模式) 或占位符 (Disk 模式)。
- output_frames_dir (v1.9.25 New): Disk 模式下处理后的帧保存路径。

Note

v1.9.17 改进：使用 Perlin 噪声 替代正弦波，运动更有机自然。已移除垂直方向位移，减少叠加 Ditto 头部运动时的"晕船"感。

Tip

OOM-Safe 工作流 (v1.9.24+): Ditto (Disk) → BodySway (frames_directory) → VideoCombine (frames_directory)，全流程无 OOM 风险。 性能无损 (v1.9.28+): 采用并行 I/O 和零压缩策略，Disk 模式生成速度与 Memory 模式完全一致 (~30fps+)，且极大降低 RAM 占用。强烈推荐长视频生成使用！ 自动清理 (v1.11.1 New): 开启 VideoCombine 的 cleanup_frames 后，中间帧目录会在合成成功后自动删除，无需手动清理磁盘。

3. 音频智能处理 (Intelligent Audio Processing)

3.1 说话人日志 (Diarization)

这组节点利用 NeMo Sortformer E2E 模型，为您的音频提供先进的说话人识别功能。在4090RTX显卡上只需2秒钟就能完成10分钟音频的声纹分割聚类任务。

1. AIIA Generate Speaker Segments

用途: 对一段音频进行分析，找出“谁在什么时候说话”。
输入: AUDIO 张量。
输出: WHISPER_CHUNKS (一个结构化的数据，包含一系列带有说话人标签的时间片段，如 SPEAKER_00, SPEAKER_01 等)。
亮点: 提供多种后处理配置（从宽松到严格），让您可以微调分割的灵敏度，以适应不同质量的音频。

2. AIIA E2E Speaker Diarization

用途: 将 Generate Speaker Segments 的识别结果精确地应用到由 Whisper 等工具生成的、带有文本的 WHISPER_CHUNKS 上。
输入: WHISPER_CHUNKS (来自文本转录节点) 和 AUDIO 张量。
输出: 更新后的 WHISPER_CHUNKS，其中每个文本块都已被赋予了最匹配的说话人标签。
工作流: (音频) -> Whisper -> (文本Chunks) + (音频) => E2E Diarizer => 最终带有说话人标签的文本稿。

3.2 说话人隔离与合并 (Speaker Isolation & Merger)

Audio Speaker Isolator (AIIA)

用途: 根据说话人日志（Diarization）产生的 JSON 数据，从原始音轨中精确提取属于特定说话人的声音。
输入:
- audio: 原始音频张量。
- whisper_chunks: 由 Diarization 节点生成的 JSON 片段数据。
- speaker_label: 要提取的说话人 ID（例如 "SPEAKER_00"）。
- isolation_mode:
  - Maintain Duration (推荐): 输出与原音频等长的音轨，非目标说话人部分填充静音。这对于 视频驱动（Talking Head） 工作流至关重要，能确保口型与原视频时间轴严格对齐。
  - Concatenate: 将属于该说话人的所有片段无缝拼接在一起，去除中间的空隙。
亮点:
- 防爆音: 内置微小的淡入淡出（Fade In/Out）处理，确保片段边缘自然顺滑。
  - 时间对齐: 专门针对 AIIA 视频节点套件优化，保证音画同步。

Audio Speaker Merger (AIIA)

用途: 将两段不同的音频流合并为一条。通常用于在分别对不同说话人进行视频驱动后，将各自的音轨重新混缩。
输入:
- audio_1, audio_2: 待合并的两段音频。
- duration_mode:
  - Longest: 输出时长等于两段音频中的最大值。
  - Shortest: 输出时长等于两段音频中的最小值。
  - Audio 1 / Audio 2: 严格跟随特定输入段的时长。
  - Specified: 手动指定输出秒数。
  - normalize: 开启后将自动防止音量叠加导致的破音。

3.3 智能切片 (Smart Chunking)

Audio Smart Chunker (Silence-based)

用途: 全量扫描长音频，寻找最优切片方案。
机制:
- 全局静音扫描: 自动识别音频中的天然停顿区间。
- 贪心优化算法: 在不超出设定时长（如 27s）的前提下，计算出能让每一刀都切在静音处的片段序列。
输出: 供 Voice Conversion (AIIA Unlimited) 使用的 whisper_chunks 引导数据。
协同优势: 预先规划好切点，避免转换节点在词句中间暴力切分，是彻底消除拼接毛刺的关键。

3.4 Voice Conversion (AIIA Unlimited) (CosyVoice 增强)

1. CosyVoice Model Loader (AIIA)

用途: 不需要安装任何其他第三方节点，直接加载 CosyVoice 模型。
功能:
- 自动安装依赖: 首次运行时会自动安装 cosyvoice 及其依赖环境。
- 自动下载模型: 选择模型后，首次运行会自动从 HuggingFace 下载模型权重。
- 支持模型:
  - Fun-CosyVoice3-0.5B-2512 (最新 CosyVoice 3.0, 推荐)
  - CosyVoice2-0.5B (CosyVoice 2.0)
  - CosyVoice-300M 系列 (SFT, Instruct, TTSFRD)

输出: COSYVOICE_MODEL (专为 AIIA Voice Conversion 节点优化)。

✅ 依赖版本兼容性 (Dependency Compatibility): CosyVoice 对 transformers 和 PyTorch 版本敏感。AIIA 已内置深度兼容层，完美支持最新版本的 transformers。

依赖	兼容版本	备注
transformers	全版本兼容 ✅	AIIA 内置 Qwen2Encoder 兼容层，自动适配新旧版本
PyTorch	≤ 2.8.1 ✅ / ≥ 2.10.0 ✅	2.9.x ❌ (PyTorch regression bug)

[!NOTE] transformers > 4.53 重写了 Qwen2Model.forward() 的注意力掩码和隐藏状态输出，导致原版 CosyVoice 生成乱码。AIIA 通过手动逐层迭代 + SDPA 专用掩码 + POST-norm 输出还原，完全绕过了不兼容的新接口，确保与原始训练行为 100% 一致。

如遇到 PyTorch 2.9.x 导致的问题，请升级：

pip install torch==2.10.0 torchaudio==2.10.0 --index-url https://download.pytorch.org/whl/cu128

⚠️ 模型下载问题 (Model Download Issues): 如果遇到自动下载卡顿或失败，请手工下载模型文件夹，并将其放入 ComfyUI/models/cosyvoice/ 目录中。

目录结构示例 (Directory Structure): 请注意：文件夹名称建议与下方列表保持一致（即去除 FunAudioLLM/ 前缀）。

ComfyUI/models/cosyvoice/
├── Fun-CosyVoice3-0.5B-2512/  <-- 对应选项 FunAudioLLM/Fun-CosyVoice3-0.5B-2512
│   ├── cosyvoice.yaml
│   ├── model.pt
│   └── ...
├── CosyVoice2-0.5B/           <-- 对应选项 FunAudioLLM/CosyVoice2-0.5B
└── CosyVoice-300M/            <-- 对应选项 CosyVoice-300M

下载地址 (Download Sources):

ModelScope (魔搭社区) (搜索 CosyVoice)
HuggingFace - FunAudioLLM

使用命令行快速下载 (CLI Examples):

[!TIP] 国内用户推荐使用 ModelScope (魔搭)，下载速度更快且无需代理。

1. 使用 ModelScope (推荐):

# 进入 ComfyUI/models/cosyvoice 目录
cd ComfyUI/models/cosyvoice

# 下载 CosyVoice 3.0 (0.5B - 推荐)
modelscope download --model FunAudioLLM/Fun-CosyVoice3-0.5B-2512 --local_dir Fun-CosyVoice3-0.5B-2512

# 下载 CosyVoice 2.0 (0.5B)
modelscope download --model iic/CosyVoice2-0.5B --local_dir CosyVoice2-0.5B

# 下载 CosyVoice 300M 系列 (V1)
modelscope download --model iic/CosyVoice-300M --local_dir CosyVoice-300M
modelscope download --model iic/CosyVoice-300M-SFT --local_dir CosyVoice-300M-SFT
modelscope download --model iic/CosyVoice-300M-Instruct --local_dir CosyVoice-300M-Instruct

2. 使用 HuggingFace:

# 下载 CosyVoice 3.0 (0.5B)
huggingface-cli download FunAudioLLM/Fun-CosyVoice3-0.5B-2512 --local-dir Fun-CosyVoice3-0.5B-2512

# 下载 CosyVoice 2.0 (0.5B)
huggingface-cli download FunAudioLLM/CosyVoice2-0.5B --local-dir CosyVoice2-0.5B

# 下载 CosyVoice 300M 系列 (V1)
huggingface-cli download FunAudioLLM/CosyVoice-300M --local-dir CosyVoice-300M
huggingface-cli download FunAudioLLM/CosyVoice-300M-SFT --local-dir CosyVoice-300M-SFT
huggingface-cli download FunAudioLLM/CosyVoice-300M-Instruct --local-dir CosyVoice-300M-Instruct

2. Voice Conversion (AIIA Unlimited)

用途: 增强版语音转换节点，解决了原版 CosyVoice3 只能转换 30 秒内语音的限制。
🔥 核心突破: 全球首个突破时长限制的 ComfyUI 节点。通过创新的静音点智能切片技术，本节点彻底突破了 CosyVoice 3 官方模型“建议 20 秒、最长 60 秒”的生成限制。它实现了真正无限时长的音色克隆，且拼接处自然无痕，完美满足长篇教学视频、有声书等专业制作需求。
创新设计 (创新亮点):
- 语义感知切片 (Semantic-Aware Chunking): 节点可选接入 whisper_chunks 数据。它能智能识别每句话之间的“缝隙”，优先在说话人停顿的天然空隙处进行切分，从根本上避免了“在单词中间切开”导致的违和感。
- 牺牲上下文无缝拼接 (Sacrificial Context Stitching): 针对生成式模型在重叠区域的相位不稳定性，我们在拼接时采用“牺牲上下文”策略。即利用重叠区域作为生成引导，但在最终拼接时丢弃前一片段的“尾部”，仅保留极短的 Cross-fade（约 50ms），从而彻底消除长音频拼接处的“发虚”和回声感。
- 双层寻点算法: 在语义缝隙确定的候选范围内，算法会自动进行微秒级的物理静音探测（基于能量平滑曲线），确保切点处于绝对静默状态。
输入:
- model: 连接 CosyVoice Model Loader (AIIA) 的输出。
- source_audio: 待转换的源音频（支持任意时长）。
- whisper_chunks (可选): 接入 Diarization 节点数据，开启语义感知切片。
- target_audio: 目标音色参考音频（自动截取前 30 秒）。
- chunk_size: 目标切片大小（默认 25 秒）。
- overlap_size: 重叠大小，用于平滑衔接。

3.5 CosyVoice 3.0 TTS (AIIA) (全版本集成文本转语音)

用途: 一个节点通连 CosyVoice 全系列模型 (V1, V2, V3)，支持从纯文字描述生成到高保真音色克隆的全场景需求。
🔥 核心架构优势:
- 全版本自适应 (Version-Agnostic): 自动根据 Model Loader 加载的模型版本切换底层推理逻辑。无论是老牌的 300M 系列还是最新的 V3 0.5B 模型，均能获得最佳表现。
- 300M-Instruct (V1) 专项修复:
  - 指令跟随 (Fixed): 已修复指令读出问题。
  - 能力矩阵:
    - ✅ 支持: 情感 (Emotion), 语速 (Speed), 基础性别 (Gender)。
    - ⚠️ 注意: 请务必使用 英文指令 (如 "Sad tone", "Fast speed") 以确保生效。中文指令可能被忽略。
    - ❌ 不支持: 方言 (Dialect)。300M-Instruct 模型无法通过指令修改方言。
- V3 稳定性引擎: 深度适配 V3 模型的推理协议。内置自动补全机制，确保在任何配置下（即使缺少参考音频或内部音色）都能稳定运行，杜绝 AudioDecoder 和 KeyError 等常见崩溃。
- 无限长文本支持 (Streaming Architecture): 与 VibeVoice (类 GPT) 存在 8K/32K Token 上限不同，CosyVoice 采用流式架构，理论支持无限长文本输入的连续生成。系统会自动按句切分流式合成，适合长篇有声读物生成。
🚀 五种核心生成模式:
1. 风格/情感建模 (Instruct): 文字 + 描述。通过文字描述（如“非常开心地说”、“四川话”、“语速极快”）来控制生成的表现力。
2. 音色克隆 (Zero-Shot): 文字 + 音频。通过极短的参考音频，完美复现目标说话人的身份和音色特征。
3. 混合控制 (Hybrid): 音频 + 描述。在克隆音色的基础上，通过描述词改变情感或方言。
4. 跨语言 (Cross-Lingual): 让你的克隆音色流利说出 9 种语言。
5. 固定 ID (SFT): 直接选取模型内置的高保真音色（如 V3 的原生 01 序列）。
💡 进阶使用建议:
- V3 推荐用法: 优先通过 reference_audio 提供一个高音质片段。V3 模型对比 V1 有质的飞跃，其对音质的还原度和表现力极高。
- 描述词技巧: 尽量使用具体的场景化描述（例如“在大雨中嘶吼”或“温柔的枕边话”），V3 模型能捕捉到极其细微的情感波动。
- 种子音频回退: 在“描述生成 (Instruct)”模式下，若不提供参考音频，系统将使用内置的高保真种子作为底色。可以通过切换 base_gender 来获取不同的基础人声方向。

3.6 智能音频增强 (Audio AI Enhance) (推荐)

用途: 专为 CosyVoice 等生成式语音设计的增强器。它基于 resemble-enhance 强大的 Conditional Flow Matching (CFM) 模型，能同时完成后处理降噪和超分辨率（Bandwidth Extension）。
核心能力: 将任意低采样率（如 22kHz, 16kHz）的输入音频，重构为 44.1kHz 的高保真音频。

参数详解:

mode:
- Enhance (Denoise + Bandwidth Ext): (推荐) 同时去除底噪并提升音质。
- Denoise Only: 仅去除噪声，不改变音质。
solver: 推理求解器。
- Midpoint (默认): 速度与质量的最佳平衡。
- RK4: 质量最高，但速度慢 2 倍。
- Euler: 速度最快，但可能产生条纹。
nfe (Steps): 迭代步数。
- 32: 快速预览。可能会有残留条纹。
- 64: (推荐) 标准质量。
- 128: 极高画质，消除所有细微伪影，但耗时。
tau (Temperature): 先验温度 (默认 0.5)。
- 控制生成过程的“创造力”。
- 0.5 为平衡点。如果声音发虚，尝试降低到 0.3。
denoise_strength (去噪强度) :
- 范围 0.0 - 1.0。默认 0.5。
- 0.0: 保留所有原始底噪。
- 1.0: 强力去噪。
- Tip: 如果你在频谱图的低频部分看到 水平条纹 (Hum/Buzz)，请将此值提高到 0.8 - 1.0。
high_pass_hz (高通滤波) 🔥 新增 (v1.4.82):
- 范围: 0 - 1000 Hz。默认 0 (关闭)。
- 作用: 在 AI 增强之前，直接切除指定频率以下的低频信号。
- 为什么需要它？: 如果 denoise_strength=1.0 仍无法消除低频条纹，说明 AI 把这些噪音当成了“真实信号”进行增强。
- 最佳实践: 遇到顽固的低频条纹时，设置 60 - 80 Hz。
- 安全: 只要保持默认为 0，此功能完全禁用，对原音质零影响。
chunk_seconds / overlap_seconds:
- 30s / 1s: (推荐) 4090 等显卡的最佳平衡点。
- 注意: 首次运行时，模型会进行 JIT 编译（约60秒）。请耐心等待，这只发生一次。

依赖: 首次运行会自动安装 resemble-enhance。

3.7 智能音频降噪 (VoiceFixer) (Legacy)

用途: 用于修复严重受损的音频（如老电影、严重削波或极强背景噪）。
注意: 对于 CosyVoice 生成的较干净语音，不推荐使用此节点，因为它通过重构方式修复，容易在干净语音上引入伪影（Spectral Stripes）。请优先使用 Audio AI Enhance。
参数:
- mode:
  - 0 (Full): 去噪 + 去混响 + 去破音 + 超分。适合质量最差的音频。
  - 1 (No DeClip): 去噪 + 去混响 + 超分。适合大多数情况。
  - 2 (Denoise Only): 仅去噪。
- use_cuda: 是否使用 GPU (推荐)。
依赖: 首次运行会自动安装 voicefixer 库。

⚠️ 模型下载问题 (Model Download Issues): 如果遇到下载卡顿或 PytorchStreamReader 报错，请尝试手工下载模型文件，并按以下结构放入 ComfyUI/models/voicefixer 目录中：

ComfyUI/models/voicefixer/
├── analysis_module/
│   └── checkpoints/
│       └── vf.ckpt  (466MB)
└── synthesis_module/
    └── 44100/
        └── model.ckpt-1490000_trimed.pt (135MB)

下载地址 (Download Links):

vf.ckpt: HuggingFace Mirror 或 Zenodo
model.ckpt-1490000_trimed.pt: HuggingFace Mirror 或 Zenodo

使用 huggingface-cli 下载 (CLI Example):

# 进入 ComfyUI/models/voicefixer 目录
cd ComfyUI/models/voicefixer

# 下载 vf.ckpt (注意路径)
hf download Diogodiogod/VoiceFixer-vf.ckpt vf.ckpt --local-dir analysis_module/checkpoints

# 下载 model.ckpt (注意路径)
hf download Diogodiogod/VoiceFixer-model.ckpt-1490000_trimed.pt model.ckpt-1490000_trimed.pt --local-dir synthesis_module/44100

3.8 Audio Post-Process (Resample/Fade/Norm)

用途: 音频后期处理“母带”节点。
功能:
- Resample: 使用高精度算法（sinc_interp_hann）将音频上采样至 44.1kHz 或 48kHz，改善听感清晰度。
- LowPass Filter: 可选的低通滤波器（默认 11000 Hz）。采用 6级级联（Cascaded） 设计，像“砖墙”一样强力消除由 CosyVoice 带来的高频混叠（Resampling Artifacts）。
- HighPass Filter: 可选的高通滤波器（默认 60 Hz）。采用 单级平滑 设计，在去除低频轰鸣声和直流偏移的同时，完美保留人声的低音厚度。
- Fade In/Out: 对音频首尾添加淡入淡出，消除由于切割或拼接可能残留的爆音。
- Normalize: 将音量标准化至 -1dB，确保输出响度饱满且不破音。
场景: 建议串联在 Voice Conversion 节点之后使用。

3.9 Audio Splice Analyzer (AIIA Debug)

用途: 可视化验证音频拼接质量。
功能:
- 生成 Log-Mel 语谱图 (Spectrogram)。
- 如果接入了 Voice Conversion 节点的 SPLICE_INFO 输出，会自动在图上用红线标记出所有拼接点的位置。
- 帮助用户直观地检查拼接点是否位于静音区，以及是否有明显的频谱断裂。
依赖: 需要 matplotlib 库。如果未安装，节点会生成一张提示错误的图片，不会导致工作流崩溃。

3.10 音频信息查看 (Audio Info & Metadata)

用途: 实时查看音频流的元数据，确保你的采样率符合预期。
输入: AUDIO 张量。
输出:
- info_text: 包含采样率、时长、通道数、BatchSize等详细信息的文本报告。
- sample_rate: 采样率 (INT)。
- duration: 时长秒数 (FLOAT)。
- channels: 通道数 (INT)。

3.11 Microsoft VibeVoice (Beta)

用途: 微软最新的 TTS/音色克隆模型，支持 1.5B 和 7B 两种规格。
当前状态: ✅ 可用（已通过测试）
支持语言: 英文 (en) 和中文 (zh)（官方仅在这两种语言数据集上训练）
可选模型:
- microsoft/VibeVoice-Realtime-0.5B: 最新实时版，极致速度，支持多种语言（如日、韩、英、中等），上下文 8K。推荐用于低延迟对话场景。
- microsoft/VibeVoice-1.5B: 轻量版，64K 上下文（~3GB 显存）。
- vibevoice/VibeVoice-7B: 高质量版，32K 上下文（~14GB 显存）。推荐用于生产环境。
特点:
- 多语言支持: 0.5B 版本支持比 1.5B/7B 更多的语言种类。
- 即时启动: 无需预热或编译，首次运行即可使用（CosyVoice 首次需 ~1 分钟编译）。
- 语言自动识别: 模型会自动识别中英文文本。
- 零样本音色克隆: 输入 reference_audio 即可克隆声音。参考音频会自动重采样到 24000Hz。
节点参数 (推荐参数建议):
- cfg_scale (默认: 1.3): CFG 引导强度。建议使用 1.3。
- ddpm_steps (默认: 20): 扩散步数。
- do_sample (默认: "auto"): 智能采样开关。
  - "auto": 自动适配。1.5B 模型默认关闭（保证稳定性），7B 模型默认开启（释放表达力）。
  - "true": 强制开启。如果 1.5B 开启后出现电音或逻辑混乱，请切换回 "auto"。
  - "false": 强制关闭（即 Greed Search）。
- temperature (默认: 0.8): 采样温度。仅在 do_sample 开启时有效。
- top_k / top_p: 采样约束。
- speed (默认: 1.0): 播放速度。
- do_sample: "auto" (或 false) - 保证极速和绝对稳定。
- normalize_text: True - 帮助处理各种语言的特殊符号。
- 特点: 该模型支持包括韩语、日语在内的更多语种，速度极快。

🔬 详细观察与进阶技巧

0.5B 实时版:
- 频谱特征: 在静音区域（Silence）可能在全部频率范围内观察到较高的能量分布，尤其在中频区域。
- 听感: 尽管频谱显示有能量，但实际听感比较干净，只有轻微的底噪。这表明其声码器可能存在某种特征泄露，但不影响实用性。
- 迭代次数: 由于基于音素（Phoneme）和流式切片处理，其显示的迭代次数（Total Steps）通常多于标准版，这是正常的。
1.5B vs 7B 对比:
- 音质与风格: 在参数调整得当（如开启 do_sample）的情况下，1.5B 模型生成的语音内容、风格和音质与 7B 模型几乎无法区分。
- 性价比: 1.5B 模型的推理速度约为 7B 的 2倍，显存占用仅为 1/4。除非对极细微的表达有极致要求，否则 1.5B 是生产环境的最佳选择。
- 迭代差异: 1.5B 的迭代次数（Token数）可能略少于 7B，这反映了不同模型对同一文本编码的简洁程度差异，属正常现象。

💡 7B 模型音质“全开”指南

要达到官方 Benchmark 的水准，请对 7B 模型尝试以下组合：

do_sample: True (开启采样)
temperature: 0.8 - 0.9
cfg_scale: 1.3 - 1.8
ddpm_steps: 20 - 50
normalize_text: False
环境要求:
- Flash Attention 2: 强烈推荐安装（否则速度较慢）。
- Transformers: >= 4.51（重要: 旧版本不支持该模型）。
节点:
- VibeVoice Loader: 加载模型。支持从 HuggingFace 自动下载，也支持加载本地模型。
- VibeVoice TTS: 支持 Zero-shot 音色克隆（输入 reference_audio 即可）。
模型准备 (Model Preparation): 如果遇到下载问题或分词器报错，请手动下载模型文件到 models/vibevoice 目录。

必须的文件结构 (以 1.5B 为例，7B 类似):
```
ComfyUI/models/vibevoice/microsoft/VibeVoice-1.5B/  # 或 VibeVoice-7B/
├── model-*.safetensors (模型权重)
├── config.json
└── [Tokenizer Files] (必须包含以下 Qwen 文件!)
    ├── tokenizer.json
    ├── tokenizer_config.json
    ├── vocab.json
    └── merges.txt
```
💡 说明: 插件已内置并修复了所有 VibeVoice 的 Python 核心代码 (vibevoice_core)。你不需要也不建议在模型目录中保留 modeling_vibevoice_*.py 等 Python 脚本，以避免潜在的冲突。

⚠️ 重要提示: VibeVoice 依赖 Qwen2.5 的分词器。如果模型包里没有 tokenizer 文件，请手动补全：
- 1.5B 模型使用 Qwen/Qwen2.5-1.5B 的 tokenizer
- 7B 模型使用 Qwen/Qwen2.5-7B 的 tokenizer

💡 VibeVoice 使用指南 (Node Usage Guide)

由于模型架构不同，我们现在提供 两个独立的 TTS 节点 以优化体验：

1. 🗣️ VibeVoice TTS (Standard)

适用模型: VibeVoice-1.5B, VibeVoice-7B
参考音频 (Reference Audio): 可选 (optional)。如果不连接，将自动使用内置的高品质女声种子 (Fallback Seed) 进行生成。
功能: 支持零样本音色克隆 (Zero-shot Cloning)。输入任何音频，它都会模仿该音色。
不支持: voice_preset (预设)。

2. 🗣️ VibeVoice TTS (Realtime 0.5B)

适用模型: VibeVoice-Realtime-0.5B
必选参数: voice_preset (音色预设) - 必须选择。
功能: 极速实时生成。基于预计算的 .pt 缓存文件生成语音。
不支持: reference_audio (直接克隆)。
特点:
- 极低延迟: 首包延迟极低，适合即时交互。
- BF16 加速: 自动使用 Bloat16 精度进行推理（如果硬件支持），大幅提升速度。
- 多语言支持: 官方预设涵盖英、日、韩、法、德等。

3. 🎤 VibeVoice Preset Maker (0.5B) (Experimental ⚠️)

用途: 尝试制作 0.5B 模型专用的 .pt 音色预设。
现状: 极不稳定。
原因: 社区反馈和测试表明，VibeVoice-Realtime-0.5B 模型的权重似乎对自定义音色进行了限制或未进行充分的 Zero-Shot 泛化训练。即使使用长达 1 分钟的高质量音频，生成时也极易出现死循环、胡言乱语或噪音。

建议:

首选: 请直接下载并在 Realtime 0.5B 节点中使用 微软官方提供的预设 (Carter, Emma 等)。
尝试: 如果您一定要克隆音色，请使用 VibeVoice 1.5B / 7B (Standard) 节点，它们原生支持完美的 Zero-Shot 克隆。
仅供研究: 此节点保留给开发者进行研究调试，普通用户不推荐使用。

手动下载命令:

# ===== 0.5B 实时多语言模型 (Realtime) =====
mkdir -p models/vibevoice/microsoft/VibeVoice-Realtime-0.5B
hf download microsoft/VibeVoice-Realtime-0.5B --local-dir models/vibevoice/microsoft/VibeVoice-Realtime-0.5B
# 补全 Tokenizer (使用 Qwen2.5-0.5B)
wget https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct/resolve/main/tokenizer.json -P models/vibevoice/microsoft/VibeVoice-Realtime-0.5B/
wget https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct/resolve/main/tokenizer_config.json -P models/vibevoice/microsoft/VibeVoice-Realtime-0.5B/
wget https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct/resolve/main/vocab.json -P models/vibevoice/microsoft/VibeVoice-Realtime-0.5B/
wget https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct/resolve/main/merges.txt -P models/vibevoice/microsoft/VibeVoice-Realtime-0.5B/

# 🔥 [重要] 下载 0.5B 官方音色库 (Voices Presets) 🔥
# 0.5B 模型必须配合官方音色预设使用，不支持零样本克隆。
# 请务必将以下文件下载到 `models/vibevoice/voices/streaming_model` 目录：
mkdir -p models/vibevoice/voices/streaming_model
cd models/vibevoice/voices/streaming_model

# 下载核心音色 (仅示例，全部音色请参考官方 GitHub)
# ⚠️ 注意：官方仓库目前暂未提供中文 (.pt) 预设，建议使用英文或日韩文测试，或自行制作预设。

# 英文 (English)
wget -N --no-check-certificate https://github.com/microsoft/VibeVoice/raw/main/demo/voices/streaming_model/en-Carter_man.pt
wget -N --no-check-certificate https://github.com/microsoft/VibeVoice/raw/main/demo/voices/streaming_model/en-Emma_woman.pt
# 日语 (Japanese)
wget -N --no-check-certificate https://github.com/microsoft/VibeVoice/raw/main/demo/voices/streaming_model/jp-Spk0_man.pt
wget -N --no-check-certificate https://github.com/microsoft/VibeVoice/raw/main/demo/voices/streaming_model/jp-Spk1_woman.pt
# 韩语 (Korean)
wget -N --no-check-certificate https://github.com/microsoft/VibeVoice/raw/main/demo/voices/streaming_model/kr-Spk0_woman.pt
wget -N --no-check-certificate https://github.com/microsoft/VibeVoice/raw/main/demo/voices/streaming_model/kr-Spk1_man.pt
# 更多语言 (德语 de, 法语 fr, 意大利语 it, 西班牙语 sp/es, 葡萄牙语 pt 等) 均支持！

# ===== 1.5B 基础模型 =====
mkdir -p models/vibevoice/microsoft/VibeVoice-1.5B
hf download microsoft/VibeVoice-1.5B --local-dir models/vibevoice/microsoft/VibeVoice-1.5B
# 补全 Tokenizer
wget https://huggingface.co/Qwen/Qwen2.5-1.5B/resolve/main/tokenizer.json -P models/vibevoice/microsoft/VibeVoice-1.5B/
wget https://huggingface.co/Qwen/Qwen2.5-1.5B/resolve/main/tokenizer_config.json -P models/vibevoice/microsoft/VibeVoice-1.5B/
wget https://huggingface.co/Qwen/Qwen2.5-1.5B/resolve/main/vocab.json -P models/vibevoice/microsoft/VibeVoice-1.5B/
wget https://huggingface.co/Qwen/Qwen2.5-1.5B/resolve/main/merges.txt -P models/vibevoice/microsoft/VibeVoice-1.5B/

# ===== 7B 模型 =====
mkdir -p models/vibevoice/vibevoice/VibeVoice-7B
hf download vibevoice/VibeVoice-7B --local-dir models/vibevoice/vibevoice/VibeVoice-7B
# 补全 Tokenizer (如果没有)
wget https://huggingface.co/Qwen/Qwen2.5-7B/resolve/main/tokenizer.json -P models/vibevoice/vibevoice/VibeVoice-7B/
wget https://huggingface.co/Qwen/Qwen2.5-7B/resolve/main/tokenizer_config.json -P models/vibevoice/vibevoice/VibeVoice-7B/
wget https://huggingface.co/Qwen/Qwen2.5-7B/resolve/main/vocab.json -P models/vibevoice/vibevoice/VibeVoice-7B/
wget https://huggingface.co/Qwen/Qwen2.5-7B/resolve/main/merges.txt -P models/vibevoice/vibevoice/VibeVoice-7B/

3.12 VoxCPM 1.5 TTS (Beta)

用途: 下一代 Tokenizer-free TTS 模型，提供 44.1kHz 原生高保真音质。
状态: Beta (骨架已上线，推理逻辑完善中)
手动下载指南 (Manual Download): 如果节点无法自动下载模型，请手动下载 openbmb/VoxCPM1.5 并放入以下目录：
```
ComfyUI/models/voxcpm/VoxCPM1.5/
├── model.safetensors
├── config.json
└── ... (其他相关文件)
```
HuggingFace 下载命令:
```
mkdir -p models/voxcpm/VoxCPM1.5
hf download openbmb/VoxCPM1.5 --local-dir models/voxcpm/VoxCPM1.5
```
降噪模型 (Optional Denoiser - ZipEnhancer): 默认开启 enable_denoiser 会自动从 ModelScope 下载 speech_zipenhancer_ans_multiloss_16k_base 到以下目录：
```
ComfyUI/models/voxcpm/speech_zipenhancer_ans_multiloss_16k_base/
```
如需手动下载（或离线使用）：
```
pip install modelscope
modelscope download --model iic/speech_zipenhancer_ans_multiloss_16k_base --local_dir models/voxcpm/speech_zipenhancer_ans_multiloss_16k_base
```
[!NOTE] 频谱特征说明 (Spectral Analysis Note): 用户实测发现，尽管该模型输出 44.1kHz 格式，但在频谱图上可能观察到以下特征：
1. 静音区能量较高 (High Noise Floor): 并非绝对静默。
2. 水平条纹 (Horizontal Stripes): 特别是在低频区域，这通常是 Neural Upsampling (VAE/GAN) 重构波形的典型痕迹。
3. 听感: 这种“升频痕迹”可能会带来轻微的机械感或金属音，这属于模型权重的固有特性。

💡 用户实测与选型指南 (Model Comparison & Selection)

经过深度测试，我们在三个主流模型中整理了以下对比，助您选择最适合的引擎：

维度	VoxCPM 1.5 (800M)	CosyVoice 3.0 (0.5B/1.5B)	VibeVoice (1.5B/7B)
音质 (Fidelity)	44.1kHz 格式 `<br>`虽然物理格式为 44.1k，但因采用 Neural Upsampling (神经升频) 技术，听感上会有含混 (Muffled) 或金属感，且伴有底噪。	优秀 `<br>`听感最自然，但采样率稍低 (22/24kHz)，有时需 AI 增强。	良好 `<br>`主要强在语气自然度，纯音质略逊。
推理速度 (Speed)	🚀 冠军 (RTF ~0.17)`<br>`得益于 Tokenizer-free，极其高效。	极快 `<br>`流式响应仅 150ms，且支持 TensorRT 加速。	一般/较慢 `<br>`7B 版本较重，更适合离线生成。
克隆能力 (Cloning)	SOTA (Zero-Shot)`<br>`只需 3-10秒，对音色质感还原极高。	SOTA (稳定性)`<br>`对说话韵律/口音的捕捉最准。	良好 `<br>`适合克隆特定语气，而非纯粹音色。
多语言/方言	中/英 (双语优化)	👑 霸主 (9种语言 + 18种方言)	中/英
语音转换 (VC) (Audio-to-Audio)	❌不支持 `<br>`仅支持 TTS (Text-to-Speech)。无法改变已有音频的音色。	✅支持 `<br>`可以将任意音频转换为任意音色 (保留语调/停顿)。	❌不支持 `<br>`纯 TTS 模型。仅支持 Text-to-Speech。
Qwen3-TTS (1.7B/0.6B)	✅支持 `<br>`支持 Presets (内置音色) 和 VoiceDesign (描述)。	✅支持 `<br>`支持 3秒极速 Clone (克隆) 模型。	✅支持 `<br>`支持 10 种语言。

3.13 Qwen3-TTS (New! 🔥)

用途: 阿里巴巴 Qwen 团队推出的最新旗舰级 TTS 模型，支持 10 种主要语言及多种方言，具备极高的稳定性和表现力。
核心能力:
- Base (Clone): 核心能力为 3秒极速音色克隆。支持 X-Vector 模式提升稳定性。
- CustomVoice (Presets): 阿里巴巴官方提供的 9 种高品质内置音色 (如 Vivian, Zack 等)，支持极强的情感和方言控制。
- VoiceDesign: 通过自然语言描述（如“活泼的少女音，带点羞涩”）从零设计音色。
环境要求:
- qwen-tts: pip install qwen-tts (插件会自动尝试安装)。
- Flash Attention 2: 强烈推荐以获得最佳推理性能。
节点:
- 🤖 Qwen3-TTS Loader: 加载模型。支持 Base (Clone)、CustomVoice (Presets) 和 VoiceDesign 模型。
- 🗣️ Qwen3-TTS Synthesis: 执行合成。支持单模型连接或通过 Router 连接的 Bundle。
- 🔌 Qwen3-Model Router (Bundle): [新] 路由节点。将多个分立的 Qwen 模型捆绑成一个，供对话节点自动调用。
- 🎙️ Qwen3-TTS Dialogue (Specialist): [旗帜级] 专为 Qwen3 设计的对话节点。单输入设计，支持通过 Router 实现混合克隆/捏人。
模型列表:
- Qwen/Qwen3-TTS-12Hz-1.7B-Base (或 0.6B-Base)
- Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice (或 0.6B-CustomVoice)
- Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign

📊 模型功能映射表 (Model Capability Mapping)

模型版本	音色克隆 (Clone)	情感控制 (Emotion)	文字捏人 (Design)	方言支持 (Dialect)
Base (1.7B/0.6B)	👑 最强	❌ 仅限录音自带	❌ 不支持	⚠️ 仅限录音自带
CustomVoice (1.7B)	⚠️ 效果极差	✅ 支持	⚠️ 指令干扰严重	⚠️ 效果一般
VoiceDesign (1.7B)	❌ 不支持	👑 专家	👑 专家	👑 完美支持
CustomVoice (0.6B)	⚠️ 效果极差	✅ 支持	✅ 表现优异	✅ 表现优异

Tip

关于 UI 简化：现在的对话节点只有一个 qwen_model 输入槽。

如果你只需要一种模型，直接连上即可。
如果你想实现“Speaker A 克隆，Speaker B 捏人”的混合效果，请使用 🔌 Qwen3-Model Router 节点进行打包连接。

Important

结论：

做 3秒音色克隆：必须连 Base 模型。
说方言或 文字定制音色：优先连 VoiceDesign（1.7B）或 CustomVoice（0.6B）。
使用 Vivian/Zack 内置音色：连接 CustomVoice 模型。

🛠️ 手工下载指南 (Manual Download Guide):

如果节点无法自动下载，或您需要在离线环境使用，请手动从 HuggingFace 或 ModelScope 下载模型文件夹，并放入以下目录（文件夹建议保留原名）：

ComfyUI/models/qwen_tts/Qwen/
├── Qwen3-TTS-12Hz-1.7B-Base/          <-- 对应 1.7B Base (Clone)
├── Qwen3-TTS-12Hz-1.7B-CustomVoice/   <-- 对应 1.7B CustomVoice
├── Qwen3-TTS-12Hz-1.7B-VoiceDesign/   <-- 对应 1.7B VoiceDesign
├── Qwen3-TTS-12Hz-0.6B-Base/          <-- 对应 0.6B Base (Clone)
└── Qwen3-TTS-12Hz-0.6B-CustomVoice/   <-- 对应 0.6B CustomVoice/VoiceDesign

下载命令 (HuggingFace CLI):

mkdir -p models/qwen_tts/Qwen

# 1.7B 系列
hf download Qwen/Qwen3-TTS-12Hz-1.7B-Base --local-dir models/qwen_tts/Qwen/Qwen3-TTS-12Hz-1.7B-Base
hf download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local-dir models/qwen_tts/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice
hf download Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign --local-dir models/qwen_tts/Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign

# 0.6B 系列
hf download Qwen/Qwen3-TTS-12Hz-0.6B-Base --local-dir models/qwen_tts/Qwen/Qwen3-TTS-12Hz-0.6B-Base
hf download Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local-dir models/qwen_tts/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice

ModelScope 下载 (国内推荐):

# 0.6B 示例
pip install modelscope
modelscope download --model qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice --local_dir models/qwen_tts/Qwen/Qwen3-TTS-12Hz-0.6B-CustomVoice

Note

对于 0.6B 系列，官方目前将 CustomVoice 和 VoiceDesign（文字设计）能力集成在同一个模型中。因此在设计模式下，加载 0.6B-CustomVoice 即可获得极佳效果。

🎭 掌握指令控制 (Instruct Control)

Qwen3-TTS 最强大的特性之一是其自然语言指令驱动的能力。与传统的“固定标签”不同，你可以直接在 instruct 输入框中用一段描述来控制声音的表现。

1. 情感与语气控制 (Emotion & Tone) 虽然官方没有强制的固定标签列表，但以下描述词被证明效果极佳（支持中文或英文）：

基础情感: "开心" (Happy), "悲伤" (Sad), "生气" (Angry), "兴奋" (Excited), "温柔" (Gentle), "严肃" (Serious)。
微表情控制 (New!): 在 Specialist 节点中，你可以叠加更细腻的语气，如 "带点羞涩的" (With a hint of shyness), "语气充满诱惑力" (Seductive tone), "语气带着哭腔" (Crying tone), "语气充满笑意" (Cheerful tone) 等。
提示: 这些指令可以组合，例如 生气且激动的。 或 Very happy and excited.

2. 语速与节奏 (Prosody) 虽然节点有专门的 speed 滑块，但通过 instruct 可以实现更自然的节奏控制：

"语速极快" (Very fast speaking rate), "缓慢且深情地" (Slow and soulful), "中间有明显的停顿" (Dramatic pauses)。

3. 音色设计 (Voice Design) 在加载 VoiceDesign 模型时，指令框即为你的“捏人”引擎：

特征描述: "沙哑的男低音" (Raspy deep male voice), "甜美的少女音" (Sweet young girl's voice), "充满磁性的中年女性" (Magnetic middle-aged female)。
示例: A young woman with a clear, bright voice, speaking with great confidence.
示例: A young woman with a clear, bright voice, speaking with great confidence.
方言与口音 (Dialect & Accent):
- 虽然官方称全系列支持，但实测发现不同模型遵循度不同：
- VoiceDesign (1.7B/0.6B-Custom): 👑 效果最强。因为没有固定身份限制，能完美呈现粤语、上海话等方言的韵律。
- CustomVoice (Presets): 效果一般。由于 Vivian 等音色有固定的标准语设定，方言指令常会被弱化以维持音色一致性。
- Base (Clone): 效果最弱。主要取决于你的参考音频本身是什么口音。

4. 使用技巧:

句尾符号: 指令末尾建议加一个句号（如 开心地。），这有助于模型更稳定地理解指令边界。
对话剧本: 在 🎙️ Qwen3-TTS Dialogue (Specialist) 节点中，如果某位 Speaker 处于 Preset 或 Design 模式，系统会自动将剧本中的情感标签（如 [开心]）转换为对应的 instruct 指令。

3.14 IndexTTS-2 (New! 🔥)

用途: Bilibili 开源的 零样本语音克隆 + 情感控制 TTS 模型。支持音色与情感解耦，调整情感时不会导致音色漂移。
🔥 核心特性:
- 音色/情感解耦 (Voice-Emotion Decoupling): 独立控制音色和情感，改变情感不影响声音音色。这解决了其他模型在调整情感时音色漂移的顽疾。
- 8 维情感向量控制: 提供 happy, angry, sad, afraid, disgusted, melancholic, surprised, calm 八个情感滑块，精细控制输出语音的情感表达。
- 🆕 内联情感标签 (Inline Emotion Tags): 支持在文本中嵌入 [Happy]、[Sad] 等标签，逐句控制不同情感。节点自动按标签分段生成，再以余弦淡入淡出 + 静音间隔无缝拼接。
- 情感音频参考: 支持通过额外的 emotion_audio 输入捕获参考音频中的情感特征，并通过 emo_alpha 控制混合强度。
- QwenEmotion 自动推断: 启用 use_emo_text 后，内置 Qwen 情感模型自动分析文本语义，推断最合适的情感向量。
- 零样本音色克隆: 输入 reference_audio 即可克隆声音。

节点:

IndexTTS-2 Loader — 加载 IndexTTS-2 模型

参数	默认	说明
`use_fp16`	`True`	半精度推理，降低 VRAM 占用
`use_cuda_kernel`	`True`	BigVGAN CUDA 核心加速（仅 NVIDIA GPU，推理更快）
`model_dir`	空	自定义模型路径，留空使用 `ComfyUI/models/indextts2/`

IndexTTS-2 TTS — 执行语音合成

参数	默认	说明
`text`	—	待合成文本，支持中英文混合及内联情感标签
`voice_preset`	`Female_HQ`	内置音色预设（在无 `reference_audio` 时使用）
`reference_audio`	—	音色参考音频（零样本克隆，优先于 preset）
`emotion_audio`	—	独立的情感参考音频
`emo_alpha`	`1.0`	情感混合强度 (0=无情感, 1=100%情感)
`happy` ~ `calm`	`0.0`	8 个情感滑块，直接控制向量
`use_emo_text`	`False`	启用后使用 Qwen 模型自动推断情感
`emo_text`	空	自定义情感提示文本（配合 `use_emo_text`）
`interval_silence`	`200`	长文本分段间静音时长 (ms)
`max_text_tokens_per_segment`	`120`	每段最大 token 数（控制切分粒度）
`use_random`	`False`	随机采样（降低克隆保真度）
`seed`	`0`	随机种子 (-1=随机)

🆕 内联情感标签 (Inline Emotion Tags):

在文本中嵌入 [标签名] 即可逐句控制情感，节点会自动按标签拆分，每段独立生成后拼接。

使用示例：

[happy] 今天天气真好，阳光明媚！
[sad] 但是我养的小猫走丢了，我好难过。
[calm] 不过我相信它一定会自己找到回家的路。

→ 生成 3 段音频，分别带 happy / sad / calm 情感，最终余弦淡入淡出无缝拼接为一段完整音频。

[!IMPORTANT] 控制情感强度: 内联标签默认映射到全强度的情感向量 (1.0)。如果发现音色失真或情感过于夸张（如嘶吼、破音），请尝试降低 emo_alpha 参数（推荐值 0.6 ~ 0.8）。较低的 alpha 值能更好地保留原始音色特征，同时赋予适度的情感色彩。

支持的 26 种标签：

分类	标签
积极情感	`happy`, `excited`, `enthusiastic`, `proud`, `romantic`, `innocent`
消极情感	`sad`, `angry`, `afraid`, `fearful`, `disgusted`, `disappointed`, `anxious`, `nervous`
复合情感	`sarcastic`, `nostalgic`, `confused`, `mysterious`, `gossip`
中性情感	`calm`, `neutral`, `gentle`, `serious`, `lazy`, `melancholic`, `surprised`

每个标签自动映射到 IndexTTS-2 的 8 维情感向量。未知标签（不在上述列表中的）自动回退至 QwenEmotion 模型推断。

[!TIP] 内联标签通常由 AIIA Emotion Annotator 节点自动注入到 Splitter 的输出中，无需手写。也可以手动添加来精细控制。

🔧 情感控制优先级:

当多种情感来源同时存在时，按以下优先级生效：

优先级	来源	说明
1 (最高)	内联标签 `[Tag]`	逐句独立控制，覆盖所有其他设置
2	滑块向量	8 个滑块全局生效（无标签时）
3	`use_emo_text`	Qwen 自动推断（无标签无滑块时）
4 (最低)	`emotion_audio`	从参考音频提取情感

[!NOTE] 如果文本含标签，则标签内的段落使用标签情感；无标签的段落继续使用滑块或其他全局设置。

✅ 依赖版本兼容性 (Dependency Compatibility): AIIA 已内置深度兼容层，完美支持 transformers 4.57+。

[!NOTE] IndexTTS-2 的官方代码基于 transformers 4.52，与最新版本存在多处 API 不兼容。AIIA 通过预注入 5 个兼容补丁（QuantizedCacheConfig、_crop_past_key_values、NEED_SETUP_CACHE_CLASSES_MAPPING、QUANT_BACKEND_CLASSES_MAPPING、SequenceSummary），确保在最新环境下正常运行。

⚠️ 模型下载 (Model Download): IndexTTS-2 除了主模型外，还依赖 4 个外部子模型。AIIA 节点支持全离线加载，建议将所有模型统一放入 ComfyUI/models/indextts2/。

目录结构 (Directory Structure):

ComfyUI/models/indextts2/
├── config.yaml
├── gpt.pth                  <-- 主模型
├── s2mel.pth                <-- 主模型
├── bpe.model
├── feat1.pt
├── feat2.pt
├── wav2vec2bert_stats.pt
├── qwen0.6bemo4-merge/      <-- 情感 LLM
│
├── semantic_codec/          <-- [外部] MaskGCT
│   └── model.safetensors
├── campplus_cn_common.bin   <-- [外部] Campplus
├── bigvgan_v2_22khz_80band_256x/  <-- [外部] BigVGAN
└── w2v-bert-2.0/            <-- [外部] W2V-BERT

一键下载命令 (Download Commands):

[!TIP] 国内用户推荐使用 HF Mirror，下载速度更快且无需代理。

cd ComfyUI/models

# 1. 下载主模型
HF_ENDPOINT=https://hf-mirror.com huggingface-cli download IndexTeam/IndexTTS-2 --local-dir indextts2

# 2. 下载外部子模型 (直接放入 indextts2 目录)
cd indextts2

# MaskGCT (只需 semantic_codec/model.safetensors)
HF_ENDPOINT=https://hf-mirror.com huggingface-cli download amphion/MaskGCT semantic_codec/model.safetensors --local-dir .

# Campplus
HF_ENDPOINT=https://hf-mirror.com huggingface-cli download funasr/campplus campplus_cn_common.bin --local-dir .

# BigVGAN (下载整个文件夹)
HF_ENDPOINT=https://hf-mirror.com huggingface-cli download nvidia/bigvgan_v2_22khz_80band_256x --local-dir bigvgan_v2_22khz_80band_256x

# W2V-BERT 2.0 (下载整个文件夹，排除大文件 checkpointers)
HF_ENDPOINT=https://hf-mirror.com huggingface-cli download facebook/w2v-bert-2.0 --local-dir w2v-bert-2.0 --exclude "*.pt"

[!NOTE] 如果本地目录中未找到上述子模型，节点会自动尝试从 HuggingFace 在线加载（缓存到 ~/.cache/huggingface）。 首次加载时，WeTextProcessing 库需要编译中文文本正则化的 FST 语法（耗时约 3-5 分钟），后续启动会直接读取缓存。

💡 用户实测与选型指南 (Model Comparison & Selection)

选型建议:

追求“听起来最像真人” (音质+音色): 选 VoxCPM 1.5。它的 Tokenizer-free 架构带来了质的飞跃。
追求“方言/多语言/稳定性”: 选 CosyVoice 3.0。目前依然是生产环境最稳的选择。
追求“多样化音色设计/最新 Qwen 生态/长语音流畅度”: 选 Qwen3-TTS。其 VoiceDesign 功能能让你用描述语“捏”出从未听过的声音。
追求“情感精细控制/音色情感解耦”: 选 IndexTTS-2。独立的 8 维情感控制、内联情感标签（逐句不同情感）和情感音频参考是其独有优势。
要做“长篇广播剧/播客”: 选 VibeVoice。它的长窗口上下文优势依然不可替代。

4. 播客与对话生成 (Podcast & Dialogue Generation)

demo.mp4

🎬 点击观看演示视频 (GitHub 限制，需要手工取消静音)

🚀 新增功能：这是专门为生成双人对话、相声、广播剧设计的完整工作流节点。能够自动解析剧本、调度多角色 TTS，并实现长音频的智能拼接。

4.1 AIIA Podcast Script Parser (脚本解析器)

负责将自然语言剧本转换为机器可读的结构化数据。

Script Text: 剧本输入区域。
- 基本格式: 角色名: 台词 (例如 A: 大家好)
- 暂停控制: (Pause N) (例如 (Pause 0.5) 表示暂停 0.5 秒)
- 情感标签 (仅 CosyVoice): [Emotion] 台词 (例如 [Happy] 大家好)
Speaker Mapping: 角色映射配置 (可选)。
- 格式: 原剧本角色名=A, 原剧本角色名=B
- 示例: Teacher=A, Student=B

4.2 AIIA Emotion Annotator (LLM 情感标注)

[v1.13.0 New] 使用 LLM 自动为对话剧本中的每句台词标注情感，无需手工逐句添加 [Happy] 等标签。

定位与流程

插入在 Script Parser → TTS 之间，作为可选的中间处理环节：

Script Parser → Emotion Annotator → Dialogue TTS / Qwen Dialogue TTS
                     ↓                        ↓
              写入 emotion 字段          读取 emotion 字段
              "Happy" / "Calm"          → CosyVoice: [Happy]文本
              null (neutral)            → 原文直读

无侵入设计：如果不连接此节点，工作流行为与之前完全一致。连接后自动生效，对下游 TTS 透明。

参数说明

参数	说明
`dialogue_json`	来自 Script Parser 的对话 JSON（连线输入）
`model`	LLM 模型选择：`llama-3.1-8b-instant` (默认/最快)、`llama-3.3-70b-versatile`、`qwen-qwq-32b`、`deepseek-r1-distill-llama-70b`、`gemma2-9b-it`
`override_mode`	`skip_existing`：保留剧本中已有的手工标签，只标注未标注的句子；`overwrite_all`：覆盖所有标签
`api_base_url`	API 端点，默认 `https://api.groq.com/openai/v1`。支持任何 OpenAI-compatible API（Ollama、vLLM 等）
`api_key_override`	API Key。留空则自动读取环境变量 `GROQ_API_KEY`
`custom_model`	自定义模型名（覆盖下拉选择，用于 Ollama 等自建服务）
`proxy_url`	HTTP/SOCKS5 代理地址。留空则使用环境变量 `HTTPS_PROXY`

工作原理

收集台词：从 dialogue_json 中提取所有 type: "speech" 的条目
构造 Prompt：将台词编号后发送给 LLM，附上 24 种预定义情感标签，要求 LLM 从中选择
解析响应：将 LLM 返回的 JSON 数组解析为 {行号: 情感} 映射
写回标签：将情感标签（如 "Happy"、"Calm"）写入每条台词的 emotion 字段
neutral 的句子不注入标签（emotion: null），TTS 以自然语调朗读

支持的 24 种情感标签

neutral · happy · sad · angry · excited · gentle · fearful · surprised · disappointed · serious · calm · romantic · sarcastic · proud · confused · anxious · disgusted · nostalgic · mysterious · enthusiastic · lazy · gossip · innocent · nervous

下游兼容性

TTS 引擎	消费方式	效果
CosyVoice	`[Happy] 文本...` 格式注入	✅ 精准情感控制
Qwen3-TTS (CustomVoice)	提取标签 → `instruct` 指令（按情感自动拆批）	✅ 自动按情感分批生成
Qwen3-TTS (Base)	自动清洗标签（Base 模型不支持 instruct）	✅ 标签被清洗，不影响克隆
VibeVoice	自动清洗 `[Emotion]` 标签后生成	✅ 无影响，不会朗读标签

Qwen3 智能分批：当使用 Qwen3 Dialogue TTS 时，连续相同情感的句子会自动合并为一个批次，情感变化时自动拆分为新批次，确保每个批次的 instruct 只包含单一情感，语义准确。

VibeVoice 安全保障：VibeVoice Standard / Realtime 节点在文本预处理阶段会自动清洗所有 24 种情感标签（如 [Happy]、[Calm]），因此即使通过 Podcast Splitter 传递了嵌标签的文本，VibeVoice 也不会将其作为普通文字朗读。

优先级规则：如果用户在 Qwen3 节点的 UI 下拉框中手动选择了情感，该选择将优先于文本中的内嵌标签。标签仍会被清洗，但不会覆盖 UI 设置。

典型工作流

对话流程（适合大多数场景）：

Script Parser → Emotion Annotator → Dialogue TTS → Video Combine

单人旁白流程（配合 Text Splitter）：

长文本 → Text Splitter → Emotion Annotator → Qwen3 TTS / CosyVoice

高级拆分流程（多引擎混合）：

Script Parser → Emotion Annotator → Podcast Splitter → TTS_A (CosyVoice)
                                                      → TTS_B (VibeVoice)
                                                      → Podcast Stitcher

4.3 AIIA Text Splitter (文本拆分器)

[v1.13.0 New] 将单人长文本按标点拆分为标准 dialogue_json，使其可直接接入 Emotion Annotator → TTS 管线。

参数说明

参数	说明
`text`	待拆分文本（多行/长段落）
`speaker_name`	说话人名称，默认 `Narrator`
`split_mode`	`auto`：智能拆分（句末标点 + 短句合并 + 长句再拆）；`by_sentence`：仅按句号/问号/感叹号拆分；`by_line`：按换行拆分
`min_chars`	最小字符数，短于此的句子合并到前一句。默认 `4`
`max_chars`	最大字符数，超长句子在逗号/分号处强制拆分。默认 `100`

拆分行为 (`auto` 模式)

按换行分段 → 保留段落结构
段内按句末标点拆分 → 。！？!?… 和省略号 …… / ...
短句合并 → 短于 min_chars 的句子追加到前一句
长句拆分 → 超过 max_chars 的句子在逗号/分号处再切

输出

dialogue_json：标准格式，与 Script Parser 输出兼容，可直接接入 Emotion Annotator / Dialogue TTS
sentence_count：拆分后的句子数

4.4 AIIA Dialogue TTS (对话生成引擎)

核心调度与生成节点，支持自动角色切换和长音频拼接。

TTS Engine: 后端引擎选择。
- CosyVoice: 精准控制型。
- Qwen3-TTS: 万能旗舰型。支持混合模式：通过连接多个 Qwen 模型，可实现在一个对话中同时使用克隆和内置音色。
Qwen Model Pins (Multi-Routing):
- qwen_model: 默认主模型。
- qwen_base_model (可选): 连接 Base 模型，专门处理有参考音频 (Clone) 的角色。
- qwen_custom_model (可选): 连接 Custom 模型，专门处理使用内置 ID (Presets) 的角色。
- qwen_design_model (可选): 连接 VoiceDesign 模型，专门处理复杂描述的角色。
- Ref Audio: 参考音频 (用于 Zero-Shot 克隆)。
- ID: 内置音色 ID (如 CosyVoice 的 Chinese Female)。
Batch Mode: 生成模式控制。
- Natural (Hybrid): 混合批处理。仅在 (Pause) 处断开。语流最自然，但可能发生音色泄漏。
- Strict (Per-Speaker): 严格模式。每句话都会强制断开重置。彻底杜绝音色泄漏，但对话流畅度略低。
- Whole (Single Batch): 全量模式。无视所有暂停，一次性生成整本剧本。连贯性最强，但无法控制停顿时间。
Batching Parameters:
- max_batch_char (Default 1500): 单次批处理的最大字符上限。增加此值可大幅提升 Qwen3 的对话连贯性和情感一致性。最高支持模型上限 32,768。
Emotion Safeguard (New!):
- 智能检测: 系统会自动嗅探加载模型的元数据。如果你使用 CosyVoice SFT/Base 或 VibeVoice 等不支持 Instruct 功能的模型，系统将自动跳过 [Emotion] 标签插入，防止模型读出方括号。

4.5 AIIA Qwen Dialogue TTS (Qwen 旗舰对话节点)

[v1.11.0 New] 深度集成 Qwen3-TTS 的多模式特性，支持复杂的混合角色场景。

Parameters:
- seed: 随机种子。
- speed: 语速调节。
- cfg_scale: 指令遵循强度 (Classifier-Free Guidance)。建议值 1.5 - 7.0。
- emotion: [v1.11.1 New] 选中预设情感（开心、悲伤、幽默、愤怒等系统预置微调）。
- dialect: [v1.11.1 New] 选中预设方言（粤语、上海话、东北话、四川话等）。
- temperature: 采样温度。
- max_batch_char: 单次批处理上限（最高 32,768）。
Speaker A/B/C Configuration:
- Mode: 选择 Clone (音色克隆)、Preset (官方预设) 或 Design (文字设计)。
- ID: 当模式为 Preset 时，输入预设音色名 (如 Vivian, Serena, Uncle_Fu, Dylan, Eric, Ryan, Aiden, Ono_Anna, Sohee)。
- Expression: (New!) 为当前角色选择专属微表情描述。
- Dialect: [v1.11.1 New] 为当前角色选择方言/口音（支持粤语、上海话、四川话、东北话等）。
- Design Description: 当模式为 Design 时，输入对音色的详细自然语言描述。
- Ref Audio: 当模式为 Clone 时，连接参考音频。
特点: 相对于通用对话节点，此节点能根据每个人的模式自动路由到最合适的 Qwen 引擎，且支持在 UI 直接输入设计描述。

4.6 AIIA Subtitle Gen (字幕生成器)

[v1.7.0 New] 无需 STT，直接从生成过程中提取精准时间轴。

Input:
- segments_info: 来自 AIIA Dialogue TTS 或 AIIA Generate Segments 的输出。
- calibration_info (可选): [v1.10.2 新增] 接入 AIIA Generate Speaker Segments 的输出。用于将估算的时间轴自动“吸附”到真实的 VAD 语音活动区间，解决 VibeVoice 等批处理引擎的时间轴偏移问题。
Output:
- SRT: 通用字幕格式。
- ASS: 高级排版字幕格式 (自动区分角色颜色)。
原理:
- CosyVoice: 使用生成时的精确时长。
- VibeVoice: 使用智能插值算法 (Smart Interpolation)，根据字符长度自动计算长音频段内的单句时间轴。
- Qwen3-TTS: 基于生成的音频振幅精准断句，支持多角色时间轴导出。

4.7 AIIA Subtitle to Segments (字幕转分段)

[v1.10.3 New] 将现有的 SRT/ASS 字幕文件转换为 segments_info 格式，以便进行时间轴重新校准。

Input:
- subtitle_text: SRT 或 ASS 格式的文本内容。
- subtitle_path (可选): 字幕文件的本地路径（如果提供，将优先读取文件）。
Output:
- segments_info: 标准化的 JSON 字符串，可直接输入到 AIIA Subtitle Gen。
用途: 结合 Subtitle Gen 的 calibration_info 输入，可以将旧的、不准的字幕自动对齐到新的、精准的音轨上。

4.8 AIIA Subtitle Preview (字幕预览)

[v1.7.1 New] 实时校验音画同步效果。

Input:
- subtitle_content: 来自 Subtitle Gen 的 srt_content 或 ass_content。
- audio (Optional): 待预览的音频。
Output:
- 交互式界面: 提供 Web 播放器，按时间轴滚动显示字幕。
- ASS 样式渲染: 尝试还原 ASS 字幕的字体颜色、大小和描边效果。

4.9 Interactive Teaching (Web Export) (互动式教学导出)

[v1.8.1 New] 将播客升级为视听同步的互动网页。支持“读写分离”的缓存优化，修改 Visual 标签无需重跑 TTS。

工作流 (Workflow):
1. Script Parser 输出 tts_data (连接到 TTS) 和 full_script (连接到 Merge)。
2. AIIA Dialogue TTS 生成音频和 segments_info。
3. AIIA Segment Merge 将 full_script 中的 Visual 标签重新贴回到 segments_info 时间轴上。
4. AIIA Web Export 生成最终 HTML。
Input:
- audio: 音频信号。
- segments_info: 来自 Merge 节点的包含 Visual 信息的 JSON。
- template: Split Screen (适合宽屏) 或 Presentation (适合演示)。
Visual Tag 语法:
- 在剧本中插入 (Visual: url)。
- 支持绝对 URL: (Visual: https://example.com)
- 支持相对路径: (Visual: ./slides/01.jpg) (相对于导出 HTML 的位置)

4.10 AIIA Podcast Splitter (对话拆分器)

[v1.12.0 New] 将对话 JSON 按说话人拆分为独立文本列表，用于"拆分→生成→拼接"的高级流程。

Input:
- dialogue_json: 来自 Script Parser 的对话 JSON。
Output:
- split_map: 拆分映射表（JSON），保存原始顺序和各句话归属信息。
- text_A, text_B: 分别为说话人 A、B 的纯文本列表（每行一句），可直接送入各自的 TTS 节点独立生成。
用途: 实现对不同说话人使用不同 TTS 引擎/参数生成音频，再通过 Stitcher 精确拼接的高级工作流。

4.11 AIIA ASR Node (语音识别)

[v1.12.0 New] 基于 FunASR 的语音识别节点，输出带词级时间戳的识别结果，为 Stitcher 提供精确对齐依据。

Input: audio (AUDIO 张量)。
Output: ASR_RESULT（包含词级时间戳的识别结果）。
依赖: 需要安装 funasr 库。模型首次运行时自动下载。

4.12 AIIA Podcast Stitcher (精确拼接器)

[v1.12.0 New] 将分轨生成的多角色音频按原始对话顺序精确拼接，还原自然对话节奏。

核心工作原理:
1. 利用 ASR 词级时间戳找到每句话在各自音频中的时间边界。
2. 通过三层匹配策略（精确子串→编辑距离模糊→等分回退）实现鲁棒对齐。
3. 在切分边界处进行精细微调（能量检测或 VAD），确保不切断语音、不吃进相邻句子。
4. 对切片施加余弦淡入淡出，并在说话人切换处插入自然过渡间隙。
Input:
- split_map: 来自 Splitter 的拆分映射。
- audio_A, audio_B: 各说话人独立生成的完整音频。
- asr_A, asr_B: 对应的 ASR 识别结果。
Parameters:
- gap_duration (Default 0.25s): 说话人交替时的过渡间隙。
- padding (Default 0.10s): 切片前后保留的呼吸/尾音余量。
- fade_ms (Default 30ms): 余弦淡入淡出时长。
- use_vad (Default False): 🔬 启用 Silero VAD 精确边界检测。
  - 开启后，使用 Silero VAD 神经网络模型（~2MB，首次自动下载）替代基于能量的边界检测。
  - VAD 能精确识别语音起止点，彻底解决清辅音误切、尾音截断等能量检测的固有缺陷。
  - 关闭时使用内置的平滑能量包络检测（20ms 窗口 + 5-point 滑动平均），已能应对大部分场景。
- use_forced_align (Default False): 🎯 启用 MMS Forced Alignment 字级强制对齐。
  - 使用 Facebook MMS 声学模型（~1.2GB）对文本和音频进行字级强制对齐，精度最高。
  - 中文文本自动转换为拼音（pypinyin）后送入模型。
  - 当与 use_vad 同时启用时，三种方法（FA/VAD/Energy）全部运行，输出 IoU 匹配度用于质量评估。
  - 模型首次使用时自动下载，成功后会自动复制到 models/mms_fa/model.pt 以便后续直接加载。

手动下载（适用于网络受限环境）：

# 方法 1：直接下载 torchaudio 官方权重
mkdir -p ComfyUI/models/mms_fa
wget -O ComfyUI/models/mms_fa/model.pt \
  "https://dl.fbaipublicfiles.com/mms/torchaudio/ctc_alignment_mling_uroman/model.pt"

# 方法 2：从 HuggingFace 镜像下载
pip install huggingface_hub
huggingface-cli download facebook/mms-fa --local-dir ComfyUI/models/mms_fa

Output: 拼接后的完整 AUDIO + segments_info (JSON)。

💡 引擎选型与最佳实践 (Best Practices)

特性	CosyVoice	VibeVoice	Qwen3-TTS
核心优势	精准控制 (Instruction)	自然演绎 (Context-Aware)	万能旗舰 (Voice Design)
情感控制	✅支持 (使用 `[Happy]` 等标签)	❌ 不支持显式标签 (依赖上下文)	✅支持 (通过 `instruct` 或标签)
生成逻辑	逐句生成 (严格遵循每句话的指令)	混合批处理 (Hybrid Batching)	动态引擎 (支持流式与批处理)
最佳场景	需要精确指定某句话语气、方言时	长篇对话、广播剧、闲聊	音色定制、高质量配音、极速克隆
使用建议	可以在剧本中详细标注情感。	尽量减少 `(Pause)`！`<br>`让多句对话连在一起，模型能更好地联系上下文产生自然语气。	尝试使用其 Voice Design 进行创意捏人。

📝 综合测试剧本 (Example Script)

复制以下内容到 Script Parser 进行测试，能够充分体现两种引擎的特性：

# 这是一个展示 CosyVoice 和 VibeVoice 能力的综合剧本
# 角色映射建议：A=男声, B=女声

A: 大家好，欢迎来到 AIIA 播客直播间。
B: [开心] 哇，今天的人气好高啊！看到这么多朋友在线，我太激动了。

(Pause 0.5)

A: 呵呵，淡定一点。即使是 VibeVoice 这种基于 LLM 的模型，也需要你保持从容。
B: [疑惑] 为什么？难道它不喜欢太吵闹的声音吗？
A: 不是不喜欢，而是因为它会“读取”上下文。你越自然，它演得越像。

(Pause 0.8)

A: 比如说，如果我们用 CosyVoice，我可以强行指定你现在的状态。
B: [悲伤] 比如让我突然变得很伤心？
A: 对，就像这样。CosyVoice 是“指哪打哪”，非常听话。

(Pause 0.5)

B: [机器人的方式] 那如果我变成一个机器人呢？可以吗？
A: 哈哈，完全没问题。

(Pause 1.0)

A: 但是，如果你想演一场相声，或者很自然的闲聊，VibeVoice 的“混合批处理”就是神技了。
B: [excited] 也就是它会把我们现在说的这一长串话，一口气生成出来？
A: 没错！只要我们中间不加 Pause，它就会一口气读完，语气极其连贯，就像真人对话一样。
B: 太神奇了！那我们快去生成试试吧！

5. 图像工具 (Image Utilities)

Image Concatenate (AIIA Utils, Disk)

用途: 将两个图像序列（来自两个不同的目录）逐帧拼接在一起，非常适合创建对比视频或多面板视频。
核心亮点 (OOM-Safe): 此节点逐帧读取、处理和保存，从不将整个图像序列加载到内存中，因此可以处理任意数量的帧。
功能:
- 支持上下左右四个方向的拼接。
- 可自动调整其中一个图像序列的尺寸以匹配另一个，并保持宽高比。
- 可自定义背景填充颜色。
输出: STRING (包含所有拼接后帧的新目录路径)。

AIIA Image Smart Crop (智能图像裁切)

用途: 一个功能全面的智能裁切节点，专为解决人脸比例、视频构图等问题设计。
场景: 强烈建议在 Ditto Sampler 或其他视频生成节点之前使用，以确保输入图像（特别是人脸）处于最佳位置和比例，避免“嘴巴太大”或“五官漂移”等问题。
参数:
- crop_basis: 裁切基准。
  - fixed_width / fixed_height: 锁定一条边 (使用 width/height 参数)，另一条边自适应。
  - fixed_long_side: 匹配原图长边。裁切出的长边长度等于原图长边长度 (忽略 width/height 参数)。
  - fixed_short_side: 匹配原图短边。裁切出的短边长度等于原图短边长度 (忽略 width/height 参数)。适合“最大化裁切”。
  - custom_size: 强制裁切为指定的 width x height。
- aspect_ratio: 裁切比例。
  - 默认为 original (保持原图比例或使用 custom_size 的宽高)。
  - 可选 1:1, 16:9, custom 等。
  - 选择非 original 时，会根据 crop_basis 自动计算另一条边的长度。
- custom_aspect_ratio: 自定义比例值 (例如 2.35)。仅在 aspect_ratio 选 custom 时生效。
- position: 锚点位置 (九宫格)。支持 center, top, bottom_left 等。
- offset_x / offset_y: 相对偏移量。用于在自动定位的基础上进行微调 (范围 -1.0 到 1.0)。
输出: IMAGE (裁切后的图像)。

6. 调试与实用工具 (Debug & Utilities)

6.1 文本调试拼接 (Text Debug Splicer)

用途: 方便地将多段文本拼接为一个字符串，支持自定义标题和分隔符，常用于构建和调试复杂的 Prompt 或记录中间结果。
功能:
- 多路输入: 支持最多 3 路文本输入 (text_1~3) 和自定义标题 (title)。
- 灵活分隔: 内置多种常用分隔符 (换行、分割线等)。
- 自动归档: 支持将拼接结果自动保存为 .txt 文件，文件名支持自定义前缀 (save_prefix)，方便回溯。
输出: STRING (拼接后的文本)。

6.2 JSON 提取器 (AIIA JSON Extractor 🔑)

用途: 从 STRING 类型的 JSON 字符串中，按 key 路径提取指定字段的值。无需依赖第三方 JSON 节点，完全基于 STRING 类型，兼容所有上下游节点。
功能:
- 嵌套路径: 支持 dot 路径 + 数组索引，例如 data.items[0].name、[2].speaker。
- 多类型输出: 同时输出 STRING、INT、FLOAT、BOOLEAN，自动安全转换。
- 鲁棒容错: JSON 格式错误、key 不存在、类型不匹配等情况不会崩溃，统一返回 fallback 默认值。
- 自动清理: 自动处理 BOM、首尾空白等常见 JSON 字符串问题。
输入:
- json_string (STRING, forceInput) — 待解析的 JSON 字符串
- key_path (STRING) — 提取路径，例: name, data.items[0].text, [2].speaker
- fallback (STRING, 可选) — 解析失败时的默认值
输出: value (STRING), value_int (INT), value_float (FLOAT), found (BOOLEAN)

路径语法示例:

路径	JSON 示例	提取结果
`name`	`{"name": "Alice"}`	`Alice`
`data.count`	`{"data": {"count": 42}}`	`42`
`items[0].text`	`{"items": [{"text": "Hello"}]}`	`Hello`
`[2].speaker`	`[{}, {}, {"speaker": "B"}]`	`B`
(空)	`{"a": 1}`	返回整个 JSON

6.3 JSON 构建器 (AIIA JSON Builder 🏗️)

用途: 将多组 key-value 组装为 JSON 对象字符串，方便下游节点消费。
功能:
- 支持最多 4 对 key-value 输入。
- 值如果是合法 JSON（数组、对象、数字、布尔），会自动解析为对应类型而非字符串。
输入: key_1 + value_1 (必填), key_2~~key_4 + value_2~~value_4 (可选)
输出: json_string (STRING)

❓ 故障排查

错误: "FFmpeg not found" / "NeMo model not found"
- 请返回阅读安装与先决条件部分，确保所有依赖都已正确安装和放置。
错误: "帧目录验证失败"
- 请确保您填写的路径是绝对路径且真实存在。

许可证

本项目采用 MIT 许可证。

Changelog

[1.14.2] - 2026-02-17

NeMo Diarization 兼容性修复: 修复 PyTorch 2.10+ 环境下 NeMo 说话人分割(diarize())因 lhotse 1.32 不兼容报 object.__init__() takes exactly one argument 的崩溃。
- 自动检测 PyTorch 版本，仅在 >= 2.10 时 monkey-patch CutSampler.__init__，移除已废弃的 data_source 参数。
JSON Extractor 节点 (New): 从 STRING 类型的 JSON 字符串中按 key 路径提取值，支持嵌套路径和数组索引（如 data.items[0].name）。
- 多类型输出：STRING、INT、FLOAT、BOOLEAN。
- 鲁棒容错：JSON 格式错误、key 不存在时返回 fallback 默认值，不会崩溃。
JSON Builder 节点 (New): 将多组 key-value 组装为 JSON 对象字符串，支持最多 4 对输入。
Qwen3-TTS Voice Preset: 新增 voice_preset 下拉框（Female_HQ/Male_HQ/Female/Male），无需手动接入参考音频即可使用内置音色，自动启用 Zero-Shot 模式。
Qwen3-TTS 鲁棒性: reference_text 为空或字面值 "None" 时自动切换到 Zero-Shot 模式，防止意外走入慢速 ICL 模式。
CosyVoice 参考音频限制: 参考音频超过 30 秒时自动截断，防止 AssertionError。

[1.12.0] - 2026-02-16

Podcast Stitcher - MMS Forced Alignment 集成: 新增 use_forced_align 开关，使用 Facebook MMS 声学模型（~1.2GB）进行字级强制对齐。
- 中文文本自动转拼音（pypinyin），英文自动小写化以兼容 MMS_FA tokenizer。
- 混合切割策略: FA 精确定位语音起点 + 能量检测定位自然收尾点，兼顾起音精准与尾音完整。
- 重叠防护: 尾部扩展不会吃进下一句 FA 起点，取中点并保底不低于 FA 原始终点。
- 三方法交叉验证: FA + VAD + Energy 同时启用时，输出 IoU 匹配度（✂️ USED / 🔬），方便评估各方法精度。
- 优先级: FA > VAD > Energy，FA 缺失时自动回退。
- 模型支持从 models/mms_fa/model.pt 本地加载，避免重复下载。

[1.11.1] - 2026-02-15

Video Combine: 新增 cleanup_frames 开关（默认关闭）。
- 开启后，视频合成成功时自动删除输入的 frames_directory，减少磁盘空间占用。
- 防误删安全机制: 引入 .aiia_temp 标记文件，只有 AIIA 节点自动生成的帧目录才会包含此标记，用户提供的素材目录不会被误删。
ToDisk 节点安全标记: 所有产生帧输出的节点（FloatProcess_ToDisk、DittoSampler 磁盘模式、PersonaLive_ToDisk、BodySway）现在会在输出目录中写入 .aiia_temp 标记文件。

[1.11.0] - 2026-02-04

Qwen3-TTS: 新增阿里巴巴 Qwen3-TTS 全系列支持。
- 🤖 Qwen3-TTS Loader: 支持加载 Base, CustomVoice, VoiceDesign 及其 1.7B/0.6B 版本。
- 🗣️ Qwen3-TTS Synthesis: 实现全功能生成，包括 Zero-shot 克隆、音色设计和内置音色合成。
Podcast Integration: AIIA Dialogue TTS 节点现在正式集成 Qwen3-TTS 引擎。
- 支持多角色混合场景下的 Qwen3 驱动，支持使用脚本标签触发 instruct。
Auto-Dependency: 首次运行 Qwen3 节点会自动检测并安装 qwen-tts 库。

[1.10.17] - 2026-02-03

Subtitle: 引入“说话人 ID 为了映射 (Speaker Mapping)”机制。
- 在字幕校准过程中，系统会建立脚本角色与 VAD 检测角色的对应关系。这确保了即使在短句重叠（Spillover）的情况下，字幕也能强制匹配到正确的说话人音频，避免被相邻的音量大/时长长的角色“抢走”。

[1.10.16] - 2026-02-02

Subtitle: 优化了多片段合并逻辑，引入“贪婪说话人占用”原则。
- 对于同一说话人的连续音频片段，只要中间没有被其他说话人占用且停顿小于 3s，都会自动合并到当前行字幕中。解决多句/长句被意外截断的问题。

[1.10.15] - 2026-02-02

Subtitle: 修复了字幕时间校准逻辑中的 Bug。
- 增加了说话人一致性检查，防止上一句音频片段（VAD Chunk）被错误地共享给下一个不同说话人的句子，从而导致当前句字幕被截断。

[1.10.14] - 2026-02-02

Ditto Sampler: 修复了由于 comfy.model_management 接口版本差异导致的 AttributeError。

[1.10.13] - 2026-02-02

Ditto Sampler: 修复了采样过程中无法正常响应 ComfyUI 中断/取消信号的问题。
- 为所有工作线程增加了超时检测和状态轮询，支持在长任务执行期间即时退出。

[1.10.12] - 2026-02-02

Debug & Utilities: 新增 Text Debug Splicer 节点。
- 支持多路文本拼接、自定义分隔符和自动文件归档。

[1.9.0] - 2026-01-20

Ditto Talking Head: 新增 Ditto 模型支持 (PyTorch 版)。
- AIIA Ditto Loader: 支持自动下载与加载。
- AIIA Ditto Sampler: 支持内存内流式生成。
EchoMimic V3: 优化了音频同步逻辑，修复了唇形漂移问题。

[1.8.4] - 2026-01-19

VibeVoice Speed Control: 实现了基于系统 sox 命令的变速不变调（Time Stretching）。
稳定性修复:
- 修复了 VibeVoice 在调整速度时由于张量类型不匹配（Half vs Float）导致的崩溃。
- 强制所有音频输出为 float32，解决了在 speed=1.0 且有参考音频时，下游节点（如 Resemble Enhance）报错的问题。
依赖更新: 新增 sox 依赖。Linux 服务器用户请确保安装系统库：sudo apt-get install libsox-dev sox。

[1.8.3] - 2026-01-07

VibeVoice TTS (Standard): reference_audio 变为可选参数。如果不输入，节点会自动加载内置的高品质女声种子，方便快速测试。
Fix: 修复 GitHub Actions 发布的子模块错误。

[1.8.1] - 2026-01-05

互动式教学 (Interactive Teaching): 新增 AIIA Web Export 节点，一键生成包含播放器、字幕和同步 Visual 展示的 HTML 页面。
Visual Tag 支持: 剧本解析器支持 (Visual: url) 标签，并支持相对路径。
缓存优化 (Caching): 实现了 Script Parser 的读写分离和 Segment Merge 节点，支持修改 Visual 标签而不触发 TTS 重生成。
字幕增强: 修复了 ASS 字幕的多角色颜色显示问题 (自动分配颜色)。

[1.3.1] - 2026-01-03

本次更新标志着 CosyVoice 架构的完全大一统。通过“手术级”精准推理逻辑，我们成功解决了 300M 系列模型的所有顽疾。

✅ 已完成 (Perfectly Supported)

V3 系列 (0.5B): 完美支持。性别、方言、情感以及指令文本均能精准跟随。
V2 系列 (0.5B): 完美支持。
300M-Instruct (V1): 彻底修复 (Fully Fixed)。
- 指令跟随修复: 强制注入官方缺失的 <|endofprompt|> 边界标识，完美解决了模型将指令文本读出来的问题。
- 能力矩阵:
  - ✅ 支持: 情感控制 (Happy/Sad/Angry)、语速控制 (Fast/Slow)、基础性别 (Male/Female)。
    
    Note: 为了确保指令生效，请务必使用英文描述 (如 "Sad tone", "Male speaker")。中文描述虽然不会导致报错，但模型极有可能忽略其语义。
  - ❌ 不支持: 方言指令 (Dialect) - 此模型架构原生不支持通过指令更改方言 (无论中文或英文)，请使用 V3 或 V2 模型获取方言能力。
300M-SFT / Base (V1): 恢复原生巅峰音质。
稳定性: 杜绝了 AudioDecoder、KeyError 以及 llm_embedding 缺失导致的各种崩溃。

🔈 资源更新

HQ 种子音色: 内置从 300M-SFT 提取的高保真男声/女声种子音频。在零参考音频的“指令模式”下，V2/V3 将自动调用这些高保真资源，消除破碎感。

Name		Name	Last commit message	Last commit date
Latest commit History 1,081 Commits
.github/workflows		.github/workflows
.vscode		.vscode
assets		assets
examples		examples
js		js
libs		libs
personalive		personalive
tests		tests
vibevoice_core		vibevoice_core
video_formats_aiia		video_formats_aiia
voxcpm_core/voxcpm		voxcpm_core/voxcpm
.gitignore		.gitignore
README.md		README.md
TODO.md		TODO.md
__init__.py		__init__.py
aiia_asr_nodes.py		aiia_asr_nodes.py
aiia_audio_debug.py		aiia_audio_debug.py
aiia_audio_denoise.py		aiia_audio_denoise.py
aiia_audio_enhance.py		aiia_audio_enhance.py
aiia_audio_info.py		aiia_audio_info.py
aiia_audio_isolator.py		aiia_audio_isolator.py
aiia_audio_merger.py		aiia_audio_merger.py
aiia_audio_processor.py		aiia_audio_processor.py
aiia_browser_node.py		aiia_browser_node.py
aiia_cosyvoice_nodes.py		aiia_cosyvoice_nodes.py
aiia_cosyvoice_nodes.py.bak		aiia_cosyvoice_nodes.py.bak
aiia_debug_nodes.py		aiia_debug_nodes.py
aiia_ditto_nodes.py		aiia_ditto_nodes.py
aiia_e2e_diarizer.py		aiia_e2e_diarizer.py
aiia_echomimic_nodes.py		aiia_echomimic_nodes.py
aiia_emotion_annotator.py		aiia_emotion_annotator.py
aiia_float_nodes.py		aiia_float_nodes.py
aiia_generate_segments.py		aiia_generate_segments.py
aiia_image_nodes.py		aiia_image_nodes.py
aiia_indextts_nodes.py		aiia_indextts_nodes.py
aiia_json_extractor.py		aiia_json_extractor.py
aiia_personalive_nodes.py		aiia_personalive_nodes.py
aiia_podcast_nodes.py		aiia_podcast_nodes.py
aiia_podcast_splitter.py		aiia_podcast_splitter.py
aiia_podcast_stitcher.py		aiia_podcast_stitcher.py
aiia_qwen_nodes.py		aiia_qwen_nodes.py
aiia_subtitle_nodes.py		aiia_subtitle_nodes.py
aiia_text_splitter.py		aiia_text_splitter.py
aiia_utils_nodes.py		aiia_utils_nodes.py
aiia_vibevoice_nodes.py		aiia_vibevoice_nodes.py
aiia_vibevoice_preset_maker.py		aiia_vibevoice_preset_maker.py
aiia_vibevoice_realtime_tts.py		aiia_vibevoice_realtime_tts.py
aiia_video_nodes.py		aiia_video_nodes.py
aiia_voxcpm_nodes.py		aiia_voxcpm_nodes.py
aiia_web_export_nodes.py		aiia_web_export_nodes.py
audio2motion_old.py		audio2motion_old.py
convert_to_bf16.py		convert_to_bf16.py
debug_config.py		debug_config.py
debug_preset.py		debug_preset.py
debug_sr.py		debug_sr.py
deploy.sh		deploy.sh
experiment_instruct.py		experiment_instruct.py
identity_grid.py		identity_grid.py
inspect_resemble.py		inspect_resemble.py
node.zip		node.zip
official_preset.pt		official_preset.pt
package-lock.json		package-lock.json
pyproject.toml		pyproject.toml
test_strict_indextts.py		test_strict_indextts.py
verify_podcast_nodes.py		verify_podcast_nodes.py

Folders and files

Latest commit

History

Repository files navigation

AIIA Nodes for ComfyUI

🚀 全新旗舰节点：AIIA 媒体浏览器 🚀

✨ 为何选择 AIIA 浏览器？

核心亮点

1. 强大的核心功能

2. 顶级的界面与用户体验

3. 无与伦比的性能与技术

4. 灵活的自定义选项

🚀 核心设计理念：为大规模生成而生

🌟 告别OOM：为处理海量帧而生

v1.9.21+ 内存优化

两种工作模式

🔧 强大且可扩展的预设系统

🛠️ 安装与先决条件

1. 安装 FFmpeg (视频与浏览器节点强依赖)

2. 安装 SoX (VibeVoice 变速不变调必须)

3. 安装 NeMo 模型 (音频AI节点必须)

4. 安装本节点套件

✨ 可用节点

1. 媒体管理 (Media Management)

AIIA 媒体浏览器

2. 视频生成与合成 (Video Generation & Compositing)

2.1 视频合并 (AIIA, 图像或目录)

2.2 FLOAT 影片生成 (内存与磁盘模式)

2.3 PersonaLive 视频驱动 (AIIA Integrated)

2.4 EchoMimic V3 (AIIA Integrated)

2.5 Ditto Talking Head (AIIA Integrated)

2.6 身体微动后处理 (Body Sway Post-Processing)

3. 音频智能处理 (Intelligent Audio Processing)

3.1 说话人日志 (Diarization)

3.2 说话人隔离与合并 (Speaker Isolation & Merger)

3.3 智能切片 (Smart Chunking)

3.4 Voice Conversion (AIIA Unlimited) (CosyVoice 增强)

3.5 CosyVoice 3.0 TTS (AIIA) (全版本集成文本转语音)

3.6 智能音频增强 (Audio AI Enhance) (推荐)

3.7 智能音频降噪 (VoiceFixer) (Legacy)

3.8 Audio Post-Process (Resample/Fade/Norm)

3.9 Audio Splice Analyzer (AIIA Debug)

3.10 音频信息查看 (Audio Info & Metadata)

3.11 Microsoft VibeVoice (Beta)

🔬 详细观察与进阶技巧

💡 7B 模型音质“全开”指南

💡 VibeVoice 使用指南 (Node Usage Guide)

1. 🗣️ VibeVoice TTS (Standard)

2. 🗣️ VibeVoice TTS (Realtime 0.5B)

3. 🎤 VibeVoice Preset Maker (0.5B) (Experimental ⚠️)

3.12 VoxCPM 1.5 TTS (Beta)

💡 用户实测与选型指南 (Model Comparison & Selection)

3.13 Qwen3-TTS (New! 🔥)

📊 模型功能映射表 (Model Capability Mapping)

🎭 掌握指令控制 (Instruct Control)

3.14 IndexTTS-2 (New! 🔥)

💡 用户实测与选型指南 (Model Comparison & Selection)

4. 播客与对话生成 (Podcast & Dialogue Generation)

4.1 AIIA Podcast Script Parser (脚本解析器)

4.2 AIIA Emotion Annotator (LLM 情感标注)

定位与流程

参数说明

工作原理

支持的 24 种情感标签

下游兼容性

典型工作流

4.3 AIIA Text Splitter (文本拆分器)

参数说明

拆分行为 (auto 模式)

输出

4.4 AIIA Dialogue TTS (对话生成引擎)

4.5 AIIA Qwen Dialogue TTS (Qwen 旗舰对话节点)

4.6 AIIA Subtitle Gen (字幕生成器)

4.7 AIIA Subtitle to Segments (字幕转分段)

4.8 AIIA Subtitle Preview (字幕预览)

4.9 Interactive Teaching (Web Export) (互动式教学导出)

4.10 AIIA Podcast Splitter (对话拆分器)

4.11 AIIA ASR Node (语音识别)

4.12 AIIA Podcast Stitcher (精确拼接器)

💡 引擎选型与最佳实践 (Best Practices)

拆分行为 (`auto` 模式)

Packages