usePlaybackEffect API

Usage notes

Use this hook for clip-local effects such as highlighting subtitles, toggling preview overlays, triggering analytics, or coordinating lightweight external state when a known clip becomes active. `onUpdate` can fire every playback tick while the playhead is inside the clip, so keep that callback cheap and avoid broad React state updates for dense timelines.

Signature

usePlaybackEffect(clipId: string, callbacks: { onEnter: (time: RationalTime) => void; onLeave: (time: RationalTime) => void; onUpdate: (time: RationalTime) => void }): void

Parameters

Name	Type	Description
clipId	string	The unique string ID of the target clip to track.
callbacks	{ onEnter: (time: RationalTime) => void; onLeave: (time: RationalTime) => void; onUpdate: (time: RationalTime) => void }	Callback handlers triggered on transition crossings.

Returns

void

Nothing; the hook manages playback event subscriptions for the component lifetime.

Examples

import { useState } from 'react';
import { usePlaybackEffect } from '#react/hooks';

export function ClipActiveBadge({ clipId }: { clipId: string }) {
  const [active, setActive] = useState(false);

  usePlaybackEffect(clipId, {
    onEnter: () => setActive(true),
    onLeave: () => setActive(false),
  });

  return active ? <span>Active now</span> : null;
}

- useTimelineEvent - Events and lifecycle