Extensions/SongBloom_ComfyUI
ComfyUI Extension

SongBloom_ComfyUI

SongBloom is a music generation plugin for ComfyUI that integrates the entire process of lyrics standardization, model loading, generation, saving, and previewing, and provides DeepSeek V3 assistance for lyric formatting.

By xuchenxu168·Created 12 months ago·Updated 10 months ago· 15
xuchenxu168/SongBloom_ComfyUI
Nodes14
On cloudLocal install
CategorySongBloom/Utils, SongBloom/Audio
Stars15
Updated10 months ago

Nodes (14)

SongBloom Advanced Config

The config node that packages SongBloom's sampling knobs into one object

SongBloom/Utils
SongBloom Audio Analyzer

Check your reference clip before SongBloom hears it

SongBloom/Utils
SongBloom Audio Cropper

Cut a reference clip down to size before SongBloom uses it

SongBloom/Audio
SongBloom Audio Ensure2D

The shape-fixer that stops 'Dimension out of range' before it happens

SongBloom/Audio
SongBloom Audio Preview

The in-graph player that lets you hear a song before you save it

SongBloom/Audio
SongBloom Audio Prompt

The 10-second clip that makes SongBloom sing *your* song

SongBloom/Audio
SongBloom Audio Saver

The saver that finally puts your SongBloom output on disk

SongBloom/Audio
SongBloom Batch Processor

Queue up a dozen songs from one model load

SongBloom/Utils
SongBloom DeepSeek Lyric Formatter

This node formats lyrics via DeepSeek — and it needs a key

SongBloom/Text
SongBloom Generator

The node at the center of every SongBloom workflow

SongBloom/Generation
SongBloom Lyric Generator

The node that writes your lyrics (DeepSeek or templates), pre-formatted for SongBloom

SongBloom/Lyrics
SongBloom Lyric Processor

The lyric cleanup node that stops the model from singing nonsense

SongBloom/Text
SongBloom Lyric Validator

The referee that tells you why your song came out as gibberish

SongBloom/Utils
SongBloom Model Loader

Loading the 2B SongBloom model

SongBloom/Models
Readme

ComfyUI SongBloom 插件（完整文档）

面向 ComfyUI 的 SongBloom 音乐生成插件，集成歌词规范、模型加载、生成、保存与预览等全流程能力，并提供 DeepSeek V3 辅助“歌词格式化”。

亮点功能

  • 端到端歌曲生成：最长约 150s（取决于模型配置）
  • 结构化歌词驱动：规范的标签格式，生成更稳定
  • 参考音频提示：可选风格参考（自动重采样/裁剪）
  • 质量优化预设：一键切换 Ultra/High/Balanced/Fast
  • 低显存保护：支持低显存模式、自动降级与重试
  • 音频工具集：截取、维度修复、保存与内置预览
  • DeepSeek V3 对齐实现：用于“歌词格式转换”的 API 节点，支持从 JSON/环境变量读取 Key

Installation

Prerequisites

  • ComfyUI installed and working
  • Python 3.8 or higher
  • CUDA-compatible GPU (recommended)
  • At least 8GB VRAM for float32, 6GB for bfloat16

Step 1: Clone the Plugin

cd ComfyUI/custom_nodes
git clone https://github.com/your-repo/ComfyUI_SongBloom.git

Step 2: Install Dependencies（依赖安装）

cd ComfyUI_SongBloom
pip install -r requirements.txt

Step 3: 安装脚本（可选）

cd ComfyUI_SongBloom
python install.py

This script will:

  • Check system requirements
  • Verify dependencies
  • Set up model directories
  • Test SongBloom components

模型设置

模型下载链接（参考官方仓库）

下表与官方仓库的“Models”保持一致，便于直接跳转下载模型文件。官方仓库链接

| 名称 | 规模 | 最长时长 | 提示类型 | 下载/说明 | | --- | --- | --- | --- | --- | | songbloom_full_150s | 2B | 2m30s | 10s wav | HuggingFace | | songbloom_full_150s_dpo | 2B | 2m30s | 10s wav | HuggingFace |

