Skip to content

ReferenceMedia

HlsBackgroundVideo

HLS background video without controls, audio, captions, or adaptive quality

HlsBackgroundVideo plays an HLS source through the SPF background engine. It is fixed to muted, inline playback, loops and autoplays unless you pass loop={false} or autoPlay={false}, and omits controls, audio, text, DRM, and adaptive rendition switching.

See Add a background video for layout, poster, accessibility, and source-choice guidance.

Import

import { HlsBackgroundVideo } from '@videojs/react/media/hls-background-video';

Source behavior

src takes a complete HLS manifest URL. The engine starts loading when it receives the URL and pins the largest rendition that fits the screen. The ladder may be video-only, but its video renditions must use fMP4/CMAF. This engine does not include MPEG-TS transmuxing or DRM playback.

<HlsBackgroundVideo
  src="https://media.example.com/hero.m3u8"
  crossOrigin="anonymous"
  onError={handleError}
/>

There is no source object, preload mode, or opt-out for muted. Assigning a new src restarts playback from scratch.

Pass autoPlay={false} to hold playback until you call play() on the <video> from ref, for example after checking prefers-reduced-motion, and loop={false} to play the video once. Without autoPlay={false}, calling pause() before the stream attaches has no effect: autoplay starts the video once the stream loads.

API

Member Description
src HLS manifest URL
onError Fires on the rendered <video> when SPF reports a fatal source error
ref Ref to the rendered native <video> element
mediaRef Ref that receives the HlsBackgroundVideoAdapter driving the <video>, including its SPF engine

onError receives an error event dispatched on the rendered <video>. The video’s own error can remain null because SPF, rather than the browser, rejected the source.

Styling

The component renders a native <video>. Set its size, object-fit, and object-position through className or style.