music_doctor
体检：引擎、ffmpeg、FluidSynth、SoundFont、Python 包、声音服务、磁盘。装完先跑它，缺什么会直接列出来。
DOCS / 32 TOOLS / v0.17.0
每个工具，
只做一件事。
这不是 API 参考，是使用地图。先 S0 体检，再按 S1–S8 的顺序排，也可以直接搜工具名。
每个工具的参数以 music_describe 返回的为准；这里只讲它干什么、什么时候用。
开工前：先确认它真的能跑
先体检，再建工程。音乐制作最怕的不是不会写，是跑到母带才发现 ffmpeg 没装、SoundFont 是空的、 Python 包版本不对。这些东西应该在第一步就报出来。
没有一键安装包。 这套东西依赖 ffmpeg、FluidSynth、Python 和几个音频库。
付费安装会按你的系统逐项配好；自己装，按文末的清单来。
32 个工具
没有匹配的工具。试试“母带”“和声”“stems”。
SYSTEM 系统与开工
music_project
create / open / list。建工程要曲风、BPM、调性、小节数；之后所有文件都落在工程目录里。
music_genres
list 看菜单，get 看完整曲风包：和弦、鼓型、音色、结构。目前 15 种，含 citypop、国风、trap、vocalrock。
music_job
长任务查询、等待、取消。人声渲染、深分析、Remix 都走它；长歌先拿 jobId，再续查。
推荐路线
music_doctor
→ music_project create
→ music_genres get
→ music_lyrics set
→ music_compose
→ music_render
→ music_vocals / music_vocal_finish
→ music_mix
→ music_master
→ music_export写歌与编曲：把决定留在 MIDI 里
这一组工具不替你“灵感爆发”，它负责把已经定下来的结构、和弦、节奏写成可编辑的 MIDI。 生成完不满意，改音符比重写整首便宜。
WRITE 写歌与编曲
music_theory
和弦进行、配和弦、色彩、节奏、演奏真实感、曲式、旋律、歌词、混音、曲风速查。写之前先翻一眼。
music_compose
按曲风与结构生成伴奏 + 人声旋律 MIDI。可以只重生成某一轨；同一个 seed 可复现。
music_lyrics
set 写入并校验，validate 只校验。中文字数、句长会检查；读音由 music_vocals 再转拼音。
music_notes
钢琴卷帘。按小节 + 拍读写音符，支持移调、量化、人性化、改力度和时值。
music_patterns
像 FL 的 pattern / playlist：抓一段乐句，摆到 playlist 上重复，最后 apply 展开成整曲 MIDI。
music_harmony
给主唱写和声：三度、六度、五度、八度、加倍；密度可全曲、半曲或按乐句。输出 MIDI + 计划。
渲染与试听：先听见，再往下走
MIDI 是图纸，WAV 才是房子。渲染之后要停下来听，不要一口气冲到母带。 分析工具可以帮你找问题，但不能替你决定这首歌好不好听。
RENDER 渲染、预览与分析
music_render
MIDI → 每轨 WAV。鼓走 FluidR3，旋律走 GeneralUser，吉他过箱体 IR；quality 可选 high / balanced / fast。
music_preview
生成波形 / 段落图，返回可展示的音频路径。适合发进度，不是播放器。
music_analyze
BPM、调性、段落、响度；deep 走 dsh-soundcheck，补 LUFS、真峰值、削波、分轨能量。可只分析一段。
music_listen
直接采系统正在放的声音：QQ 音乐、网易云、浏览器都行。返回 BPM、调性、响度；grab 可留 wav 当参考。
人声：唱、扫、修、调，分开做
人声是最容易“听起来差不多，其实一堆问题”的部分。这里的顺序是固定的： 先写和声，再唱主唱，再体检；能修就修，修不了才建议重唱。调教放在最后。
唱歌要另装声音服务。 纯编曲、混音、母带不需要。TTS 模型约 7.5GB，RVC 约 90MB，
SVS 权重不公开；CPU 上 20 秒人声大约 5–6 分钟。
VOCALS 人声与调教
music_vocals
sing 按谱唱，speak 念白，import 导外部干声。中文会转带声调拼音；长歌用 jobId 续查。
music_vocal_doctor
扫 8 类问题：静音、死起音、死音、拖尾、重叠、断口、音准、超音域。fix 可修音准、尾音、切/补、去串音。
music_vocal_finish
S5 一条龙：和声 → 扫主唱 → 修 → 复扫 → 重唱建议 → 可选调教。最后给 ok / needs-fix / needs-resing。
music_tune
WORLD 声码器重合成。加滑音、颤音、句尾下落、力度、气口；四种风格；可出 A/B。不改时长。
music_yutiao
语调教：按汉语声调重写音高线，让唱歌的人声像在说话。时长和节奏跟原唱一致。
music_tunefile
和洛天依互通：导出 .svp / .vsqx，在那边唱完再导回。不是声库，不能替她发声。
music_voicebanks
扫目录，认出 RVC / Vocaloid / Synthesizer V 等格式，标出本引擎能不能直接加载。只读，不解密。
混音与母带：让每一轨有位置
自动混音不是“一键变好听”。它先把音量、声像、频段和动态摆到一个合理起点， 再让你用效果链、总线和自动化去修。母带放在最后，别拿它救混音。
MIX / MASTER 混音与母带
music_mix
工程或裸 stems 自动粗混，给指标和 MIX_NOTES。可以挂参考曲，按 6 个频段和响度匹配。
music_fx
每轨效果链，按顺序挂：EQ、压缩、饱和、合唱、延迟、混响、限幅、展宽等 11 种。有现成预设。
music_bus
分组总线：鼓 / 贝斯 / 键盘 / 吉他送进 mix，再进主输出；也能给单轨设混响 / 延迟送出量。
music_automation
按小节画断点，让 gain、pan、低通、高通在歌里动。支持 linear / step / smooth。
music_master
软限幅 + 4 倍过采样真峰值，目标 LUFS / dBTP 自己定。输出 24-bit WAV + 320k MP3。
交付与再创作：把歌带走
插件不是终点。你可以导出工程继续在 DAW 里改，也可以把成品变成方案页、MV 或 Remix。 这一步的产物应该能离开插件独立存在。
DELIVER 交付与再创作
music_export
导出 stems、MIDI、标记、歌词、MIX_NOTES、IMPORT。daw=reaper 时多一个能直接打开的 session.rpp。
music_design
把工程报告排成单页 HTML：曲目档案、音准前后、气口、混音、段落能量，附 A/B。swiss / magazine 两套版式。
music_remix
分离人声 → 变速 / 变调对齐 → 换新伴奏 → 混音 → 母带。remix 保原唱，cover 换声，rearrange 保留原伴奏加新鼓 / 贝斯。
素材与自动化：把重复劳动交出去
音效库、采样器和 Code Mode 是三种不同的“省时间”。前两个省找素材和搭乐器的时间， 最后一个省重复点工具的时间。
TOOLS 素材与自动化
music_library
给硬盘上的音效 / 采样建索引，不搬文件。支持标签、星级、时长、采样率搜索；搜到可直接进工程。
music_sampler
通道机架：把导入的音频当乐器。pitch 按音高变调，oneshot 整段播；库里的素材也能直接当采样。
music_code
一段 JavaScript 调所有工具：music.tools()、music.describe()、music.job()。沙箱里没有 process / require / fs。
复测：把“听起来不错”变成数字
《不必害怕明天的风》的读数不是平台估算，是工程报告。你自己的歌可以按同样顺序复测：
- 母带后跑
music_analyze（deep: true），记下 integrated LUFS、true peak、clipping count。 - 人声调教前后各跑一次
music_vocal_doctor，对比 median pitch error（cents）。 - 用
music_mix挂参考曲，检查 6 个频段的偏差，而不是只看总响度。 music_design（deep: true）会把上述数字排进方案页，方便 A/B。
注意：不同音源、不同目标平台，读数会变。不要拿《不必害怕明天的风》的 -10.7 LUFS 当唯一标准。
已知限制
下面这些不是“以后会修”的客气话，是现在就会遇到的边界。
| 能做到 | 别期待 |
|---|---|
| 32 个工具、默认离线 | 一键安装、零依赖 |
| 15 种曲风包 | 覆盖所有冷门风格 |
| 人声调教、体检、修补 | 附带商业声库 |
| Remix 分离与重组 | 替你解决版权授权 |
| Reaper / Audacity 工程导出 | 每个 DAW 的原生工程 |
| Windows 逐项实测 | macOS / Linux 同等验证 |
- SoundFont 的音色有上限。要更真实的吉他、鼓，导出 MIDI 换音源。
- 没有装 Demucs 时，人声分离是中心声道近似，会有串音。
- 中文歌词的读音有边缘情况，发布前请自己听一遍。
- CPU 上唱长句很慢；这是本地推理，不是云端排队。
成本：插件价格不含模型 token。调用插件的是你的 agent；一首 3–4 分钟的完整歌约 40–100 万 token，
按 API 价约 ¥2–¥8，改得越多越贵。包月 / 订阅用户只消耗额度，没有边际账单。
详见 成本说明。
安装与依赖
没有一键脚本。下面是实际依赖；付费安装会按你的系统逐项配好，并跑通一首完整 demo。 自己装也可以，按表来。
| 依赖 | 用途 | 必须 |
|---|---|---|
| DSH / Node | 宿主与插件运行时 | 是 |
| ffmpeg | 解码、转码、抽帧、波形 | 是 |
| FluidSynth + SoundFont | MIDI 渲染 | 是 |
| Python 3.11 / 3.12 | 音频分析、母带、人声处理 | 是 |
| numpy / scipy / soundfile / librosa / pedalboard / pyloudnorm / pretty_midi / mido | 分析、效果、响度、MIDI | 是 |
| pyworld / pypinyin | 调教 / 中文读音 | 唱歌时 |
| 肥鱼声音服务 | TTS / RVC / SVS | 唱歌时 |
| Demucs | 更好的 Remix 分离 | 可选 |
| dsh-soundcheck | 整曲深分析 | 可选 |
music_doctor
# 先看它报什么，再决定装什么。