说明：当前两个版本权重均托管在同一模型卡页面，请在页面内选择对应的 .pt 与配置文件。

本地模型（推荐）

如果您已经有本地模型文件，请将它们放置在以下目录：

ComfyUI/models/SongBloom/
├── songbloom_full_150s.pt              # 基础模型
├── songbloom_full_150s_dpo.pt          # DPO微调模型（推荐）
├── songbloom_full_150s.yaml            # 配置文件（可选）
├── songbloom_full_150s_dpo.yaml        # 配置文件（可选）
├── stable_audio_1920_vae.json          # VAE配置
├── autoencoder_music_dsp1920.ckpt      # VAE权重
└── vocab_g2p.yaml                      # G2P词汇表

支持的模型文件：

  • songbloom_full_150s.pt: 基础模型 (2B参数)
  • songbloom_full_150s_dpo.pt: DPO微调模型 (推荐使用)

自动下载模型

如果没有本地模型，插件会自动从HuggingFace Hub下载。确保有网络连接。

下载的文件：

  • 模型权重 (.pt文件)
  • 配置文件 (.yaml)
  • VAE组件
  • G2P词汇文件

总下载大小: ~8GB

加载模式

在SongBloomModelLoader节点中，您可以选择不同的加载模式：

  • local_first (默认): 优先使用本地模型，如果不存在则下载
  • local_only: 仅使用本地模型，不下载
  • download_only: 强制从网络下载

自动配置修复

插件包含智能配置修复功能，会自动处理常见的配置问题：

  • VAE配置自动修复: 自动检测和配置VAE设置，解决"Missing key vae"错误
  • 文件智能匹配: 支持多种文件名和扩展名（.pt, .ckpt, .pth）
  • 详细错误日志: 提供清晰的修复过程信息

音频质量优化

质量配置节点（SongBloomQualityConfig）

新增的 SongBloomQualityConfig 节点提供专业级音频质量优化：

质量预设

  • Ultra High: CFG=4.0, Steps=200, Top_k=50 - 最高质量，适合最终作品
  • High: CFG=3.0, Steps=100, Top_k=100 - 高质量，日常推荐
  • Balanced: CFG=2.0, Steps=75, Top_k=150 - 质量与速度平衡
  • Fast: CFG=1.5, Steps=50, Top_k=200 - 快速生成，适合测试

参数说明

  • CFG系数: 控制对歌词的遵循程度，越高质量越好但生成时间越长
  • 推理步数: 扩散模型去噪步数，越多细节越丰富
  • Top_k采样: 限制采样候选数，越低越稳定

使用方法

  1. 添加 SongBloomQualityConfig 节点
  2. 选择质量预设或自定义参数
  3. 连接到 SongBloomGenerator 的 quality_config 输入
  4. 生成高质量音频

质量优化建议

如果音频质量不佳，请尝试：

  • 使用 "High" 或 "Ultra High" 质量预设
  • 确保歌词格式规范（使用 SongBloomLyricProcessor 验证）
  • 提高CFG系数到3.0以上
  • 增加推理步数到100以上
  • 降低Top_k值到100以下

详细的质量优化指南请参考：音频质量优化指南.md

快速开始

