Overview
The TimelineManager handles all timeline operations including tracks, elements, splitting, trimming, and element manipulation. Access it through editor.timeline.
All mutations to the timeline automatically push to the undo/redo history unless pushHistory: false is specified.
Adding tracks
// Add a media track
const trackId = editor.timeline.addTrack({ type: 'media' });
// Add a text track at a specific index
const textTrackId = editor.timeline.addTrack({
type: 'text',
index: 0
});
Working with elements
// Insert an element at the playhead
editor.timeline.insertElement({
element: {
type: 'video',
mediaId: 'media-123',
startTime: 0,
duration: 5.0,
// ... other properties
},
placement: {
type: 'at-time',
trackId: 'track-123',
time: editor.playback.getCurrentTime()
}
});
Splitting elements
const rightSideElements = editor.timeline.splitElements({
elements: [{ trackId: 'track-1', elementId: 'element-1' }],
splitTime: 5.0,
retainSide: 'both'
});
Track methods
addTrack()
Adds a new track to the timeline.
addTrack({ type, index }: {
type: TrackType;
index?: number
}): string
Type of track: "media", "text", "audio", or "image"
Position to insert the track. Defaults to end of track list
string - The ID of the newly created track
Example
const trackId = editor.timeline.addTrack({
type: 'media',
index: 0
});
removeTrack()
Removes a track from the timeline.
removeTrack({ trackId }: { trackId: string }): void
ID of the track to remove
editor.timeline.removeTrack({ trackId: 'track-123' });
toggleTrackMute()
Toggles the mute state of a track.
toggleTrackMute({ trackId }: { trackId: string }): void
ID of the track to toggle
editor.timeline.toggleTrackMute({ trackId: 'track-123' });
toggleTrackVisibility()
Toggles the visibility state of a track.
toggleTrackVisibility({ trackId }: { trackId: string }): void
ID of the track to toggle
editor.timeline.toggleTrackVisibility({ trackId: 'track-123' });
getTracks()
Returns all tracks in the current scene.
getTracks(): TimelineTrack[]
TimelineTrack[] - Array of timeline tracks
Example
const tracks = editor.timeline.getTracks();
console.log(`Total tracks: ${tracks.length}`);
getTrackById()
Finds a track by its ID.
getTrackById({ trackId }: { trackId: string }): TimelineTrack | null
TimelineTrack | null - The track, or null if not found
Example
const track = editor.timeline.getTrackById({ trackId: 'track-123' });
if (track) {
console.log(`Track has ${track.elements.length} elements`);
}
Element methods
insertElement()
Inserts an element into the timeline.
insertElement({ element, placement }: InsertElementParams): void
Where to place the element (at-time, after-element, etc.)
editor.timeline.insertElement({
element: {
type: 'video',
mediaId: 'media-123',
startTime: 0,
duration: 5.0
},
placement: {
type: 'at-time',
trackId: 'track-123',
time: 10.0
}
});
deleteElements()
Deletes multiple elements from the timeline.
deleteElements({ elements }: {
elements: { trackId: string; elementId: string }[]
}): void
elements
Array<{ trackId: string; elementId: string }>
required
Array of track/element ID pairs to delete
editor.timeline.deleteElements({
elements: [
{ trackId: 'track-1', elementId: 'element-1' },
{ trackId: 'track-2', elementId: 'element-2' }
]
});
duplicateElements()
Duplicates elements and places them immediately after the originals.
duplicateElements({ elements }: {
elements: { trackId: string; elementId: string }[]
}): { trackId: string; elementId: string }[]
elements
Array<{ trackId: string; elementId: string }>
required
Array of track/element ID pairs to duplicate
Array<{ trackId: string; elementId: string }> - The duplicated elements
Example
const duplicates = editor.timeline.duplicateElements({
elements: [{ trackId: 'track-1', elementId: 'element-1' }]
});
updateElements()
Updates properties of multiple elements.
updateElements({
updates,
pushHistory = true
}: {
updates: Array<{
trackId: string;
elementId: string;
updates: Partial<Record<string, unknown>>;
}>;
pushHistory?: boolean;
}): void
updates
Array<ElementUpdate>
required
Array of element updates to apply
Whether to push to undo/redo history
editor.timeline.updateElements({
updates: [
{
trackId: 'track-1',
elementId: 'element-1',
updates: { volume: 0.5, opacity: 0.8 }
}
]
});
splitElements()
Splits elements at a specific time.
splitElements({
elements,
splitTime,
retainSide = 'both'
}: {
elements: { trackId: string; elementId: string }[];
splitTime: number;
retainSide?: 'both' | 'left' | 'right';
}): { trackId: string; elementId: string }[]
elements
Array<{ trackId: string; elementId: string }>
required
Elements to split
Time in seconds where the split should occur
retainSide
'both' | 'left' | 'right'
default:"'both'"
Which side(s) of the split to keep
Array<{ trackId: string; elementId: string }> - The right-side elements created by the split
Example
// Split and keep both sides
const rightSide = editor.timeline.splitElements({
elements: [{ trackId: 'track-1', elementId: 'element-1' }],
splitTime: 5.0,
retainSide: 'both'
});
moveElement()
Moves an element to a different track or time.
moveElement({
sourceTrackId,
targetTrackId,
elementId,
newStartTime,
createTrack
}: {
sourceTrackId: string;
targetTrackId: string;
elementId: string;
newStartTime: number;
createTrack?: { type: TrackType; index: number };
}): void
ID of the track containing the element
ID of the destination track
ID of the element to move
New start time in seconds
createTrack
{ type: TrackType; index: number }
Optional: Create a new track if target doesn’t exist
editor.timeline.moveElement({
sourceTrackId: 'track-1',
targetTrackId: 'track-2',
elementId: 'element-1',
newStartTime: 10.0
});
updateElementTrim()
Updates the trim points of an element.
updateElementTrim({
elementId,
trimStart,
trimEnd,
pushHistory = true
}: {
elementId: string;
trimStart: number;
trimEnd: number;
pushHistory?: boolean;
}): void
ID of the element to trim
Trim from the start in seconds
Trim from the end in seconds
Whether to push to undo/redo history
// Trim 2 seconds from start, 1 second from end
editor.timeline.updateElementTrim({
elementId: 'element-1',
trimStart: 2.0,
trimEnd: 1.0
});
updateElementDuration()
Updates the duration of an element.
updateElementDuration({
trackId,
elementId,
duration,
pushHistory = true
}: {
trackId: string;
elementId: string;
duration: number;
pushHistory?: boolean;
}): void
ID of the track containing the element
Whether to push to undo/redo history
editor.timeline.updateElementDuration({
trackId: 'track-1',
elementId: 'element-1',
duration: 10.0
});
updateElementStartTime()
Updates the start time of multiple elements.
updateElementStartTime({
elements,
startTime
}: {
elements: { trackId: string; elementId: string }[];
startTime: number;
}): void
elements
Array<{ trackId: string; elementId: string }>
required
Elements to update
New start time in seconds
editor.timeline.updateElementStartTime({
elements: [{ trackId: 'track-1', elementId: 'element-1' }],
startTime: 5.0
});
toggleElementsVisibility()
Toggles visibility for multiple elements.
toggleElementsVisibility({ elements }: {
elements: { trackId: string; elementId: string }[]
}): void
elements
Array<{ trackId: string; elementId: string }>
required
Elements to toggle
editor.timeline.toggleElementsVisibility({
elements: [{ trackId: 'track-1', elementId: 'element-1' }]
});
toggleElementsMuted()
Toggles muted state for multiple elements.
toggleElementsMuted({ elements }: {
elements: { trackId: string; elementId: string }[]
}): void
elements
Array<{ trackId: string; elementId: string }>
required
Elements to toggle
editor.timeline.toggleElementsMuted({
elements: [{ trackId: 'track-1', elementId: 'element-1' }]
});
Clipboard methods
pasteAtTime()
Pastes clipboard items at a specific time.
pasteAtTime({
time,
clipboardItems
}: {
time: number;
clipboardItems: ClipboardItem[];
}): { trackId: string; elementId: string }[]
Time in seconds to paste at
Array<{ trackId: string; elementId: string }> - The pasted elements
Example
const pastedElements = editor.timeline.pasteAtTime({
time: 10.0,
clipboardItems: copiedItems
});
Preview methods
previewElements()
Previews element updates without committing to history.
previewElements({ updates }: {
updates: Array<{
trackId: string;
elementId: string;
updates: Partial<Record<string, unknown>>;
}>
}): void
updates
Array<ElementUpdate>
required
Updates to preview
editor.timeline.previewElements({
updates: [{
trackId: 'track-1',
elementId: 'element-1',
updates: { opacity: 0.5 }
}]
});
commitPreview()
Commits the current preview to history.
Example
editor.timeline.commitPreview();
discardPreview()
Discards the current preview and restores previous state.
Example
editor.timeline.discardPreview();
isPreviewActive()
Checks if a preview is currently active.
isPreviewActive(): boolean
boolean - True if preview is active
Example
if (editor.timeline.isPreviewActive()) {
console.log('Preview active');
}
Utility methods
getTotalDuration()
Returns the total duration of the timeline in seconds.
getTotalDuration(): number
number - Total duration in seconds
Example
const duration = editor.timeline.getTotalDuration();
console.log(`Timeline duration: ${duration}s`);
getElementsWithTracks()
Returns elements with their parent tracks.
getElementsWithTracks({ elements }: {
elements: { trackId: string; elementId: string }[]
}): Array<{ track: TimelineTrack; element: TimelineElement }>
elements
Array<{ trackId: string; elementId: string }>
required
Elements to retrieve
Array<{ track: TimelineTrack; element: TimelineElement }> - Elements with their tracks
Example
const elementsWithTracks = editor.timeline.getElementsWithTracks({
elements: [{ trackId: 'track-1', elementId: 'element-1' }]
});
subscribe()
Subscribes to timeline state changes.
subscribe(listener: () => void): () => void
Function called when timeline state changes
() => void - Unsubscribe function
Example
const unsubscribe = editor.timeline.subscribe(() => {
console.log('Timeline changed');
});
The useEditor() hook automatically subscribes to timeline changes. Only use subscribe() directly in non-React code.