`audio`

Places a music or sound file on a timeline level. Can loop a specific segment to fill the full edit duration.

When to use

Use to add background music, looping ambient sound, or a one-shot sound effect. For voice-over narration, use elevenlabs_tts or heygen_speaker instead.

In the editor

Add it from the Library (Audio group), or with + add step and a search for audio.

Under Inputs, add source as a file input naming the music or effect. Then decide which of the two jobs you want.

For background music, turn on loop, set backbone_step to the ID of the step that decides how long the video is, and use start_sec and end_sec to pick the part of the track worth repeating. fade_in_sec and fade_out_sec stop it starting and ending abruptly. For a single sound at a single moment, leave loop off and set position_sec to the second it should land on.

gain_db is the volume, and the default sits music well under a speaking voice. Set Output Level to an audio level such as music or sfx, kept separate from your voice so you can adjust one without the other.

In the run timeline the music shows up as a run of clips end to end, the last one trimmed to finish exactly with the video; a one-shot shows up as a single clip where you placed it.

YAML Example

# Loop a music segment for the full cut
- id: music
  processor: audio
  input:
    - id: source
      file: music-track
  cache_deps:
    - ai_cut
  params:
    loop: true
    start_sec: 5
    end_sec: 25
    gain_db: -23
    fade_in_sec: 0
    fade_out_sec: 1.5
    backbone_step: ai_cut
  output:
    timeline: music
  cache: true

# One-shot sound effect at a specific position
- id: sting
  processor: audio
  input:
    - id: source
      file: sfx-track
  params:
    loop: false
    start_sec: 0
    end_sec: 2.5
    position_sec: 12.0
    gain_db: -10
  output:
    timeline: sfx

Inputs

ID	Source	Description
`source`	file	Audio or video file (audio track used)

Params

Param	Type	Default	Description
`gain_db`	number	`-23`	Volume in dB
`loop`	bool	`false`	Tile the segment to fill backbone duration
`loop_count`	number	`0`	Repeat the segment exactly N times when `loop: true`. 0 = tile to fill backbone duration. Mutually exclusive with `backbone_step`.
`min_loop_sec`	duration (s)	`0`	Minimum segment duration for detected loop (used with `auto_cut_loop`)
`auto_duration`	bool	`false`	Probe source file to determine `end_sec` at run time. Only valid when `loop: false`. Overrides any configured `end_sec`.
`fade_in_sec`	duration (s)	`0`	Fade in on the first tile
`fade_out_sec`	duration (s)	`0`	Fade out on the last tile
`start_sec`	duration (s)	`0`	Start of the source segment to use
`end_sec`	duration (s)	`0`	End of the source segment to use
`position_sec`	duration (s)	`0`	Timeline position for one-shot placement (when `loop: false`)
`auto_cut_loop`	bool	`false`	Detect the best loop point automatically. Requires `loop: true`.
`backbone_step`	string	none	Step ID for duration when `loop: true` and `loop_count` is 0. Required for loop mode unless `loop_count` is set.

Output

EditDecisions: one edit decision per tile (loop mode) or one (one-shot mode).

Notes

Use cache_deps: [backbone_step] with loop mode so the audio re-runs when the cut length changes.
Tiles are placed end-to-end without gaps. The last tile is trimmed to match the backbone end exactly.