基础工作流

  1. 加载模型: 使用 SongBloomModelLoader 加载SongBloom模型

    • 选择模型: songbloom_full_150s 或 songbloom_full_150s_dpo (推荐)
    • 选择加载模式: local_first (优先本地), local_only (仅本地), download_only (仅下载)
    • 选择数据类型: float32 (高质量) 或 bfloat16 (节省显存)

  2. 处理歌词: 使用 SongBloomLyricProcessor 格式化歌词

    • 支持中文和英文歌词
    • 自动验证歌词格式
    • 提供格式建议和错误修正

  3. 准备音频提示: 使用 SongBloomAudioPrompt 选择音频风格参考 (可选)

    • 智能文件选择: 下拉菜单自动显示系统中的音频文件
    • 多目录搜索: 自动搜索音乐文件夹、桌面、ComfyUI输入目录等
    • 格式支持: WAV, FLAC, MP3, OGG, M4A, AAC等格式
    • 自动处理: 自动重采样到48kHz，调整到10秒长度
    • 可选使用: 选择"无 (不使用音频提示)"可跳过音频风格参考

  4. 生成歌曲: 使用 SongBloomGenerator 创建歌曲

    • 可调节CFG系数、步数等参数
    • 支持不同质量设置
    • 显示生成进度和信息

  5. 保存音频与预览: 使用 SongBloomAudioSaver 保存结果（节点面板会显示预览）

    • 支持FLAC, WAV, MP3格式
    • 自动文件命名和时间戳
    • 可自定义输出目录
    • 内置音频预览功能 - 保存的同时提供音频预览输出

  6. 音频预览: 使用 SongBloomAudioPreview 试听音频（本插件自带的高级预览器）

示例工作流

插件提供了多个示例工作流，位于 example_workflows/ 目录：

  1. local_quick_start.json - 快速开始工作流

    • 最简单的本地模型使用示例
    • 预配置参数，开箱即用

  2. audio_file_selection_demo.json - 音频文件选择演示

    • 展示音频风格参考功能
    • 智能音频文件搜索和选择

  3. audio_playback_demo.json - 音频播放功能演示 (新增)

    • 展示音频保存和播放功能
    • 包含音频预览和专门的播放器节点
    • 完整的音频处理工作流

音频文件选择功能（SongBloomAudioPrompt）

新版本的 SongBloomAudioPrompt 节点提供了智能音频文件选择功能：

自动搜索目录

插件会自动搜索以下目录中的音频文件：

ComfyUI相关目录:

  • ComfyUI/input/ - ComfyUI输入目录
  • ComfyUI/models/audio/ - 音频模型目录

用户常用目录:

  • ~/Music 或 ~/音乐 - 用户音乐文件夹
  • ~/Desktop - 桌面目录
  • ~/Downloads 或 ~/下载 - 下载文件夹
  • ~/Documents/Music - 文档音乐文件夹

系统目录 (Windows):

  • C:/Users/Public/Music - 公共音乐文件夹
  • C:/Windows/Media - 系统音频文件夹

音频软件目录:

  • FL Studio、Audacity等音频软件的文档目录

支持的音频格式

  • WAV (推荐，无损格式)
  • FLAC (无损压缩)
  • MP3 (有损压缩)
  • OGG (开源格式)
  • M4A (Apple格式)
  • AAC (高效压缩)

使用方法

  1. 在 SongBloomAudioPrompt 节点中点击 audio_file 下拉菜单
  2. 从列表中选择您想要的音频文件作为风格参考
  3. 选择 "无 (不使用音频提示)" 可以不使用音频风格参考
  4. 插件会自动处理音频文件（重采样、调整长度等）

智能处理特性

  • 自动搜索多个系统目录
  • 智能文件去重和排序
  • 自动格式验证和错误提示
  • 支持多种音频格式

音频质量建议

  • 最佳长度: 5-15秒的音频片段
  • 推荐格式: WAV或FLAC无损格式
  • 采样率: 任意采样率（插件会自动转换为48kHz）
  • 声道: 支持单声道和立体声（会自动转换为单声道）

歌词格式示例

[intro] [intro] [intro] [intro] [intro] [intro] [intro] [intro] [intro] [intro] , 
[verse] City lights flicker through the car window. Dreams pass fast where the lost ones go. Neon signs echo stories untold. I chase shadows while the night grows cold , 
[chorus] Run with me down the empty street. Where silence and heartbeat always meet. Every breath. a whispered vow. We are forever. here and now , 
[inst] [inst] [inst] [inst] [inst] [inst] [inst] [inst] [inst] [inst] [inst] [inst] , 
[verse] Footsteps loud in the tunnel of time. Regret and hope in a crooked rhyme. You held my hand when I slipped through the dark. Lit a match and you became my spark , 
[bridge] We were nothing and everything too. Lost in a moment. found in the view. Of all we broke and still survived. Somehow the flame stayed alive , 
[chorus] Run with me down the empty street. Where silence and heartbeat always meet. Every breath. a whispered vow. We are forever. here and now , 
[outro] [outro] [outro] [outro] [outro] [outro] [outro] [outro] [outro] [outro] [outro]

