Skip to content

ReferenceMedia

hls-background-video

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

<hls-background-video> plays an HLS source through the SPF background engine. It is fixed to muted, inline playback, loops and autoplays unless you set noloop or noautoplay, 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 '@videojs/html/media/hls-background-video';

Or load it from the CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.6.0/media/hls-background-video.js"></script>

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.

<hls-background-video
  src="https://media.example.com/hero.m3u8"
  crossorigin
></hls-background-video>

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

Set noautoplay to hold playback until your script calls target.play(), for example after checking prefers-reduced-motion, and noloop to play the video once. Without noautoplay, calling pause() before the stream attaches has no effect: autoplay starts the video once the stream loads.

API

Attributes

Attribute Description
src HLS manifest URL
noloop Turns off looping
noautoplay Turns off autoplay
crossorigin, controls, controlslist Passed through to the inner video
keep-alive Keeps the engine running after the element is removed

An explicit loop or autoplay attribute wins over its opt-out. Opt-outs and passed-through attributes also apply when set or changed after the element is created. Muted can’t be turned off, and preload isn’t passed through: the engine loads as soon as it has a source.

Properties

Property Description
src HLS manifest URL. Assigning a new one restarts playback from scratch
error Fatal SPF media error for the current source, or null
target Inner native <video> element. Call play() and pause() on it
video Same element as target
adapter The HlsBackgroundVideoAdapter driving the inner video, including its SPF engine

The element also fires an error event when error becomes fatal. The inner video’s own error can remain null because SPF, rather than the browser, rejected the source.

Removing the element releases its engine a microtask later. If the element has its own keep-alive, the engine keeps running until you call adapter.destroy(). keep-alive on an ancestor, such as <background-video-player keep-alive>, doesn’t keep it.

Styling

Custom property Default Description
--media-object-fit inherit How the video fits its box
--media-object-position 50% 50% Position of the video within its box

Set an explicit size on the custom element or an author-owned wrapper.