RelayrtcDocs
Get started
Documentation
Streaming

Live DVR

Pause, rewind within retained live media, and return to the live edge.

On this page

DVR retains a rolling window of a broadcast's canonical program. It does not create another encoder or a permanent recording. Configure retention before starting a broadcast and obtain consent for that retention.

Enable retention

TypeScript
import { relay } from './relay.js'
 
export async function enableDvr(streamId: string) {
  return relay.streams.dvr.configure(streamId, {
    policy: {
      enabled: true,
      durationSeconds: 300,
      maxBytes: 134217728,
      endedRetentionSeconds: 300,
      consentAcknowledged: true,
    },
  })
}

A source connection without a running broadcast does not produce a DVR window. Capture can wait for recording-worker capacity. Read streams.dvr.getPlayback(streamId, { broadcastId }) and wait for a non-empty available range.

Authorize a specific run

Your backend must authenticate the viewer and authorize DVR access to the selected broadcast:

TypeScript
import { relay } from './relay.js'
 
export async function grantDvr(streamId: string, authorizedBroadcastId: string) {
  return relay.streams.createPlaybackGrant(streamId, {
    mode: 'dvr',
    broadcastId: authorizedBroadcastId,
    ttlSeconds: 300,
  })
}

Bind metadata and renewal to that same broadcast. If it changes, refresh the application selection instead of silently switching runs. Ordinary live grants and schedule-viewer grants do not authorize DVR. After-event entitlement is an application decision.

Render and seek

Use BroadcastPlayer with mode="dvr" and application-backed metadata/grant callbacks, following private playback. Its DVR controls expose rewind, the retained range and Go live. useDvrPlayback supports a custom control surface.

DVR delivers rolling HLS with complete fragmented-MP4 segments, not LL-HLS partials. For an HLS engine, use DVR-appropriate settings: disable low-latency mode and avoid a finite maximum-live-latency setting that would undo intentional rewinds. Native HLS works where supported.

Understand the range

Configured duration is an upper bound. Startup, source gaps, byte pressure and playlist constraints can shorten it. Defaults retain five minutes under 128 MiB; supported duration is 30–1800 seconds, with storage bounded by deployment limits.

Use returned startSeconds, endSeconds and wall-time metadata instead of assuming the browser's currentTime equals run media time. DVR exposes a contiguous retained tail. Expired segments return DVR_RANGE_EXPIRED; an expired window returns DVR_WINDOW_EXPIRED. Refresh metadata and clamp seeking to the current available range.

Stop, disable or change policy

The run snapshots its DVR policy. Later duration/byte changes apply to the next run; updates require the current policy version. Disabling prevents new attachments and drains existing windows for their saved ended-retention period. Re-enabling does not revive a drained run.

Stopping a broadcast freezes its window until ended retention expires. Owning-resource deletion revokes access immediately. Use recording or clips when media must survive beyond that bounded window.

Shared retention and usage

DVR and clip buffers share retained objects. Playlist and clip pins can hold media beyond the nominal duration while still consuming the same byte cap. Capture pauses under storage pressure rather than exceeding that cap.

Shared buffer storage is metered once by recording infrastructure. DVR's storage breakdown is not an additional charge. Delivered bytes measure successfully completed origin response payloads, not protocol overhead or CDN-edge traffic.

See DVR REST APIs, Node methods and player controls.