# BroadcastPlayer Private native/HLS playback independent of an RTC room. ## Availability and source contract Use compatible React and browser SDK builds; see [installation](/installation) for package availability. This player is independent of RelayProvider and RelayRoom; it does not create an RTC participant. ```tsx 'use client' import Hls from 'hls.js' import { BroadcastPlayer, getHlsPlaybackConfig } from '@relayrtc/react' import type { HlsEngineFactory, StreamPlaybackOptions } from '@relayrtc/client' async function request(path: string, method: string, signal: AbortSignal) { const response = await fetch(path, { method, signal, credentials: 'same-origin', cache: 'no-store' }) if (!response.ok) throw new Error('Playback unavailable') return response.json() } // Keep callbacks stable, or memoize them when they depend on a selected stream. const source: StreamPlaybackOptions = { getPlayback: signal => request('/app-api/playback', 'GET', signal), getGrant: signal => request('/app-api/grant', 'POST', signal), } const createHlsEngine: HlsEngineFactory = (media, url, onError, onReady) => { if (!Hls.isSupported()) throw new Error('HLS unavailable') const hls = new Hls(getHlsPlaybackConfig('live')) hls.on(Hls.Events.ERROR, (_event, data) => { if (data.fatal) onError() }) hls.on(Hls.Events.MANIFEST_PARSED, onReady) hls.attachMedia(media) hls.loadSource(url) return () => hls.destroy() } export function Viewer() { return } ``` Install hls.js in your application if you need it. It remains optional; native HLS does not load this engine. The adapter follows the [hls.js API](https://github.com/video-dev/hls.js/blob/master/docs/API.md). `getHlsPlaybackConfig` is exported by both `@relayrtc/react` and `@relayrtc/client`. Pass its result to your hls.js constructor to use the SDK playback defaults. It is not automatically applied to an arbitrary custom engine or native HLS. For live playback, defaults enable low latency, target 3 seconds behind the playlist edge, set a finite 8-second recovery threshold, allow playback up to 1.1x to catch up, and increase the target by 0.25 seconds after a stall. These are player targets, not a camera-to-viewer latency guarantee or a strict maximum during network stalls. Encoding, composition and delivery add upstream latency. A live viewer may jump forward to recover; use DVR mode for intentional rewind. Configure another live target with `getHlsPlaybackConfig('live', { liveSyncDuration: 2, liveMaxLatencyDuration: 6, maxLiveSyncPlaybackRate: 1.05 })`. The recovery threshold must exceed the positive target, playback rate must be between 1 and 2, and stall increase must be non-negative; all live values must be finite. Do not combine the returned seconds-based targets with hls.js `liveSyncDurationCount` or `liveMaxLatencyDurationCount` options. ## Props and lifecycle source requires application-authorized getPlayback/getGrant callbacks and optional pollIntervalMs. createHlsEngine is optional. onPlaybackState receives loading/playing/paused/blocked/unavailable/unsupported/error. Standard video props apply except src/srcObject/onError, which are owned by the player. Controls, autoplay and playsInline are enabled by default. Mute preview to avoid delayed host feedback. The optional `StreamPlaybackMetadata.sourceState` and `readiness` fields can carry the API's source lifecycle and viewer-readiness observation through your backend. Matching React builds re-export `StreamPlaybackReadiness`; application callbacks may omit the additive fields. [Playback metadata](/reference/api/v1/streams#playback-metadata) describes their meanings. The player renews grants before expiry and reconciles session/generation changes. Autoplay denial exposes a Play stream button. Missing source waits for live media; errors expose Retry. Cleanup stops requests/subscriptions, removes source URLs, releases media and destroys the HLS engine. Keep source callbacks and engine factory stable to avoid intentional attachment replacement. useStreamPlayback(source) exports the same playback/grant/error snapshot, client and refresh for custom UIs. It starts its own client and stops it on unmount. Do not put management keys in callbacks. [Application authorization](/guides/streaming-playback) describes the backend boundary. ## Recorded video Use mode `vod` and application-backed recording metadata and asset playback-grant callbacks for private recorded video. Ready recordings can seek with native controls; grant renewal preserves position for the same asset. See [useRecording](/reference/sdk/client/react/use-recording). ## Live DVR Use mode `dvr` with application-backed DVR metadata and mode=dvr playback grants for the same broadcast. The player exposes native pause, a seek slider, rewind 30 seconds, behind-live status, expired-seek recovery and Go live. Grant renewal preserves an existing rewind or pause for the same window; changed window identity attaches the new run. A retained ended run remains playable until expiry. Stable callbacks may accept the fetched metadata as the optional second getGrant argument to bind the renewal to its broadcastId. Provide a DVR-specific HLS adapter using `new Hls(getHlsPlaybackConfig('dvr'))`: lowLatencyMode is false, liveMaxLatencyDuration is infinite, and maximum catch-up playback rate is 1. Intentional rewinds are not forced forward. Use `getHlsPlaybackConfig('vod')` for recordings and clips; it also disables catch-up. Live-option overrides are ignored in DVR/VOD modes. DVR delivery uses full segments, separate from the original live LL-HLS endpoint. See [live DVR](/guides/live-dvr) and [useDvrPlayback](/reference/sdk/client/react/use-dvr-playback). The HLS defaults include `liveSyncMode: "buffered"` for hls.js 1.7+: recovery uses downloaded media rather than repeatedly seeking ahead of the buffer. Use hls.js 1.7.3 or newer for this behavior. Conservative targets reduce edge starvation but do not eliminate network or delivery stalls.