Usage notes
Use this hook when your preview surface owns the media clock. The hook tells
TimelineEngine
to play with an external clock, reads timeline seconds from `getClockTime`,
and calls `syncLayers` with an ActiveLayerResult whenever active
clips need to be rendered, sought, or paused.
Higher-level adapters such as `useHTMLTimelineMedia` and
`useMediabunnyTimelineMedia` wrap this contract for common media stacks.
Signature
Interface UseTimelineMediaPlaybackOptionsType parameters
| Name | Constraint | Default | Description |
|---|---|---|---|
LayerName | string | string | Named media layer keys inferred from `layers`, such as
`"visuals" | "audio"`. |
Properties
| Name | Signature | Description |
|---|---|---|
frameRate? | frameRate?: TimecodeFrameRate | Optional sequence frame rate used to quantize playback updates to project frames. |
getClockTime | (): number | Returns current timeline seconds from the external media clock. |
layers | layers: Record<LayerName, ActiveLayerSelector> | Named active layer selectors used by the external media surface. |
loop? | (timelineTime: RationalTime, activeLayers: ActiveLayerResult<LayerName>): MaybePromise<void> | Enables looping and realigns the external clock after Core returns to the range start. The callback is invoked once per loop transition until the clock re-enters range. Its presence and implementation are captured when each playback run begins. |
onError? | (error: Error): void | Receives external rendering or scheduling failures before playback is paused. |
onStatus? | (status: TimelineContentPlaybackStatus): void | Receives high-level playback status changes. |
playbackOptions? | playbackOptions?: Omit<PlaybackOptions, "clock" | "loop"> | Core playback range policy applied to the external clock; looping is configured by `loop`. |
setClockRate? | (playbackRate: number): void | Applies a validated playback-rate change to the external media clock. |
stopClock? | (): void | Stops the external media clock when timeline playback pauses or leaves active content. |
syncLayers? | (details: TimelineLayerSyncDetails<LayerName>): MaybePromise<void> | Synchronizes external rendering, audio, text, or effects for the active layers. |
Related links
- - TimelineLayerSyncDetails - useTimelineMediaSync - Mediabunny media sync demo