# Clips and replay Create independently retained highlights from recordings or a rolling buffer. A clip turns retained media into a private HLS/MP4 asset. Start a [recording](/guides/recording-and-vod) 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: ```ts 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. ```ts 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](/guides/recording-and-vod). 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](/reference/api/v1/clips) and [Node methods](/reference/sdk/server/node/clips).