# 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](https://www.fluidsynth.org/)（LGPL-2.1，经 pyfluidsynth 动态调用），音色库是
[GeneralUser GS v1.471](http://www.schristiancollins.com)（约 30MB，GM 全音色采样）。

[中文说明](README.zh-CN.md) · License: [AGPL-3.0-only](LICENSE)

## 工具（MCP）

| 工具 | 输入 | 输出 |
| --- | --- | --- |
| `list_instruments` | — | `{instruments: [{id, name, program, bank, hint}]}` —— 精选的十几个音色，不是 128 个全给模型 |
| `render_notes` | `notes: [{midi, start_ms, end_ms, velocity?}]`, `instrument?`, `out_path?`, `reverb?` | `{path, duration_ms, instrument, ms, …}` |
| `render_midi` | `path` (.mid), `instrument?`, `out_path?`, `reverb?` | 同上 |

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

## 安装

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

```bash
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](https://github.com/JustEnoughLinuxOS/generaluser-gs)。
- 许可证：**允许在软件项目里自由使用与再分发**（含商用音乐制作），但作者声明无法 100% 保证
  其中全部采样的来源；全文见 [docs/licenses.md](docs/licenses.md) 与
  [docs/GeneralUser-GS-LICENSE.txt](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 采样常驻后仍有富余，实测数字见验收）。

## 开发

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

## 许可证

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