SunoAuxTool

Suno / 海绵音乐 / 网易天音等 AI 音乐工具的前期 + 后期处理工具箱（原 SmartNoteGen， v1.0.0 起统一为单一发行版 sunoauxtool）。

• 前期：旋律制作、程序化多轨 MIDI 生成、谱面产出（五线谱/简谱/MusicXML）、MIDI↔WAV 互转
• 后期：音频下载/转码（猫抓取证 + API adapter 留位，DownloadHelper）、DSP（规划中）、 音乐视频产出（多轨混音 + 7 种视觉含滚动谱面）、音质提升/分离修复（AudioSR 接入，R5）

技术栈：Python 3.12+ · Typer · music21 · pretty_midi · FluidSynth · numpy/soundfile · Pillow · PyTorch（AI 可选） P1 可选：MusicGen / DiffRhythm（AI 扩编曲与歌曲草稿，默认不安装）

模块布局（单包多子模块）：sunoauxtool（核心：生成/谱面/分析/导出）· sunoauxtool.video（原 videomaker）· sunoauxtool.download（DownloadHelper， 原 Suno-Cat-Catch-Resolve）。旧包名 smartnotegen / videomaker 兼容 shim 已于 1.4.5 移除，请使用新包名。 完整功能清单（命令树、模块能力、错误码总表）见 docs/features.md。

安装

1. 准备 venv 并安装依赖

cd SunoAuxTool
python -m venv venv
venv\Scripts\activate
pip install -r requirements/base.txt      # P0 运行依赖（不含 torch）
pip install -r requirements/dev.txt       # 开发依赖（pytest 等）
pip install -e .                          # 安装 sunoauxtool / sunoaux / downloadhelper 命令

从 PyPI 安装（1.5.3 起）：推 v* tag 时 CI 自动构建并发布到 PyPI， 之后可直接 pip install sunoauxtool。PyPI 侧需一次性配置 Trusted Publisher（.github/workflows/publish.yml 顶部有说明；token 兜底见注释）。

2. Windows 外部程序（渲染必需）

不装 FluidSynth/SoundFont 时，generate midi / generate melody 仍可用；render / pipeline 会以退出码 4 提示安装指引。

3. MP3 导出（可选）

pip install lameenc

快速开始（零参数 demo）

sunoauxtool pipeline
# → 读默认配置（C major / 120bpm / 8 小节 / C-G-Am-F / 3 轨）
# → 生成 MIDI → FluidSynth 渲染 WAV（44.1kHz/16bit）→ 裁剪至 25s + 淡入淡出
# → output/YYYYMMDD/pop_Cmajor_120_8bars_demo_*_suno25s.wav
# → 打印：文件路径 + 元数据（时长/采样率/位深/和弦进行/seed）

也可以用聚合入口 sunoaux（v1.0.0 起）：pre = 前期创作，post = 后期处理 （详见 sunoaux --help）：

sunoaux pre midi --chords C-G-Am-F      # = sunoauxtool generate midi
sunoaux post convert cache/song.mp3     # = downloadhelper decode（fMP4 转码）
sunoaux post video render song.wav      # = sunoauxtool.video 渲染（音乐视频）

子命令一览

后期处理三件套（enhance / dsp / fetch）挂在聚合入口的 post 组下： sunoaux post enhance song.wav、sunoaux post dsp song.wav --ops "reverb 0.3"、 sunoaux post fetch "歌名" --source catcatch --dry-run。

完整参数说明见 docs/usage.md；乐谱生成（五线谱 / 简谱 / MusicXML）见 docs/score.md。

音乐视频（sunoauxtool.video，原 videomaker）

把 SunoAuxTool 产出的音频一键合成可发布的音乐视频 / 音频可视化， 适配抖音/YouTube/Instagram/官网四大平台。非 AI，已并入主包。

输入格式：WAV / MP3 / FLAC / OGG / MIDI（MIDI 自动用 FluidSynth 渲染） 能力：多轨混音（增益/声像/归一化）、分轨可视化、滚动谱面（五线谱/简谱）、8 种视觉效果、多平台批量

sunoaux post video render ... 命令随 `pip install -e .` 一并安装

# 抖音竖屏波形
sunoaux post video render output/.../x.wav --preset douyin --style waveform

# MIDI 直接出视频（自动渲染）
sunoaux post video render song.mid -p youtube -s circular_spectrum

# 多轨混音 + 分轨可视化（WAV/MP3/MIDI 可混用，同产混音 WAV）
sunoaux post video render drums.wav "bass.mid:gain=0.8:pan=-0.3" melody.mp3 \
    -p douyin -s tracks --title "三轨混音"

# 一次产出全部平台 + Logo 水印 + 标题
sunoaux post video multi x.wav --presets douyin,youtube,instagram,official \
    --style circular_spectrum --logo logo.png

# 8 种视觉效果：waveform / spectrum / circular_spectrum / reactive / tracks / waveform_scroll / score / bars
# score 样式：滚动谱面（播放头居中、当前音高亮），--tempo-grid 叠加节拍网格 + BPM 标注
videomaker render song.mid -p douyin --style score --tempo-grid --notation jianpu

