# 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, autoplaying, inline, looped playback and omits controls, audio, text, DRM, and adaptive rendition switching.

See [Add a background video](../../guides/background-video.md) for layout, poster, accessibility, and source-choice guidance.

## Import

```ts
import '@videojs/html/media/hls-background-video';
```

Or load it from the [CDN](../../guides/cdn.md):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.0-rc.3/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.

```html
<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, autoplay, and loop. Assigning a new `src` restarts playback from scratch.

## API

| Member | Description |
| --- | --- |
| `src` | HLS manifest URL |
| `error` | Fatal SPF media error for the current source, or `null` |
| `video` | Inner native `<video>` element |

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.

## 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.