OpenSC2K FluidSynth MIDI 音乐引擎:运行时 FFI 集成、线程模型与 SoundFont 实战指南

原创2026-10-12 21:13:102,269 阅读
文章标签:游戏开发

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。原文档记录了审查过的候选及其结论:

  • fluidsynth 0.0.1(2018 年,无人维护,构建时链接);
  • fluidlite / fluidlite-sys 0.2.1(2021 年,绑定的是精简版 FluidSynth 1 的分支,静态编入程序,会加重 LGPL 合规负担);
  • oxisynth 0.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)是一份可直接对照的完整样板。

登录后查看全文
OpenSC2K