Audio

The format models audio at three levels:

1. AudioTrack — per-panel audio (panels.<id>.audio[]): music, ambience, SFX, or voice-over that plays while the panel is current.
2. SequenceAudioTrack — chapter-level audio (chapters[].sequenceAudioTracks[]): tracks that span multiple panels on a timeline, with fades and playback rate.
3. AudioLayer — audio as a panel layer (kind: "audio" inside panels.<id>.layers[]), which additionally supports the layer-level visibleIf and other layer common properties.

All three reference audio assets from the asset catalog by assetId. Audio assets (category: "audio") carry one or more AudioVariants (src, mime matching audio/*, optional bitrateKbps, channels, sampleRateHz, loop, locale).

AudioTrack

Defined as $defs/AudioTrack, used in panels.<panelId>.audio[] and in extras blocks.

{
  "panels": {
    "p1": {
      "audio": [
        { "assetId": "sfx-rain", "role": "ambient", "loop": true, "gain": 0.3 },
        { "assetId": "vo-p1-line-left", "role": "voiceover", "startAtMs": 0,
          "visibleIf": { "==": [ { "var": "path.choice" }, "left" ] } }
      ]
    }
  }
}

SequenceAudioTrack

Defined as $defs/SequenceAudioTrack: "Audio track that spans multiple panels within a chapter". Placed in chapters[].sequenceAudioTracks[], these describe a timeline relative to the chapter/sequence start — the natural home of background music that should not restart on every panel.

{
  "chapters": [
    {
      "id": "ch-1",
      "sequenceAudioTracks": [
        {
          "id": "seq-music-main",
          "friendlyId": "main-theme",
          "name": "Main Theme",
          "assetId": "music-theme",
          "role": "music",
          "startTime": 0,
          "duration": 90000,
          "volume": 0.8,
          "loop": true,
          "fadeIn": 2000,
          "fadeOut": 3000,
          "startPanelId": "p1",
          "endPanelId": "p12"
        }
      ],
      "panels": { "p1": { "layers": [] } },
      "graph": { "entry": "p1", "edges": [{ "from": "p1", "to": "p1" }] }
    }
  ]
}

AudioLayer

An audio track expressed as a panel layer ($defs/AudioLayer). It extends the shared layer base (LayerCommon — id, z, opacity, visibleIf, etc.; see Layers) with:

AudioTrack vs. AudioLayer

Both attach panel-scoped audio; the practical differences:

• AudioTrack (in panels.<id>.audio[]) has a role, which ties it to the reader's audio/SFX/speech toggles and the settings.ui defaults (audioDefault, sfxDefault, speechDefault — see Settings).
• AudioLayer participates in the layer list (ordering alongside visual layers, visibleIf, layer editor state) but has no role.

For most authoring, prefer AudioTrack for panel sound and SequenceAudioTrack for chapter-spanning music.

Mixing model

• Gain/volume is a linear multiplier from 0 to 2 on every audio object (gain on tracks/layers, volume on sequence tracks); 1 is the asset's natural level.
• Roles partition the mix into reader-controllable groups: the audio toggle is the master mute for everything (including video sound); sfx and ui additionally fall under the SFX toggle; voiceover additionally under the speech toggle; music, ambient and none are silenced only by the audio toggle. See Player audio for the bus mapping.
• Fades (fadeIn/fadeOut) and playbackRate exist only on SequenceAudioTrack.
• Per-bubble voice-over: a speech bubble can reference audio directly via audioAssetId.

Related pages

• Assets — audio catalog items and variants
• Settings — audioDefault, sfxDefault, speechDefault
• Player audio behavior — how the player schedules and mixes these tracks