详见 docs/videomaker.md。

Suno-Cat-Catch-Resolve 子项目（Suno 猫抓产物解码）

把「猫抓」(CatCatcher) 从 Suno 抓下来的打不开的文件转成可播放音频： 自动识别哪份是明文、哪份是加密密文，并把明文解码为 Opus / MP3。 纯本地处理，独立包，依赖 ffmpeg。

为什么需要它：猫抓会给出两份同一首曲子的文件——

<uuid>.m4a 经取证（卡方 χ²≈215 完美均匀 + 周期扫描无异于随机基线）判定为 AES / ChaCha20 级强加密，这是数学结论而非工具限制——所以包不会对它假装成功， 而是明确报错并提示改用缓存捕获的那份（它已是完整明文副本）。

downloadhelper 命令随 `pip install -e .` 一并安装
export SUNO_FFMPEG=/d/tools/ffmpeg/bin/ffmpeg.exe   # ffmpeg 不在 PATH 时：指文件或指目录

downloadhelper probe  "Suno _ AI Music.mp3"      # 取证判定
downloadhelper decode "Suno _ AI Music.mp3" -o ./out
downloadhelper batch  ./downloads -o ./out       # 批量，密文自动跳过

# —— 通用转码中枢（1.6.0）——
downloadhelper convert song.flac --fmt mp3 --bitrate 320k    # 音频互转
downloadhelper convert song.mp3 --profile suno               # 44.1k/16bit wav 合规预设
downloadhelper extract-audio clip.mp4 --fmt m4a              # 视频分离音轨（AAC 直通零损）
sunoaux post convert-audio / extract-audio                   # 聚合入口镜像

命名：三包合一后本子包为 sunoauxtool.download（CLI 入口 downloadhelper）。 旧目录名 Suno-Cat-Catch-Resolve、旧入口 suno-cat-catch-resolve 与旧 import 名 suno_cat_catch_resolve 均已移除，无兼容 shim——请改用上面的 downloadhelper 命令 与 import sunoauxtool.download（smartnotegen / videomaker shim 亦已于 1.4.5 移除）。

详见 docs/downloadhelper.md（三包合一后子包位于 src/sunoauxtool/download/，原 src/Suno-Cat-Catch-Resolve/ 目录已移除）。

致谢 / 相关项目

转码与 NCM 解包设计过程中参考了下列优秀项目（仅设计参考，零代码依赖， examples/ 目录本地研读不入库）：

• ncm2mp3 —— 纯 Python 标准库网易云 NCM 解锁
• ncmdump —— C++ NCM 转储实现
• ncm2mp3-js —— Web/ekey 路线参考
• SUNO Capture —— Chrome 扩展：suno.com 页面注入 MP3/WAV 下载按钮
• DLBunny —— Suno 在线音频下载站

配置

配置合并优先级（低 → 高）：内置默认值 < config/default.toml < 用户配置文件 < CLI 参数。

sunoauxtool config init            # 生成 sunoauxtool.toml（可修改 SoundFont 路径）
sunoauxtool config show            # 查看生效配置
sunoauxtool --config my.toml generate midi   # 指定配置文件

用户配置文件默认查找项目根 sunoauxtool.toml，也可用 --config 显式指定。

错误码

P1 AI 集成（可选）

AI 依赖默认不安装（P0/P1-非AI 环境零 torch import）。安装后使用：

# 1. CUDA 版 torch + torchaudio（RTX 4060 / CUDA 12.1；务必用 cu121 索引避免装回 CPU 版）
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121

# 2. 其余 AI 依赖（audiocraft / DiffRhythm 运行库）
pip install -r requirements/ai.txt

# 3. DiffRhythm 仓库（官方不可 pip 安装，需手动克隆到 module/diffrhythm 或设置 DIFFRHYTHM_DIR）
git clone https://github.com/ASLP-lab/DiffRhythm.git module/diffrhythm

# 4. Windows：DiffRhythm 人声合成依赖 espeak-ng（下载 .msi 安装并加入 PATH）
#    https://github.com/espeak-ng/espeak-ng/releases

# 5. 权重下载较慢时使用国内镜像（首次需下载数 GB 权重）
set HF_ENDPOINT=https://hf-mirror.com

用法示例：

# MusicGen：以旋律 WAV 为条件扩编曲（medium fp16 默认；显存不足可 --model-size small）
sunoauxtool ai musicgen --input melody.wav --prompt "upbeat pop" --output acc.wav --duration 20 --seed 42

# DiffRhythm：风格提示 → ≥60s 带人声歌曲草稿（chunked=True 默认；草稿不进 Suno 导出链）
sunoauxtool ai diffrhythm --prompt "slow ballad" --lyrics "第一句词" --duration 95

详见 docs/ai-integration.md。

开发

pytest            # 运行全部测试（渲染用例使用 mock，无需真实 fluidsynth）
ruff check src    # lint