name: mp3-to-piano description: 把 mp3 / wav 等音频转换成钢琴曲（钢琴版 / 钢琴伴奏 / 钢琴翻弹）时使用。完全本地脚本完成，无需联网（首次运行 basic-pitch 会下载约 100MB 模型权重）。当用户说"把这首歌变成钢琴曲""转成钢琴伴奏""做个钢琴翻弹版"等意图时调用。

MP3 → 钢琴曲

把任意歌曲/音频离线转成钢琴演奏版。本地完成，零外部采样依赖（不依赖 SoundFont / 联网音色库）。

原理

1. mp3 → wav：ffmpeg 转 22050Hz 单声道（basic-pitch 推荐输入）
2. 音频转 MIDI 转录：basic-pitch（Spotify 开源的神经网络多音高检测）把频谱转录成 MIDI 音符。若开 --hpss，转录前先用 librosa 做谐波/打击乐分离，只把旋律(谐波)轨送进去，避开鼓点误判
3. 音符过滤（可选）：按音高范围去除底鼓/超高频误判
4. MIDI → 钢琴 WAV：纯 numpy 加法合成器，建模钢琴声学特征（多谐波 + 轻微 inharmonicity + 指数衰减包络 + 击弦瞬态 + 轻量卷积混响）
5. WAV → mp3：ffmpeg 导出 192kbps 钢琴版

依赖

# 系统
ffmpeg          # 在 PATH 中，或用环境变量 FFMPEG_EXE 指定绝对路径

# Python —— 必须 3.9~3.11（3.12+ 装不上 basic-pitch：其依赖 numpy<2/TF 无新版 wheel）
pip3 install basic-pitch pretty_midi numpy scipy soundfile
# 注意：basic-pitch 会顺带安装 tensorflow/jax，若遇到 ml_dtypes 版本冲突，执行：
#   pip3 install "ml-dtypes==0.5.1"

# 真实钢琴采样渲染（--soundfont 用，可选但推荐）
#   引擎 A（优先，纯 pip，3.9 也能用）：
pip3 install tinysoundfont
#   引擎 B（回退，需系统库）：pip install pyfluidsynth + 系统装 fluidsynth
#   钢琴 SoundFont：FreePats UprightPianoKW(CC0, 6MB) / FluidR3_GM / Salamander Grand

脚本启动时会自动做环境自检（Python 版本 / ffmpeg / basic-pitch），不通过会给出修复指引后退出。

关于模型权重：basic-pitch 安装包内已自带 ONNX 格式模型（nmp.onnx），装有 onnxruntime 时无需 TensorFlow、无需联网下载权重，开箱即用。只有走 TF 后端才需要首次联网下载约 100MB 权重。

Windows / 沙箱环境跑通指南（已实测）

在「无 ffmpeg + 默认 Python 3.13」的 Windows 机器上，按以下方式可完整跑通：

# 1) 用系统已有的 Python 3.9~3.11 建 venv（py -0 可列出已装版本）
py -3.9 -m venv venv39
venv39/Scripts/python.exe -m pip install basic-pitch pretty_midi numpy scipy soundfile

# 2) 没有 ffmpeg？用 imageio-ffmpeg 拿静态二进制，再用 FFMPEG_EXE 指过去
venv39/Scripts/python.exe -m pip install imageio-ffmpeg
# 二进制位置：<venv>/Lib/site-packages/imageio_ffmpeg/binaries/ffmpeg-win-*.exe

# 3) 运行（FFMPEG_EXE 指向上面的二进制；沙箱中建议加 PYTHONDONTWRITEBYTECODE=1
#    避免向系统 Python 目录写 __pycache__ 被拦截）
FFMPEG_EXE="<ffmpeg绝对路径>" PYTHONDONTWRITEBYTECODE=1 \
  venv39/Scripts/python.exe scripts/mp3_to_piano.py 输入.mp3 -o 输出.mp3

实测环境：Windows + Python 3.9.5 + basic-pitch 0.4.0（ONNX 后端）+ imageio-ffmpeg 静态二进制，端到端通过。

用法

python3.11 scripts/mp3_to_piano.py 输入.mp3 -o 输出.mp3

参数

调优建议

