Clips and replay
Create independently retained highlights from recordings or a rolling buffer.
On this page
A clip turns retained media into a private HLS/MP4 asset. Start a recording or enable a rolling buffer before the moment you want to save. Clipping cannot recover media that was never retained or has already been evicted.
Enable a rolling buffer
Set a buffer policy before starting the broadcast. Capture begins when a broadcast is live, not merely when an encoder connects. Call this backend helper after obtaining retention consent:
import { relay } from './relay.js'
export async function enableClipBuffer(streamId: string) {
const current = await relay.streams.clips.getBufferPolicy(streamId)
return relay.streams.clips.setBufferPolicy(streamId, {
version: current.version,
policy: {
enabled: true,
durationSeconds: 300,
maxBytes: 134217728,
consentAcknowledged: true,
},
})
}Read streams.clips.getWindow(streamId) for retained recording/run identities and actual ranges. Storage pressure can make the available interval shorter than the configured duration. Request buffer clips while that buffer is active; use a full recording for later editing.
Request a clip
Use a recordingId returned for the authorized recording or buffer. Reuse the same command ID and payload when retrying an uncertain response.
import { relay } from './relay.js'
export async function saveHighlight(
streamId: string, recordingId: string, commandId: string,
) {
return relay.streams.clips.create(streamId, {
recordingId,
interval: { kind: 'last', seconds: 30 },
cutMode: 'keyframe',
retentionSeconds: 604800,
label: 'Match highlight',
}, { idempotencyKey: commandId })
}Poll clips.get(clipId) until ready or failed. A last-N request fails unless the complete requested interval is available.
| Interval | Coordinates |
|---|---|
last | Last N retained seconds |
media | startSeconds and endSeconds on the selected recording's media timeline |
wall | UTC start and end, when segment program timestamps map uniquely |
Buffer eviction does not reset media time. Requests spanning missing media or incompatible source generations fail rather than silently joining unrelated intervals.
Choose cut accuracy
keyframe expands to complete retained segment boundaries and remuxes without transcoding. Inspect requested and resolved bounds; the result can be longer than requested.
precise decodes and re-encodes the interval to H.264/AAC, including its edges. It uses more processing and provides frame/sample-level accuracy, with validation tolerance for rounding. Ready results expose the rendered bounds and verified duration.
Publish and retain
A ready clip is not automatically published. Operators can preview it; use clips.publish(clipId) when your application is ready to issue viewer grants. Publication keeps the bucket private and does not replace application authorization. Use its asset with the VOD playback and download workflow.
Completed clips retain their own media independently of source-buffer eviction or broadcast stop. Clip retention ranges from one hour to 90 days, defaulting to seven days. Deleting the owning stream or tenant still revokes dependent assets.
Limits and cleanup
Defaults allow 120 requested seconds per clip, four pending/rendering jobs globally and ten new clips per environment per minute. A rolling buffer defaults to five minutes and 128 MiB; duration supports 30–1800 seconds, bounded by deployment storage limits.
Pinned inputs survive eviction while a clip is prepared. They still count against the hard byte cap. If capture reports BUFFER_STORAGE_PRESSURE, inspect pinned work and bitrate before increasing capacity. Cleanup releases temporary inputs and obsolete outputs; cumulative usage remains.
Clips share recording infrastructure accounting. Do not add clip breakdowns to recording totals a second time. Subscribe to clip.ready and clip.failed, verify webhook signatures and reconcile current state. See clip REST contracts and Node methods.