Compositions (nested sequences)

Build a lower third, a logo sting or a whole scene once as a composition, then place it anywhere as one clip that moves, masks and grades like a picture, from the bin or by an agent with addComp, inComp and precompose.

A composition (comp) is a timeline of its own, with its own size, length, tracks and clips, that is placed on the main timeline (or inside another comp) as one clip. Build a lower third, a logo sting or a whole scene once, then use it as many times as you like: every clip that shows the comp changes when the comp is edited. Comps live in project.comps:

"comps": [
  { "id": "lt", "name": "Lower third", "width": 1280, "height": 720, "duration": 5,
    "background": "#00000000",   // optional; leave it out for transparent
    "tracks": [ { "id": "V2", "kind": "video" }, { "id": "V1", "kind": "video" }, { "id": "A1", "kind": "audio" } ],
    "clips": [
      { "id": "bar", "kind": "shape", "track": "V1", "start": 0, "duration": 5, "props": { "shapes": [ … ] } },
      { "id": "name", "kind": "text", "track": "V2", "start": 0.3, "duration": 4.7, "props": { "text": "Ada Lovelace" } },
      { "id": "whoosh", "kind": "audio", "mediaId": "m_whoosh", "track": "A1", "start": 0, "in": 0, "duration": 0.6 }
    ] }
],
"clips": [
  { "id": "c_lt1", "kind": "comp", "compId": "lt", "mediaId": null, "track": "V3", "start": 4, "in": 0, "duration": 5,
    "props": { "fit": "none", "y": 220 } }
]

A comp clip (kind:"comp", compId, no mediaId) shows the comp from its in (comp seconds) for its duration, at speed 1. It draws like a picture of the comp's size: fit defaults to none (the comp's own pixels), and its transform, keyframes, opacity, transitions, masks, track matte, blend, grade and filters all apply to the comp's frame as a whole. Trims and splits move its in like a video clip's; the window can't run past the comp's length.

The media inside a comp plays and exports as if it were on the timeline: its video frames, and its audio, which goes through the main timeline's audio track of the same name (its fader, effects and bus). A comp clip that is disabled, or sits on a disabled track, silences the comp's audio too. Comps nest up to 4 deep, and a comp can never contain itself.

In the editor: the bin's Project tab lists the comps; drag one onto the timeline to place it, and double-click it (or a comp clip, or Open in the Inspector's Composition section) to open it. An open comp takes over the timeline: every tool, shortcut and inspector works on its clips, and the breadcrumb above the timeline (or Esc, once nothing is selected) goes back out. Right-click clips → Precompose moves them into a new comp and puts a comp clip in their place; right-click the Project tab → New composition starts an empty one. The Composition section also sets the comp's name, size, length and background.

Agents:

• {op:"addComp", comp:{id?, name, duration, width?, height?, background?, tracks?, clips?:[…]}} adds one (its clips go through the same checks as addClip). {op:"updateComp", id, set:{name?, width?, height?, duration?, background?, tracks?}} changes it; {op:"removeComp", id} is refused while a clip still uses it.
• Place it with addClip {kind:"comp", compId, track, start, duration, in?}.
• {op:"inComp", comp, ops:[…]} runs clip and timeline ops on the comp's own clips: addClip, updateClip, removeClip, split, rippleDelete, the trims, setShape, setMask, setGrade, setParent, setMotionPath, setTextPath, clip setFx, precompose, and inComp for a comp inside it.
• {op:"precompose", ids:[…], name?, id?} moves those clips (here, or in the comp an inComp is running in) into a new comp that starts at the earliest of them; a comp clip of the same length takes their place.
• The compact view shows a comp clip as comp(lt in:1.5) and lists every comp under COMPS with its clips.

Recipes: reusable lower third - a template (next section) gives every speaker their own copy with their own name; a plain comp suits a graphic that is the same every time; logo sting - a draw-on logo comp at the head and tail of the edit; picture in picture of a whole scene - precompose the scene's clips, then scale the comp clip down and move it into a corner; one grade for a sequence - precompose it and grade the comp clip once.