• 鼓点重/节奏飘/怪音多（最大杠杆） → 加 --hpss 先分离打击乐再转录，低频鼓点误判可减少约 68%（实测《Four Leaf Clover》音符数 2984→1107、低频音符 397→127），音符更干净、更连贯
• 音符太稀疏/丢旋律 → 调低 --onset 0.3 --frame 0.2
• 噪声多/误判鼓点 → 调高 --onset 0.6，或收窄 --min-note 36（去掉低音区底鼓误判）
• 想要更"厅堂"感 → 调高 --reverb 0.3
• 追求录音级真实钢琴 → pip install tinysoundfont + 一个钢琴 SoundFont（如 FreePats UprightPianoKW / FluidR3_GM.sf2），用 --soundfont 渲染。引擎自动选 tinysoundfont，缺依赖再回退 fluidsynth。觉得太糊可加 --no-pedal 让各音更分明。
• 转录碎片/力度不稳（小杠杆，已暴露） → 先 --keep-midi 导出 MIDI 听一遍，定位是转录层还是渲染层问题；再调 --merge-gap 0.12（更积极合并碎音）、--vel-smooth 0.7（力度更平）、--min-note-len 0.06（更去噪）。默认值已是 v1–v6 最佳配方，大部分歌无需动。
• 满编流行歌"糊成一锅"（最常见抱怨） → 核心是复音堆叠，而非音色。用 --max-voices 4（或 5/6）直接砍掉同时响的弱音；再配 --reverb 0.12（降混响让各音更分明）、--vel-smooth 0.25（保留原动态、别压平）、--merge-gap 0.10（轻微合并碎音）。"干净抒情歌"预设（实测《比我幸福》A/B 明显更清晰）： --hpss --max-voices 4 --merge-gap 0.10 --vel-smooth 0.25 --reverb 0.12 --min-note-len 0.06 仍觉得糊就把 --max-voices 降到 3；觉得太单薄就升到 5~6。这招只改密度不改变音色——想要"真钢琴"质感仍要走 SoundFont（见上）。
• 换更大编制钢琴 SF2（中等杠杆） → 把 --soundfont 指向 Salamander Grand / FluidR3_GM 等长采样 SF2。渲染器会自动探测余响长度：短采样(余响<1.5s)保持常踩踏板+尾巴；长采样(余响>1.5s)自动关掉常踩踏板、改用自然衰减衔接（否则会糊）。即你换上大钢琴，踏板会"自动生效"，不用改代码。

实战调参记录（v1–v5 经验沉淀，可直接抄）

本技能在真实歌曲《Four Leaf Clover》(5:40) 上迭代了 5 版，以下为可复用的实证结论，不是拍脑袋建议。

A. 数学合成路径（默认，无 --soundfont）

• v1 默认参数被听出「像电子琴不像清脆钢琴」→ v2 改逐谐波衰减包络后明显改善；v3 加延音踏板 + 碎片清理更连贯；v4 收紧转录阈值（--onset 0.5 --frame 0.3）+ 调性过滤 + 软量化 → 音色最接近钢琴，但被听出「节奏像业余人弹、偶发怪音」（这是转录层问题，不是合成层）。
• 结论：数学合成路径靠「逐音松键尾巴 + 轻混响(0.18) + 力度平滑」自带给连奏，无需额外调。

B. 真实采样路径（--soundfont）

• v5 换真实 Kawai 立式钢琴采样（FreePats UprightPianoKW，6MB，CC0）→ 音色天花板远高于数学合成，是最大一步升级。
• 但初版「断断续续、流畅度比 v4 差」：实测定位两个根因——
• ❌ 节奏抖动：检查渲染循环发现已精确到采样点，不存在（没白改）。
• ❌ 踏板连奏：合成两音 + 2s 长间隙测试，踏板开/关在 1.6s 后 RMS 都 = 0 → 小体积 SF2 采样太短，CC64 踏板对其完全无效，音在采样结束即死。
• ✅ 真连奏手段 = --tail 松键延音尾巴：间隙段 RMS 0.0196(无尾) → 0.0904(尾 0.35s)，衔接度 4.6×。
• v5b 把 V4 的连奏机制搬到真采样上（--tail 0.35 + 混响 0.18 + 音符清理）→ 非静音帧 93% → 98.3%，连奏回来且保留真钢琴音色。

C. 抄作业命令

# 默认数学合成（稳，先听个大概）
python scripts/mp3_to_piano.py song.mp3 -o out.mp3

# 真实钢琴采样（推荐，音色天花板高）
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --soundfont piano.sf2

# 采样版太糊 → 收尾巴
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --soundfont piano.sf2 --tail 0.15

# 采样版想要各音分明、颗粒感 → 关踏板
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --soundfont piano.sf2 --no-pedal

# 大编制长采样 SF2（如 Salamander Grand）→ 踏板真正生效，可让尾巴交给踏板
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --soundfont salamander.sf2

