ComfyUI-AudioLoopHelper：LTX 2.3 长篇音乐视频生成神器，自动处理循环、提示调度与无缝衔接

在 AI 视频生成领域，制作与音乐完美同步的长篇视频一直是个难题。传统的分段生成不仅耗时，还容易出现画面跳跃、节奏脱节、提示词切换生硬等问题。

ComfyUI-AudioLoopHelper 是一套专为 LTX 2.3 模型设计的自定义节点集合与工作流系统。它通过智能处理循环时序、音频边界检测、潜在空间重叠转换以及基于时间戳的提示调度，让你能够轻松生成音画同步、场景连贯、无缝衔接的长篇音乐视频。

• GitHub：https://github.com/fblissjr/ComfyUI-AudioLoopHelper

无需手动计算迭代次数或调整脆弱的常数，只需关注创意本身。

核心亮点：六大工作流变体

该插件提供了六种经过精心调试的工作流变体，满足不同质量与效率需求：

1. 潜在空间工作流（基线版）

• 高效稳定：直接在潜在空间（Latent Space）中进行上下文提取与重叠修剪，避免每次迭代的 VAE 编解码往返，大幅提升速度。
• 无缝拼接：使用 LTXVTiledVAEDecode 进行空间分块解码，消除时间分块带来的接缝。
• 精准 Sigma：反向工程 LTX 2.3 蒸馏管道，生成精确的 DISTILLED_SIGMAS，确保生成质量。

2. 潜在空间 + STG 混合版

• 画质提升：在基线基础上引入 Spacetime Guidance (STG)。
• 多模态引导：使用 MultimodalGuider 替代传统 CFGGuider，分别为音频和视频设置引导参数（cfg=1, stg=1），显著提升时空一致性。
• 绕过 NAG：直接绕过 LTX2_NAG，获得更纯净的控制效果。

3. 潜在空间 + 关键帧调度版

• 场景变换：结合 KeyframeImageSchedule 与 ImageBlend，允许为歌曲的不同部分指定不同的参考图像。
• 真实转场：实现真正的场景切换（如从室内到室外），而不仅仅是光照或颜色的渐变。

4. 图像 + 逐步 AdaIN 版

• 色彩稳定：每次迭代进行 VAE 编解码，并在模型链上应用 LTXVPerStepAdainPatcher。
• 防止漂移：在每个去噪步骤应用 AdaIN（自适应实例归一化），有效防止长视频生成中的色彩漂移问题。

5. 重拍（Reshoot）功能

• 局部修正：无需重新渲染整个视频。加载已生成的 MP4，编码后应用 LatentTemporalMask，仅对指定时间窗口进行重新采样和生成。
• 音频保留：原样传递音频，确保音画同步不受影响。

6. kijai 风格长循环扩展

• 社区适配：改编自 kijai 的 LTX 2.3 长循环测试工作流，兼容社区主流用法。

核心节点功能

• Audio Loop Controller：大脑中枢。仅根据音频张量和窗口/重叠设置，自动计算循环时序、停止信号、种子、步长及掩码。修改 overlap_seconds 即可自动调整所有相关参数，实现“一键控制”。
• Timestamp Prompt Schedule (Batch Encode)：性能优化利器。在循环外对所有提示词进行一次预编码，配合 ConditioningSelectByIteration 使用，保持 CLIP 远离每次迭代路径，大幅降低显存占用并提升速度。
• Keyframe Image Schedule：视觉导演。根据时间戳调度选择每次迭代的关键帧图像，让视频画面随音乐章节变化。
• Audio Loop Planner：可视化助手。显示迭代时间线，帮助你规划提示词调度的时间戳。

快速开始指南

1. 音频分析（离线预处理）

首先，提取音频特征以生成智能提示词调度表：

cd custom_nodes/ComfyUI-AudioLoopHelper
uv sync --group analysis
uv run --group analysis python scripts/analyze_audio_features.py your_song.wav --subject "你的场景描述" --trim 5

• --subject：描述视频整体风格或主体。
• --trim：截取的音频时长用于分析（秒）。

2. 配置工作流

1. 粘贴提示词：将脚本输出的 Node 169 提示词粘贴到对应节点。
2. 设置调度表：将生成的调度文本粘贴到 TimestampPromptScheduleBatchEncode 节点的 schedule 输入中。
3. 保持默认：确保 snap_boundaries=True（默认），这将强制调度边界落在步长的整数倍上，保证每次迭代运行在纯粹的提示词上下文中。

3. 运行生成

点击运行，工作流将在到达音频结尾时自动停止。

调优指南

• overlap_seconds（重叠秒数）：
  • 作用：控制模型从上一次迭代中“看到”多少上下文。
  • 建议：值越高，连贯性越好，但每次迭代覆盖的新内容越少。通常设置为窗口长度的 20%-30%。
• window_seconds（窗口秒数）：
  • 作用：每次迭代生成的视频时长。
  • 建议：根据显存大小调整，通常 4-8 秒为宜。
• base_seed（基础种子）：
  • 机制：每次迭代使用 base_seed + iteration_number，防止生成内容退化或重复。
• blend_seconds（混合秒数）：
  • 作用：控制提示词过渡的平滑程度。
  • 建议：若希望场景切换干脆，设小一点；若希望渐变自然，设大一点。