节点一览（本插件提供）

SongBloomModelLoader（模型加载）

加载本地或自动下载的 SongBloom 模型，并支持 dtype/加载模式等设置。

Inputs:

  • model_name: Choose between available models
  • dtype: Precision (float32/bfloat16)
  • force_reload: Force re-download of model files

Outputs:

  • model: Loaded SongBloom model

SongBloomLyricProcessor（歌词处理与校验）

Inputs:

  • lyrics: Multi-line text with structure tags
  • validate_format: Enable format validation

Outputs:

  • processed_lyrics: Formatted lyrics
  • validation_info: Validation results

SongBloomAudioPrompt（参考音频处理）

Inputs:

  • audio_path: Path to audio file
  • audio: Audio tensor (alternative to path)
  • target_duration: Duration in seconds (default: 10s)

Outputs:

  • processed_audio: Prepared audio prompt
  • info: Processing information

SongBloomGenerator（歌曲生成）

Inputs:

  • model: SongBloom model
  • lyrics: Processed lyrics
  • audio_prompt: Audio prompt
  • cfg_coef: Classifier-free guidance coefficient
  • steps: Number of diffusion steps
  • top_k: Top-k sampling parameter
  • seed: Random seed (-1 for random)

Outputs:

  • generated_audio: Generated song
  • generation_info: Generation statistics

SongBloomAudioSaver（音频保存，带节点内预览）

Inputs:

  • audio: Audio to save
  • filename: Output filename
  • format: Audio format (FLAC/WAV/MP3)
  • output_dir: Output directory (optional)
  • enable_preview: Enable audio preview output (optional)

Outputs:

  • file_path: Path to saved file
  • audio_preview: Audio preview for playback (when enabled)

SongBloomAudioPreview（音频预览输出节点）

Inputs:

  • audio: Audio to play
  • title: Display title for the audio (optional)
  • auto_play: Enable automatic playback (optional)

Outputs:

  • audio: Pass-through audio for further processing
  • info: Audio information (duration, sample rate, etc.)

歌词格式规范

Structure Tags

  • [intro] - Introduction section
  • [verse] - Verse section with vocals
  • [chorus] - Chorus section with vocals
  • [bridge] - Bridge section with vocals
  • [inst] - Instrumental section
  • [outro] - Outro section

Formatting Rules

  1. Use structure tags to mark different sections
  2. Separate sentences with . in vocal sections
  3. Separate sections with ,
  4. Repeat tags for longer instrumental sections
  5. Include at least one vocal section

DeepSeek V3（歌词格式转换）

  • 节点：SongBloom DeepSeek Lyric Formatter
  • 实现：使用 OpenAI SDK，base_url=https://api.deepseek.com，模型 DeepSeek-V3（内部映射为 deepseek-chat）
  • 读取 API Key 优先级：
    1. 节点输入 api_key
    2. 环境变量 DEEPSEEK_API_KEY
    3. DeepseekAP-config.json（本项目根目录）
    4. config.yaml 中 deepseek.api_key（兜底）
  • JSON 配置文件示例（DeepseekAP-config.json）：
{
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxx"
}

