Jean-Luc Makiola
aa802582ec
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>
33 lines
1.7 KiB
Markdown
33 lines
1.7 KiB
Markdown
# Background music (GUI)
|
|
|
|
Background music plays only in the Swing GUI. It is **data-driven and bundled**:
|
|
|
|
- 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);
|
|
a room with no `music:` field fades to silence; the same track keeps playing
|
|
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 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;
|
|
`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).
|