Timeline and levels

A level is a named track in your timeline. Every clip a step places belongs to one. Levels are how you stack b-roll over a speaker, captions over both, and music underneath.

Levels are declared once, in your template's timeline settings:

timeline:
  levels:
    - name: music
      order: -1
      type: audio
      backbone: false
    - name: main
      order: 1
      type: any
      backbone: true
    - name: broll
      order: 2
      type: video
      backbone: false
    - name: captions
      order: 4
      type: video
      backbone: false

Each step writes to one level, set by its Output level in the editor.

The backbone level

Exactly one level is the backbone (backbone: true). It is the spine of the video: it sets the total duration, and everything on other levels is positioned against it. In practice the backbone is your main footage or your voiceover.

Stacking order

order decides what sits in front of what. Higher numbers render nearer the viewer, lower numbers further back, and the backbone sits in between at its own order. In the example above, b-roll covers the speaker, captions sit over the b-roll, and music plays underneath everything.

Two steps on the same level

What happens when more than one step writes to the same level depends on whether it is the backbone:

On the backbone, steps are intersected. Only the segments that every backbone step agrees to keep survive. Use this when you want two independent passes, say a content cut and a silence trim, and only want what both approve.
On any other level, steps are combined. Every clip is kept. This is how broll_place and broll_veo_generate can both fill the broll level without fighting each other.

Level types

Type	Use
`video`	Video-only clips
`audio`	Audio-only clips
`any`	Mixed video and audio
`title`	Text and title cards

The type records what the level is meant to carry, which keeps a template readable when it has several levels. Exactly one level must be the backbone, and level names must be unique; the editor tells you if either rule is broken.

Levels and gaps