Soundfont Renderer（真乐器渲染）

Platform support: macOS — supported (developed & verified on this machine) · Windows — unverified (paths are cross-platform in the codebase, but no real-machine testing yet).

把音符或 MIDI 渲染成真乐器单轨：钢琴、小提琴、吉他、弦乐、铜管…… 引擎是 FluidSynth（LGPL-2.1，经 pyfluidsynth 动态调用），音色库是 GeneralUser GS v1.471（约 30MB，GM 全音色采样）。

中文说明 · License: AGPL-3.0-only

工具（MCP）

render_midi 内部先把 .mid 解析成和 render_notes 同一形状的音符列表，再走同一条渲染路径 （只有一个渲染规则）。

Related MCP server: Vibe Composer MIDI MCP

安装

引擎（libfluidsynth）与 Python 绑定装在插件自己的虚拟环境里，Micromamba 用户态安装，无需 sudo：

mkdir -p ~/Documents/ShadowRoom/_venvs && cd ~/Documents/ShadowRoom/_venvs
curl -sL https://github.com/mamba-org/micromamba-releases/releases/latest/download/micromamba-osx-arm64 -o micromamba && chmod +x micromamba
MAMBA_ROOT_PREFIX=$PWD/mamba-root ./micromamba create -y -p ./soundfont-renderer -c conda-forge python=3.12 fluidsynth numpy
./soundfont-renderer/bin/python -m pip install pyfluidsynth

SoundFont 首次使用自动下载（约 30MB，sha256 校验，见下）。代理环境可设 SHADOWROOM_SOUNDFONT 指向自己下载的 .sf2 文件。

SoundFont：来源与许可证

• 来源：GeneralUser GS v1.471，作者 S. Christian Collins（http://www.schristiancollins.com）， 镜像 JustEnoughLinuxOS/generaluser-gs。

• 许可证：允许在软件项目里自由使用与再分发（含商用音乐制作），但作者声明无法 100% 保证 其中全部采样的来源；全文见 docs/licenses.md 与 docs/GeneralUser-GS-LICENSE.txt。

• 因为这一条采样来源的不确定性，加上约 30MB 的二进制不适合放在 git 仓库里，本插件不随包携带 SoundFont，而是首次使用时下载到 ~/Documents/ShadowRoom/_soundfonts/GeneralUser-GS-1.471.sf2 并做 sha256 校验（f45b6b4a68b6bf3d792fcbb6d7de24dc701a0f89c5900a21ef3aaece993b839a）—— 与 stem-splitter 首次使用下载 Demucs 模型是同一个先例。

• FluidSynth 本体是 LGPL-2.1：本插件通过 pyfluidsynth（MIT）动态调用，未静态链接；以这种 方式分发不需要把插件改为 LGPL。

性能

• SoundFont 在插件进程里只加载一次并常驻（进程存活期间所有渲染复用同一个 synth）。

• 离线渲染：音频按块从 synth 拉取，音符事件按采样位置触发，不受实时时钟限制—— 8 小节（15s 音频）渲染实测远低于 3 秒。

• 插件进程空闲 RSS < 150MB（GeneralUser GS 约 30MB 采样常驻后仍有富余，实测数字见验收）。

开发

PYTHONPATH=src python -m unittest discover -s tests -p "test_*_unittest.py"

许可证

AGPL-3.0-only（见 LICENSE）。SoundFont 与 FluidSynth 各自的许可证见 docs/licenses.md。