{"tab":"other","section":"gameplayMusicSettings","title":"Music","summary":"Defines the world's music: track families with their audio variants, the cues that select them in play, and the family used during character creation.","kind":"schema","uiLocation":"Files → Other → Music","uiSubtitle":"\"Creator-owned character creation and gameplay music, including external HTTPS tracks.\"","wikiUrl":"/other/gameplayMusicSettings","schema":{"_type":"intersection","parts":[{"_type":"required","fields":{"characterCreationTrackId":"string","tracks":{"_type":"record","domain":"string","codomain":{"_type":"intersection","parts":[{"_type":"required","fields":{"variants":{"_type":"array","of":{"_type":"intersection","parts":[{"_type":"partial","fields":{"url":"string","narrationUrl":"string","gameplayUrl":"string"}}]}}}},{"_type":"partial","fields":{"matchTags":{"_type":"array","of":"string"},"cues":{"_type":"array","of":{"_type":"union","of":[{"_type":"literal","value":"character-creation"},{"_type":"literal","value":"combat"},{"_type":"literal","value":"travel"},{"_type":"literal","value":"near-death"},{"_type":"literal","value":"dying"},{"_type":"literal","value":"dead"},{"_type":"literal","value":"recovery"}]}}}}]}}}}]},"sizeLimits":[],"blocks":[{"type":"example","lang":"json","code":"{\n  \"gameplayMusicSettings\": {\n    \"characterCreationTrackId\": \"OpeningTheme\",\n    \"tracks\": {\n      \"OpeningTheme\": {\n        \"cues\": [\"character-creation\"],\n        \"variants\": [\n          { \"url\": \"https://example.com/audio/opening.mp3\" }\n        ]\n      },\n      \"BattleTheme\": {\n        \"cues\": [\"combat\"],\n        \"matchTags\": [\"siege\", \"boss\"],\n        \"variants\": [\n          {\n            \"narrationUrl\": \"https://example.com/audio/battle-narration.ogg\",\n            \"gameplayUrl\": \"https://example.com/audio/battle-gameplay.ogg\"\n          }\n        ]\n      }\n    }\n  }\n}"},{"type":"prose","md":"## Overview\n\nEach 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.\n\nMusic 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.\n\nAudio 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."},{"type":"fields","fields":[{"name":"characterCreationTrackId","tooltip":"The track family played during character creation; must name a key in tracks.","md":"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."},{"name":"tracks","tooltip":"The world's track families, keyed by family id; each holds its variants and optional selection rules.","md":"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."},{"name":"variants","required":true,"tooltip":"The audio for a family; use url for one shared track, or narrationUrl and gameplayUrl for separate versions.","md":"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`.\n\nA family with no variants has nothing to play, so Voyage rejects a track entry without this field."},{"name":"cues","tooltip":"Moments the family is eligible for, such as combat or travel; omit for a family only triggers select.","md":"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."},{"name":"matchTags","tooltip":"Free-form tags that narrow contextual selection within a cue.","md":"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."}]}],"body":"## Example\n\n```json\n{\n  \"gameplayMusicSettings\": {\n    \"characterCreationTrackId\": \"OpeningTheme\",\n    \"tracks\": {\n      \"OpeningTheme\": {\n        \"cues\": [\"character-creation\"],\n        \"variants\": [\n          { \"url\": \"https://example.com/audio/opening.mp3\" }\n        ]\n      },\n      \"BattleTheme\": {\n        \"cues\": [\"combat\"],\n        \"matchTags\": [\"siege\", \"boss\"],\n        \"variants\": [\n          {\n            \"narrationUrl\": \"https://example.com/audio/battle-narration.ogg\",\n            \"gameplayUrl\": \"https://example.com/audio/battle-gameplay.ogg\"\n          }\n        ]\n      }\n    }\n  }\n}\n```\n\n## Overview\n\nEach 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.\n\nMusic 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.\n\nAudio 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.\n\n## Fields\n\n### characterCreationTrackId\n\nNames 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.\n\n### tracks\n\nA 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.\n\n### variants\n\nThe 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`.\n\nA family with no variants has nothing to play, so Voyage rejects a track entry without this field.\n\n### cues\n\nThe 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.\n\n### matchTags\n\nFree-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."}