OpenSC2K FluidSynth MIDI 音乐引擎:运行时 FFI 集成、线程模型与 SoundFont 实战指南
OpenSC2K FluidSynth MIDI 音乐引擎:运行时 FFI 集成、线程模型与 SoundFont 实战指南
本文以 OpenSC2K(Rust + Godot 重写的 SimCity 2000)中负责 MIDI 音乐回放的 FluidSynth 子系统为主线,讲解其"事件解析 → 序列器 → 合成器 → Godot 音频总线"的端到端架构、手写 FFI 的运行时库加载方案、多线程安全模型,以及 SoundFont 选择、随包分发与 LGPL 合规的完整实践。读完本文,你将掌握如何在 Godot 项目中集成外部声音合成库、如何围绕实时音频线程设计安全边界,以及如何为 LGPL 动态库构建可复现、可替换的分发方案。
1. 概览:用 FluidSynth 取代自定义合成器
OpenSC2K 的 MIDI 音乐播放经历过一次架构替换:早期版本内置的自定义加法合成器(additive synthesizer)已被移除,取而代之的是 FluidSynth——一个成熟、持续维护、跨平台的 SoundFont 2.04 合成器,配合操作系统自带的 General MIDI 音色集或玩家自选的 SoundFont 播放音乐。只有 Linux 发行包额外附带一个 SoundFont(FluidR3Mono GM),作为系统音色缺失时的最后选择。
这一选择的核心设计原则是:FluidSynth 只做"渲染 PCM 样本"这一件事,不接管音频输出。它不打开任何音频驱动,把浮点立体声 PCM 写入调用方提供的缓冲区,再由 Godot 的 AudioStreamGenerator 环形缓冲与音频线程接管,从而让音量设置、暂停、焦点静音和 Master 总线等 Godot 原生机制全部自然生效。
2. 端到端架构:从 MIDI 文件到扬声器
2.1 数据流
原文档给出了完整的数据链路,这里逐级展开并补充实现细节:
SOUNDS/<track>.MID 或音乐包中的 MIDI 文件
| StandardMidiFile(GDScript)在主线程解析文件
v
事件数组:每个事件包含时间,以及 kind、channel、a、b 字段
| MidiSynthPlayer 把它们交给音乐线程
v
FluidMidiSynth(Rust GDExtension,native/audio)
| Sequencer 让每个事件在各自的采样点触发
| FluidSynth 通过 fluid_synth_write_float 渲染 float PCM
v
AudioStreamGenerator 环形缓冲(1 秒)
| Godot 音频线程读取它
v
AudioStreamPlayer -> Master 总线 -> 输出设备
2.2 各组件职责
- game/src/audio/standard_midi_file.gd:解析标准 MIDI 文件,报告 note、program、controller、pitch-bend、channel-pressure 与 key-pressure 事件。文档强调它被保留的原因是它已经能给出精确的事件时间,且原版游戏的曲目结束、间隙与随机播放规则都依赖这套解析器。从当前实现看,GDScript 层把二进制数据交给原生解析器
NativeMidiFile.parse()(Rust 侧见 native/core/audio/src/smf.rs),再填充成Event对象数组,因此解析精度由 Rust 侧保证。 - game/src/audio/midi_synth_player.gd:保持公开行为
play_path、play_sequence、stop、set_paused、set_volume_linear、track_finished,并新增set_soundfont(choice, custom_path)用于运行时切换音色。它还维护着 SoundFont 的 WorkerThreadPool 加载任务、等待中的曲目队列与合成器线程的生命周期。 - native/core/audio/src/sequencer/mod.rs:实现
MidiOutput抽象的序列器。它在事件时间点切分每次渲染、支持跳转(重放 program、controller、bend 与 pressure,但不重放音符)、循环播放,并在曲目结束后渲染最多 2 秒的释放尾音。 - native/core/audio/src/fluidsynth:唯一调用 FluidSynth 的代码。
platform.rs负责打开动态库,api.rs持有函数表,synth.rs是安全的FluidSynth所有者,log.rs记录 FluidSynth 最近一次错误。 - native/audio/src/fluid_midi_synth.rs:暴露给 GDScript 的 Godot 类
FluidMidiSynth,封装了序列器与合成器的调用。
2.3 为什么不用 FluidSynth 自带的 MIDI 播放器
FluidSynth 本身带有一个 MIDI 文件播放器,但 OpenSC2K 没有使用它。原因在于游戏已经有自己的 MIDI 解析器,而它的曲目结束、间隙和 shuffle 规则依赖该解析器。只替换合成器意味着:两个合成器播放完全相同的事件序列,曲目可以在当前位置无缝切换合成器。FluidSynth 会收到解析器报告的每一个通道消息;System Exclusive 消息仍被跳过(原版曲目不含此类消息)。
3. 为什么选择 FluidSynth
文档给出的选型理由可以归纳为以下几点,它们都是可验证的技术事实:
- 完整、成熟的 General MIDI 行为:支持 program 与 bank 切换、第 10 通道鼓组、力度、弯音及其范围、延音、表情、音量、声像、混响与合唱发送、调制器,以及 SF3 压缩 SoundFont。
- 渲染进调用方缓冲区:不依赖音频驱动,Godot 完全掌控输出。
- 维护活跃、跨平台:SoundFont 2.04 规范实现,macOS、Windows、Linux 均可构建。
4. Rust 集成:运行时 FFI 而非 crate
OpenSC2K 直接对公开的 FluidSynth 2 C API 做 FFI,库在运行时加载,不使用任何 Rust FluidSynth crate。原文档记录了审查过的候选及其结论:
fluidsynth0.0.1(2018 年,无人维护,构建时链接);fluidlite/fluidlite-sys0.2.1(2021 年,绑定的是精简版 FluidSynth 1 的分支,静态编入程序,会加重 LGPL 合规负担);oxisynth0.1 与rustysynth(Rust 实现的其他合成器,并非 FluidSynth)。
结论是没有任何一个维护中的 FluidSynth 2 绑定。而构建时链接还会带来两个实际问题:每个开发机都需要安装 FluidSynth,且库缺失时游戏直接无法启动。OpenSC2K 只用到 23 个函数,手写一张函数表很小且不引入任何 crate。
4.1 函数表与版本校验
在 native/core/audio/src/fluidsynth/api.rs 中,Api 结构体按 FluidSynth API 文档声明了函数指针字段(new_fluid_settings、new_fluid_synth、fluid_synth_sfload、fluid_synth_write_float、fluid_synth_noteon 等),全部 unsafe 代码集中在 fluidsynth 模块内,其余 crate 代码只使用安全的 FluidSynth 类型。
加载时的关键校验:调用 fluid_version 读取主版本号,必须为 2,否则拒绝加载并给出明确错误(见 api.rs 中 SUPPORTED_MAJOR_VERSION 与版本检查逻辑)。函数表通过 OnceLock 缓存为进程级单例,首次调用后不再重复加载,库缺失会稳定上报而非反复重试。
4.2 平台库加载细节
platform.rs 是唯一平台相关代码:
- macOS / Linux:通过
dlopen(RTLD_NOW)打开,dlsym解析符号;用dladdr定位音频扩展自身所在目录,从而在同目录用完整路径打开 FluidSynth,不需要@rpath、@loader_path、RPATH或$ORIGIN查找。 - Windows:
LoadLibraryExW配合LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | LOAD_LIBRARY_SEARCH_DEFAULT_DIRS,绝不搜索当前目录和PATH;用GetModuleHandleExW+GetModuleFileNameW定位自身模块路径。
库查找顺序为:环境变量 OPENSC2K_FLUIDSYNTH 指定路径 → 音频扩展同目录 → 系统搜索路径 → 开发安装目录(macOS 额外尝试 /opt/homebrew/lib 与 /usr/local/lib)。文档还提到,macOS 库的 install name 是 @rpath/libfluidsynth.3.dylib,因此替换版本也可以被正常链接。
5. 线程模型与实时性
5.1 三层线程分工
- WorkerThreadPool 任务:创建
FluidMidiSynth并加载 SoundFont。加载会读取整个文件,SF3 还要解码。文档给出的实测量级是:macOS 系统音色集约 10 ms;15 MB 的 SF3 文件约 1.5 s、占用约 144 MB 内存。 - 主线程:把合成器与曲目一起交给音乐线程,之后不再调用它。
- 音乐线程:唯一的
render调用者,把 1 秒的AudioStreamGenerator缓冲按每次最多 1024 帧的块填满;缓冲满时等待 10 ms 再轮询。 - Godot 音频线程:只读环形缓冲,绝不调用 FluidSynth,也不做文件访问、SoundFont 加载或大块内存分配。
5.2 关键设置
在 synth.rs 的 FluidSynth::new 中可以看到具体的合成器配置:
| 设置 | 值 | 含义 |
|---|---|---|
synth.sample-rate |
44100 | 采样率 |
synth.polyphony |
256 | 复音数 |
synth.midi-channels |
16 | MIDI 通道数 |
synth.cpu-cores |
1 | 不开 FluidSynth 工作线程 |
synth.threadsafe-api |
0 | 关闭 API 内部锁:每个合成器同时只被一个线程拥有 |
synth.lock-memory |
0 | 不锁内存 |
synth.limiter.active |
1 | 开启限制器(FluidSynth 2.5+;旧库忽略此设置) |
synth.limiter.output-limit |
0.891 | 峰值限制在约 -1 dBFS,为同总线上的音效留出余量 |
FluidSynth 会在进程级共享缓存中共享已加载的采样。创建合成器、加载 SoundFont、删除合成器都经过一个 Rust 互斥锁(LIFECYCLE),保证两个线程不会同时改动该缓存;而渲染路径从不取这个锁。序列器的渲染缓冲区增长到最大请求尺寸后复用,避免反复分配。
事件时序方面,FluidSynth 在下一个 64 帧块(44.1 kHz 下约 1.5 ms)处触发事件,因此测试中不同请求块大小会得到相同的曲目长度(game/tests/fluidsynth_music_test.gd 对此有断言)。
5.3 Sequencer 的事件级渲染
sequencer/mod.rs 的实现保证输出不依赖请求块大小:render 在循环中先派发到期的所有事件(send_due_events),再计算到下一个事件边界为止的块长(block_length),每次 render 都按边界切分。seek 从起点重放所有非音符事件(program、controller、bend、pressure),让跳转后的合成器状态与目标时间点一致。曲目结束后进入释放尾音阶段,最多 2 秒(MAX_TAIL_SECONDS),并且只在完整的 256 帧尾音块边界检查"尾音超时或无声"(tail_is_over),保证任意请求尺寸下曲目都在同一帧结束。
6. 音频如何进入 Godot
FluidMidiSynth 以 44100 Hz 渲染立体声 float 帧到 AudioStreamGenerator(其 mix_rate 即设为该值),Godot 再重采样到设备实际采样率(见 midi_synth_player.gd 中 SAMPLE_RATE、BUFFER_LENGTH_SECONDS = 1.0、PREFILL_SECONDS = 0.20、MAX_FRAMES_PER_FILL = 1024、IDLE_POLL_MSEC = 10 等常量)。音乐因此走 Godot 常规路径:音乐音量设置、暂停、焦点静音、Master 总线全部生效。FluidSynth 不打开任何音频驱动,构建时也全部关闭了驱动。
音量策略上,FluidSynth gain 为 0.35(见 fluid_midi_synth.rs 的 DEFAULT_GAIN):密集的原版曲目在这一电平下正好达到满刻度,FluidSynth 限制器(-1 dBFS 输出上限)把峰值压住。玩家音量属于 Godot 播放器/总线层面,不通过 gain 实现。
7. 构建 FluidSynth 库
7.1 构建步骤与前置要求
按文档,先运行 python3 tools/build_native.py 构建原生库,再运行 tools/build_fluidsynth.py 构建 FluidSynth;每步会跳过已是最新的输出,校验运行器也调用同一套构建。前置要求:
- Rust(见仓库根 rust-toolchain.toml);
- CMake 3.24 或更高;
- Python 3;
- C 与 C++ 编译器。
7.2 构建脚本的细节
tools/build_fluidsynth.py 是全部构建逻辑所在,其可复现性设计值得展开:
- 固定版本:
FLUIDSYNTH_VERSION = '2.6.1'。 - 锁定源码与哈希:
SOURCES表逐条列出 libogg 1.3.6、libvorbis 1.3.7、libFLAC 1.5.0、Opus 1.5.2、libsndfile 1.2.2,以及 FluidSynth 2.6.1 记录的两个 git 子模块(gcem、Signalsmith Audio Basics)和 Signalsmith 的三个被拉取仓库(linear 0.3.1、dsp v1.7.1、hilbert-iir 1.0.0)的下载 URL 与 SHA-256。下载后校验哈希,不匹配即报错删除。 - 静态编解码器:libogg、libvorbis、libFLAC、Opus、libsndfile 全部构建为静态库,再把它们一起链接进 FluidSynth 动态库,使最终库能读取 SF3 压缩 SoundFont,且运行时只依赖操作系统库。
- 完全断网构建:CMake 带
FETCHCONTENT_FULLY_DISCONNECTED=ON,Signalsmith 的 configure 期抓取改为使用脚本固定的本地副本,构建过程不会下载脚本未固定的任何东西。 - 关闭一切驱动:
FLUIDSYNTH_OPTIONS把 audio、MIDI、shell、network、LADSPA、OpenMP 全部关闭(enable-aufile/alsa/dbus/jack/ladspa/oss/pulseaudio/pipewire/coreaudio/dsound/wasapi/waveout/winmidi等均为 OFF),因为 Godot 负责播放。 - 依赖白名单校验:
check_dependencies用otool -L(macOS)、readelf -d(Linux)、自实现的 PE 导入表解析(Windows)检查最终库,拒绝任何需要操作系统之外的共享库的产物。 - 配方指纹:
recipe_hash()对脚本本身求 SHA-256 并写入fluidsynth.recipe标记文件,脚本一变即触发重建。
7.3 平台差异
| 平台 | 构建要点 |
|---|---|
| Windows | Visual Studio 2022(含 C++ 工作负载;arm64 构建还需 ARM64 构建工具);CMake 使用 Visual Studio 生成器,平台取 Python 架构(x64 或 ARM64);-DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded 静态 CRT,DLL 无需 VC++ 可再发行组件 |
| macOS | Xcode 命令行工具;用 lipo 合成 arm64 + x86_64 通用库,部署目标 macOS 11.0;install_name_tool 设置 @rpath/libfluidsynth.3.dylib;codesign 做 ad-hoc 签名(install_name_tool 会移除原有签名,Apple Silicon 需要补签) |
| Linux | GCC 或 Clang;-static-libstdc++ -static-libgcc 静态链接 C++ 运行时,最终只依赖 glibc;静态库按链接顺序排列(GNU ld 顺序解析) |
7.4 使用系统库与 OPENSC2K_FLUIDSYNTH
开发者也可以直接使用系统安装的 FluidSynth 2 库:macOS 加载器额外尝试 /opt/homebrew/lib 与 /usr/local/lib,Linux 走系统搜索路径。设置 OPENSC2K_FLUIDSYNTH 指向某个库文件时,则只用该库。tools/build_native.py 在构建出库后会把 OPENSC2K_FLUIDSYNTH 与 OPENSC2K_REQUIRE_FLUIDSYNTH=1 注入环境(见 tools/build_native.py),CI 亦然。
8. 测试体系
原文档描述了三个层次的测试,均可从仓库验证:
- Rust 单元/集成测试:在
native/audio目录执行cargo test --release,测试序列器,并在库存在时测试 FluidSynth:合法、非法、截断、缺失的 SoundFont,SoundFont 切换,program、鼓通道、力度、弯音、延音、音量、表情、声像、gain,以及库缺失场景。没有库时这些测试以备注形式通过,除非设置了OPENSC2K_REQUIRE_FLUIDSYNTH。 - 测试用 SoundFont:
game/tests/fixtures/soundfonts/opensc2k_test_gm.sf2(17 KB)由 native/core/audio/src/fluidsynth/test_soundfont.rs 生成——bank 0 program 0 是正弦波、program 80 是方波、bank 128 鼓组播放噪声爆发,样本全部由代码生成,不含任何第三方内容。设置OPENSC2K_UPDATE_FIXTURES=1可重新写出该文件。 - Godot 集成测试:game/tests/fluidsynth_music_test.gd 使用 Dummy 音频驱动,覆盖库加载、SoundFont 错误、MIDI 解析、渲染、循环、跳转、回退顺序、已保存偏好、延迟启动(曲目等待 SoundFont 加载)、运行时切换与曲目结束,并断言
FluidSynth 2.x版本前缀与soundfont_path的更新。
9. 运行时库布局
开发与打包两种形态下,库文件位于不同位置(来自原文档表格):
| 平台 | 开发 | 打包 |
|---|---|---|
| Windows | game/bin/opensc2k_audio/windows-x86_64/libfluidsynth-3.dll(或 windows-arm64) |
libfluidsynth-3.dll 位于 OpenSC2K.exe 旁 |
| macOS | game/bin/opensc2k_audio/macos/libfluidsynth.3.dylib |
OpenSC2K.app/Contents/Frameworks/libfluidsynth.3.dylib |
| Linux | game/bin/opensc2k_audio/linux-x86_64/libfluidsynth.so.3(或 linux-arm64) |
libfluidsynth.so.3 位于 OpenSC2K.x86_64 或 OpenSC2K.arm64 旁 |
game/opensc2k_audio.gdextension 的 [dependencies] 段会让 Godot 导出时把库(和 SoundFont)一并复制。音频扩展先找到自身文件,再从同目录按完整路径打开 FluidSynth,因此:Windows 永不搜索当前目录与 PATH;macOS 与 Linux 无需任何 rpath/RPATH 处理。
若同目录文件缺失,加载器依次尝试系统搜索路径与开发目录;全部失败时,游戏在设置界面与音乐提示中显示失败原因,MIDI 音乐不播放(录制的原声音轨不受影响)。
10. SoundFont 选择机制
10.1 偏好设置与候选顺序
Settings > Audio > Music SoundFont 列表写入偏好 audio/music_soundfont:
| 选项 | 值 | SoundFont |
|---|---|---|
| macOS GS Sound Set / Microsoft GS Wavetable Sound Set / System SoundFont | system(默认) |
操作系统音色集 |
| Custom SoundFont | custom |
audio/music_soundfont_path 指向的文件 |
系统音色集就地读取、绝不复制:
- macOS:
/System/Library/Components/CoreAudio.component/Contents/Resources/gs_instruments.dls(macOS MIDI 合成器的 Roland GS 音色集); - Windows:
%SystemRoot%\System32\drivers\gm.dls(Microsoft GS Wavetable Synth 的 Roland GS 音色集); - Linux/BSD:依次尝试
/usr/share/sounds/sf2/default-GM.sf2、/usr/share/sounds/sf3/default-GM.sf3、/usr/share/soundfonts/default.sf2、发行版的 FluidR3 GM 文件,然后是可执行文件旁的FluidR3Mono_GM.sf3(仅 Linux 包附带,菜单标签为 Bundled SoundFont (FluidR3 Mono))。
这些实现全部可在 native/core/audio/src/soundfont.rs 与 game/src/audio/sound_font_catalog.gd 中核实。早期版本保存过的值(default、fluidr3mono、musescore_general、builtin)会统一归一到 system(normalize 逻辑)。
SoundFontCatalog.candidates 给出实际尝试的文件列表(Rust 侧 candidates):自定义音色优先,失败后回退到系统音色集。DLS 文件由 FluidSynth 的原生 DLS 加载器读取。
10.2 回退与失败处理
- 自定义 SoundFont 失败(缺失、不支持或损坏)→ 加载系统音色集;
- 无任何 SoundFont 可加载,或 FluidSynth 库缺失 → 不播放 MIDI 音乐:等待中的曲目立即以
track_finished结束,之后的曲目在切换选择前持续失败,状态文本会点名每个失败原因; - 自定义 SoundFont 就地读取,从不复制或改写;
- 音乐播放中切换:同一曲目从当前位置继续,使用新 SoundFont(
set_soundfont会按debug_metrics().position_seconds重开播放); - SoundFont 在首次播放 MIDI 音乐时才加载(非启动时),首曲会等待加载完成。
11. 随包分发 SoundFont
Linux 没有操作系统音色集,因此 Linux 包附带 FluidR3Mono GM。tools/build_desktop_release.py 下载 MuseScore 2.3.2 的文件,校验 SHA-256 后放到可执行文件旁。其许可证文本位于 game/assets/licenses/fluidr3mono,游戏仅在 Linux 平台于 About > Licenses 展示。Windows 与 macOS 包不含 SoundFont。
原文档同时给出流程性建议:在往包里新增 SoundFont 之前,必须从规范上游源审查其许可证与采样来源,并把许可证加入 game/assets/licenses、about_dialog.gd 与 THIRD_PARTY_NOTICES.md。
12. SoundFont 审核表
原文档记录了截至 2026-10-01 从上游源完成的审核,完整保留如下:
| SoundFont | 许可证 | 大小 | 是否随包 | 来源 | 备注 |
|---|---|---|---|---|---|
| FluidR3Mono GM 2.312 | MIT | 14.5 MB (SF3) | 仅 Linux 包(2026-10-01 之前所有包) | MuseScore 2.3.2 share/sound(github.com/musescore/MuseScore,commit 45924076) |
完整 GM 音色集,含 GS 鼓组。Michael Cowgill 制作的 FluidR3 单声道采样。加载约 1.5 s,内存约 144 MB |
| MuseScore General 0.2 | MIT | 38 MB (SF3)、206 MB (SF2) | 否(2026-10-01 前随包) | ftp.osuosl.org/pub/musescore/soundfont/MuseScore_General(MuseScore 下载服务器) | FluidR3Mono 加上 S. Christian Collins 的新钢琴等乐器。各 preset 的采样来源均已列出;新采样为公有领域或作者原创。加载约 3.2 s,内存约 240 MB |
| MuseScore General HQ | MIT | 约 480 MB (SF2) | 否 | 同一项目;MuseScore 下载服务器未提供 | 对游戏下载而言过大,玩家可自选为 Custom SoundFont |
| MS Basic (MuseScore 4) | MIT | 51 MB (SF3) | 否 | github.com/musescore/MuseScore share/sound |
MIT、当前维护、完整 GM。其许可证文件仍描述 MuseScore General 0.2(MuseScore issue 19446),且是 MuseScore General 的更名后代,增益有限 |
| FluidR3 GM (stereo) | MIT(Debian fluid-soundfont,源自 Frank Wen 2008 年发布) |
141 MB (SF2) | 否 | ftp.osuosl.org/pub/musescore/soundfont/fluid-soundfont.tar.gz | 完整 GM。MuseScore 归档里是社区编辑的 "GM2-2" 文件,readme 称 "public domain" 但无许可证文件,来源不够清晰;FluidR3Mono 覆盖相同采样 |
| GeneralUser GS 2.0.3 | GeneralUser GS License v2.0(宽松,非 MIT) | 31 MB (SF2) | 否 | github.com/mrbumpy409/GeneralUser-GS | 高质量且经 FluidSynth 测试。许可证声明部分采样来源不确定,故不随包;可作为自定义 SoundFont |
| FreePats General MIDI | GPL-3.0-or-later(带例外) | 307 MB (SF2) | 否 | freepats.zenvoid.org | 不完整:45 个旋律条目、43 个鼓条目 |
| TimGM6mb | GPL-2.0 | 6 MB | 否 | Debian timgm6mb-soundfont |
GPL,不适合随 MIT 项目分发 |
审核结论:未找到与 FluidR3 无派生关系、且为 MIT 许可的完整 General MIDI SoundFont;试听测试中,免费音色集对本游戏音乐的表现差于 macOS/Windows 的 Roland GS 音色集,因此 OpenSC2K 使用操作系统音色集并允许玩家自选,Linux 包则以 FluidR3Mono GM 兜底。
13. 第三方许可与 LGPL 合规
13.1 许可归属
- OpenSC2K 自身代码(含
native/audio)为 MIT;FluidSynth 是独立的 LGPL-2.1-or-later 库,见 THIRD_PARTY_NOTICES.md。 - 包内包含
THIRD_PARTY_NOTICES.md与licenses文件夹,游戏在 About > Licenses 展示相同文本;文本位于 game/assets/licenses/fluidsynth。 - 操作系统音色集属于系统,只就地读取(系统 MIDI 合成器同样如此),OpenSC2K 从不复制。
13.2 LGPL 合规措施
LGPL 2.1 允许 MIT 程序使用 LGPL 库,前提是用户能替换库并让程序使用替换后的库(第 6 节)。OpenSC2K 的对应做法:
- 独立、可替换的库:FluidSynth 从不静态链接、也从不在构建时链接;音频扩展运行时打开它,只调用公开 API。任何同文件名、兼容的 FluidSynth 2 构建,或
OPENSC2K_FLUIDSYNTH指定的库,都能原位替换(第 6b 节)。 - OpenSC2K 内无 FluidSynth 代码:FFI 声明根据 API 文档手写,不复制任何 FluidSynth 头文件或源码。OpenSC2K 是"使用该库的作品",保持 MIT 许可(第 5 节)。
- 源码未改动:FluidSynth 及其内部每个库都从上游发布归档原样构建,零补丁。
- 对应源代码:每个发行版在包旁发布
OpenSC2K-<version>-fluidsynth-source.zip,内含库的每个源码归档、构建脚本及其 SHA-256 清单(第 4、6 节)。tools/build_fluidsynth.py --source-bundle <folder>可写出相同内容(脚本write_source_bundle还会生成SOURCES.txt)。 - 声明:LGPL 文本、FluidSynth 版权与作者、其他每个库的通知都随包并显示在游戏内。
- 不用官方 Windows 二进制:其
sndfile.dll还包含 mpg123 与 LAME(LGPL),OpenSC2K 无法确定这些组件的精确源码版本;从固定源码构建可在每个平台给出相同的对应源代码。
原文档同时留下运维提醒:若未来修改 FluidSynth,必须把改动以补丁文件形式放在构建脚本旁、在构建中应用、纳入源码包,并按 LGPL 第 2 节标记被改文件。
14. 已知问题与后续优化
原文档坦诚列出了现存边界,这些也是评估该系统时的客观参考:
- Windows 构建仅在 CI(
windows-2025)上运行,未经本地测试。 - macOS 包为 ad-hoc 签名;公证(notarization)还需以同一身份对 FluidSynth 库签名。
- 内存:SF3 SoundFont 加载时解码,大型自定义 SoundFont 可能占用数百 MB。FluidSynth 的
synth.dynamic-sample-loading可降低占用,但会在音乐线程的程序切换时读文件,故保持关闭。 - 首曲延迟:SoundFont 在首个 MIDI 曲目时加载,大 SF3 文件会让该曲延迟数秒;录制的原声音轨不受影响。
- 无音色集的 Linux 系统:在玩家选择自定义 SoundFont 之前,MIDI 音乐不播放。
综合来看,这套设计的价值在于:把"合成"这一外部依赖严格隔离在运行时加载的独立库中,用事件级序列器保证与 Godot 音频线程之间清晰、低风险的职责边界,并通过固定源码构建、哈希校验与对应源码包,让 LGPL 库的分发既合规又可复现。对希望在自己的 Godot/Rust 项目中集成外部音频库的开发者而言,docs/fluidsynth.md 与本仓库对应的实现(native/core/audio/src/fluidsynth、game/src/audio/midi_synth_player.gd、tools/build_fluidsynth.py)是一份可直接对照的完整样板。