THB/Jander_Semester2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(io): bundle background music as classpath resources

Browse Source 
Switch OggMusicBackend from streaming an external, git-ignored music/ folder
(relative to the run directory) to streaming bundled classpath resources under
/music/, so the four manor tracks ship inside the JAR and play out of the box —
consistent with how fonts are bundled. The play loop reopens the resource each
iteration via a BufferedInputStream (the vorbisspi SPI needs mark/reset to read
the OGG header). Missing tracks still fall back to silence.

Add the four converted OGG Vorbis tracks (manor-theme/cellar-drone/musicbox/
lament) under src/main/resources/music/, un-ignore that path, and re-anchor the
gitignore so only the top-level MP3 source folder stays ignored. Update
docs/music.md for the bundled approach and conversion recipes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jean-Luc Makiola
2026-06-02 09:21:11 +02:00
parent d8e1a662bc
commit aa802582ec
7 changed files with 42 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
Semesterprojekt/docs/music.md
View File

@@ -1,9 +1,10 @@
# Background music (GUI)
Background music plays only in the Swing GUI. It is **data-driven and external**:
Background music plays only in the Swing GUI. It is **data-driven and bundled**:
- Put `.ogg` (OGG Vorbis) files in a `music/` folder next to where you run the game.
This folder is git-ignored and never bundled in the JAR.
- Tracks live as `.ogg` (OGG Vorbis) files in `src/main/resources/music/`, so they
are on the classpath and ship inside the JAR — the game plays music out of the box,
with no external folder to set up.
- A room plays a track via an optional `music:` field in `rooms.yaml`, e.g.
`music: manor-theme.ogg`. Entering a room with a different track fades the old one
out and the new one in (sequential, not an overlapping cross-fade);
@@ -11,7 +12,21 @@ Background music plays only in the Swing GUI. It is **data-driven and external**
seamlessly across rooms.
- Volume is the **Music** setting (Off / Low / Medium / High) in the Settings menu,
persisted to `saves/settings.json`. Off disables playback.
- Missing files are ignored (silent) — the game never crashes over absent audio.
- Missing tracks are ignored (silent) — the game never crashes over absent audio.
- The console version is always silent.
Decoding uses the `vorbisspi` + `jorbis` libraries via the `javax.sound` SPI.
Decoding uses the `vorbisspi` + `jorbis` libraries via the `javax.sound` SPI;
`OggMusicBackend` streams each track from the classpath (`/music/<track>`) on a
daemon thread.
## Adding or replacing a track
1. Convert your source audio to OGG Vorbis. With ffmpeg:
`ffmpeg -i in.mp3 -c:a libvorbis -q:a 5 out.ogg`
or with gstreamer (no ffmpeg needed):
`gst-launch-1.0 filesrc location=in.mp3 ! decodebin ! audioconvert ! audioresample ! vorbisenc quality=0.5 ! oggmux ! filesink location=out.ogg`
2. Drop the `.ogg` into `src/main/resources/music/`.
3. Reference it from a room's `music:` field in `rooms.yaml`.
The four tracks shipped today: `manor-theme.ogg` (ground floor),
`cellar-drone.ogg` (cellar), `musicbox.ogg` (upper floor), `lament.ogg` (chapel).