useClip
Create and publish retained highlights through authorized application endpoints.
On this page
useClip(options) is independent of RelayProvider and RelayRoom. Supply stable callbacks to authenticated application endpoints. Keep management keys on the backend.
Options
| Option | Contract |
|---|---|
getClip | Required; receives AbortSignal and returns ClipResource or null. |
create, publish, delete | Optional application commands receiving { signal, idempotencyKey }. |
pollIntervalMs | Integer 1000–60000 milliseconds; default 2500. |
Forward command keys to your backend SDK calls. Callbacks must honor AbortSignal. isReady means ready; isProcessing means rendering and does not include queued work. Bind the selected recording and interval in your backend command. A ready clip needs explicit publication before viewer grants; operator preview uses a separate audience. Use VOD playback for the resulting asset.
Returns
The hook returns clip, pending, error, isReady, isProcessing, create, publish, delete and refresh. pending covers the application request, not completion of asynchronous server work. Errors are sanitized in the snapshot.
Example
The parent supplies memoized options bound to one selected resource.
import { useClip } from '@relayrtc/react'
export function ClipPanel({ options }: { options: Parameters<typeof useClip>[0] }) {
const highlight = useClip(options)
return <section>
<p>{highlight.clip?.state ?? 'No selected clip'}</p>
<button disabled={!options.create || !!highlight.pending}
onClick={() => { void highlight.create() }}>Create highlight</button>
<button disabled={!options.publish || !highlight.isReady || !!highlight.pending}
onClick={() => { void highlight.publish() }}>Publish</button>
{highlight.error && <p role="alert">{highlight.error.message}</p>}
</section>
}Lifecycle and retries
Unmounting stops polling and aborts outstanding callbacks. Status revisions prevent stale polling from overwriting a newer command result. An uncertain command retains its idempotency key; retry the same action/payload rather than reusing it for another resource. HTTP cancellation does not undo committed server work.
See the workflow for backend setup, retention and authorization. The browser SDK exposes the corresponding client without React.