Fundamentals
Tracks
Layers for clips. Track order is render order.
project.dispatch({ type: "track/add", payload: { id: "main", kind: "video" } });
project.dispatch({ type: "track/add", payload: { id: "titles", kind: "video", name: "Titles" } });
project.dispatch({ type: "track/add", payload: { id: "music", kind: "audio" } });Kinds
| Kind | Accepts | Rendering |
|---|---|---|
video | video, image, text, caption, html clips | Drawn, layered by track order |
audio | audio clips | Mixed |
Adding a clip to a track of the wrong kind throws CommandRejectedError with code kind-mismatch. TRACK_ACCEPTS holds this table as data.
Order
doc.trackOrder lists track ids bottom layer first. A track drawn later covers the ones before it.
// New tracks go on top unless you pass an index
project.dispatch({ type: "track/add", payload: { id: "background", kind: "video", index: 0 } });
// Move a track: index 0 is the bottom
project.dispatch({ type: "track/reorder", payload: { trackId: "titles", index: 0 } });
project.getState().doc.trackOrder; // ["titles", "background", "main", "music"]Fields
| Field | Default | Meaning |
|---|---|---|
id | required | Your id |
kind | required | "video" or "audio" |
name | the id | Display name |
muted | false | Silences the track's sound: audio clips and the audio of video clips |
solo | false | When any track is soloed, only soloed tracks are heard |
locked | false | Editor hint: your UI should block edits. The core doesn't enforce it |
hidden | absent | Video tracks: clips aren't drawn in preview, export or stills, and aren't hit-tested. Their sound still plays |
project.dispatch({ type: "track/set-property", payload: { trackId: "titles", hidden: true } });
project.dispatch({ type: "track/set-property", payload: { trackId: "music", muted: true, locked: true } });Setting hidden: false removes the field, so saved documents stay minimal.
Commands
| Command | Payload | Effect |
|---|---|---|
track/add | { id, kind, name?, index? } | Create a track |
track/remove | { id } | Delete a track and its clips |
track/reorder | { trackId, index } | Move in the layer order |
track/rename | { trackId, name } | Rename |
track/set-property | { trackId, muted?, solo?, locked?, hidden? } | Change flags |
track/remove is one undo step: undo brings back the track and its clips.