DeepSeek API 申请指南与使用说明

  1. 申请步骤（以 DeepSeek 官方为准）

    • 前往 DeepSeek 官网注册并完成实名认证（若需）
    • 进入控制台创建 API Key，复制得到形如 sk-... 的密钥
    • 建议为本项目单独创建一个 Key，便于额度管理

  2. 在本项目中配置 API Key（四选一，按优先级覆盖）

    • 方式 A（节点内最直观）：在 SongBloom DeepSeek Lyric Formatter 或 SongBloom Lyric Generator（勾选 use_deepseek）节点的 api_key 输入框中粘贴 Key
    • 方式 B（环境变量）
      • Windows PowerShell（会话级）：$env:DEEPSEEK_API_KEY = "sk-xxxx"
      • 永久：在系统环境变量新增 DEEPSEEK_API_KEY
    • 方式 C（推荐）在项目根目录创建/编辑 DeepseekAP-config.json： 
      {
  "api_key": "sk-xxxxxxxxxxxxxxxxxxxx"
}
    • 方式 D（兜底）在 config.yaml 中新增： 
      deepseek:
  api_key: "sk-xxxxxxxxxxxxxxxxxxxx"

  3. 在工作流中的用法

    • 仅格式化：直接使用 SongBloom DeepSeek Lyric Formatter，填入 prompt（你的主题/要求），其余保持默认（model 选 DeepSeek-V3）
    • 融入生成链：在 SongBloom Lyric Generator 勾选 use_deepseek，将 style/mood/language/theme_keywords/user_requirements 等参数作为上下文传入，由 DeepSeek 生成结构化歌词；本节点会自动做格式清洗与校验
    • 默认系统提示词已内置，保证输出严格遵循 SongBloom 标签格式；如需定制，可在节点的 deepseek_system_prompt 中覆盖

  4. 常见问题

    • 400/401 错误：通常是 Key 无效或模型名不匹配（本插件已将 DeepSeek-V3 映射为 deepseek-chat）
    • 代理：若系统设置了 HTTP_PROXY/HTTPS_PROXY，SDK 将继承；需要直连时清空相关环境变量
    • 额度：请在 DeepSeek 控制台查看用量与账单，避免因额度不足导致失败

工具节点

SongBloomAudioCropper（音频截取）

  • 输入：音频、start_sec、end_sec、pad_to_end
  • 输出：裁剪后的音频与信息字符串
  • 特性：自动矫正形状为 (channels, samples)，支持空结果兜底（可补 0.01s 静音）

SongBloomAudioEnsure2D（维度修复）

  • 将任意 0D/1D/3D/列表/ndarray 规约为 2D (channels, samples)，并保证 CPU/contiguous
  • 建议在使用非本插件的保存节点前串联，避免“Dimension out of range”

生成与显存优化

低显存模式（SongBloomGenerator 可选项）

  • low_memory_mode：启用后在 OOM 时自动清缓存、降步数/CFG/增大 top_k，并可重试
  • max_memory_retries：最大重试次数（默认 2）
  • prompt_max_seconds：限制参考音频最长秒数（默认 10），超出会裁剪

建议参数

  • 紧张显存：bfloat16 + steps 40~60 + cfg 1.5~2.0 + prompt_max_seconds 5
  • 高质量：float32 + steps ≥100 + cfg 3.0

额外提示（与官方实现一致的显存管理）

  • 在底层生成循环开始前会显式调用一次 torch.cuda.empty_cache()，以释放碎片显存。
  • max_frames 值越大峰值显存越高，建议根据目标时长调节；显存紧张时将其下调（如 7500 或更低）。

故障排查（Troubleshooting）

Common Issues

"SongBloom dependencies not available"

  • Install requirements: pip install -r requirements.txt
  • Ensure all dependencies are properly installed

"CUDA out of memory"

  • Use bfloat16 dtype instead of float32
  • Reduce batch size or song length
  • Close other GPU-intensive applications

"Model download failed"

  • Check internet connection
  • Verify HuggingFace Hub access
  • Try force reload option

Performance Tips

  • Use bfloat16 for lower VRAM usage
  • Start with shorter songs for testing
  • Use lower step counts for faster generation
  • Enable flash attention if available

Advanced Usage

Custom Model Paths

You can specify custom model cache directories by modifying the cache_dir in the model loader.

