Documentation Index
Fetch the complete documentation index at: https://mintlify.com/OpenCut-app/OpenCut/llms.txt
Use this file to discover all available pages before exploring further.
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.