enhancement(audio): FluidSynth SoundFont replacement (SoH-only, no libultraship changes)

.github/macports.yml

@@ -20,4 +20,8 @@ ports:
   - name: opusfile
     select: [ universal ]
   - name: libvorbis
-    select: [ universal ]
+    select: [ universal ]
+  # FluidSynth is built from source in soh/CMakeLists.txt (osal=cpp11, no glib).
+  # libsndfile is a dependency of FluidSynth, needed to decode SF3 SoundFonts.
+  - name: libsndfile
+    select: [ universal ]

CMakeLists.txt

@@ -101,7 +101,8 @@ if (CMAKE_SYSTEM_NAME STREQUAL "Windows")
     endif()
 
     vcpkg_bootstrap()
-    vcpkg_install_packages(zlib bzip2 libzip libpng sdl2 sdl2-net glew glfw3 nlohmann-json tinyxml2 spdlog libogg libvorbis opus opusfile)
+    # fluidsynth[sndfile] pulls libsndfile with Ogg/Vorbis, required to decode SF3 SoundFonts.
+    vcpkg_install_packages(zlib bzip2 libzip libpng sdl2 sdl2-net glew glfw3 nlohmann-json tinyxml2 spdlog libogg libvorbis opus opusfile fluidsynth[sndfile])
     if (CMAKE_C_COMPILER_LAUNCHER MATCHES "ccache|sccache")
         set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT Embedded)
     endif()
@@ -193,6 +194,11 @@ add_compile_definitions(CONTROLLERBUTTONS_T=uint32_t)
 ################################################################################
 # Sub-projects
 ################################################################################
+# Synth code lives SoH-side (soh/soh/Enhancements/audio), so soh links FluidSynth.
+# Default ON; override with -DENABLE_FLUIDSYNTH=OFF.
+if(NOT DEFINED ENABLE_FLUIDSYNTH)
+    set(ENABLE_FLUIDSYNTH ON)
+endif()
 add_subdirectory(libultraship ${CMAKE_BINARY_DIR}/libultraship)
 target_compile_options(libultraship PRIVATE "${WARNING_OVERRIDE}")
 target_compile_definitions(libultraship PUBLIC INCLUDE_MPQ_SUPPORT)

docs/BUILDING.md

@@ -164,6 +164,7 @@ git submodule update --init
 # Add `-DCMAKE_BUILD_TYPE:STRING=Release` if you're packaging
 # Add `-DSUPPRESS_WARNINGS=0` to prevent suppression of warnings from LUS and decomp (src) files. set to 1 to re-enable suppression
 # Add `-DPython3_EXECUTABLE=$(which python3)` if you are using non-standard Python installations such as PyEnv
+# Add `-DENABLE_FLUIDSYNTH=OFF` to build without the FluidSynth synth backend (on by default; drops the fluidsynth dependency)
 cmake -H. -Bbuild-cmake -GNinja
 
 # Generate soh.o2r
@@ -242,11 +243,12 @@ cd ShipWright
 git submodule update --init
 
 # Install development dependencies (assuming homebrew)
-brew install sdl2 sdl2_net libpng glew ninja cmake tinyxml2 nlohmann-json libzip opusfile libvorbis
+brew install sdl2 sdl2_net libpng glew ninja cmake tinyxml2 nlohmann-json libzip opusfile libvorbis fluid-synth
 
 # Generate Ninja project
 # Add `-DCMAKE_BUILD_TYPE:STRING=Release` if you're packaging
 # Add `-DSUPPRESS_WARNINGS=0` to prevent suppression of warnings from LUS and decomp (src) files. set to 1 to re-enable suppression
+# Add `-DENABLE_FLUIDSYNTH=OFF` to build without the FluidSynth synth backend (on by default; drops the fluidsynth dependency)
 cmake -H. -Bbuild-cmake -GNinja
 
 # Generate soh.o2r
@@ -296,14 +298,16 @@ cmake -H. -Bbuild-cmake -GNinja
 # Extract assets & generate OTR (run this anytime you need to regenerate OTR)
 cmake --build build-cmake --target ExtractAssets
 # Setup cmake project for building for Switch