Batch Processing

使用 SongBloomBatchProcessor 可批量生成多首歌曲（同一模型/提示，不同歌词）。

Quality Settings

  • High Quality: steps=100, cfg_coef=2.0, dtype=float32
  • Balanced: steps=50, cfg_coef=1.5, dtype=bfloat16 (default)
  • Fast: steps=25, cfg_coef=1.0, dtype=bfloat16

Memory Optimization

For systems with limited VRAM:

  1. Use bfloat16 dtype
  2. Reduce max_frames in advanced config
  3. Close other GPU applications
  4. Consider using CPU offloading (slower but uses less VRAM)

故障排除

常见问题

1. 模型加载失败

问题: "Model file not found" 或 "Failed to load model" 解决方案:

  • 确保模型文件位于 ComfyUI/models/SongBloom/ 目录
  • 检查文件名是否正确: songbloom_full_150s.pt 或 songbloom_full_150s_dpo.pt
  • 尝试使用 download_only 模式重新下载模型
  • 运行 python test_local_models.py 检查模型状态

1.1. OmegaConf Resolver错误

问题: "resolver 'eval' is already registered" 解决方案:

  • 这是多次加载模型时的常见问题，已在v1.1.0中修复
  • 重启ComfyUI应用修复
  • 现在支持多次加载和切换模型
  • 如果仍有问题，运行 python test_model_loading.py 验证修复

2. 显存不足

问题: "CUDA out of memory" 解决方案:

  • 使用 bfloat16 数据类型
  • 减少生成步数 (steps)
  • 关闭其他GPU应用程序
  • 降低 max_frames 参数

3. 歌词格式错误

问题: "Invalid lyric format" 或生成质量差 解决方案:

  • 使用 SongBloomLyricValidator 检查歌词格式
  • 确保包含必要的结构标签: [intro], [verse], [chorus], [outro]
  • 参考示例歌词格式
  • 每个部分用逗号分隔

4. 音频提示问题

问题: 音频加载失败或格式不支持 解决方案:

  • 确保音频文件存在且可读
  • 支持的格式: WAV, FLAC, MP3, OGG
  • 音频长度建议5-15秒
  • 使用 SongBloomAudioAnalyzer 检查音频质量

5. 生成速度慢

问题: 生成时间过长 解决方案:

  • 减少生成步数 (25-50步通常足够)
  • 使用 bfloat16 数据类型
  • 确保使用GPU而非CPU
  • 检查CUDA版本兼容性

性能优化建议

  1. 首次使用: 选择 local_first 模式，让插件自动处理模型加载
  2. 显存优化: 使用 bfloat16 + 50步数 + CFG系数1.5
  3. 质量优化: 使用 float32 + 100步数 + CFG系数2.0
  4. 速度优化: 使用 bfloat16 + 25步数 + CFG系数1.0

License

遵循上游 SongBloom 项目的相同协议，详见仓库 LICENSE。

Citation

If you use this plugin in your research, please cite the original SongBloom paper:

@article{yang2025songbloom,
title={SongBloom: Coherent Song Generation via Interleaved Autoregressive Sketching and Diffusion Refinement},
author={Yang, Chenyu and Wang, Shuai and Chen, Hangting and Tan, Wei and Yu, Jianwei and Li, Haizhou},
journal={arXiv preprint arXiv:2506.07634},
year={2025}
}

Contributing

欢迎提交 Issue/PR 参与共建。

Support

若遇到问题：

  • 先参考本文"故障排查/性能优化"章节
  • 查看 example_workflows/ 示例工作流
  • 反馈具体日志与截图，便于定位

联系方式

如有技术问题或合作需求，欢迎通过微信联系：

微信二维码

<div align="center"> <img src="https://github.com/xuchenxu168/images/blob/main/%E5%BE%AE%E4%BF%A1%E5%8F%B7.jpg" alt="微信二维码" width="200" height="200"> <p><em>扫码添加微信，备注"SongBloom"</em></p> </div>