## Example

```json
{
  "gameplayMusicSettings": {
    "characterCreationTrackId": "OpeningTheme",
    "tracks": {
      "OpeningTheme": {
        "cues": ["character-creation"],
        "variants": [
          { "url": "https://example.com/audio/opening.mp3" }
        ]
      },
      "BattleTheme": {
        "cues": ["combat"],
        "matchTags": ["siege", "boss"],
        "variants": [
          {
            "narrationUrl": "https://example.com/audio/battle-narration.ogg",
            "gameplayUrl": "https://example.com/audio/battle-gameplay.ogg"
          }
        ]
      }
    }
  }
}
```

## Overview

Each key in `tracks` is a **track family**: a named group of audio the engine can switch to. A family holds one or more `variants` (the audio itself) and, optionally, the `cues` and `matchTags` that let the engine pick it during play.

Music is selected two ways. **Contextually**, the engine matches the current situation against a family's `cues` and `matchTags`. **Explicitly**, a trigger pins a family with the `music-track-set` effect and releases it again with `music-track-clear`; a pinned family overrides contextual selection until it is cleared. Both effects are listed on the [Triggers](/mechanics/triggers) page.

Audio is hosted by you: each variant URL points at an HTTPS `.mp3`, `.ogg`, or `.wav` file. Voyage does not host creator audio, and creator-provided sound effects and ambience are not supported -- this section covers music only.

## Fields

### characterCreationTrackId

Names the family in `tracks` used while the player builds their character. It must match a key in `tracks` exactly -- a name that resolves to nothing is rejected on load, so the validator flags it.

### tracks

A map of family id to family. The key is the id you reference from `characterCreationTrackId` and from a `music-track-set` trigger effect, so keep it stable once triggers point at it.

### variants

The audio a family can play, as a list. A variant either carries a single `url` used in every context, or a `narrationUrl` and `gameplayUrl` pair so narration and active play get different versions of the same piece. Each URL is an HTTPS `.mp3`, `.ogg`, or `.wav`.

A family with no variants has nothing to play, so Voyage rejects a track entry without this field.

### cues

The moments a family is eligible for. Each entry is one of `character-creation`, `combat`, `travel`, `near-death`, `dying`, `dead`, or `recovery`. A family with no cues is never chosen contextually, which is what you want for one a trigger pins explicitly.

### matchTags

Free-form tags that refine contextual selection, letting several families share a cue and be told apart by situation. Optional: a family with cues but no tags is simply eligible whenever its cue is active.