-cmake -H. -Bbuild-switch -GNinja -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/Switch.cmake
+cmake -H. -Bbuild-switch -GNinja -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/Switch.cmake -DENABLE_FLUIDSYNTH=OFF
 # Build project and generate nro
 cmake --build build-switch --target soh_nro
 
 # Now you can run the executable in ./build-switch/soh/soh.nro
 # To develop the project open the repository in VSCode (or your preferred editor)
 ```
 
+_Note: FluidSynth is disabled above because devkitpro doesn't ship it. To use the synth backend, build a fluidsynth for the platform (e.g. [fluidsynth-lite](https://github.com/rsn8887/fluidsynth-lite)) and drop `-DENABLE_FLUIDSYNTH=OFF`._
+
 ## Wii U
 1. Requires that your build machine is setup with the tools necessary for your platform above
 2. Requires that you have the Wii U build tools installed
@@ -317,14 +321,16 @@ cmake -H. -Bbuild-cmake -GNinja
 # Extract assets & generate OTR (run this anytime you need to regenerate OTR)
 cmake --build build-cmake --target ExtractAssets
 # Setup cmake project for building for Wii U
-cmake -H. -Bbuild-wiiu -GNinja -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/WiiU.cmake # -DCMAKE_BUILD_TYPE:STRING=Release (if you're packaging)
+cmake -H. -Bbuild-wiiu -GNinja -DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/WiiU.cmake -DENABLE_FLUIDSYNTH=OFF # -DCMAKE_BUILD_TYPE:STRING=Release (if you're packaging)
 # Build project and generate rpx
 cmake --build build-wiiu --target soh # --target soh_wuhb (for building .wuhb)
 
 # Now you can run the executable in ./build-wiiu/soh/soh.rpx or the Wii U Homebrew Bundle in ./build-wiiu/soh/soh.wuhb
 # To develop the project open the repository in VSCode (or your preferred editor)
 ```
 
+_Note: As with Switch, FluidSynth is disabled above (not shipped by devkitpro); drop `-DENABLE_FLUIDSYNTH=OFF` once you've built a fluidsynth for the platform._
+
 # Compatible Roms
 See [`supportedHashes.json`](supportedHashes.json)
 

docs/CUSTOM_MUSIC.md

@@ -1,18 +1,20 @@
-### Custom Music
+# Custom Music
 
 We support importing custom [Seq64](https://github.com/sauraen/seq64) files to replace the in game music and fanfares (Sound effect and instrument replacement is currently not supported).
 
 First you will need to prepare a folder with the desired sequences. Every sequence requires two files with the same name and different extensions - a `.seq` Seq64 file and a `.meta` plaintext file. These files can be categorically nested in folders if desired, - Retro will recursively search each subfolder it finds.
 
 The `.meta` file requires two lines - the first line is the name that will be displayed in the SFX editor, and the second line is the instrument set number in `base16` format. For example, if there is a sequence file `Foo.seq` then you need a meta file `Foo.meta` that could contain:
-```
+
+```text
 Awesome Name
 C
 ```
 
 Once you have prepared your sequences folder:
-1. Download and open [Retro](https://github.com/HarbourMasters/retro/releases). 
-1. Choose the "Create OTR" option. 
+
+1. Download and open [Retro](https://github.com/HarbourMasters/retro/releases).
+1. Choose the "Create OTR" option.
 1. Choose the "Custom Sequences" option.
 1. Using the file selection screen, choose the sequences folder you prepared in the previous instructions.
 1. Click the "Stage Files" button.
@@ -22,3 +24,7 @@ Once you have prepared your sequences folder:
     - This `mods` folder should be in the same folder as your `oot.o2r` file.
 
 Assuming you have done everything correctly, boot up SoH and select the SFX Editor from the enhancements dropdown menu. You should now be able to swap out any of the in game sequences/fanfares for the sequences added in your newly generated OTR file. If you have any trouble with this process, please reach out in the support section of the Discord.
+
+## Use SF2 / SF3 formatted Synth Packs
+
+See [CUSTOM_SYNTH](CUSTOM_SYNTH.md)