# 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).