Play AltSound packs instead of the ROM's sound

.github/workflows/build.yml

@@ -34,6 +34,19 @@ jobs:
         run: |
           cd VisualPinball.Engine.PinMAME
           dotnet build -c Release -r ${{ matrix.rid }}
+      - name: Build AltSound
+        if: matrix.rid == 'win-x64' || matrix.rid == 'win-x86' || matrix.rid == 'osx' || matrix.rid == 'linux-x64'
+        run: |
+          out="${{ runner.temp }}/altsound"
+          case "${{ matrix.rid }}" in
+            win-x64) cmake -S native/AltSound -B "$out" -A x64 ;;
+            win-x86) cmake -S native/AltSound -B "$out" -A Win32 ;;
+            osx) cmake -S native/AltSound -B "$out" -DCMAKE_BUILD_TYPE=Release -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0 ;;
+            linux-x64) cmake -S native/AltSound -B "$out" -DCMAKE_BUILD_TYPE=Release ;;
+          esac
+          cmake --build "$out" --config Release
+          find "$out" -maxdepth 2 \( -name VpeAltSound.dll -o -name libVpeAltSound.dylib -o -name libVpeAltSound.so \) -exec cp {} VisualPinball.Engine.PinMAME.Unity/Plugins/${{ matrix.rid }}/ \;
+          ls VisualPinball.Engine.PinMAME.Unity/Plugins/${{ matrix.rid }} | grep -i altsound
       - run: |
           mkdir tmp
           cp -r VisualPinball.Engine.PinMAME.Unity/Plugins/${{ matrix.rid }} tmp

VisualPinball.Engine.PinMAME.Unity/README.md

@@ -12,7 +12,9 @@ This package adds a new gamelogic engine called *PinMAME*. Add the component to
 
 The catalog and cache are editor-only. A player build receives the serialized hardware mappings and machine/ROM identifiers; it does not fetch or contain the source metadata. Display layouts continue to be queried directly from the selected ROM through PinMAME.
 
-In the Player, this package contributes a **PinMAME** settings section with a global **Volume** slider, also exposed in the **Sound** mixer. The default is 100%; zero mutes playback while the ROM continues running. Both surfaces edit the same plugin-owned value. Gain is applied before the first ROM audio frame and can change during playback, independently of ROM volume and NVRAM. Raw PCM published to other integrations is unaffected; a plugin replacing audio playback owns its output gain. The settings adapter applies only to tables using PinMAME, and cannot be disabled independently of the existing gamelogic engine.
+In the Player, this package contributes a **PinMAME** settings section with a global **Volume** slider, also exposed in the **Audio** mixer. The default is 100%; zero mutes playback while the ROM continues running. Both surfaces edit the same plugin-owned value. Gain is applied before the first ROM audio frame and can change during playback, independently of ROM volume and NVRAM. Raw PCM published to other integrations is unaffected; a plugin replacing audio playback owns its output gain. The settings adapter applies only to tables using PinMAME, and cannot be disabled independently of the existing gamelogic engine.
+
+The same section turns on **AltSound**: a pack of recorded music, callouts and effects that the ROM's sound commands trigger instead of its own sound, as in Visual PinMAME. A pack is a folder named after the ROM inside a folder named `altsound`, such as `VPinMAME/altsound/<rom>`. The **AltSound folder** setting points at that `altsound` folder; left empty, the plugin looks next to VPinMAME's ROM folder and in VPE's PinMAME folder. When it is on, **AltSound volume** sets the pack's level on its own (up to 200%, the ROM volume doesn't change it), **Follow the game's volume** lets the volume set in the game's menu scale the pack too, as in Visual PinMAME (off by default, since packs are often much quieter then), and **ROM sound under AltSound** keeps some of the ROM's own sound for packs that don't replace all of it (off by default, like Visual PinMAME). The pack plays through VPE's central mixer on the ROM bus when that is on, and through Unity otherwise. It is mixed by [libaltsound](https://github.com/vpinball/libaltsound) (BSD-3-Clause), built into `VpeAltSound` from `native/AltSound` for Windows, macOS and Linux, at the packs' 44.1 kHz; the plugin converts it to the output rate with a windowed-sinc resampler, since libaltsound's own resampling puts audible images of the treble into the mix.
 
 Existing scenes and packages that used the retired class-based definitions remain compatible through a small runtime alias resolver. New and repopulated tables serialize numeric PinMAME IDs and populated flipper-wire mappings on the table. Candidate hardware snapshots stay in the editor scene and are omitted from packaged gamelogic data, so no machine-definition classes or catalog records are shipped with the player.