# 转录太稀疏/丢旋律
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --onset 0.3 --frame 0.2

# 噪声/鼓点误判多
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --onset 0.6 --min-note 36

# 鼓点重/节奏飘/怪音多（最大杠杆）→ 先分离打击乐再转录
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --soundfont piano.sf2 --hpss

⚠️ 关键边界：--soundfont 只换音色、不动转录。若听完觉得「节奏业余/有怪音」，那是 basic-pitch 转录层的问题，靠音色参数（reverb/tail/pedal）解决不了，需回到 --onset/--frame 重新转录或换 MIDI 重编。

D. 打击乐分离（--hpss，v6 最大杠杆落地）

• 听感上「节奏飘、混杂怪音」的最大单一来源是 basic-pitch 把鼓点/打击乐误判成快速装饰音或低频怪音。
• v6 在转录前插入 librosa HPSS 谐波/打击乐分离，只把旋律(谐波)轨喂给转录器。
• 实测《Four Leaf Clover》(5:40)：
• 音符总数 2984 → 1107（砍掉 63% 噪声音符）
• 低频鼓点误判音符 397 → 127（减少 68%），极低频(C1 以下) 1.2% → 0.0%
• 平均音符时长 0.38s → 0.55s（残余音符更连贯、更稳定）
• 渲染后静音帧 2.1% → 1.1%（断续感减半），单首歌处理耗时约 1.3 分钟（纯 CPU、零新增依赖）
• 结论：--hpss 是性价比最高的「流畅度提升」开关，流行/电音/鼓点重的歌默认就该开；纯钢琴独奏或清唱人声提升有限、可不开。

E. 小杠杆 + 中等杠杆落地（v7）

• 小杠杆（暴露参数）：把原本硬编码的转录清理参数（合并间隙 / 最短音 / 力度平滑）全部暴露为 --merge-gap / --min-note-len / --vel-smooth，并新增 --keep-midi（保留中间 MIDI 便于调试）。这些参数与"歌的风格"相关，不同歌曲可微调，但默认值已是 v1–v6 迭代出的最佳配方，大部分歌无需动。
• 中等杠杆（SoundFont 自适应）：新增 _detect_ringout() 在渲染前自动探测 SF2 单音余响长度，自适应选择「常踩踏板+尾巴」还是「自然衰减」策略，并新增 --sf2-preset 指定钢琴预设。意义：当前自带的 UprightPianoKW 余响仅 0.2s（极短采样），必须靠 --tail 补连奏；而一旦你换成余响数秒的大编制三角钢琴，渲染器会自动切到自然衰减、让踏板真正生效，连奏更自然且不糊。这部分代码已就绪，只等你提供更大的 SF2 即可见效（见下节）。
• 实测验证：V7 与 V6（HPSS+真采样）输出逐字节相同 → 新代码零回归；自适应探测正确判定当前 SF2 为短采样并沿用踏板+尾巴。

升级到更大钢琴 SoundFont（中等杠杆的落地指引）

中等杠杆的"真收益"——让延音踏板真正生效、连奏接近录音级——需要更长的采样 SF2（当前自带的 UprightPianoKW 仅 6MB、余响 0.2s，踏板无效）。渲染器已自适应就绪，你只需提供更大的 SF2：

1. 下载（注意网络）：本机环境对 GitHub release CDN 与大部分境外大文件源访问受限、且带宽极低（~1MB/min、易断）。可尝试：
2. Salamander Grand Piano（CC0，~120MB）：搜索 SalamanderGrandpiano 仓库的 .sf2 发布物
3. FluidR3_GM.sf2（~140MB，含全部 GM 乐器，钢琴预设通常在 0 号）
4. 或任何你信任的 .sf2 钢琴采样

若本机拉不动，请在有正常网络的机器上下好，再拷到本机 soundfonts/ 目录（tinysoundfont C 引擎支持 .sf2 / .sf3）。 2. 列预设选钢琴（可选）：若默认选的预设不是你想要的钢琴，先用脚本打印 preset 名再 --sf2-preset <编号> 指定。 3. 渲染：python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --soundfont <大钢琴>.sf2 - 渲染器会自动探测到余响 >1.5s → 关掉常踩踏板、改用自然衰减，连奏自然且不糊。 4. 若仍想用常踩踏板：传较小的 --tail 0.2 之类，避免长采样叠加发糊。

注：当前 soundfonts/piano.sf2 是 6MB 的 UprightPianoKW，音色已足够"真钢琴"，只是连奏靠尾巴模拟。换大编制是"锦上添花"而非"必须"——且本机网络拉大文件困难，按需再操作即可。

