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. |
onStatus? | (status: TimelineContentPlaybackStatus): void | Receives high-level playback status changes. |
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. |