Suno MIDI 整音（MIDI Tidy）

把「音频转出来的 MIDI」修成能用的 MIDI。核心思路只有一句：
不要相信 MIDI 里写的数字，一切回到 WAV 里找证据。

规范与安装位置

本技能采用 Agent Skills 通用结构（SKILL.md + YAML frontmatter name / description
+ scripts/ + references/），WorkBuddy 与 Codex 共用同一份包，无需改动：

放在技能目录里的脚本用相对路径互相引用（sys.path.insert(0, dirname(__file__))），
不依赖任何绝对路径，因此改挂到哪个平台都能直接跑。

> 安装（或从外部导入）任何技能前，先按本机的 skills 安全审计流程过一遍脚本与
> 依赖清单，再决定是否启用。

〇、完全免费，全功能开放

本技能完全免费：所有能力默认开放，无需授权码，全程离线，不联网、不埋点。

• 当前能力开放情况：python scripts/midi_tidy.py --show-license
• 能力总览：FREE_vs_PRO.md；本包说明：EDITION.md。
• 完整用法见下文；判据与阈值的实测标定见 references/thresholds.md。

> 历史沿革：本技能曾按「免费版 / 专业版」两档分发，专业版凭 license.key
> （Ed25519 离线签名）解锁。现两档已合并为单一全功能免费版——原先锁定的
> mix 输出、拍号写入、无声清理、人声核验、精细力度、批量与长音频，全部默认可用。
> 老用户的 license.key 仍然有效，但已不再影响任何功能的放行。

一、要解决的四个真实问题

均来自日本创作者熊野ぴ太郎的公开发开日志（「MIDI整音」/ MIDI Tidy）：

人声分轨还有两个附加问题：冒高八度和弦、混进整串低音（伴奏串进主唱轨）。
音量检测对它无效——歌手正在唱时，假音符所在位置同样有声音。因此人声走音高证据判据。

二、铁律

1. 原始文件永不修改。 只往输出目录写。输出目录不能位于输入目录内部（代码会拒绝）。
2. 对齐必须排在力度与清理之前。 否则原本属于贝斯第一下的声音会被记到第二个音符头上。
3. 先造一组答案已知的测试音乐，再碰真实歌曲。 程序生成的 MIDI 通常都能打开，实际听起来却可能是错的。不跑通 selftest.py 就不要处理真实分轨。
4. 偏移量先报告、后应用。 默认流程是先分析让你确认；批量处理时才加 --yes。
5. 删除必须留档。 每次运行都产出 *_removed_notes.csv，要能逐个回听。
6. 宁可不删。 删除需要同时满足两个条件（局部信噪比低 且 明显弱于邻近音符）。不确定就用 --conservative。

三、准备素材

同一条分轨的 .mid 与 .wav 放同一个文件夹，文件名必须相同：

我的歌 (Bass).mid     我的歌 (Bass).wav
我的歌 (Drums).mid    我的歌 (Drums).wav
我的歌 (Vocal).mid    我的歌 (Vocal).wav

• 已经在 Suno Studio 导出过 MIDI 的直接用。
• 只有 WAV 的话，可以先用 Spotify 开源的 Basic Pitch 转出 MIDI（单声部贝斯、独奏旋律效果好；复调乐器需要更多人工校对），再交给本技能整理。
• 录音质量差、底噪很高的素材，把 --snr-db-min 调高（见阈值表）。

四、标准流程

第 0 步：环境自检

python -c "import numpy, pretty_midi, soundfile; print('deps ok')"

缺依赖时装（国内走清华镜像）：

python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

> 若本机已有装好依赖的 Python 环境（numpy / scipy / soundfile / pretty_midi 齐备），
> 直接用它的绝对路径替换下面的 python 即可，例如
> /path/to/venv/bin/python scripts/midi_tidy.py ...（Windows 用 D:\py\Scripts\python.exe 同理）。

第 1 步：先跑合成测试（不可跳过）

python scripts/selftest.py

它会生成三组答案已知的素材并逐项断言，覆盖：180ms 延迟识别、15 音→13 音（去 1 重复 + 1 哑音）、力度 1 种→≥8 种、安静前奏零误删、人声假音剔除、原始文件未被改动，以及 Ed25519 的 RFC 8032 官方向量比对、授权码篡改/过期/换机/换产品的拒绝，还有全功能开放的回归护栏（能力集 == 全集、无授权码时默认即产出 mix + score + 逐音清单 + 拍号）。全部 PASS 才继续。

