View raw

audio#

A standalone audio clip — voiceover, music bed, sound effect. Inherits common fields, but x, y, width, height, rotation, scale, and opacity are ignored: audio is mixed, not drawn.

interface AudioElement extends BaseElement {
  type: 'audio';
  source: string;
  volume?: number | Keyframe[];
  trim_start?: number;
  trim_duration?: number;
  loop?: boolean;
}

Required#

FieldTypeDefaultDescription
sourcestring (URL)requiredHTTP(S) URL of the audio file. MP3, AAC, Opus, WAV, and FLAC are supported.

Mix#

FieldTypeDefaultDescription
volumenumber | Keyframe[]100Volume from 0 (silent) to 100 (unity gain). Animatable — use keyframes for fades, ducks, crossfades.

Trimming#

FieldTypeDefaultDescription
trim_startnumber (seconds)0Where in the source file playback begins.
trim_durationnumber (seconds)source-derivedHow much of the source file to play, starting from trim_start.
loopbooleanfalseWhether to loop if the element's duration exceeds the trimmed clip length.

Examples#

Background music with fade-out#

{
  "type": "audio",
  "source": "https://example.com/track.mp3",
  "time": 0,
  "duration": "end",
  "volume": [
    { "time": 0,   "value": 70 },
    { "time": 5.5, "value": 70 },
    { "time": 7,   "value": 0 }
  ]
}

Voiceover#

{
  "type": "audio",
  "source": "https://example.com/vo.mp3",
  "time": 1.2,
  "trim_start": 0.3
}

Looped ambience#

{
  "type": "audio",
  "source": "https://example.com/ambience.wav",
  "duration": "end",
  "loop": true,
  "volume": 30
}

Notes#

  • Mix bus — all audio elements are summed (plus the audio tracks of any video elements with volume > 0). The runtime peak-limits the master to prevent clipping; no manual compressor / limiter is exposed.
  • Frame-rate independence — audio sample rate is fixed at 48 kHz output regardless of the Source's frame_rate.
  • Volume scale — 100 is unity gain, not the maximum. The runtime accepts higher values (150, 200), but boosting past unity drives the master limiter (audible gain reduction, not hard clipping); reduce other sources rather than boost above 100.