五线谱导出 / 编辑 / 再导入工作流（v8 新增）

把"机器转录"升级成"人机协作"：机器先出初稿五线谱，你用打谱软件精修，再一键渲染成更优质的钢琴曲。

导出可编辑五线谱

默认每次转换都会在同目录导出 <输出名>.musicxml（钢琴双行谱 Grand Staff，标准 MusicXML）。这是一个可编辑的乐谱文件，用 MuseScore（免费，https://musescore.org）或任意打谱软件打开即可看到并修改音高、时值、和声。

python scripts/mp3_to_piano.py song.mp3 -o out.mp3        # 自动产出 out.musicxml（可编辑五线谱）
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --png   # 额外渲染一张五线谱视图 out_score.png（纯本地，方便直接预览）
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --no-score   # 不想要 musicxml 时关掉

编辑后重新导入

在打谱软件里改好乐谱（修正错音、调整节奏、重编和声…）→ 另存为 .musicxml（或导出 .mid）→ 用 --from 直接渲染，跳过转录、直接出钢琴曲：

python scripts/mp3_to_piano.py 原曲.mp3 -o 精修版.mp3 --from 我改好的谱子.musicxml
python scripts/mp3_to_piano.py 原曲.mp3 -o 精修版.mp3 --from 我改好的谱子.mid

--from 模式下所有渲染参数（--reverb / --soundfont / --hpss 等）照常生效，HPSS/转录会自动跳过。 这形成一个可不断打磨的正循环：机器出初稿 → 你精修 → 渲染试听 → 再精修，直到满意。（想保留精修谱子供复用，配 --keep-midi 即可。）

实现说明（零依赖）

• midi_to_musicxml：把转录 MIDI 写成双行谱 MusicXML（高/低音谱表按音高自动分配，和弦用 <chord/>，音符按 4/4 小节切分），无任何第三方库。
• musicxml_to_midi：把用户改过的 .musicxml 解析回 MIDI（支持 <note>/<chord>/<rest>/<backup>/<forward> 与多小节顺序），供渲染消费。
• render_score_png：纯 numpy + zlib 本地画五线谱视图 PNG，不依赖 Pillow/LilyPond/MuseScore/联网，任意环境都能出图。
• 跨歌稳定性修复见下节。

稳定性与健壮性修复（v8）

之前"换首歌就崩"是两个独立 bug，现已固化进代码，不再依赖手动绕过：

1. GBK 编码崩溃（Bug A）：basic-pitch 转录完会往控制台打印 emoji，中文 Windows 默认 GBK 编码直接 UnicodeEncodeError 中断。已在脚本顶部 sys.stdout/stderr.reconfigure(encoding='utf-8')，与系统编码彻底绝缘——无需再手动设 PYTHONUTF8=1。
2. SoundFont 加载失败崩溃（Bug B）：以前一旦 --soundfont 的 SF2 被 tinysoundfont 拒载，就裸 traceback。现改为三级降级链： tinysoundfont(纯 pip) → fluidsynth(需系统库) → 内置 numpy 合成器，任意一级失败都打印清晰的 [降级] 提示并继续下一级，永远产出可用结果，不再神秘崩溃。
3. 想用真正的"采样钢琴"音色，按「升级到更大钢琴 SoundFont」一节提供 tinysoundfont 能解析的 .sf2。本机自带的 UprightPianoKW 在 v8 实测仍会被 tinysoundfont 拒（触发降级到 numpy）——这是 SF2 兼容性而非代码问题，换一个 tinysoundfont 支持的 SF2 即生效。

v9 新功能：预设 / 调性吸附 / 节奏量化 / 转录质检（零新依赖）

在 v8 的"转录+五线谱闭环"基础上，把"按歌型选参 + 自动修错音 + 节奏对齐 + 效果自检"固化进脚本，全部纯 Python 实现，不新增任何依赖。

一键预设（--preset）

把"按歌型选参数"做成三个配方，省去记忆一长串 flag：

预设是参数基底：任何显式 CLI 参数都会覆盖预设同名项；未显式给出的参数沿用预设值。

python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --preset pop
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --preset ballad --reverb 0.3   # 预设基础上微调

调性吸附（--snap-to-key）

basic-pitch 转录流行歌时，常把人声/贝斯/鼓误判成离调怪音。开启后会先估计调性（按时长加权的音阶覆盖率选大/小调），再把"音阶级不在音阶内"的音就近吸附回音阶、修掉疑似错音；已在音阶内的音不动，因此不会破坏原本正确的旋律与和声。调性估计偏保守，仅在明显离调时位移，不改变整体调式。