把 --keep 加上可以保留测试目录，人工听检一遍。

第 2 步：只分析，先看偏移量

python scripts/midi_tidy.py --input "我的歌分轨" --out "整理输出" --dry-run

输出形如：

=== 我的歌 (Bass) ===
起音偏移: WAV 比 MIDI 晚 180 ms  (相关性 1236.2)
          估计拍周期 499 ms -> 180 ms 约为 0.36 拍
已应用对齐: +180 ms (MIDI 时间轴)
轨道                           原始       保留       重删       哑删       力度种类
Bass                         15       13        1        1      1→13

看到这一行再决定是否继续。若报告里的偏移量接近一个整拍，说明可能是鼓组循环造成的整拍歧义——换一条乐器轨的结果对照，或用 --no-align 只处理力度。

第 3 步：正式整理

python scripts/midi_tidy.py --input "我的歌分轨" --out "整理输出" --time-sig 3/4 --yes

拍号一定要显式给对——Suno 导出的 MIDI 拍号常常一律写成 4/4，一首三拍子华尔兹也会是 4/4，进 MuseScore 后小节全乱。--time-sig 会把正确的拍号写进 MIDI 元事件。

想用图形界面（含文件夹选择）：

python scripts/start_gui.py            # 启动界面
python scripts/start_gui.py --check    # 只做环境自检，不启动

解释器没有 tkinter 时会自动降级为文本交互，功能完全一致。

> 若拿到的是作者直发包，Windows 上还可以双击 RUN_WINDOWS.bat：它会自建
> .venv、装好依赖再启动界面。技能市场版不含 .bat——.bat / .cmd
> 属于可执行脚本，平台审核一律不接受（见 references/pitfalls.md）。

第 4 步：回听验证（这一步不能省）

1. 把 mix/ 里的整理后 MIDI 和原 WAV 一起拖进 DAW，叠着播放。
2. 打开 report/*_removed_notes.csv，逐个回听被删掉的音。若删错，调高 --snr-db-min 或直接用 --no-delete-silent 重跑。
3. 人声串音没干净，再调 --vocal-min-evidence-db；谱面仍然乱，才考虑加节拍、拍号、MusicXML 输出。

五、输出结构

整理输出/
├── mix/      演奏时间细节版（Cubase / Ableton 继续编曲）
├── score/    按栅格量化版（MuseScore 出谱），拍号已写入
└── report/
    ├── <曲名>_report.csv         每轨：原始/保留音符数、各类删除数、力度种类前后对比、偏移量
    ├── <曲名>_removed_notes.csv 被删音符逐个清单（音名、时间、删除原因、局部 SNR）← 回听就看这个
    └── <曲名>_summary.json      完整参数与警告，便于复现

mix 与 score 的差别只在时间处理：mix 原样保留演奏时间（可含亚毫秒抖动），score 量化到 --grid 指定的栅格并保证音符长度不为零。力度、清理结果两者完全一致。

六、判据与阈值

阈值怎么定的、为什么用「同频段非谐波内容的 95 百分位」当人声参考（而不是全频段中位谱）、以及各判据的实测隔离带，见 references/thresholds.md。

七、已知限制（必须如实告知用户）

• 复调乐器（钢琴和弦）力度不可精确还原。 几个音同时响在同一条 WAV 里，程序无法判断是哪根手指更用力。流程会自动标记「复调不确定音」并在报告里给出警告，需人工复核。
• 和声、合唱、颤音、滑音超出当前人声判据的适用范围（单人主唱效果好）。最终判断仍要放回歌曲里听。
• 八度上方的误判只报告不自动改音高（报告里出现 suspect-octave-up）。自动移调的风险大于收益。
• 起音对齐用的是能量突变而非严肃的 onset detection 库；对极弱的弦乐起音、连续渐强的 pad，相关性会下降，此时以报告里的相关性数值为准判断可信度。

八、扩展新功能

这个技能本身就是「一份写得足够细的需求说明」，可以继续长。改之前先记住循环：

1. 在 scripts/synth_fixture.py 里加一组会失败的合成素材（把想要的新行为对应的错误故意插进去）。
2. 在 scripts/selftest.py 里加断言，先看它 FAIL。
3. 改 scripts/tidy_core.py，直到全绿。
4. 最后才拿真实分轨验证。

已有的自然下一步：鼓组按 GM 映射整理、节拍/拍号检测与 MusicXML 导出、整体移调与调号、score 版的分谱（一行一乐器）输出。

文件清单