Usage notes
The hook is collection-first: each named layer returns every matching active
clip in stable track order. `primary` is only a convenience first match.
Use it for preview panels, custom media status, subtitle overlays, and
diagnostics that need to inspect which timeline clips are active without
starting playback. For transport controls that drive an external media clock,
compose useTimelineMediaSync or useTimelineMediaPlayback
instead.
Signature
useActiveLayers(options: ActiveLayerOptions<LayerName>): ActiveLayerResult<LayerName>Type parameters
| Name | Constraint | Default | Description |
|---|---|---|---|
LayerName | string | string | Named layer keys inferred from `options.layers`, such
as `"visuals" | "audio"`. |
Parameters
| Name | Type | Description |
|---|---|---|
| options | ActiveLayerOptions<LayerName> | Active layer selectors and optional lookup time. |
Returns
ActiveLayerResult<LayerName>
Active clips grouped by the configured layer selectors.
Examples
import { useMemo } from 'react';import { useActiveLayers } from '#react/hooks';
const previewLayers = { visuals: { trackKind: 'visual' }, audio: { trackKind: 'audio' },} as const;
export function ActiveMediaReadout() { const layers = useMemo(() => previewLayers, []); const activeLayers = useActiveLayers({ layers });
return ( <dl> <dt>Visual</dt> <dd>{activeLayers.primary.visuals?.clip.name ?? 'No visual clip'}</dd> <dt>Audio clips</dt> <dd>{activeLayers.layers.audio.length}</dd> </dl> );}