python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --snap-to-key

节奏量化（--quantize）

把转录出来"犹豫/抢拍"的起止时间对齐到规整节奏，听感更稳。网格基于估计拍速（拍速估偏时自动夹到 [40,240] 防崩）。

python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --quantize 16   # 十六分网格
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --quantize 8    # 八分网格（更柔）

转录质检报告（默认输出）

每次转换默认在同目录写出 <输出名>_质检报告.txt，包含：估计调性、拍速、总时长、音符总数 / 密度、音域、峰值同时音数、离调(疑似错音)占比、本次生效的处理选项、清洗前后音数对比。离调占比高时报告会主动提示"开 --snap-to-key / 满编歌加 --hpss --max-voices"。用 --no-report 可关闭。

python scripts/mp3_to_piano.py song.mp3 -o out.mp3            # 自动产出 out_质检报告.txt
python scripts/mp3_to_piano.py song.mp3 -o out.mp3 --no-report # 不想要报告

注：质检报告基于 basic-pitch 原始转录统计，调性/拍速为"估计值"仅供方向性参考，不保证绝对准确（尤其满编歌）。它用于快速判断"这版转录烂不烂、该往哪个方向调"，而非定音鼓式精确分析。

进步空间（已知局限与后续方向）

1. 转录层仍是节奏/音准天花板：听感上「业余人弹、混杂怪音」主要来自 basic-pitch 转录误差，不在合成/采样层。v9 已开放 --quantize(显式节奏量化) 与 --snap-to-key(调性吸附) 缓解，但要达到"录音级准"，仍需更强转录器（如 demucs 分离后转录）或经五线谱 --from 人工精修闭环。
2. 小体积 SF2 踏板无效（已部分缓解）：UprightPianoKW 这类短采样，CC64 延音踏板不产生延音；已通过自适应探测缓解——渲染器自动判定采样余响，短采样保持踏板+尾巴、长采样切自然衰减。要有真正的"踏板连贯"（长采样自然延音），仍须换大编制长采样 SF2（Salamander Grand 等，见上节指引）。
3. ~~无转录后质检~~（v9 已解决）：现已默认输出 <输出名>_质检报告.txt（调性/拍速/密度/音域/峰值复音/离调占比/处理选项/清洗前后对比），离调占比高会自动建议调 --snap-to-key / --hpss / --max-voices。
4. 不分离人声/伴奏：整曲被钢琴化。已内置轻量 --hpss 分离打击乐（只把旋律轨喂给转录器，实测低频误判 -68%）；若要更彻底的「人声 / 鼓 / 贝斯 / 其他」四轨分离，可用 demucs 分离后再分别转录，产出「人声旋律钢琴版 / 纯伴奏钢琴版」——翻弹用户最常要的两种形态（demucs 需装 torch，本机网络慢，优先级低于 --hpss）。
5. --min-note-len 已暴露（v7）：快歌装饰音/grace note 会被 basic-pitch 默认 ~127ms 阈值静默丢弃导致「丢音」；现已暴露为 --min-note-len（默认 0.045s）可微调。
6. 单文件、无批量：一次一个文件，缺 --dir 批量 + 进度条。

   这个技能的最新版本可以在7w4.net小葱技能站找到。

7. 合成器可玩性：数学合成路径未做音色选择（三角钢琴/电钢/八音盒）与力度分层；真实采样路径已支持任意 .sf2 切换。
8. 输出格式：目前只 mp3，可加 wav/flac 无损选项。

局限

• 转录质量取决于原曲：人声旋律、清晰和声效果好；重度失真、强节奏鼓点、复杂编曲会有误判。
• 默认合成器是物理建模"电钢琴"音色，非真实采样；想要真实钢琴请用 --soundfont。
• 不分离人声/乐器——整曲频谱被钢琴化，人声旋律也会变成钢琴音符（这正是"钢琴翻弹"的常见听感）。如需只保留伴奏/只保留人声旋律，可先用 demucs 分离再分别转录（进阶用法，本 skill 未内置）。

质量较好，核心技术扎实、文档详尽、调参指引充分。优点是音色可调（从数学合成到真实采样钢琴）、自动降级不怕崩、五线谱导出无需联网。不足是依赖较多（ffmpeg等），转录质量受原曲影响大，不支持批量处理。整体适合愿意按文档调参的用户，纯小白可能需要一些学习成本。