# Video.js v10 — HTML API (complete)

> Every HTML API page in one file (about 47k tokens). Index with descriptions: https://videojs.org/docs/framework/html/reference/api/llms.txt

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/html-create-player -->

# createPlayer

Factory function that creates a typed player element and controller for HTML custom elements

## Import

```ts
import { createPlayer } from "@videojs/html";
import { videoFeatures } from "@videojs/html/video";
```

`createPlayer` is the entry point for custom HTML player compositions. It accepts a `features` array and returns the configured `PlayerElement`, a [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) already bound to that player, and `playerContext` as a lower-level escape hatch. Import `ContainerElement` separately when you need a custom container.

**player.ts**

```ts
import { createPlayer, UIElement, selectPlayback } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerElement: VideoPlayerElement, PlayerController } = createPlayer({
  features: videoFeatures,
});

customElements.define('video-player', VideoPlayerElement);

// Control element with selector
class PlayButton extends UIElement {
  #playback = new PlayerController(this, selectPlayback);
}
```

`PlayerElement` and `PlayerController` are scoped to the created player’s feature set. The element owns its store and attachment lifecycle; the configured controller does not need a context argument. `ContainerElement` consumes the shared player context, so the same class works with any created player.

Use split elements (recommended for reusable skins/layouts):

**player.ts**

```ts
import { ContainerElement, createPlayer } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerElement: PlayerRoot } = createPlayer({ features: videoFeatures });

class PlayerRegion extends ContainerElement {}
```

## Examples

### Basic Usage

**index.html**

```html
<demo-video-player class="demo-video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
    <demo-play-toggle>
      <button type="button" class="media-play-button">
        <span class="paused">Play</span>
        <span class="playing">Pause</span>
      </button>
    </demo-play-toggle>
  </media-container>
</demo-video-player>
```

**index.css**

```css
.demo-video-player media-container {
  position: relative;
}

.demo-video-player media-container video {
  width: 100%;
}

.demo-video-player demo-play-toggle {
  position: absolute;
  bottom: 10px;
  left: 10px;
}

.media-play-button {
  padding-block: 8px;
  padding-inline: 20px;
  font: inherit;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.media-play-button .paused {
  display: none;
}

.media-play-button .playing {
  display: none;
}

.demo-video-player demo-play-toggle[data-paused] .paused {
  display: inline;
}

.demo-video-player demo-play-toggle:not([data-paused]) .playing {
  display: inline;
}
```

**index.ts**

```ts
import { createPlayer, selectPlayback, UIElement } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';
import '@videojs/html/ui/container';

const { PlayerElement: VideoPlayerElement, PlayerController } = createPlayer({
  features: videoFeatures,
});

class PlayToggle extends UIElement {
  static readonly tagName = 'demo-play-toggle';

  readonly #player = new PlayerController(this, selectPlayback);

  #disconnect: AbortController | null = null;

  override connectedCallback(): void {
    super.connectedCallback();
    this.#disconnect = new AbortController();

    this.querySelector('button')?.addEventListener('click', this.#toggle, { signal: this.#disconnect.signal });
  }

  override disconnectedCallback(): void {
    super.disconnectedCallback();
    this.#disconnect?.abort();
    this.#disconnect = null;
  }

  protected override update(changed: Map<string, unknown>): void {
    super.update(changed);
    const state = this.#player.value;
    if (!state) return;

    this.toggleAttribute('data-paused', state.paused);
    this.toggleAttribute('data-ended', state.ended);
  }

  #toggle = (): void => {
    const state = this.#player.value;
    if (!state) return;

    if (state.paused) state.play();
    else state.pause();
  };
}

customElements.define('demo-video-player', VideoPlayerElement);
customElements.define(PlayToggle.tagName, PlayToggle);
```

## API Reference

### Video

`createPlayer(config): CreatePlayerResult<VideoPlayerStore>`

Creates a typed HTML player class and bound controller.

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaQualityState>, PlayerFeature<MediaAudioTrackState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaFullscreenState>, PlayerFeature<MediaPictureInPictureState>, PlayerFeature<MediaRemotePlaybackState>, PlayerFeature<MediaControlsState>, PlayerFeature<MediaTextTrackState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |

#### Return Value

| Property | Type | Description |
| --- | --- | --- |
| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement<VideoPlayerStore>)` | Configured player element class that owns the store and attachment lifecycle. |
| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<VideoPlayerStore>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<VideoPlayerStore['state'], Result>): PlayerController<VideoPlayerStore, Result> }` | Player controller bound to this player's context. |
| `playerContext` | `Context<symbol, VideoPlayerStore>` | Context that carries the player store to descendant elements. |

### Audio

`createPlayer(config): CreatePlayerResult<AudioPlayerStore>`

Creates a typed HTML audio player class and bound controller.

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `config` (required) | `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }` | — | Player configuration with features. |

#### Return Value

| Property | Type | Description |
| --- | --- | --- |
| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement<AudioPlayerStore>)` | Configured player element class that owns the store and attachment lifecycle. |
| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<AudioPlayerStore>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<AudioPlayerStore['state'], Result>): PlayerController<AudioPlayerStore, Result> }` | Player controller bound to this player's context. |
| `playerContext` | `Context<symbol, AudioPlayerStore>` | Context that carries the player store to descendant elements. |

### Generic

`createPlayer<const Features extends AnyPlayerFeature[]>(config): CreatePlayerResult<PlayerStore<Features>>`

Creates a typed HTML player class with custom features.

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `config` (required) | `{ features: Features }` | — | Player configuration with features. |

#### Return Value

| Property | Type | Description |
| --- | --- | --- |
| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement<PlayerStore<Features>>)` | Configured player element class that owns the store and attachment lifecycle. |
| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<PlayerStore<Features>>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<PlayerStore<Features>['state'], Result>): PlayerController<PlayerStore<Features>, Result> }` | Player controller bound to this player's context. |
| `playerContext` | `Context<symbol, PlayerStore<Features>>` | Context that carries the player store to descendant elements. |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/player-controller -->

# PlayerController

Reactive controller for accessing player store state in HTML custom elements

## Import

```ts
import { PlayerController } from "@videojs/html/video";
```

`PlayerController` is a reactive controller that consumes the player store from `playerContext`. Without a selector it returns the store instance directly (no subscription — use this for actions). With a selector it returns the selected value and subscribes to changes, triggering a host update on shallow-equal change. Access the current value via `.value`, which returns `undefined` until connected to a player.

The controller exported by each preset, or returned by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player), is already bound to that player’s context, so pass only the host and optional selector. The lower-level `PlayerController` exported from `@videojs/html` accepts the context as its second argument; its constructor signatures are documented below.

```ts
import { UIElement, selectPlayback } from '@videojs/html';
import { PlayerController } from '@videojs/html/video';

class PlayButtonElement extends UIElement {
  readonly #playback = new PlayerController(this, selectPlayback);
}
```

The host must be a reactive controller host, such as a subclass of [`UIElement`](https://videojs.org/docs/framework/html/reference/api/ui-element), so the controller can request updates.

## Player context

`playerContext` is the context every player element provides to its descendants, whether the element comes from a preset or from [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player). `PlayerController` requests it from its host when the host connects, and the nearest ancestor player answers with its store. An element outside a player receives nothing, so `value` stays `undefined`.

Pass `playerContext` to the `PlayerController` exported from `@videojs/html`:

```ts
import { PlayerController, playerContext, selectPlayback, UIElement } from "@videojs/html";

class PlayButtonElement extends UIElement {
  readonly #playback = new PlayerController(this, playerContext, selectPlayback);
}
```

With a selector, the selector types the value. Without one, `value` is typed as the base player store, with no feature state or actions, because `playerContext` does not know the player’s features. For typed access, use the `PlayerController` that `createPlayer` returns, which is already bound to its player, or pass the context `createPlayer` returns, which is the same context as `playerContext` typed for its feature set:

```ts
import { createPlayer, PlayerController, UIElement } from "@videojs/html";
import { videoFeatures } from "@videojs/html/video";

const { playerContext } = createPlayer({ features: videoFeatures });

class VolumeResetElement extends UIElement {
  readonly #store = new PlayerController(this, playerContext);

  reset() {
    this.#store.value?.setVolume(1);
  }
}
```

## Examples

### Basic Usage

**index.html**

```html
<demo-ctrl-player class="demo-ctrl-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
    <div class="panel">
      <demo-ctrl-actions class="actions">
        <button type="button" class="play">Play</button>
        <button type="button" class="pause">Pause</button>
        <button type="button" class="volume">50% Volume</button>
      </demo-ctrl-actions>
      <demo-ctrl-state class="state">
        <span class="text">Paused: Yes | Time: 0.0s | Volume: 100%</span>
      </demo-ctrl-state>
    </div>
  </media-container>
</demo-ctrl-player>
```

**index.css**

```css
.demo-ctrl-player media-container {
  position: relative;
}

.demo-ctrl-player media-container video {
  width: 100%;
}

.panel {
  display: flex;
  gap: 16px;
  align-items: center;
  padding: 12px;
  background: rgba(0, 0, 0, 0.05);
  border-top: 1px solid rgba(0, 0, 0, 0.1);
}

.actions {
  display: flex;
  gap: 6px;
}

.actions button {
  padding: 4px 12px;
  font-size: 0.8125rem;
  color: #111827;
  cursor: pointer;
  background: white;
  border: 1px solid #ccc;
  border-radius: 6px;
}

.state {
  font-size: 0.8125rem;
  font-variant-numeric: tabular-nums;
  color: #374151;
}
```

**index.ts**

```ts
import { createPlayer, selectPlayback, selectTime, selectVolume, UIElement } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';
import '@videojs/html/ui/container';

const { PlayerElement: DemoPlayerElement, PlayerController } = createPlayer({
  features: videoFeatures,
});

class PlayerActions extends UIElement {
  static readonly tagName = 'demo-ctrl-actions';

  readonly #player = new PlayerController(this);

  #disconnect: AbortController | null = null;

  override connectedCallback(): void {
    super.connectedCallback();
    this.#disconnect = new AbortController();
    const signal = this.#disconnect.signal;

    const bind = (selector: string, action: () => void) => {
      this.querySelector(selector)?.addEventListener('click', action, { signal });
    };

    bind('.play', () => this.#player.value?.play());
    bind('.pause', () => this.#player.value?.pause());
    bind('.volume', () => this.#player.value?.setVolume(0.5));
  }

  override disconnectedCallback(): void {
    super.disconnectedCallback();
    this.#disconnect?.abort();
    this.#disconnect = null;
  }
}

class PlayerState extends UIElement {
  static readonly tagName = 'demo-ctrl-state';

  readonly #playback = new PlayerController(this, selectPlayback);
  readonly #time = new PlayerController(this, selectTime);
  readonly #volume = new PlayerController(this, selectVolume);

  protected override update(changed: Map<string, unknown>): void {
    super.update(changed);
    const playback = this.#playback.value;
    const time = this.#time.value;
    const volume = this.#volume.value;

    if (!playback) return;

    const el = this.querySelector('.text');

    if (el) {
      el.textContent = `Paused: ${playback.paused ? 'Yes' : 'No'} | Time: ${(time?.currentTime ?? 0).toFixed(1)}s | Volume: ${Math.round((volume?.volume ?? 0) * 100)}%`;
    }
  }
}

customElements.define('demo-ctrl-player', DemoPlayerElement);
customElements.define(PlayerActions.tagName, PlayerActions);
customElements.define(PlayerState.tagName, PlayerState);
```

## API Reference

### Without Selector

`new PlayerController<Store extends PlayerStore, Result = Store>(host, context)`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | The host element that owns this controller. |
| `context` (required) | `Context<symbol, Store>` | — | Player context to resolve the store from. |

#### Return Value

| Property | Type |
| --- | --- |
| `value` | `Result \| undefined` |
| `displayName` | `string \| undefined` |

### With Selector

`new PlayerController<Store extends PlayerStore, Result = Store>(host, context, selector)`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | The host element that owns this controller. |
| `context` (required) | `Context<symbol, Store>` | — | Player context to resolve the store from. |
| `selector` (required) | `{ (state: Store['state']): Result; displayName?: string }` | — | Derives a value from the player store state. |

#### Return Value

| Property | Type |
| --- | --- |
| `value` | `Result \| undefined` |
| `displayName` | `string \| undefined` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/ui-element -->

# UIElement

Base class for custom elements that read player state through reactive controllers

`UIElement` is the base class for Video.js custom elements, and the one the built-in UI elements extend. It adds reactive properties, a batched update cycle, reactive controllers, and deferred destruction to `HTMLElement`, and renders into the light DOM: the subclass writes its own DOM in `update()`.

`UIElement` extends `DestroyMixin(ReactiveElement)` from Video.js’s own element base, not from Lit. Its reactive properties and update cycle follow the model of Lit’s `ReactiveElement`, with the same names: `static properties`, `requestUpdate()`, `willUpdate()`, `update()`, `updated()`, `updateComplete`, and reactive controllers. It has no templates, shadow root, or `static styles`, no decorators, and no reflection of properties to attributes. `DestroyMixin` adds the [destruction](https://videojs.org/docs/framework/html/reference/api/ui-element#destruction) lifecycle and the `hostDestroyed` controller hook, which Lit doesn’t have.

## Import

```ts
import { UIElement } from "@videojs/html";
```

## Usage

Extend `UIElement`, add a [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) for the player state the element needs, and write DOM in `update()`. The controller requests an update whenever its selected state changes.

```ts
import { PlayerController, playerContext, selectTime, UIElement, type PropertyValues } from "@videojs/html";

class CurrentTimeElement extends UIElement {
  readonly #time = new PlayerController(this, playerContext, selectTime);

  protected override update(changed: PropertyValues): void {
    super.update(changed);

    const time = this.#time.value;
    if (!time) return;

    this.textContent = time.currentTime.toFixed(1);
  }
}

customElements.define("current-time", CurrentTimeElement);
```

The element must be a descendant of a player element, such as `<video-player>`, to receive state. Until then, and when the player lacks the selected feature, `value` is `undefined`.

`playerContext` is the context every player element provides to its descendants. See [Player context](https://videojs.org/docs/framework/html/reference/api/player-controller#player-context) for how it resolves and how it is typed. The `PlayerController` exported by a preset, or returned by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player), is already bound to that player’s context and takes only the host and an optional selector.

## Reactive properties

Declare reactive properties in `static properties` and initialize them as class fields. Setting a declared property to a new value (compared with `Object.is`) schedules an update. Each declaration also observes a matching attribute.

```ts
class SeekByElement extends UIElement {
  static override properties = {
    seconds: { type: Number },
    skipTo: { type: Number, attribute: "skip-to" },
    disabled: { type: Boolean },
  };

  seconds = 10;
  skipTo = 0;
  disabled = false;
}
```

A `PropertyDeclaration` has two options:

| Option | Default | Description |
| --- | --- | --- |
| `type` | `String` | Converts the attribute value. `String` passes the value through (`null` when the attribute is removed), `Number` parses it (`null` when removed), and `Boolean` is `true` while the attribute is present. |
| `attribute` | The property name | The observed attribute. HTML lowercases attribute names, so give camelCase properties a lowercase attribute, such as `{ attribute: "skip-to" }`. |

Attributes update properties; properties do not reflect back to attributes. Set attributes yourself in `update()` when styling or accessibility depends on them.

Values assigned before the element is defined, or before it connects, are replayed through the reactive accessors on first connection, so they win over the class-field defaults.

A subclass of an element that already declares properties must spread the parent’s declarations:

```ts
class LabeledSeekByElement extends SeekByElement {
  static override properties = {
    ...SeekByElement.properties,
    icon: { type: String },
  };

  icon = "";
}
```

## Update cycle

Property changes and `requestUpdate()` calls made in the same task are batched into one update, which runs in a microtask. The first update waits until the element connects. Each update calls, in order:

1. `willUpdate(changed)` — compute values derived from other properties. Changes made here join the current update.
2. `hostUpdate()` on each controller.
3. `update(changed)` — write the element’s DOM. Property changes made here do not schedule another update.
4. `hostUpdated()` on each controller.
5. `firstUpdated(changed)` — once, after the first update.
6. `updated(changed)` — after every update. Property changes made here, or in `firstUpdated`, schedule another update.

`changed` is a `Map` from each changed property name to its previous value. Call `super` when overriding any of these methods.

| Member | Description |
| --- | --- |
| `requestUpdate(name?, oldValue?)` | Schedules an update. Call it with no arguments when the element depends on state outside its reactive properties. |
| `updateComplete` | Promise that resolves when the pending update finishes. It resolves to `false` when that update scheduled another one. |
| `hasUpdated` | `true` after the first update. |
| `isUpdatePending` | `true` from when an update is scheduled until its `update()` call returns. |

## Controllers

A reactive controller is an object that hooks into its host element’s lifecycle. Controllers such as `PlayerController` add themselves to the host when they are constructed.

### ReactiveController

`ReactiveController` is the interface a controller implements. Every hook is optional:

| Hook | Called when |
| --- | --- |
| `hostConnected()` | The element connects, or immediately when the controller is added to a connected element |
| `hostDisconnected()` | The element disconnects |
| `hostUpdate()` | During each update, before `update()` |
| `hostUpdated()` | During each update, after `update()` |
| `hostDestroyed()` | The element is destroyed |

### ReactiveControllerHost

`ReactiveControllerHost` is the interface of the element a controller attaches to. `UIElement` implements it, so a controller whose constructor accepts a `ReactiveControllerHost` works with any `UIElement` subclass.

| Member | Description |
| --- | --- |
| `addController(controller)` | Adds a controller so the element calls its hooks. Calls `hostConnected()` immediately when the element is connected. |
| `removeController(controller)` | Removes a controller. Its hooks stop being called; `hostDisconnected()` is not called. |
| `requestUpdate()` | Schedules an update of the element. |
| `updateComplete` | Promise that resolves when the element’s pending update finishes. It resolves to `false` when that update scheduled another one. |

```ts
import type { ReactiveController, ReactiveControllerHost } from "@videojs/html";

class ClockController implements ReactiveController {
  now = Date.now();
  readonly #host: ReactiveControllerHost;
  #timer = 0;

  constructor(host: ReactiveControllerHost) {
    this.#host = host;
    host.addController(this);
  }

  hostConnected(): void {
    this.#timer = window.setInterval(() => {
      this.now = Date.now();
      this.#host.requestUpdate();
    }, 1000);
  }

  hostDisconnected(): void {
    this.#stop();
  }

  // `destroy()` can run while the element is still connected.
  hostDestroyed(): void {
    this.#stop();
  }

  #stop(): void {
    window.clearInterval(this.#timer);
  }
}
```

## Destruction

When the element disconnects, it waits two animation frames and then destroys itself if it is still disconnected. Moving the element within the document, or a framework reordering it, therefore keeps it alive. Destruction calls `hostDestroyed()` on every controller. A destroyed element stops updating and ignores later connections.

| Member | Description |
| --- | --- |
| `destroy()` | Destroys the element now. Calling it again has no effect. |
| `destroyed` | `true` after destruction. |
| `destroyCallback()` | Runs once on destruction. Override it, calling `super.destroyCallback()`, to release resources the element owns. |

Add the `keep-alive` attribute to skip automatic destruction, for example when you detach an element and insert it again later. Call `destroy()` yourself when you are done with it.

Release listeners and observers that the element starts on connection in `disconnectedCallback()`, calling `super.disconnectedCallback()`, because an element can connect and disconnect many times before it is destroyed.

## Examples

### Basic Usage

A seek button with a reactive `seconds` property, set from its attribute.

**index.html**

```html
<video-player class="html-ui-element-basic">
  <media-container class="html-ui-element-basic__container">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <div class="html-ui-element-basic__controls">
      <demo-seek-by seconds="-10">
        <button type="button" class="html-ui-element-basic__button"></button>
      </demo-seek-by>
      <demo-seek-by seconds="10">
        <button type="button" class="html-ui-element-basic__button"></button>
      </demo-seek-by>
    </div>
  </media-container>
</video-player>
```

**index.css**

```css
.html-ui-element-basic__container {
  position: relative;
}

.html-ui-element-basic__container video {
  width: 100%;
}

.html-ui-element-basic__controls {
  position: absolute;
  bottom: 12px;
  left: 12px;
  display: flex;
  gap: 8px;
}

.html-ui-element-basic__button {
  padding: 6px 12px;
  font-size: 0.875rem;
  font-variant-numeric: tabular-nums;
  color: white;
  cursor: pointer;
  background: rgba(0, 0, 0, 0.6);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 6px;
}

.html-ui-element-basic__button:disabled {
  cursor: default;
  opacity: 0.5;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import { PlayerController, playerContext, type PropertyValues, selectTime, UIElement } from '@videojs/html';

class SeekByElement extends UIElement {
  static readonly tagName = 'demo-seek-by';

  static override properties = {
    seconds: { type: Number },
  };

  seconds = 10;

  readonly #time = new PlayerController(this, playerContext, selectTime);

  #disconnect: AbortController | null = null;

  override connectedCallback(): void {
    super.connectedCallback();
    this.#disconnect = new AbortController();
    this.querySelector('button')?.addEventListener('click', this.#seek, { signal: this.#disconnect.signal });
  }

  override disconnectedCallback(): void {
    super.disconnectedCallback();
    this.#disconnect?.abort();
    this.#disconnect = null;
  }

  protected override update(changed: PropertyValues): void {
    super.update(changed);

    const button = this.querySelector('button');
    if (!button) return;

    if (changed.has('seconds')) {
      const amount = Math.abs(this.seconds);

      button.textContent = `${this.seconds < 0 ? '-' : '+'}${amount}s`;
      button.ariaLabel = `Seek ${this.seconds < 0 ? 'backward' : 'forward'} ${amount} seconds`;
    }

    button.disabled = !this.#time.value;
  }

  #seek = () => {
    const time = this.#time.value;

    time?.seek(time.currentTime + this.seconds);
  };
}

customElements.define(SeekByElement.tagName, SeekByElement);
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/media-capabilities -->

# Media capability guards

Type guards that narrow a Media object to the capabilities it supports

The media a player attaches is typed as `Media`, which guarantees only a `play()` method and the `addEventListener`, `removeEventListener`, and `dispatchEvent` event methods. A native `<video>` element, an engine-backed media such as `HlsVideo`, and an embed such as YouTube each support a different set of everything else. Capability guards test whether a media supports one capability and narrow its type to that capability’s members.

## Import

```ts
import { isMediaSeekCapable, isMediaVolumeCapable } from "@videojs/html";
```

Every guard on this page is a named export of the same package.

## Usage

The player element’s `store.target` holds the media the player attached. It’s `null` until a media component inside the player registers, so read it when you need it rather than once at startup:

**index.ts**

```ts
import "@videojs/html/video/player";
import { isMediaVolumeCapable } from "@videojs/html";

const player = document.querySelector("video-player");

document.querySelector("#half-volume")?.addEventListener("click", () => {
  const media = player?.store.target?.media;
  if (isMediaVolumeCapable(media)) media.volume = 0.5;
});
```

The examples below assume `player` is the queried player element.

Each `isMedia*Capable` guard accepts any value and returns `false` for `null`, `undefined`, and other non-objects, so you can pass the media straight in without a separate null check.

## Behavior

A guard checks that a few members of a capability are present, then narrows to every member of that capability’s contract. The table lists both.

Some media, such as embeds, can’t provide buffered ranges, text tracks, or remote playback, and report a shared empty placeholder in their place. `isMediaBufferCapable`, `isMediaTextTrackCapable`, and `isMediaRemotePlaybackCapable` return `false` for that placeholder.

A guard describes what the media object supports, not its current state. `isMediaErrorCapable` returns `true` while `error` is `null`, and `isMediaVolumeCapable` returns `true` on platforms that ignore volume changes. For current state and availability, such as `volumeAvailability` from the [volume feature](https://videojs.org/docs/framework/html/reference/api/feature-volume), read the player’s [features](https://videojs.org/docs/framework/html/guides/features) instead.

| Guard | Checks | Narrows to |
| --- | --- | --- |
| `isMediaPauseCapable` | `paused`, `ended`, `pause()` | `pause()`, `paused`, `ended` |
| `isMediaSeekCapable` | `currentTime`, `duration`, `seeking` | `currentTime`, `loop`, `duration`, `seeking` |
| `isMediaSourceCapable` | `src`, `currentSrc`, `readyState`, `load()` | `src`, `currentSrc`, `readyState`, `preload`, `crossOrigin`, `load()`, `canPlayType()` |
| `isMediaVolumeCapable` | `volume`, `muted` | `volume`, `muted`, `defaultMuted` |
| `isMediaPlaybackRateCapable` | `playbackRate` | `playbackRate`, `defaultPlaybackRate` |
| `isMediaBufferCapable` | `buffered`, `seekable`, neither an empty placeholder | `buffered`, `seekable` |
| `isMediaErrorCapable` | `error` (`null` counts) | `error` |
| `isMediaTextTrackCapable` | `textTracks`, not an empty placeholder | `textTracks`, `addTextTrack()` |
| `isMediaVideoRenditionCapable` | `videoRenditions` | `videoRenditions` |
| `isMediaAudioTrackCapable` | `audioTracks` | `audioTracks`, `addAudioTrack()`, `removeAudioTrack()` |
| `isMediaVideoDimensionsCapable` | `videoWidth`, `videoHeight` | `videoWidth`, `videoHeight` |
| `isMediaRemotePlaybackCapable` | `remote` is an object, not an empty placeholder | `remote`, `disableRemotePlayback` |
| `isMediaStreamTypeCapable` | `streamType` | `streamType` |
| `isMediaLiveCapable` | `liveEdgeStart`, `targetLiveWindow` | `liveEdgeStart`, `targetLiveWindow` |

`hasMetadata` isn’t a type guard: it takes a media already narrowed by `isMediaSourceCapable` and returns a boolean.

## Guards

### `isMediaPauseCapable`

Narrows to `pause()` and the read-only `paused` and `ended` booleans.

```ts
function togglePaused() {
  const media = player?.store.target?.media;
  if (!isMediaPauseCapable(media)) return;

  if (media.paused) media.play();
  else media.pause();
}
```

### `isMediaSeekCapable`

Narrows to the writable `currentTime` and `loop`, and the read-only `duration` and `seeking`. All times are in seconds.

```ts
function skipForward() {
  const media = player?.store.target?.media;
  if (isMediaSeekCapable(media)) media.currentTime = Math.min(media.currentTime + 10, media.duration);
}
```

### `isMediaSourceCapable`

Narrows to the writable `src`, `preload`, and `crossOrigin`; the read-only `currentSrc` and `readyState`; and the `load()` and `canPlayType(type)` methods. `canPlayType` returns `''`, `'maybe'`, or `'probably'`.

```ts
function playNext(url: string) {
  const media = player?.store.target?.media;
  if (!isMediaSourceCapable(media)) return;

  media.src = url;
  media.play();
}
```

### `hasMetadata`

Returns `true` when the media’s `readyState` is at least `HAVE_METADATA` (`1`), meaning duration and dimensions are known. It reads only `readyState`, so narrow with `isMediaSourceCapable` first.

```ts
function resumeAt(seconds: number) {
  const media = player?.store.target?.media;
  if (!isMediaSourceCapable(media) || !hasMetadata(media)) return;
  if (isMediaSeekCapable(media)) media.currentTime = seconds;
}
```

### `isMediaVolumeCapable`

Narrows to the writable `volume` (`0` to `1`), `muted`, and `defaultMuted`.

```ts
function unmuteAtHalfVolume() {
  const media = player?.store.target?.media;
  if (!isMediaVolumeCapable(media)) return;

  media.muted = false;
  media.volume = 0.5;
}
```

### `isMediaPlaybackRateCapable`

Narrows to the writable `playbackRate` and `defaultPlaybackRate`.

```ts
function playFaster() {
  const media = player?.store.target?.media;
  if (isMediaPlaybackRateCapable(media)) media.playbackRate = 1.5;
}
```

### `isMediaBufferCapable`

Narrows to the read-only `buffered` and `seekable` time ranges. Each range list has a `length` and `start(index)` and `end(index)` methods that return seconds.

```ts
function getBufferedEnd() {
  const media = player?.store.target?.media;
  if (!isMediaBufferCapable(media) || media.buffered.length === 0) return 0;

  return media.buffered.end(media.buffered.length - 1);
}
```

### `isMediaErrorCapable`

Narrows to the read-only `error`, which is `null` or an object with a numeric `code` and a `message`.

```ts
function reportError() {
  const media = player?.store.target?.media;
  if (isMediaErrorCapable(media) && media.error) console.error(media.error.code, media.error.message);
}
```

### `isMediaTextTrackCapable`

Narrows to the read-only `textTracks` list and `addTextTrack(kind, label?, language?)`. The list is iterable and indexable, and each track has `kind`, `label`, `language`, `id`, a writable `mode` (`'showing'`, `'hidden'`, or `'disabled'`), and `cues`.

```ts
function showCaptions(language: string) {
  const media = player?.store.target?.media;
  if (!isMediaTextTrackCapable(media)) return;

  for (const track of media.textTracks) {
    if (track.kind === "captions" || track.kind === "subtitles") {
      track.mode = track.language === language ? "showing" : "disabled";
    }
  }
}
```

### `isMediaVideoRenditionCapable`

Narrows to the read-only `videoRenditions` list. The list is iterable and indexable, has `getRenditionById(id)`, and has a writable `selectedIndex`; `-1` means automatic selection. Each rendition has `id`, `width`, `height`, `bitrate`, `frameRate`, `codec`, and `selected`.

```ts
function switchToAutomaticQuality() {
  const media = player?.store.target?.media;
  if (isMediaVideoRenditionCapable(media)) media.videoRenditions.selectedIndex = -1;
}
```

### `isMediaAudioTrackCapable`

Narrows to the read-only `audioTracks` list, `addAudioTrack(kind, label?, language?)`, and `removeAudioTrack(track)`. The list is iterable and indexable, and each track has `id`, `kind`, `label`, `language`, and a writable `enabled`.

```ts
function selectAudioLanguage(language: string) {
  const media = player?.store.target?.media;
  if (!isMediaAudioTrackCapable(media)) return;

  for (const track of media.audioTracks) track.enabled = track.language === language;
}
```

### `isMediaVideoDimensionsCapable`

Narrows to the read-only `videoWidth` and `videoHeight`, in pixels. Both are `0` until metadata loads.

```ts
function getAspectRatio() {
  const media = player?.store.target?.media;
  if (!isMediaVideoDimensionsCapable(media) || !media.videoHeight) return null;

  return media.videoWidth / media.videoHeight;
}
```

### `isMediaRemotePlaybackCapable`

Narrows to the read-only `remote` object and the writable `disableRemotePlayback`. `remote` has a `state` (`'connecting'`, `'connected'`, or `'disconnected'`), `prompt()`, `watchAvailability(callback)`, and `cancelWatchAvailability(id?)`, matching the browser’s [Remote Playback API](https://developer.mozilla.org/en-US/docs/Web/API/RemotePlayback).

```ts
function castToDevice() {
  const media = player?.store.target?.media;
  if (isMediaRemotePlaybackCapable(media)) media.remote.prompt();
}
```

Call `prompt()` from a user gesture, such as a click handler; browsers reject it otherwise.

### `isMediaStreamTypeCapable`

Narrows to `streamType`: `'on-demand'`, `'live'`, or `'unknown'` before the type is determined.

```ts
function isLiveStream() {
  const media = player?.store.target?.media;
  return isMediaStreamTypeCapable(media) && media.streamType === "live";
}
```

### `isMediaLiveCapable`

Narrows to the read-only `liveEdgeStart` and `targetLiveWindow`. Playback is at the live edge when `currentTime` is at or past `liveEdgeStart`, which is `NaN` when the stream isn’t live or the value is unknown. `targetLiveWindow` is `0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown; it isn’t a duration.

```ts
function isAtLiveEdge() {
  const media = player?.store.target?.media;
  if (!isMediaLiveCapable(media) || !isMediaSeekCapable(media)) return false;

  return media.currentTime >= media.liveEdgeStart;
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/preset-video -->

# Video preset

The general-purpose video preset — a player, feature bundle, skins, and media for on-demand video

`@videojs/html/video` is the general-purpose preset for on-demand video. It bundles the `<video-player>` element, the `videoFeatures` bundle it is configured with, and two skins, and plays through the browser’s native `<video>`. See [Presets](https://videojs.org/docs/framework/html/guides/presets) for how presets fit together and how to customize one.

## Import

```ts
import '@videojs/html/video/player';
import '@videojs/html/video/skin';
```

Import `@videojs/html/video/neutral-skin` instead for the neutral skin. Or load one [CDN](https://videojs.org/docs/framework/html/guides/cdn) bundle that registers the player and a skin together:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/video.js"></script>
```

`video-neutral.js` registers the neutral skin instead, and `video-player.js` registers `<video-player>` alone.

## Usage

**index.html**

```html
<script type="module">
  import '@videojs/html/video/player';
  import '@videojs/html/video/skin';
</script>

<video-player>
  <video-skin>
    <video src="video.mp4"></video>
  </video-skin>
</video-player>
```

## Player

`@videojs/html/video/player` registers `<video-player>`, whose class is `VideoPlayerElement`. It is a [player](https://videojs.org/docs/framework/html/reference/components/player) element created by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) with `videoFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](https://videojs.org/docs/framework/html/reference/components/player-container) inside it.

| Attribute | Property | Description |
| --- | --- | --- |
| `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
| `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |

`content-title` and `poster` come from the [metadata feature](https://videojs.org/docs/framework/html/reference/api/feature-metadata#player-inputs). The element’s read-only `store` property returns its player store.

The preset root also exports a `PlayerController` bound to the video player’s store. Use it from any custom element inside `<video-player>`; see [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller).

## Feature bundle

`videoFeatures` is the array of [features](https://videojs.org/docs/framework/html/guides/features) the player is configured with:

| Feature | Description |
| --- | --- |
| [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback) | Play/pause state and actions for the player store |
| [`playbackRateFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback-rate) | Playback speed state and actions for the player store |
| [`qualityFeature`](https://videojs.org/docs/framework/html/reference/api/feature-quality) | Video rendition state and actions for the player store |
| [`audioTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-audio-track) | Audio track state and actions for the player store |
| [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume) | Volume level and mute state for the player store |
| [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time) | Playback position and duration state for the player store |
| [`sourceFeature`](https://videojs.org/docs/framework/html/reference/api/feature-source) | Media source state and actions for the player store |
| [`bufferFeature`](https://videojs.org/docs/framework/html/reference/api/feature-buffer) | Buffered and seekable time range state for the player store |
| [`fullscreenFeature`](https://videojs.org/docs/framework/html/reference/api/feature-fullscreen) | Fullscreen state and actions for the player store |
| [`pipFeature`](https://videojs.org/docs/framework/html/reference/api/feature-pip) | Picture-in-picture state and actions for the player store |
| [`remotePlaybackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-remote-playback) | Remote playback state and actions for the player store |
| [`controlsFeature`](https://videojs.org/docs/framework/html/reference/api/feature-controls) | User activity and controls visibility state for the player store |
| [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks) | Subtitles, captions, and chapter track state for the player store |
| [`errorFeature`](https://videojs.org/docs/framework/html/reference/api/feature-error) | Media error state and actions for the player store |
| [`metadataFeature`](https://videojs.org/docs/framework/html/reference/api/feature-metadata) | Resolved title and poster values for the player store |

Its type, `VideoFeatures`, is the tuple of those features in order. Import it from the package root:

```ts
import type { VideoFeatures } from '@videojs/html';
```

To add or remove a feature, pass your own array to `createPlayer`. The skins expect the features they render controls for.

```ts
import { createPlayer, orientationLockFeature } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerElement } = createPlayer({
  features: [...videoFeatures, orientationLockFeature],
});

customElements.define('my-video-player', PlayerElement);
```

## Skins

- [VideoSkin](https://videojs.org/docs/framework/html/reference/components/video-skin) — the default skin, with the modern, frosted look.
- [NeutralVideoSkin](https://videojs.org/docs/framework/html/reference/components/video-neutral-skin) — the visually lighter variant, closer to a classic control bar.

## Media

The preset plays through a native [`<video>`](https://videojs.org/docs/framework/html/reference/components/video), so it registers no media component of its own. Swap it for any compatible [media component](https://videojs.org/docs/framework/html/guides/media-sources), such as [`<hlsjs-video>`](https://videojs.org/docs/framework/html/reference/components/hlsjs-video) for HLS.

## Exports

The preset root, `@videojs/html/video`, has no side effects. Importing it never registers an element:

| Export | Description |
| --- | --- |
| `VideoPlayerElement` | The [player](https://videojs.org/docs/framework/html/reference/api/preset-video#player) element class. |
| `PlayerController` | The player controller, bound to the video player’s store. |
| `videoFeatures` | The [feature bundle](https://videojs.org/docs/framework/html/reference/api/preset-video#feature-bundle). |
| `VideoSkinElement` | The default [skin](https://videojs.org/docs/framework/html/reference/api/preset-video#skins) element class. |
| `NeutralVideoSkinElement` | The neutral [skin](https://videojs.org/docs/framework/html/reference/api/preset-video#skins) element class. |

Registration entry points are side-effect-only:

| Entry point | Registers |
| --- | --- |
| `@videojs/html/video/player` | `<video-player>` |
| `@videojs/html/video/skin` | `<video-skin>`, `<media-container>`, and the UI elements the skin composes |
| `@videojs/html/video/neutral-skin` | `<video-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
| `@videojs/html/video/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
| `@videojs/html/video/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/preset-audio -->

# Audio preset

The audio-only preset — a player, feature bundle, skins, and media for on-demand audio

`@videojs/html/audio` is the preset for on-demand audio. It bundles the `<audio-player>` element, the `audioFeatures` bundle it is configured with, and two skins, and plays through the browser’s native `<audio>`. See [Presets](https://videojs.org/docs/framework/html/guides/presets) for how presets fit together and how to customize one.

## Import

```ts
import '@videojs/html/audio/player';
import '@videojs/html/audio/skin';
```

Import `@videojs/html/audio/neutral-skin` instead for the neutral skin. Or load one [CDN](https://videojs.org/docs/framework/html/guides/cdn) bundle that registers the player and a skin together:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/audio.js"></script>
```

`audio-neutral.js` registers the neutral skin instead, and `audio-player.js` registers `<audio-player>` alone.

## Usage

**index.html**

```html
<script type="module">
  import '@videojs/html/audio/player';
  import '@videojs/html/audio/skin';
</script>

<audio-player>
  <audio-skin>
    <audio src="audio.m4a"></audio>
  </audio-skin>
</audio-player>
```

## Player

`@videojs/html/audio/player` registers `<audio-player>`, whose class is `AudioPlayerElement`. It is a [player](https://videojs.org/docs/framework/html/reference/components/player) element created by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) with `audioFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](https://videojs.org/docs/framework/html/reference/components/player-container) inside it.

| Attribute | Property | Description |
| --- | --- | --- |
| `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
| `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |

`content-title` and `poster` come from the [metadata feature](https://videojs.org/docs/framework/html/reference/api/feature-metadata#player-inputs). The element’s read-only `store` property returns its player store.

The preset root also exports a `PlayerController` bound to the audio player’s store. Use it from any custom element inside `<audio-player>`; see [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller).

## Feature bundle

`audioFeatures` is the array of [features](https://videojs.org/docs/framework/html/guides/features) the player is configured with, a subset of the [video preset’s](https://videojs.org/docs/framework/html/reference/api/preset-video#feature-bundle) `videoFeatures`:

| Feature | Description |
| --- | --- |
| [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback) | Play/pause state and actions for the player store |
| [`playbackRateFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback-rate) | Playback speed state and actions for the player store |
| [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume) | Volume level and mute state for the player store |
| [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time) | Playback position and duration state for the player store |
| [`sourceFeature`](https://videojs.org/docs/framework/html/reference/api/feature-source) | Media source state and actions for the player store |
| [`bufferFeature`](https://videojs.org/docs/framework/html/reference/api/feature-buffer) | Buffered and seekable time range state for the player store |
| [`errorFeature`](https://videojs.org/docs/framework/html/reference/api/feature-error) | Media error state and actions for the player store |
| [`metadataFeature`](https://videojs.org/docs/framework/html/reference/api/feature-metadata) | Resolved title and poster values for the player store |

Its type, `AudioFeatures`, is the tuple of those features in order. Import it from the package root:

```ts
import type { AudioFeatures } from '@videojs/html';
```

To add or remove a feature, pass your own array to `createPlayer`. The skins expect the features they render controls for.

```ts
import { createPlayer, remotePlaybackFeature } from '@videojs/html';
import { audioFeatures } from '@videojs/html/audio';

const { PlayerElement } = createPlayer({
  features: [...audioFeatures, remotePlaybackFeature],
});

customElements.define('my-audio-player', PlayerElement);
```

## Skins

- [AudioSkin](https://videojs.org/docs/framework/html/reference/components/audio-skin) — the default skin, with the modern, frosted look.
- [NeutralAudioSkin](https://videojs.org/docs/framework/html/reference/components/audio-neutral-skin) — the visually lighter variant, closer to a classic control bar.

## Media

The preset plays through a native [`<audio>`](https://videojs.org/docs/framework/html/reference/components/audio), so it registers no media component of its own. Swap it for any compatible [media component](https://videojs.org/docs/framework/html/guides/media-sources), such as [`<hls-audio>`](https://videojs.org/docs/framework/html/reference/components/hls-audio) for HLS.

## Exports

The preset root, `@videojs/html/audio`, has no side effects. Importing it never registers an element:

| Export | Description |
| --- | --- |
| `AudioPlayerElement` | The [player](https://videojs.org/docs/framework/html/reference/api/preset-audio#player) element class. |
| `PlayerController` | The player controller, bound to the audio player’s store. |
| `audioFeatures` | The [feature bundle](https://videojs.org/docs/framework/html/reference/api/preset-audio#feature-bundle). |
| `AudioSkinElement` | The default [skin](https://videojs.org/docs/framework/html/reference/api/preset-audio#skins) element class. |
| `NeutralAudioSkinElement` | The neutral [skin](https://videojs.org/docs/framework/html/reference/api/preset-audio#skins) element class. |

Registration entry points are side-effect-only:

| Entry point | Registers |
| --- | --- |
| `@videojs/html/audio/player` | `<audio-player>` |
| `@videojs/html/audio/skin` | `<audio-skin>`, `<media-container>`, and the UI elements the skin composes |
| `@videojs/html/audio/neutral-skin` | `<audio-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
| `@videojs/html/audio/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
| `@videojs/html/audio/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/preset-live-video -->

# Live video preset

The live video preset — a player, feature bundle, skins, and media for live video streams

`@videojs/html/live-video` is the preset for live video streams. It bundles the `<live-video-player>` element, the `liveVideoFeatures` bundle it is configured with, and two skins that swap the time slider and time displays for a Live button, and plays through the browser’s native `<video>`. See [Presets](https://videojs.org/docs/framework/html/guides/presets) for how presets fit together and [Live streams](https://videojs.org/docs/framework/html/guides/live-streams) for playing a live source.

## Import

```ts
import '@videojs/html/live-video/player';
import '@videojs/html/live-video/skin';
```

Import `@videojs/html/live-video/neutral-skin` instead for the neutral skin. Or load one [CDN](https://videojs.org/docs/framework/html/guides/cdn) bundle that registers the player and a skin together:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/live-video.js"></script>
```

`live-video-neutral.js` registers the neutral skin instead, and `live-video-player.js` registers `<live-video-player>` alone.

## Usage

Live streams are usually HLS, so this example plays through an HLS media component instead of the preset’s native video.

**index.html**

```html
<script type="module">
  import '@videojs/html/live-video/player';
  import '@videojs/html/live-video/skin';
  import '@videojs/html/media/hlsjs-video';
</script>

<live-video-player>
  <live-video-skin>
    <hlsjs-video src="https://example.com/live.m3u8"></hlsjs-video>
  </live-video-skin>
</live-video-player>
```

## Player

`@videojs/html/live-video/player` registers `<live-video-player>`, whose class is `LiveVideoPlayerElement`. It is a [player](https://videojs.org/docs/framework/html/reference/components/player) element created by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) with `liveVideoFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](https://videojs.org/docs/framework/html/reference/components/player-container) inside it.

| Attribute | Property | Description |
| --- | --- | --- |
| `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
| `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |

`content-title` and `poster` come from the [metadata feature](https://videojs.org/docs/framework/html/reference/api/feature-metadata#player-inputs). The element’s read-only `store` property returns its player store.

The preset root also exports a `PlayerController` bound to the live video player’s store. Use it from any custom element inside `<live-video-player>`; see [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller).

## Feature bundle

`liveVideoFeatures` is the array of [features](https://videojs.org/docs/framework/html/guides/features) the player is configured with. It is the [video preset’s](https://videojs.org/docs/framework/html/reference/api/preset-video#feature-bundle) `videoFeatures` without playback rate, quality, and audio-track selection, plus the [live feature](https://videojs.org/docs/framework/html/reference/api/feature-live):

| Feature | Description |
| --- | --- |
| [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback) | Play/pause state and actions for the player store |
| [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume) | Volume level and mute state for the player store |
| [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time) | Playback position and duration state for the player store |
| [`sourceFeature`](https://videojs.org/docs/framework/html/reference/api/feature-source) | Media source state and actions for the player store |
| [`bufferFeature`](https://videojs.org/docs/framework/html/reference/api/feature-buffer) | Buffered and seekable time range state for the player store |
| [`fullscreenFeature`](https://videojs.org/docs/framework/html/reference/api/feature-fullscreen) | Fullscreen state and actions for the player store |
| [`pipFeature`](https://videojs.org/docs/framework/html/reference/api/feature-pip) | Picture-in-picture state and actions for the player store |
| [`remotePlaybackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-remote-playback) | Remote playback state and actions for the player store |
| [`controlsFeature`](https://videojs.org/docs/framework/html/reference/api/feature-controls) | User activity and controls visibility state for the player store |
| [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks) | Subtitles, captions, and chapter track state for the player store |
| [`errorFeature`](https://videojs.org/docs/framework/html/reference/api/feature-error) | Media error state and actions for the player store |
| [`liveFeature`](https://videojs.org/docs/framework/html/reference/api/feature-live) | Live edge state for the player store |
| [`metadataFeature`](https://videojs.org/docs/framework/html/reference/api/feature-metadata) | Resolved title and poster values for the player store |

Its type, `LiveVideoFeatures`, is the tuple of those features in order. Import it from the package root:

```ts
import type { LiveVideoFeatures } from '@videojs/html';
```

To add or remove a feature, pass your own array to `createPlayer`. The skins expect the features they render controls for.

```ts
import { createPlayer, streamTypeFeature } from '@videojs/html';
import { liveVideoFeatures } from '@videojs/html/live-video';

const { PlayerElement } = createPlayer({
  features: [...liveVideoFeatures, streamTypeFeature],
});

customElements.define('my-live-video-player', PlayerElement);
```

## Skins

- [LiveVideoSkin](https://videojs.org/docs/framework/html/reference/components/live-video-skin) — the default skin, which swaps the time controls for a Live button.
- [NeutralLiveVideoSkin](https://videojs.org/docs/framework/html/reference/components/live-video-neutral-skin) — the visually lighter variant, closer to a classic control bar.

## Media

The preset plays through a native [`<video>`](https://videojs.org/docs/framework/html/reference/components/video), so it registers no media component of its own. Most browsers need a streaming [media component](https://videojs.org/docs/framework/html/guides/media-sources) to play a live source, such as [`<hlsjs-video>`](https://videojs.org/docs/framework/html/reference/components/hlsjs-video) for HLS.

## Exports

The preset root, `@videojs/html/live-video`, has no side effects. Importing it never registers an element:

| Export | Description |
| --- | --- |
| `LiveVideoPlayerElement` | The [player](https://videojs.org/docs/framework/html/reference/api/preset-live-video#player) element class. |
| `PlayerController` | The player controller, bound to the live video player’s store. |
| `liveVideoFeatures` | The [feature bundle](https://videojs.org/docs/framework/html/reference/api/preset-live-video#feature-bundle). |
| `LiveVideoSkinElement` | The default [skin](https://videojs.org/docs/framework/html/reference/api/preset-live-video#skins) element class. |
| `NeutralLiveVideoSkinElement` | The neutral [skin](https://videojs.org/docs/framework/html/reference/api/preset-live-video#skins) element class. |

Registration entry points are side-effect-only:

| Entry point | Registers |
| --- | --- |
| `@videojs/html/live-video/player` | `<live-video-player>` |
| `@videojs/html/live-video/skin` | `<live-video-skin>`, `<media-container>`, and the UI elements the skin composes |
| `@videojs/html/live-video/neutral-skin` | `<live-video-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
| `@videojs/html/live-video/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
| `@videojs/html/live-video/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/preset-live-audio -->

# Live audio preset

The live audio preset — a player, feature bundle, skins, and media for live audio streams

`@videojs/html/live-audio` is the preset for live audio streams. It bundles the `<live-audio-player>` element, the `liveAudioFeatures` bundle it is configured with, and two skins that swap the time slider and time displays for a Live button, and plays through the browser’s native `<audio>`. See [Presets](https://videojs.org/docs/framework/html/guides/presets) for how presets fit together and [Live streams](https://videojs.org/docs/framework/html/guides/live-streams) for playing a live source.

## Import

```ts
import '@videojs/html/live-audio/player';
import '@videojs/html/live-audio/skin';
```

Import `@videojs/html/live-audio/neutral-skin` instead for the neutral skin. Or load one [CDN](https://videojs.org/docs/framework/html/guides/cdn) bundle that registers the player and a skin together:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/live-audio.js"></script>
```

`live-audio-neutral.js` registers the neutral skin instead, and `live-audio-player.js` registers `<live-audio-player>` alone.

## Usage

Live streams are usually HLS, so this example plays through an HLS media component instead of the preset’s native audio.

**index.html**

```html
<script type="module">
  import '@videojs/html/live-audio/player';
  import '@videojs/html/live-audio/skin';
  import '@videojs/html/media/hls-audio';
</script>

<live-audio-player>
  <live-audio-skin>
    <hls-audio src="https://example.com/live.m3u8"></hls-audio>
  </live-audio-skin>
</live-audio-player>
```

## Player

`@videojs/html/live-audio/player` registers `<live-audio-player>`, whose class is `LiveAudioPlayerElement`. It is a [player](https://videojs.org/docs/framework/html/reference/components/player) element created by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) with `liveAudioFeatures`. It owns the player store but no layout. Put a skin or a [`<media-container>`](https://videojs.org/docs/framework/html/reference/components/player-container) inside it.

| Attribute | Property | Description |
| --- | --- | --- |
| `content-title` | `contentTitle` | The title to display. Takes precedence over the title the media reports. |
| `poster` | `poster` | The poster to display. Takes precedence over the poster the media reports. |
| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |

`content-title` and `poster` come from the [metadata feature](https://videojs.org/docs/framework/html/reference/api/feature-metadata#player-inputs). The element’s read-only `store` property returns its player store.

The preset root also exports a `PlayerController` bound to the live audio player’s store. Use it from any custom element inside `<live-audio-player>`; see [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller).

## Feature bundle

`liveAudioFeatures` is the array of [features](https://videojs.org/docs/framework/html/guides/features) the player is configured with. It is the [audio preset’s](https://videojs.org/docs/framework/html/reference/api/preset-audio#feature-bundle) `audioFeatures` without playback rate, plus the [live feature](https://videojs.org/docs/framework/html/reference/api/feature-live):

| Feature | Description |
| --- | --- |
| [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback) | Play/pause state and actions for the player store |
| [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume) | Volume level and mute state for the player store |
| [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time) | Playback position and duration state for the player store |
| [`sourceFeature`](https://videojs.org/docs/framework/html/reference/api/feature-source) | Media source state and actions for the player store |
| [`bufferFeature`](https://videojs.org/docs/framework/html/reference/api/feature-buffer) | Buffered and seekable time range state for the player store |
| [`errorFeature`](https://videojs.org/docs/framework/html/reference/api/feature-error) | Media error state and actions for the player store |
| [`liveFeature`](https://videojs.org/docs/framework/html/reference/api/feature-live) | Live edge state for the player store |
| [`metadataFeature`](https://videojs.org/docs/framework/html/reference/api/feature-metadata) | Resolved title and poster values for the player store |

Its type, `LiveAudioFeatures`, is the tuple of those features in order. Import it from the package root:

```ts
import type { LiveAudioFeatures } from '@videojs/html';
```

To add or remove a feature, pass your own array to `createPlayer`. The skins expect the features they render controls for.

```ts
import { createPlayer, streamTypeFeature } from '@videojs/html';
import { liveAudioFeatures } from '@videojs/html/live-audio';

const { PlayerElement } = createPlayer({
  features: [...liveAudioFeatures, streamTypeFeature],
});

customElements.define('my-live-audio-player', PlayerElement);
```

## Skins

- [LiveAudioSkin](https://videojs.org/docs/framework/html/reference/components/live-audio-skin) — the default skin, which swaps the time controls for a Live button.
- [NeutralLiveAudioSkin](https://videojs.org/docs/framework/html/reference/components/live-audio-neutral-skin) — the visually lighter variant, closer to a classic control bar.

## Media

The preset plays through a native [`<audio>`](https://videojs.org/docs/framework/html/reference/components/audio), so it registers no media component of its own. Most browsers need a streaming [media component](https://videojs.org/docs/framework/html/guides/media-sources) to play a live source, such as [`<hls-audio>`](https://videojs.org/docs/framework/html/reference/components/hls-audio) for HLS.

## Exports

The preset root, `@videojs/html/live-audio`, has no side effects. Importing it never registers an element:

| Export | Description |
| --- | --- |
| `LiveAudioPlayerElement` | The [player](https://videojs.org/docs/framework/html/reference/api/preset-live-audio#player) element class. |
| `PlayerController` | The player controller, bound to the live audio player’s store. |
| `liveAudioFeatures` | The [feature bundle](https://videojs.org/docs/framework/html/reference/api/preset-live-audio#feature-bundle). |
| `LiveAudioSkinElement` | The default [skin](https://videojs.org/docs/framework/html/reference/api/preset-live-audio#skins) element class. |
| `NeutralLiveAudioSkinElement` | The neutral [skin](https://videojs.org/docs/framework/html/reference/api/preset-live-audio#skins) element class. |

Registration entry points are side-effect-only:

| Entry point | Registers |
| --- | --- |
| `@videojs/html/live-audio/player` | `<live-audio-player>` |
| `@videojs/html/live-audio/skin` | `<live-audio-skin>`, `<media-container>`, and the UI elements the skin composes |
| `@videojs/html/live-audio/neutral-skin` | `<live-audio-neutral-skin>`, `<media-container>`, and the UI elements the neutral skin composes |
| `@videojs/html/live-audio/ui` | `<media-container>` and the UI elements of the default skin, without the skin, for a layout you write yourself |
| `@videojs/html/live-audio/neutral-ui` | `<media-container>` and the UI elements of the neutral skin, without the skin |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/preset-background -->

# Background preset

The background video preset — a player, feature bundle, skin, and media for ambient video with no controls

`@videojs/html/background` is the preset for ambient background video with no user controls. It bundles the `<background-video-player>` element, the `backgroundFeatures` bundle it is configured with, one chrome-less skin, and the `<background-video>` media component, which autoplays, mutes, and loops. See [Presets](https://videojs.org/docs/framework/html/guides/presets) for how presets fit together and [Background video](https://videojs.org/docs/framework/html/guides/background-video) for building one.

## Import

```ts
import '@videojs/html/background/player';
import '@videojs/html/background/skin';
import '@videojs/html/background/video';
```

Or load the [CDN](https://videojs.org/docs/framework/html/guides/cdn) bundle that registers all three:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/background.js"></script>
```

Unlike the other presets, the background preset has one bundle and no player-only bundle.

## Usage

**index.html**

```html
<script type="module">
  import '@videojs/html/background/player';
  import '@videojs/html/background/skin';
  import '@videojs/html/background/video';
</script>

<background-video-player>
  <background-video-skin>
    <background-video src="hero.mp4"></background-video>
  </background-video-skin>
</background-video-player>
```

## Player

`@videojs/html/background/player` registers `<background-video-player>`, whose class is `BackgroundVideoPlayerElement`. It is a [player](https://videojs.org/docs/framework/html/reference/components/player) element created by [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) with `backgroundFeatures`. It owns the player store but no layout. Put the skin or a [`<media-container>`](https://videojs.org/docs/framework/html/reference/components/player-container) inside it.

| Attribute | Property | Description |
| --- | --- | --- |
| `keep-alive` | — | Keeps the player and its store alive when the element leaves the DOM. Call `destroy()` when you’re done with it. |

The bundle has no feature that takes player inputs, so the element has no player-input attributes such as `content-title` or `poster`; `keep-alive` is the only attribute it reads. Its read-only `store` property returns its player store.

The preset root also exports a `PlayerController` bound to the background player’s store. Use it from any custom element inside `<background-video-player>`; see [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller).

## Feature bundle

`backgroundFeatures` is the array of [features](https://videojs.org/docs/framework/html/guides/features) the player is configured with. The background media component handles autoplay, muting, and looping on its own:

`backgroundFeatures` is currently empty, so the player's store holds no feature state or actions.

Its type, `BackgroundFeatures`, is the matching empty tuple. Import it from the package root:

```ts
import type { BackgroundFeatures } from '@videojs/html';
```

To add a feature, pass your own array to `createPlayer`. For example, add playback to drive a play button over the background video:

```ts
import { createPlayer, playbackFeature } from '@videojs/html';
import { backgroundFeatures } from '@videojs/html/background';

const { PlayerElement } = createPlayer({
  features: [...backgroundFeatures, playbackFeature],
});

customElements.define('my-background-player', PlayerElement);
```

## Skins

- [BackgroundVideoSkin](https://videojs.org/docs/framework/html/reference/components/background-video-skin) — the only skin, a chrome-less surface that sizes the video and renders no controls.

## Media

`@videojs/html/background/video` registers [`<background-video>`](https://videojs.org/docs/framework/html/reference/components/background-video), which renders a `<video>` inside shadow DOM that is muted, looped, and autoplaying by default. It is the same registration as `@videojs/html/media/background-video`. For HLS or Mux sources, use [`<hls-background-video>`](https://videojs.org/docs/framework/html/reference/components/hls-background-video) or [`<mux-background-video>`](https://videojs.org/docs/framework/html/reference/components/mux-background-video) instead.

## Exports

The preset root, `@videojs/html/background`, has no side effects. Importing it never registers an element:

| Export | Description |
| --- | --- |
| `BackgroundVideoPlayerElement` | The [player](https://videojs.org/docs/framework/html/reference/api/preset-background#player) element class. |
| `PlayerController` | The player controller, bound to the background player’s store. |
| `backgroundFeatures` | The [feature bundle](https://videojs.org/docs/framework/html/reference/api/preset-background#feature-bundle). |
| `BackgroundVideoSkinElement` | The [skin](https://videojs.org/docs/framework/html/reference/api/preset-background#skins) element class. |

Registration entry points are side-effect-only:

| Entry point | Registers |
| --- | --- |
| `@videojs/html/background/player` | `<background-video-player>` |
| `@videojs/html/background/skin` | `<background-video-skin>` and `<media-container>` |
| `@videojs/html/background/video` | `<background-video>` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/player-store -->

# Player store

Every state field and action on the player store, grouped by the feature that adds it

The player store combines the state and actions of every feature the player includes. A field or action exists only when its feature is included. This page lists the whole store; each feature’s reference page adds its selector and examples.

## Access

The player element exposes the store as `store`. State fields and actions are properties of the store, and `store.subscribe()` reports changes. `store.state` is a frozen snapshot of the current state, which is the object selectors take. Inside a custom element, [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) subscribes to a selection and updates its host.

```ts
const player = document.querySelector('video-player');

player.store.paused;
player.store.play();

const unsubscribe = player.store.subscribe(() => {
  console.log(player.store.currentTime);
});
```

Each feature also exports a selector, such as `selectPlayback`, that returns its state and actions, or `undefined` when the player doesn’t include the feature. See [`createSelector`](https://videojs.org/docs/framework/html/reference/api/create-selector) to write your own.

## State and actions

Each feature links to the same entry on its reference page.

| Name | Type | Feature | Description |
| --- | --- | --- | --- |
| `paused` | `boolean` | [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback#playback-state-paused) | Whether playback is paused. |
| `ended` | `boolean` | [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback#playback-state-ended) | Whether playback has reached the end. |
| `started` | `boolean` | [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback#playback-state-started) | Whether playback has started (played or seeked). |
| `waiting` | `boolean` | [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback#playback-state-waiting) | Whether playback is stalled waiting for data. |
| `play` | `() => Promise<void>` | [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback#playback-action-play) | Start playback. Updates `paused` immediately when the media starts. |
| `pause` | `() => void` | [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback#playback-action-pause) | Pause playback. Updates `paused` immediately. |
| `currentTime` | `number` | [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time#time-state-currentTime) | Current playback position in seconds. |
| `duration` | `number` | [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time#time-state-duration) | Total duration in seconds (0 if unknown). |
| `seeking` | `boolean` | [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time#time-state-seeking) | Whether a seek operation is in progress. |
| `seek` | `(time: number) => Promise<number>` | [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time#time-action-seek) | Seek to a time in seconds. Returns the actual position after seek. |
| `volume` | `number` | [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume#volume-state-volume) | Volume level from 0 (silent) to 1 (max). |
| `muted` | `boolean` | [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume#volume-state-muted) | Whether audio is muted. |
| `volumeAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume#volume-state-volumeAvailability) | Whether volume can be programmatically set on this platform. |
| `mutedAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume#volume-state-mutedAvailability) | Whether the media can be muted. Separate from `volumeAvailability` because the two come apart: an embed can take a mute command while offering no way to set a level, and iOS Safari refuses a volume write on media that mutes perfectly well. |
| `setVolume` | `(volume: number) => number` | [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume#volume-action-setVolume) | Set volume (clamped 0-1). Returns the clamped value. |
| `setMuted` | `(muted: boolean) => boolean` | [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume#volume-action-setMuted) | Set the muted state, updating the store immediately. Unmuting at volume 0 restores volume to 0.25. Returns the new muted value. |
| `isFullscreen` | `boolean` | [`fullscreenFeature`](https://videojs.org/docs/framework/html/reference/api/feature-fullscreen#fullscreen-state-isFullscreen) | Whether fullscreen mode is currently active. |
| `fullscreenAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`fullscreenFeature`](https://videojs.org/docs/framework/html/reference/api/feature-fullscreen#fullscreen-state-fullscreenAvailability) | Whether fullscreen can be requested on this platform. |
| `requestFullscreen` | `() => Promise<void>` | [`fullscreenFeature`](https://videojs.org/docs/framework/html/reference/api/feature-fullscreen#fullscreen-action-requestFullscreen) | Enter fullscreen mode. Tries container first, falls back to media component. |
| `exitFullscreen` | `() => Promise<void>` | [`fullscreenFeature`](https://videojs.org/docs/framework/html/reference/api/feature-fullscreen#fullscreen-action-exitFullscreen) | Exit fullscreen mode. |
| `userActive` | `boolean` | [`controlsFeature`](https://videojs.org/docs/framework/html/reference/api/feature-controls#controls-state-userActive) | Whether the user has recently interacted with the player. |
| `controlsVisible` | `boolean` | [`controlsFeature`](https://videojs.org/docs/framework/html/reference/api/feature-controls#controls-state-controlsVisible) | Whether controls should be visible. |
| `requestControlsLock` | `() => (() => void)` | [`controlsFeature`](https://videojs.org/docs/framework/html/reference/api/feature-controls#controls-action-requestControlsLock) | Keep controls visible during a sustained interaction. The returned function releases the lock. Multiple concurrent locks are supported and each release function is idempotent. |
| `toggleControls` | `(forceShow?: boolean) => boolean` | [`controlsFeature`](https://videojs.org/docs/framework/html/reference/api/feature-controls#controls-action-toggleControls) | Toggle controls visibility, or force it with `forceShow`. Returns the new `controlsVisible` value. |
| `buffered` | `[number, number][]` | [`bufferFeature`](https://videojs.org/docs/framework/html/reference/api/feature-buffer#buffer-state-buffered) | Buffered time ranges as \[start, end\] tuples. |
| `seekable` | `[number, number][]` | [`bufferFeature`](https://videojs.org/docs/framework/html/reference/api/feature-buffer#buffer-state-seekable) | Seekable time ranges as \[start, end\] tuples. |
| `textTrackList` | `MediaTextTrack[]` | [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks#textTrack-state-textTrackList) | All text tracks available on the media component. |
| `subtitlesShowing` | `boolean` | [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks#textTrack-state-subtitlesShowing) | Whether a captions/subtitles track is showing. |
| `chaptersCues` | `MediaTextCue[]` | [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks#textTrack-state-chaptersCues) | Cues from the first `kind="chapters"` track, with cue ends clamped to a finite media duration. |
| `thumbnailsTrack` | `{ cues: MediaTextCue[]; src: string \| null; crossOrigin: 'anonymous' \| 'use-credentials' \| null } \| null` | [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks#textTrack-state-thumbnailsTrack) | The first thumbnails track, or `null` when there is none. |
| `toggleSubtitles` | `(forceShow?: boolean) => boolean` | [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks#textTrack-action-toggleSubtitles) | Toggle captions/subtitles visibility. Showing enables one caption/subtitle track. A track already showing stays selected. Otherwise, selection prefers the last track shown, then a track matching the browser language, then the first available track. Returns whether a track is showing. |
| `selectSubtitlesTrack` | `(id: string \| null) => void` | [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks#textTrack-action-selectSubtitlesTrack) | Show the captions/subtitles track with `id`, or turn captions/subtitles off with `null`. |
| `playbackRates` | `readonly number[]` | [`playbackRateFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback-rate#playbackRate-state-playbackRates) | Available playback rates. |
| `playbackRate` | `number` | [`playbackRateFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback-rate#playbackRate-state-playbackRate) | Current playback rate. |
| `setPlaybackRate` | `(rate: number) => void` | [`playbackRateFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback-rate#playbackRate-action-setPlaybackRate) | Set the playback rate. |
| `isPictureInPicture` | `boolean` | [`pipFeature`](https://videojs.org/docs/framework/html/reference/api/feature-pip#pip-state-isPictureInPicture) | Whether picture-in-picture mode is currently active. |
| `pictureInPictureAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`pipFeature`](https://videojs.org/docs/framework/html/reference/api/feature-pip#pip-state-pictureInPictureAvailability) | Whether picture-in-picture can be requested on this platform. |
| `requestPictureInPicture` | `() => Promise<void>` | [`pipFeature`](https://videojs.org/docs/framework/html/reference/api/feature-pip#pip-action-requestPictureInPicture) | Enter picture-in-picture mode, exiting fullscreen first. Rejects before metadata is loaded. |
| `exitPictureInPicture` | `() => Promise<void>` | [`pipFeature`](https://videojs.org/docs/framework/html/reference/api/feature-pip#pip-action-exitPictureInPicture) | Exit picture-in-picture mode. |
| `error` | `{ code: number; message: string } \| null` | [`errorFeature`](https://videojs.org/docs/framework/html/reference/api/feature-error#error-state-error) | The current media error, or null if none. |
| `dismissError` | `() => void` | [`errorFeature`](https://videojs.org/docs/framework/html/reference/api/feature-error#error-action-dismissError) | Dismiss the current error by clearing it. |
| `title` | `string` | [`metadataFeature`](https://videojs.org/docs/framework/html/reference/api/feature-metadata#metadata-state-title) | The resolved content title. Set it through the player, not through the store. |
| `poster` | `string` | [`metadataFeature`](https://videojs.org/docs/framework/html/reference/api/feature-metadata#metadata-state-poster) | The resolved poster URL, independent of the media component's own `poster`. Set it through the player, not through the store. |
| `currentSrc` | `string` | [`sourceFeature`](https://videojs.org/docs/framework/html/reference/api/feature-source#source-state-currentSrc) | Current media source URL (empty string if none). |
| `canPlay` | `boolean` | [`sourceFeature`](https://videojs.org/docs/framework/html/reference/api/feature-source#source-state-canPlay) | Whether enough data is loaded to begin playback. |
| `videoRenditionList` | `MediaVideoRendition[]` | [`qualityFeature`](https://videojs.org/docs/framework/html/reference/api/feature-quality#quality-state-videoRenditionList) | Video renditions available for manual quality selection. |
| `activeVideoRendition` | `{ id: string; width?: number; height?: number; bitrate?: number; frameRate?: number; codec?: string; selected: boolean } \| null` | [`qualityFeature`](https://videojs.org/docs/framework/html/reference/api/feature-quality#quality-state-activeVideoRendition) | Video rendition currently playing, including when automatic ABR is selected. |
| `selectVideoRendition` | `(id: string) => void` | [`qualityFeature`](https://videojs.org/docs/framework/html/reference/api/feature-quality#quality-action-selectVideoRendition) | Select a video rendition by `id`, or automatic ABR with `"auto"`. |
| `audioTrackList` | `MediaAudioTrack[]` | [`audioTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-audio-track#audioTrack-state-audioTrackList) | Audio tracks available for manual track selection. |
| `selectAudioTrack` | `(id: string) => void` | [`audioTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-audio-track#audioTrack-action-selectAudioTrack) | Select an audio track by `id`. |
| `remotePlaybackState` | `'disconnected' \| 'connecting' \| 'connected'` | [`remotePlaybackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-remote-playback#remotePlayback-state-remotePlaybackState) | Current remote playback connection state. |
| `remotePlaybackAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | [`remotePlaybackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-remote-playback#remotePlayback-state-remotePlaybackAvailability) | Whether remote playback can be requested on this platform. |
| `promptRemotePlayback` | `() => Promise<void>` | [`remotePlaybackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-remote-playback#remotePlayback-action-promptRemotePlayback) | Prompt the user to pick a remote playback device. Exits fullscreen first when connecting. |
| `liveEdgeStart` | `number` | [`liveFeature`](https://videojs.org/docs/framework/html/reference/api/feature-live#live-state-liveEdgeStart) | Playback time where the live edge begins. Playback is live when `currentTime >= liveEdgeStart`. `NaN` when the stream is not live or the value is unknown. |
| `targetLiveWindow` | `number` | [`liveFeature`](https://videojs.org/docs/framework/html/reference/api/feature-live#live-state-targetLiveWindow) | Describes the kind of live window available. This value is not a duration. `0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown. |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | [`streamTypeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-stream-type#streamType-state-streamType) | Current stream delivery type. Components use this to show live-specific UI (for example, a live indicator or a "jump to live edge" button) or hide the time display. |
| `orientationLockType` | `'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary'` | [`orientationLockFeature`](https://videojs.org/docs/framework/html/reference/api/feature-orientation-lock#orientationLock-state-orientationLockType) | Screen orientation type locked while fullscreen is active. |
| `setOrientationLockType` | `(value: 'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary' \| null \| undefined) => void` | [`orientationLockFeature`](https://videojs.org/docs/framework/html/reference/api/feature-orientation-lock#orientationLock-action-setOrientationLockType) | Sets the locked orientation type. A missing value, including an empty one, restores the default. |

## Features by preset

Each column is a preset's feature bundle. A feature no bundle includes is opt-in: add it to your [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) features yourself.

| Feature | `videoFeatures` | `audioFeatures` | `liveAudioFeatures` | `liveVideoFeatures` |
| --- | --- | --- | --- | --- |
| [`playbackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback) | ✓ | ✓ | ✓ | ✓ |
| [`timeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-time) | ✓ | ✓ | ✓ | ✓ |
| [`volumeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-volume) | ✓ | ✓ | ✓ | ✓ |
| [`fullscreenFeature`](https://videojs.org/docs/framework/html/reference/api/feature-fullscreen) | ✓ | – | – | ✓ |
| [`controlsFeature`](https://videojs.org/docs/framework/html/reference/api/feature-controls) | ✓ | – | – | ✓ |
| [`bufferFeature`](https://videojs.org/docs/framework/html/reference/api/feature-buffer) | ✓ | ✓ | ✓ | ✓ |
| [`textTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-text-tracks) | ✓ | – | – | ✓ |
| [`playbackRateFeature`](https://videojs.org/docs/framework/html/reference/api/feature-playback-rate) | ✓ | ✓ | – | – |
| [`pipFeature`](https://videojs.org/docs/framework/html/reference/api/feature-pip) | ✓ | – | – | ✓ |
| [`errorFeature`](https://videojs.org/docs/framework/html/reference/api/feature-error) | ✓ | ✓ | ✓ | ✓ |
| [`metadataFeature`](https://videojs.org/docs/framework/html/reference/api/feature-metadata) | ✓ | ✓ | ✓ | ✓ |
| [`sourceFeature`](https://videojs.org/docs/framework/html/reference/api/feature-source) | ✓ | ✓ | ✓ | ✓ |
| [`qualityFeature`](https://videojs.org/docs/framework/html/reference/api/feature-quality) | ✓ | – | – | – |
| [`audioTrackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-audio-track) | ✓ | – | – | – |
| [`remotePlaybackFeature`](https://videojs.org/docs/framework/html/reference/api/feature-remote-playback) | ✓ | – | – | ✓ |
| [`liveFeature`](https://videojs.org/docs/framework/html/reference/api/feature-live) | – | – | ✓ | ✓ |
| [`streamTypeFeature`](https://videojs.org/docs/framework/html/reference/api/feature-stream-type) | – | – | – | – |
| [`orientationLockFeature`](https://videojs.org/docs/framework/html/reference/api/feature-orientation-lock) | – | – | – | – |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/create-selector -->

# createSelector

Create a type-safe selector for a store slice's state

## Import

```ts
import { createSelector } from "@videojs/store";
```

`createSelector` is also re-exported from `@videojs/react` and `@videojs/html`.

`createSelector` creates a type-safe selector function for a given slice. The returned selector extracts that slice’s state from the full store state, or returns `undefined` if the slice is not configured.

The built-in selectors ([`selectPlayback`](https://videojs.org/docs/framework/html/reference/api/feature-playback), [`selectBuffer`](https://videojs.org/docs/framework/html/reference/api/feature-buffer), etc.) are all created with `createSelector`. Use it to create selectors for custom slices.

**my-custom-selector.ts**

```ts
import { createSelector } from '@videojs/store';
import { myCustomSlice } from './my-custom-slice';

const selectCustom = createSelector(myCustomSlice);

// Use with usePlayer (React) or PlayerController (HTML)
const state = selectCustom(store.state);
```

Pass selectors to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) or [`StoreController`](https://videojs.org/docs/framework/html/reference/api/store-controller) for reactive subscriptions.

## API Reference

`createSelector<S extends AnySlice>(slice): Selector<object, InferSliceState<S> | undefined>`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `slice` (required) | `S` | — | The slice to create a selector for. |

### Return Value

| Type |
| --- |
| `{ (state: object): (S extends Slice<any, infer State, infer Derived> ? Simplify<PublicSourceState<State> & Derived> : never) \| undefined; displayName?: string }` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/store-controller -->

# StoreController

Reactive controller for subscribing to store state in HTML custom elements

## Import

```ts
import { StoreController } from "@videojs/store/html";
```

`StoreController` is a reactive controller for accessing store state and actions in custom elements. It accepts a store instance or a context, resolving the store automatically.

**Without selector** – returns the store instance directly. Does NOT subscribe to changes. Use this to access store actions.

```ts
class VolumeControl extends HTMLElement {
  #store = new StoreController(this, storeSource);

  handleClick() {
    this.#store.value.setVolume(0.5);
  }
}
```

**With selector** – returns the selected value and subscribes to changes. Triggers a host update when the selected value changes (using shallow equality).

```ts
class PlayButton extends HTMLElement {
  #playback = new StoreController(this, storeSource, selectPlayback);

  render() {
    const playback = this.#playback.value;
    // Re-renders when playback state changes
  }
}
```

### StoreController vs PlayerController vs SnapshotController

| | `StoreController` | [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) | [`SnapshotController`](https://videojs.org/docs/framework/html/reference/api/snapshot-controller) |
| --- | --- | --- | --- |
| **Input** | Any store or context | Player store context | `State` container |
| **Typed to** | Generic store | Player features | Raw state |
| **Use case** | General-purpose store access | Player UI elements | Low-level state subscription |

[`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) is a typed wrapper around `StoreController` scoped to the player store. For player UI, prefer `PlayerController`. Use `StoreController` when working with a custom store outside the player system.

When you pass a selector, `StoreController` internally creates a [`SnapshotController`](https://videojs.org/docs/framework/html/reference/api/snapshot-controller) on the store’s `$state` container. Without a selector, no subscription is created – you get the store instance for imperative access to actions.

## API Reference

### Without Selector

`new StoreController<Store extends AnyStore, Result = Store>(host, source)`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | The host element that owns this controller. |
| `source` (required) | `Store \| Context<unknown, Store>` | — | Store instance or context to resolve the store from. |

#### Return Value

| Property | Type |
| --- | --- |
| `value` | `Result` |

### With Selector

`new StoreController<Store extends AnyStore, Result = Store>(host, source, selector)`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | The host element that owns this controller. |
| `source` (required) | `Store \| Context<unknown, Store>` | — | Store instance or context to resolve the store from. |
| `selector` (required) | `{ (state: Store['state']): Result; displayName?: string }` | — | Derives a value from the store state. |

#### Return Value

| Property | Type |
| --- | --- |
| `value` | `Result` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/snapshot-controller -->

# SnapshotController

Reactive controller for subscribing to a State container in HTML custom elements

## Import

```ts
import { SnapshotController } from "@videojs/store/html";
```

`SnapshotController` subscribes to a `State` container and triggers host updates when state changes. It has two overloads:

**Full state** – returns the entire state object. Re-renders on any state change.

```ts
class Display extends HTMLElement {
  #state = new SnapshotController(this, sliderState);

  render() {
    const value = this.#state.value;
    // Full state object
  }
}
```

**With selector** – returns a derived value from state. Re-renders only when the selected value changes (using shallow equality).

```ts
class SliderValue extends HTMLElement {
  #value = new SnapshotController(this, sliderState, (s) => s.value);

  render() {
    return this.#value.value; // Only the selected slice
  }
}
```

Use `.track(state)` to switch to a different `State` container at runtime.

### SnapshotController vs StoreController

Both are reactive controllers, but they operate at different levels:

| | `SnapshotController` | [`StoreController`](https://videojs.org/docs/framework/html/reference/api/store-controller) |
| --- | --- | --- |
| **Input** | `State` container | Store instance or context |
| **Subscribes** | Always | Only with a selector |
| **Use case** | Subscribe to raw state changes | Access store actions and optionally subscribe |

`SnapshotController` is lower-level. It works with `State` containers directly – the reactive primitives that back a store. Use it when building custom controllers or working outside the player store system.

[`StoreController`](https://videojs.org/docs/framework/html/reference/api/store-controller) is higher-level. It resolves a store from a context or direct reference and internally creates a `SnapshotController` when you pass a selector. Use it for player UI elements.

### Lifecycle

`SnapshotController` subscribes on `hostConnected()` and unsubscribes on `hostDisconnected()`. The React equivalent is [`useSnapshot`](https://videojs.org/docs/framework/react/reference/api/use-snapshot).

## API Reference

### Without Selector

`new SnapshotController<T extends object, R = T>(host, state)`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> }` | — | The host element that owns this controller. |
| `state` (required) | `{ current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }` | — | The State container to subscribe to. |

#### Return Value

| Property | Type | Description |
| --- | --- | --- |
| `value` | `R` | |
| `track` | `((state: { current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }) => void)` | Switch to tracking a different state container. |

### With Selector

`new SnapshotController<T extends object, R = T>(host, state, selector)`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> }` | — | The host element that owns this controller. |
| `state` (required) | `{ current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }` | — | The State container to subscribe to. |
| `selector` (required) | `{ (state: T): R; displayName?: string }` | — | Derives a value from the state. |

#### Return Value

| Property | Type | Description |
| --- | --- | --- |
| `value` | `R` | |
| `track` | `((state: { current: Readonly<T>; subscribe(callback: (() => void), options?: SubscribeOptions): (() => void) }) => void)` | Switch to tracking a different state container. |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/subscription-controller -->

# SubscriptionController

Reactive controller that resolves a store and manages a derived subscription

## Import

```ts
import { SubscriptionController } from "@videojs/store/html";
```

## Usage

Provide a store or store context plus functions that read the current value and subscribe to changes.

```ts
class QueueController {
  readonly #tasks;

  constructor(host, storeSource) {
    this.#tasks = new SubscriptionController(host, storeSource, {
      getValue: (store) => store.queue.tasks,
      subscribe: (store, onChange) => store.queue.subscribe(onChange),
    });
  }

  get value() {
    return this.#tasks.value;
  }
}
```

The controller requests a host update when the subscription changes and unsubscribes when the host disconnects. Reading `value` throws until a store is available.

## API Reference

`new SubscriptionController<Store extends AnyStore, Value>(host, source, config)`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | The host element that owns this controller. |
| `source` (required) | `Store \| Context<unknown, Store>` | — | Store instance or context to resolve the store from. |
| `config` (required) | `{ getValue: ((store: Store) => Value); subscribe: ((store: Store, onChange: (() => void)) => (() => void)) }` | — | Subscription and value extraction configuration. |

### Return Value

| Property | Type |
| --- | --- |
| `value` | `Value` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-buffer -->

# Buffer

Buffered and seekable time range state for the player store

Tracks buffered and seekable time ranges. Each range is a `[start, end]` pair rather than a browser `TimeRanges` object.

During live playback, `seekable` tells you which times remain available. The first start is the oldest available time, and the last end is the newest. Both values can move forward as a sliding live stream drops older video and adds new video. See [live state](https://videojs.org/docs/framework/html/reference/api/feature-live) for the live-edge values.

## Import

```ts
import { bufferFeature } from '@videojs/html';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `buffered` | `[number, number][]` | Buffered time ranges as \[start, end\] tuples. |
| `seekable` | `[number, number][]` | Seekable time ranges as \[start, end\] tuples. |

### Selector

Pass `selectBuffer` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to buffer state. Returns `undefined` if the buffer feature is not configured.

**buffer-bar.ts**

```ts
import { createPlayer, UIElement, selectBuffer } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class BufferBar extends UIElement {
  readonly #buffer = new PlayerController(this, selectBuffer);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-controls -->

# Controls

User activity and controls visibility state for the player store

Tracks user activity for showing and hiding controls, with actions to toggle visibility and keep controls shown.

## Import

```ts
import { controlsFeature } from '@videojs/html';
```

The `liveVideoFeatures` and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `userActive` | `boolean` | Whether the user has recently interacted with the player. |
| `controlsVisible` | `boolean` | Whether controls should be visible. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `requestControlsLock` | `() => (() => void)` | Keep controls visible during a sustained interaction. The returned function releases the lock. Multiple concurrent locks are supported and each release function is idempotent. |
| `toggleControls` | `(forceShow?: boolean) => boolean` | Toggle controls visibility, or force it with `forceShow`. Returns the new `controlsVisible` value. |

### Selector

Pass `selectControls` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to controls state. Returns `undefined` if the controls feature is not configured.

**controls-overlay.ts**

```ts
import { createPlayer, UIElement, selectControls } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class ControlsOverlay extends UIElement {
  readonly #controls = new PlayerController(this, selectControls);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-error -->

# Error

Media error state and actions for the player store

Tracks media errors.

## Import

```ts
import { errorFeature } from '@videojs/html';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `error` | `{ code: number; message: string } \| null` | The current media error, or null if none. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `dismissError` | `() => void` | Dismiss the current error by clearing it. |

### Selector

Pass `selectError` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to error state. Returns `undefined` if the error feature is not configured.

**error-display.ts**

```ts
import { createPlayer, UIElement, selectError } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class ErrorDisplay extends UIElement {
  readonly #error = new PlayerController(this, selectError);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-fullscreen -->

# Fullscreen

Fullscreen state and actions for the player store

Controls fullscreen mode. Tries the container element first, falls back to the media component.

## Import

```ts
import { fullscreenFeature } from '@videojs/html';
```

The `liveVideoFeatures` and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `isFullscreen` | `boolean` | Whether fullscreen mode is currently active. |
| `fullscreenAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether fullscreen can be requested on this platform. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `requestFullscreen` | `() => Promise<void>` | Enter fullscreen mode. Tries container first, falls back to media component. |
| `exitFullscreen` | `() => Promise<void>` | Exit fullscreen mode. |

### Selector

Pass `selectFullscreen` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to fullscreen state. Returns `undefined` if the fullscreen feature is not configured.

**fullscreen-button.ts**

```ts
import { createPlayer, UIElement, selectFullscreen } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class FullscreenButton extends UIElement {
  readonly #fullscreen = new PlayerController(this, selectFullscreen);
}
```

### Screen orientation

Add [`features.orientationLock`](https://videojs.org/docs/framework/html/reference/api/feature-orientation-lock) to lock screen orientation while fullscreen is active. Unsupported browsers and rejected lock requests are ignored, so iOS Safari continues to use its normal fullscreen behavior.

The feature locks to `landscape` unless the provider sets another Screen Orientation API type.

```html
<my-player orientation-lock-type="portrait">
  <video src="/video.mp4"></video>
</my-player>
```

See [Orientation lock](https://videojs.org/docs/framework/html/reference/api/feature-orientation-lock) for the player setup.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-live -->

# Live

Live edge state for the player store

Tracks when playback is at the live edge and what kind of live window the stream provides.

- `liveEdgeStart` is the playback time where the live edge begins. Playback counts as live when `currentTime` reaches this value.
- `targetLiveWindow` describes the kind of live window. Despite its name, it does not report a number of seconds: `0` means a sliding live window, `Infinity` means a live event with playback history, and `NaN` means on-demand or not known yet.

Both values are `NaN` when the media does not provide live-edge information.

Use the [buffer feature](https://videojs.org/docs/framework/html/reference/api/feature-buffer) to find the times a viewer can seek to. Its `seekable` value contains `[start, end]` pairs. On a sliding live stream, the oldest and newest available times both move forward.

The live presets do not include the [stream type feature](https://videojs.org/docs/framework/html/reference/api/feature-stream-type), so `selectStreamType` returns `undefined` unless you add it to a custom player.

The [time feature](https://videojs.org/docs/framework/html/reference/api/feature-time) reports the end of the available live video as `duration`, even when the browser reports `Infinity`. To check for live playback, use `!Number.isNaN(targetLiveWindow)` instead of checking `duration`.

## Import

```ts
import { liveFeature } from '@videojs/html';
```

The `liveAudioFeatures` and `liveVideoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `liveEdgeStart` | `number` | Playback time where the live edge begins. Playback is live when `currentTime >= liveEdgeStart`. `NaN` when the stream is not live or the value is unknown. |
| `targetLiveWindow` | `number` | Describes the kind of live window available. This value is not a duration. `0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown. |

### Selector

Pass `selectLive` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to live state. Returns `undefined` if the live feature is not configured.

**live-edge-button.ts**

```ts
import { createPlayer, UIElement, selectLive } from '@videojs/html';
import { liveVideoFeatures } from '@videojs/html/live-video';

const { PlayerController } = createPlayer({ features: liveVideoFeatures });

class LiveEdgeButton extends UIElement {
  readonly #live = new PlayerController(this, selectLive);
}
```

## Jump to the live edge

Use the packaged live button for the usual jump-to-live behavior. It combines the live, time, and buffer features, then seeks to the end of the last `seekable` range. It also manages its accessible label and disabled state.

**index.html**

```html
<script type="module">
  import '@videojs/html/ui/live-button';
</script>

<media-live-button class="station-live-button">On air</media-live-button>
```

Put the button in your custom controls and style it there. Do not calculate the destination from `duration` or set `currentTime` to `Infinity`.

If you need different behavior, you can combine the same public features yourself:

- Read `targetLiveWindow` from `selectLive` to check that the source is live.
- Read the newest available time from the last range returned by `selectBuffer`.
- Call the `seek()` action returned by `selectTime` with that time.

Read the same three selectors with [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller). Call `selectTime`’s `seek()` action with the last end time from `selectBuffer` when `selectLive` reports a live source.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-metadata -->

# Metadata

Resolved title and poster values for the player store

Resolves what is playing into two values your UI can render: `title` and `poster`.

`title` and `poster` each resolve independently through the same two tiers: the value you set, then the value the media reports. The first tier that holds a value wins; when neither does, the resolved value is an empty string. Because the tiers stay separate, clearing the value you set reveals the media’s, and a source that reports a poster but no title contributes to one while leaving the other empty.

An empty string counts as a value and stops the chain: `content-title=""` resolves the title to `''`. Remove the attribute to clear your value.

The metadata feature is included by the `videoFeatures`, `audioFeatures`, `liveVideoFeatures`, and `liveAudioFeatures` [presets](https://videojs.org/docs/framework/html/guides/presets); apps that build a custom preset can compose it in directly.

## Import

```ts
import { metadataFeature } from '@videojs/html';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### Configuration

Attributes and matching properties the player element accepts. They exist only while this feature is selected.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `contentTitle` (attribute `content-title`) | `undefined \| null \| string` | — | The title to display. Takes precedence over the title the media carries. |
| `poster` | `undefined \| null \| string` | — | The poster to display. Takes precedence over the poster the media carries. |

### State

| Property | Type | Description |
| --- | --- | --- |
| `title` | `string` | The resolved content title. Set it through the player, not through the store. |
| `poster` | `string` | The resolved poster URL, independent of the media component's own `poster`. Set it through the player, not through the store. |

### Selector

To just show the name of what is playing, drop in the [Title component](https://videojs.org/docs/framework/html/reference/components/title) — it reads this feature for you. Reach for the selector when building your own UI.

Pass `selectMetadata` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to metadata state. Returns `undefined` if the metadata feature is not configured.

**content-title.ts**

```ts
import { createPlayer, UIElement, selectMetadata } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class ContentTitle extends UIElement {
  readonly #metadata = new PlayerController(this, selectMetadata);
}
```

### Player inputs

The store publishes the resolved values and takes no writes. A player input is the only way to set one.

Every input is an attribute on [`<video-player>`](https://videojs.org/docs/framework/html/reference/components/player), each with a matching property. A player built without the metadata feature observes none of them.

`title` already means the tooltip on an HTML element, so the title input goes by `content-title` in markup, and by `contentTitle` as a property. The other inputs use their own names.

```html
<video-player content-title="The Pilot" poster="/episode-art.jpg">
  <media-container>
    <video src="episode.mp4"></video>
  </media-container>
</video-player>
```

Removing an attribute clears your value, so it falls through to what the media reports.

**title-controls.ts**

```ts
const player = document.querySelector('video-player');

player?.setAttribute('content-title', 'The Pilot');
player?.removeAttribute('content-title'); // falls back to the media
```

The flow between an attribute and its property runs one way: an attribute change writes the property, but setting the property leaves the attribute alone. Read the property for the current value.

### Media-reported values

The media tier comes from media that reports content data and announces changes to it, and it covers `title` and `poster`. A media reports only the keys it can vouch for, so either may be absent while the other arrives. A key that never arrives means that tier never contributes, and the resolved value is whatever you set. Detaching the media clears its values; the values you set survive and apply to the next source.

`poster` is the feature’s own resolved value, not the media component’s `poster` attribute. Setting one does not set the other.

A low-resolution stand-in to show while the poster loads is not part of this feature. The [poster](https://videojs.org/docs/framework/html/reference/components/poster) renders an `<img>` you control, so give it a `background-image` and that shows until the poster itself paints over it. [Add a poster and loading placeholder](https://videojs.org/docs/framework/html/guides/poster) walks through that technique for each framework.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-orientation-lock -->

# Orientation lock

Screen orientation locking while fullscreen is active

Locks screen orientation while fullscreen is active.

## Import

```ts
import { orientationLockFeature } from '@videojs/html';
```

No packaged [feature bundle](https://videojs.org/docs/framework/html/guides/presets) includes this feature — add it to your [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) features yourself.

## API Reference

### Configuration

Attributes and matching properties the player element accepts. They exist only while this feature is selected.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientationLockType` (attribute `orientation-lock-type`) | `undefined \| null \| 'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary'` | `'landscape'` | Screen orientation type to lock while fullscreen is active. |

### State

| Property | Type | Description |
| --- | --- | --- |
| `orientationLockType` | `'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary'` | Screen orientation type locked while fullscreen is active. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `setOrientationLockType` | `(value: 'any' \| 'landscape' \| 'landscape-primary' \| 'landscape-secondary' \| 'natural' \| 'portrait' \| 'portrait-primary' \| 'portrait-secondary' \| null \| undefined) => void` | Sets the locked orientation type. A missing value, including an empty one, restores the default. |

### Usage

Selecting the feature adds it to the player.

**player.ts**

```ts
import { createPlayer, features } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerElement: MyPlayer } = createPlayer({
  features: [...videoFeatures, features.orientationLock],
});

customElements.define('my-player', MyPlayer);
```

### Orientation type

The feature locks to `landscape` unless the provider sets another Screen Orientation API type. The value can change while the player is running; if the screen is already locked, it re-locks to the new type.

```html
<my-player orientation-lock-type="portrait">
  <video src="/video.mp4"></video>
</my-player>
```

The attribute only exists on a player that selected the feature. Setting it on an element built from `videoFeatures` alone does nothing.

Clearing the value restores `landscape`.

### Selector

Pass `selectOrientationLock` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to the lock state. Returns `undefined` if the orientation lock feature is not configured.

**orientation-toggle.ts**

```ts
import { createPlayer, features, UIElement, selectOrientationLock } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({
  features: [...videoFeatures, features.orientationLock],
});

class OrientationToggle extends UIElement {
  readonly #lock = new PlayerController(this, selectOrientationLock);
}
```

Unsupported browsers and rejected lock requests are ignored.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-pip -->

# Picture-in-picture

Picture-in-picture state and actions for the player store

Controls picture-in-picture mode.

## Import

```ts
import { pipFeature } from '@videojs/html';
```

The `liveVideoFeatures` and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `isPictureInPicture` | `boolean` | Whether picture-in-picture mode is currently active. |
| `pictureInPictureAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether picture-in-picture can be requested on this platform. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `requestPictureInPicture` | `() => Promise<void>` | Enter picture-in-picture mode, exiting fullscreen first. Rejects before metadata is loaded. |
| `exitPictureInPicture` | `() => Promise<void>` | Exit picture-in-picture mode. |

### Selector

Pass `selectPiP` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to picture-in-picture state. Returns `undefined` if the PiP feature is not configured.

**pip-button.ts**

```ts
import { createPlayer, UIElement, selectPiP } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class PiPButton extends UIElement {
  readonly #pip = new PlayerController(this, selectPiP);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-playback -->

# Playback

Play/pause state and actions for the player store

Controls play/pause state and tracks whether playback has started or is stalled.

## Import

```ts
import { playbackFeature } from '@videojs/html';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `paused` | `boolean` | Whether playback is paused. |
| `ended` | `boolean` | Whether playback has reached the end. |
| `started` | `boolean` | Whether playback has started (played or seeked). |
| `waiting` | `boolean` | Whether playback is stalled waiting for data. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `play` | `() => Promise<void>` | Start playback. Updates `paused` immediately when the media starts. |
| `pause` | `() => void` | Pause playback. Updates `paused` immediately. |

### Selector

Pass `selectPlayback` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to playback state. Returns `undefined` if the playback feature is not configured.

**play-button.ts**

```ts
import { createPlayer, UIElement, selectPlayback } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class PlayButton extends UIElement {
  readonly #playback = new PlayerController(this, selectPlayback);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-playback-rate -->

# Playback rate

Playback speed state and actions for the player store

Controls speed of playback.

## Import

```ts
import { playbackRateFeature } from '@videojs/html';
```

The `audioFeatures` and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `playbackRates` | `readonly number[]` | Available playback rates. |
| `playbackRate` | `number` | Current playback rate. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `setPlaybackRate` | `(rate: number) => void` | Set the playback rate. |

### Selector

Pass `selectPlaybackRate` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to playback rate state. Returns `undefined` if the playback rate feature is not configured.

**rate-display.ts**

```ts
import { createPlayer, UIElement, selectPlaybackRate } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class RateDisplay extends UIElement {
  readonly #rate = new PlayerController(this, selectPlaybackRate);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-quality -->

# Quality

Video rendition state and actions for the player store

Tracks video renditions and selects a manual rendition or automatic adaptive bitrate.

## Import

```ts
import { qualityFeature } from '@videojs/html';
```

The `videoFeatures` [feature bundle](https://videojs.org/docs/framework/html/guides/presets) includes this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `videoRenditionList` | `MediaVideoRendition[]` | Video renditions available for manual quality selection. |
| `activeVideoRendition` | `{ id: string; width?: number; height?: number; bitrate?: number; frameRate?: number; codec?: string; selected: boolean } \| null` | Video rendition currently playing, including when automatic ABR is selected. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `selectVideoRendition` | `(id: string) => void` | Select a video rendition by `id`, or automatic ABR with `"auto"`. |

### Selector

Pass `selectQuality` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to quality state. Returns `undefined` if the quality feature is not configured.

**quality-info.ts**

```ts
import { createPlayer, UIElement, selectQuality } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class QualityInfo extends UIElement {
  readonly #quality = new PlayerController(this, selectQuality);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-audio-track -->

# Audio track

Audio track state and actions for the player store

Tracks available audio tracks and selects the enabled track.

## Import

```ts
import { audioTrackFeature } from '@videojs/html';
```

The `videoFeatures` [feature bundle](https://videojs.org/docs/framework/html/guides/presets) includes this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `audioTrackList` | `MediaAudioTrack[]` | Audio tracks available for manual track selection. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `selectAudioTrack` | `(id: string) => void` | Select an audio track by `id`. |

### Selector

Pass `selectAudioTrack` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to audio track state. Returns `undefined` if the audio track feature is not configured.

**audio-track-info.ts**

```ts
import { createPlayer, UIElement, selectAudioTrack } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class AudioTrackInfo extends UIElement {
  readonly #audioTrack = new PlayerController(this, selectAudioTrack);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-remote-playback -->

# Remote Playback

Remote playback state and actions for the player store

Controls remote playback to devices like Chromecast (Chromium) and AirPlay (Safari). Exits fullscreen before initiating a remote playback session.

- [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/html/guides/casting)

## Import

```ts
import { remotePlaybackFeature } from '@videojs/html';
```

The `liveVideoFeatures` and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `remotePlaybackState` | `'disconnected' \| 'connecting' \| 'connected'` | Current remote playback connection state. |
| `remotePlaybackAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether remote playback can be requested on this platform. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `promptRemotePlayback` | `() => Promise<void>` | Prompt the user to pick a remote playback device. Exits fullscreen first when connecting. |

### Selector

Pass `selectRemotePlayback` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to remote playback state. Returns `undefined` if the remote playback feature is not configured.

**cast-button.ts**

```ts
import { createPlayer, UIElement, selectRemotePlayback } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class CastButton extends UIElement {
  readonly #remotePlayback = new PlayerController(this, selectRemotePlayback);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-source -->

# Source

Media source state and actions for the player store

Tracks the loaded media resource and how much of it is ready. To change the source, set `src` or `source` on the media component, which also carries type and engine configuration.

## Import

```ts
import { sourceFeature } from '@videojs/html';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `currentSrc` | `string` | Current media source URL (empty string if none). |
| `canPlay` | `boolean` | Whether enough data is loaded to begin playback. |

### Selector

Pass `selectSource` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to source state. Returns `undefined` if the source feature is not configured.

**source-info.ts**

```ts
import { createPlayer, UIElement, selectSource } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class SourceInfo extends UIElement {
  readonly #source = new PlayerController(this, selectSource);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-stream-type -->

# Stream type

Stream delivery type (live / on-demand) state for the player store

Tracks whether the current source is live, on-demand, or not known yet. Use it to choose which controls to show.

`streamType` is `'live'`, `'on-demand'`, or `'unknown'`. It does not tell you how close playback is to the live edge or whether viewers can rewind.

HLS media reads the stream type from the loaded playlist. If you set `streamType` yourself, your value takes priority until you set it back to `'unknown'`. Other media falls back to the browser’s duration: `Infinity` means live, a finite positive value means on-demand, and any other value means unknown.

Add `streamTypeFeature` to a custom player when you need `streamType` in player state. The live presets separately include the [live feature](https://videojs.org/docs/framework/html/reference/api/feature-live), which tracks the live edge.

## Import

```ts
import { streamTypeFeature } from '@videojs/html';
```

No packaged [feature bundle](https://videojs.org/docs/framework/html/guides/presets) includes this feature — add it to your [`createPlayer`](https://videojs.org/docs/framework/html/reference/api/html-create-player) features yourself.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | Current stream delivery type. Components use this to show live-specific UI (for example, a live indicator or a "jump to live edge" button) or hide the time display. |

### Selector

Pass `selectStreamType` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to stream type state. Returns `undefined` if the stream type feature is not configured.

**live-indicator.ts**

```ts
import { createPlayer, selectStreamType, streamTypeFeature, UIElement } from '@videojs/html';
import { liveVideoFeatures } from '@videojs/html/live-video';

const { PlayerController } = createPlayer({
  features: [...liveVideoFeatures, streamTypeFeature],
});

class LiveIndicator extends UIElement {
  readonly #stream = new PlayerController(this, selectStreamType);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-text-tracks -->

# Text tracks

Subtitles, captions, and chapter track state for the player store

Manages subtitles, captions, chapters, and thumbnail tracks.

A default `kind="chapters"` track can also divide the [time slider](https://videojs.org/docs/framework/html/reference/components/time-slider) into chapter ranges and label the chapter at the current interaction position.

`thumbnailsTrack` is the first `kind="metadata"` track labeled `thumbnails`, or `null` when there is none. Its `crossOrigin` reports the media component’s CORS mode, or `null` when the media is not CORS-enabled. [Thumbnail](https://videojs.org/docs/framework/html/reference/components/thumbnail) reads it to fetch sprite sheets the same way the browser fetched the track.

## Import

```ts
import { textTrackFeature } from '@videojs/html';
```

The `liveVideoFeatures` and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `textTrackList` | `MediaTextTrack[]` | All text tracks available on the media component. |
| `subtitlesShowing` | `boolean` | Whether a captions/subtitles track is showing. |
| `chaptersCues` | `MediaTextCue[]` | Cues from the first `kind="chapters"` track, with cue ends clamped to a finite media duration. |
| `thumbnailsTrack` | `{ cues: MediaTextCue[]; src: string \| null; crossOrigin: 'anonymous' \| 'use-credentials' \| null } \| null` | The first thumbnails track, or `null` when there is none. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `toggleSubtitles` | `(forceShow?: boolean) => boolean` | Toggle captions/subtitles visibility. Showing enables one caption/subtitle track. A track already showing stays selected. Otherwise, selection prefers the last track shown, then a track matching the browser language, then the first available track. Returns whether a track is showing. |
| `selectSubtitlesTrack` | `(id: string \| null) => void` | Show the captions/subtitles track with `id`, or turn captions/subtitles off with `null`. |

### Selector

Pass `selectTextTrack` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to text track state. Returns `undefined` if the text tracks feature is not configured.

**captions-button.ts**

```ts
import { createPlayer, UIElement, selectTextTrack } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class CaptionsButton extends UIElement {
  readonly #textTracks = new PlayerController(this, selectTextTrack);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-time -->

# Time

Playback position and duration state for the player store

Tracks playback position and duration. During live playback, the browser may report `Infinity` as the duration. The player reports the end of the last available [seekable range](https://videojs.org/docs/framework/html/reference/api/feature-buffer) instead, so the value stays finite and moves forward with the stream. This is the newest available time, not the length of the rewindable window; its first available time may be greater than zero. Use [live state](https://videojs.org/docs/framework/html/reference/api/feature-live) or [stream type](https://videojs.org/docs/framework/html/reference/api/feature-stream-type) to check whether the source is live.

## Import

```ts
import { timeFeature } from '@videojs/html';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `currentTime` | `number` | Current playback position in seconds. |
| `duration` | `number` | Total duration in seconds (0 if unknown). |
| `seeking` | `boolean` | Whether a seek operation is in progress. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `seek` | `(time: number) => Promise<number>` | Seek to a time in seconds. Returns the actual position after seek. |

### Selector

Pass `selectTime` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to time state. Returns `undefined` if the time feature is not configured.

**time-display.ts**

```ts
import { createPlayer, UIElement, selectTime } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class TimeDisplay extends UIElement {
  readonly #time = new PlayerController(this, selectTime);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/feature-volume -->

# Volume

Volume level and mute state for the player store

Controls volume level and mute state. These capabilities have independent availability values because media can support mute without supporting volume-level changes.

## Import

```ts
import { volumeFeature } from '@videojs/html';
```

The `audioFeatures`, `liveAudioFeatures`, `liveVideoFeatures`, and `videoFeatures` [feature bundles](https://videojs.org/docs/framework/html/guides/presets) include this feature.

## API Reference

### State

| Property | Type | Description |
| --- | --- | --- |
| `volume` | `number` | Volume level from 0 (silent) to 1 (max). |
| `muted` | `boolean` | Whether audio is muted. |
| `volumeAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether volume can be programmatically set on this platform. |
| `mutedAvailability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media can be muted. Separate from `volumeAvailability` because the two come apart: an embed can take a mute command while offering no way to set a level, and iOS Safari refuses a volume write on media that mutes perfectly well. |

### Actions

| Action | Type | Description |
| --- | --- | --- |
| `setVolume` | `(volume: number) => number` | Set volume (clamped 0-1). Returns the clamped value. |
| `setMuted` | `(muted: boolean) => boolean` | Set the muted state, updating the store immediately. Unmuting at volume 0 restores volume to 0.25. Returns the new muted value. |

### Selector

Pass `selectVolume` to [`PlayerController`](https://videojs.org/docs/framework/html/reference/api/player-controller) to subscribe to volume state. Returns `undefined` if the volume feature is not configured.

Check `volumeAvailability` before showing a volume-level control, and check `mutedAvailability` before showing a mute control.

**volume-slider.ts**

```ts
import { createPlayer, UIElement, selectVolume } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerController } = createPlayer({ features: videoFeatures });

class VolumeSlider extends UIElement {
  readonly #volume = new PlayerController(this, selectVolume);
}
```

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/create-i18n -->

# createI18n

Factory that creates framework i18n helpers with custom loading options

## Import

```ts
import { createI18n } from "@videojs/html/i18n";
```

`createI18n` returns a context-bound `ProviderMixin`, `TextMixin`, and `I18nController` for custom elements. Use it when you need a custom locale loader or custom i18n elements. Most apps use `<media-i18n>` and `<media-text>` from `@videojs/html/i18n`.

```ts
import { UIElement } from '@videojs/html';
import { createI18n } from '@videojs/html/i18n';

const { ProviderMixin, TextMixin } = createI18n();

class LocalizedRoot extends ProviderMixin(UIElement) {}
class LocalizedText extends TextMixin(UIElement) {}
```

## API Reference

`createI18n(options?): CreateI18nResult`

### Parameters

| Parameter | Type | Default |
| --- | --- | --- |
| `options` | `{ loader?: ((tag: string) => Promise<Partial<FlatTranslations> \| undefined>) }` | — |

### Return Value

| Property | Type |
| --- | --- |
| `context` | `Context<symbol, I18nContextValue>` |
| `I18nController` | `typeof I18nController` |
| `ProviderMixin` | `(<Base extends ReactiveElementMixinBase>(Base: Base) => Constructor<ReactiveElement> & Base)` |
| `TextMixin` | `(<Base extends ReactiveElementMixinBase>(Base: Base) => Constructor<ReactiveElement> & Base)` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/media-i18n -->

# media-i18n

HTML custom element that resolves locale and supplies translations to descendants

## Import

```ts
import "@videojs/html/i18n";
```

One import registers both `<media-i18n>` and `<media-text>`.

`<media-i18n>` applies the i18n provider mixin to a subtree. Wrap a player, standalone controls, or one of several players that need different locales with this element. Without it, HTML controls use English defaults.

Set `lang` on the provider or an ancestor. Built-in packs lazy-load automatically; register locale strings with [`registerI18n`](https://videojs.org/docs/framework/html/reference/api/register-i18n) when you need custom copy or synchronous first paint. See [Translation phrases](https://videojs.org/docs/framework/html/reference/api/translation-phrases) for supported keys.

```html
<script type="module">
  import '@videojs/html/i18n';
  import '@videojs/html/i18n/locales/es/register';
</script>

<media-i18n lang="es">
  <media-text token="buttons.play">Play</media-text>
</media-i18n>
```

## Attributes

| Attribute | Description |
| --- | --- |
| `lang` | Forces the active BCP 47 locale for this subtree. Omit to inherit the nearest ancestor `[lang]`. |

## Related

- [`<media-text>`](https://videojs.org/docs/framework/html/reference/api/media-text): Renders translated text content
- [Internationalize the player](https://videojs.org/docs/framework/html/guides/internationalization)

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/media-text -->

# media-text

HTML custom element that renders a translated string by semantic key

## Import

```ts
import "@videojs/html/i18n";
```

One import registers both `<media-i18n>` and `<media-text>`.

`<media-text>` renders a translated value inside a [`<media-i18n>`](https://videojs.org/docs/framework/html/reference/api/media-i18n) (or any ancestor with the i18n provider mixin). Set `token` to the semantic translation key and use the text content as its English fallback. Use it for authored component content, standalone labels, tooltips, or demos.

```html
<media-i18n lang="ja">
  <media-text token="buttons.play">Play</media-text>
</media-i18n>
```

## Token and fallback

The `token` attribute accepts an opaque key such as `buttons.play`. The initial text content is the fallback shown when the active locale has no value for that key. See [Translation phrases](https://videojs.org/docs/framework/html/reference/api/translation-phrases) for the supported keys and English defaults.

Without `token`, `<media-text>` keeps its text content unchanged. This is useful for literal copy that should not be translated.

Parametric translations are not yet supported on `<media-text>`. Use `createTranslator` in script for interpolated strings.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/translation-phrases -->

# Translation phrases

Semantic i18n keys, their English defaults, and the player UI that uses them

Video.js uses opaque semantic keys so English copy can change without breaking translation packs. English defaults are defined in `packages/core/src/core/i18n/locales/en.ts`. Both HTML and React controls use the same keys.

Locale packs and provider overrides use nested objects, so `buttons.play` is authored as `{ buttons: { play: '…' } }`. Translators and the `<media-text token>` attribute use the dotted form.

## Text descriptors

Each key also ships as a text descriptor: an object with the `key` and its English default `text`. Descriptors are grouped by the key’s first segment and named after the rest, so `buttons.play` is `playText` in the `buttons` module and `container.label` is `labelText` in `container`. Pass one to a translator, or to [`translateText`](https://videojs.org/docs/framework/html/reference/api/translate-text), to get the active locale’s copy with English as the fallback.

```ts
import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';
import { playText } from '@videojs/html/i18n/text/buttons';

const t = createTranslator(getI18nTranslations('fr'), 'fr');

t(playText); // 'Lecture' once French is registered, else 'Play'
```

## Playback controls

| Key | English default | Used by |
| --- | --- | --- |
| `buttons.play` | Play | Play button and its tooltip |
| `buttons.pause` | Pause | Play button and its tooltip |
| `buttons.replay` | Replay | Play button and its tooltip |
| `buttons.mute` | Mute | Mute button and its tooltip |
| `buttons.unmute` | Unmute | Mute button and its tooltip |
| `seek.forward` | Seek forward `{seconds}` seconds | Seek-forward button and its tooltip |
| `seek.backward` | Seek backward `{seconds}` seconds | Seek-backward button and its tooltip |
| `fullscreen.enter` | Enter fullscreen | Fullscreen button |
| `fullscreen.exit` | Exit fullscreen | Fullscreen button |
| `captions.enable` | Enable captions | Captions button and captions selection control |
| `captions.disable` | Disable captions | Captions button and captions selection control |
| `pip.enter` | Enter picture-in-picture | Picture-in-picture button |
| `pip.exit` | Exit picture-in-picture | Picture-in-picture button |
| `live.playing` | Playing live | Live button |
| `live.seekToEdge` | Seek to live edge | Live button |
| `live.badge` | Live | Live button badge |
| `cast.start` | Start casting | Cast button |
| `cast.stop` | Stop casting | Cast button |
| `cast.connecting` | Connecting | Cast button |
| `airplay.start` | Start AirPlay | AirPlay button |
| `airplay.stop` | Stop AirPlay | AirPlay button |
| `container.label` | Media player | Player container aria label |

## Time and volume

| Key | English default | Used by |
| --- | --- | --- |
| `slider.seek` | Seek | Time slider aria label |
| `time.current` | Current time | Current-time display aria label |
| `time.duration` | Duration | Duration display aria label |
| `time.remaining` | Remaining | Remaining-time display aria label |
| `time.elapsedSuffix` | `{duration} elapsed` | Elapsed time in a toggleable display aria label |
| `time.durationSuffix` | `{duration} duration` | Duration in a toggleable display aria label |
| `time.remainingSuffix` | `{duration} remaining` | Remaining time display |
| `time.showElapsed` | `Show elapsed time, {duration}.` | Toggleable time display aria label |
| `time.showDuration` | `Show duration, {duration}.` | Toggleable time display aria label |
| `time.showRemaining` | `Show remaining time, {duration}.` | Toggleable time display aria label |
| `time.toggleElapsed` | `Toggle between elapsed and remaining time.` | Elapsed-time toggle aria description |
| `time.toggleDuration` | `Toggle between duration and remaining time.` | Duration toggle aria description |
| `time.position` | `{current} of {duration}` | Time slider value text |
| `time.unknown` | Media not loaded, unknown time. | Time display aria label and time slider value text before a duration is known |
| `playback.rate` | Playback rate `{rate}` | Playback-rate button and radio group |
| `volume.mutedValue` | `{percent}, muted` | Muted volume slider value text |
| `volume.muted` | Muted | Volume input feedback |
| `volume.label` | Volume | Volume slider aria label |
| `volume.value` | Volume `{value}` | Volume input feedback |

## Playback feedback

| Key | English default | Used by |
| --- | --- | --- |
| `status.captionsOn` | Captions on | Input feedback after enabling captions |
| `status.captionsOff` | Captions off | Input feedback after disabling captions |
| `status.paused` | Paused | Input feedback after pausing |
| `status.playing` | Playing | Input feedback after starting playback |
| `status.fullscreen` | Fullscreen | Input feedback after entering fullscreen |
| `status.pip` | Picture in picture | Input feedback after entering picture-in-picture |
| `status.exitPip` | Exit picture in picture | Input feedback after exiting picture-in-picture |
| `status.seekedTo` | Seeked to `{time}` | Status announcer after a seek |

## Errors

| Key | English default | Used by |
| --- | --- | --- |
| `errors.aborted` | You stopped media playback before it finished. | Media error dialog for `MEDIA_ERR_ABORTED` |
| `errors.network` | This media could not be loaded due to a network or server issue. | Media error dialog for `MEDIA_ERR_NETWORK` |
| `errors.decode` | This media could not be played. It may be corrupted, or your browser may not support its format. | Media error dialog for `MEDIA_ERR_DECODE` |
| `errors.source` | This media could not be loaded. It may be unavailable, or your browser may not support its format. | Media error dialog for `MEDIA_ERR_SRC_NOT_SUPPORTED` |
| `errors.encrypted` | This media could not be played because it could not be decrypted. | Media error dialog for `MEDIA_ERR_ENCRYPTED` |
| `errors.unplayable` | This media is unsupported by the player. | Media error dialog when the player cannot play a source the browser supports |
| `errors.title` | Something went wrong. | Generic media error dialog title |
| `errors.unexpected` | An unexpected error occurred. | Generic media error dialog fallback description |
| `common.empty` | `''` | Empty description for a custom media error |
| `common.ok` | OK | Error dialog confirmation button |

## Settings and track menus

| Key | English default | Used by |
| --- | --- | --- |
| `menu.settings` | Settings | Video settings menu trigger |
| `menu.quality` | Quality | Quality menu |
| `menu.audio` | Audio | Audio-track menu and fallback track label |
| `menu.default` | Default | Reserved default-option label; no stock control currently emits it |
| `menu.speed` | Speed | Playback-rate menu |
| `menu.captions` | Captions | Captions menu |
| `menu.playbackRate` | Playback rate | Playback-rate radio group |
| `menu.back` | Back | Nested settings-menu back button |
| `menu.off` | Off | Captions menu option |
| `menu.auto` | Auto | Automatic-quality option |
| `menu.autoWithLabel` | Auto (`{label}`) | Automatic-quality option with the active rendition |
| `menu.subtitles` | Subtitles | Subtitles track option |

## Related pages

- [Internationalize the player](https://videojs.org/docs/framework/html/guides/internationalization): Translate player labels and announcements: shipped locale packs, custom translations, runtime switching, and server rendering.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/register-i18n -->

# registerI18n

Register or merge translation strings for a BCP 47 locale tag in the global i18n registry

## Import

```ts
import { registerI18n } from "@videojs/html/i18n";
```

`registerI18n` merges a partial translation map into the process-wide registry for a locale tag. Components carry their own English fallback text. Built-in non-English packs lazy-load automatically; call `registerI18n` for custom locales, CDN locale modules, or patched shipped packs before the provider renders.

Keys are nested semantic names such as `buttons.play` and `buttons.pause`. See [Translation phrases](https://videojs.org/docs/framework/html/reference/api/translation-phrases) for the complete catalog.

```ts
import { registerI18n } from '@videojs/html/i18n';

registerI18n('es', {
  buttons: {
    play: 'Reproducir',
    pause: 'Pausar',
  },
});
```

## Built-in locale packs

Each shipped pack is a module named after its locale tag. Its default export is the pack’s `Translations` map. Pass it to `registerI18n` when you load a pack yourself, for example right before switching to that locale:

```ts
import { registerI18n } from '@videojs/html/i18n';
import ja from '@videojs/html/i18n/locales/ja';

registerI18n('ja', ja);
```

A side-effect import of the pack’s `/register` subpath, such as `import '@videojs/html/i18n/locales/ja/register'`, does the same.

## API Reference

`registerI18n(locale, translations): void`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag (normalized to lowercase; unicode extensions stripped for the registry key). |
| `translations` (required) | `Partial<Translations>` | — | Partial nested locale values; merges with any existing layer for the tag. |

### Return Value

`void`

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/get-i18n-translations -->

# getI18nTranslations

Read the merged translation map for a locale using BCP 47 parent-chain fallback

## Import

```ts
import { getI18nTranslations } from "@videojs/html/i18n";
```

`getI18nTranslations` walks the BCP 47 lookup chain (`es-MX` → `es` → `en`) and merges registry layers into one map. Providers combine this map with lazy-loaded built-in packs and provider overrides. Call it directly when building custom UI outside built-in controls.

See [Internationalize the player](https://videojs.org/docs/framework/html/guides/internationalization) for merge order and fallback rules.

```ts
import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';

const t = createTranslator(getI18nTranslations('pt-BR'), 'pt-BR');
t('buttons.play', { default: 'Play' });
```

## API Reference

`getI18nTranslations(locale): FlatTranslations`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag to resolve (e.g. `es-MX`, `zh-Hant-HK`). |

### Return Value

| Type |
| --- |
| `{ [Key in TranslationKey]?: TranslationParams[Key] extends never ? string : Key extends keyof ParametricTranslations ? ParametricTranslations[Key] : string; } & Record<string, string \| undefined>` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/has-registered-locale -->

# hasRegisteredLocale

Check whether an exact locale tag exists in the global i18n registry

## Import

```ts
import { hasRegisteredLocale } from "@videojs/html/i18n";
```

`hasRegisteredLocale` returns whether a normalized locale tag has an explicit registry layer from [`registerI18n`](https://videojs.org/docs/framework/html/reference/api/register-i18n). It does **not** indicate whether a lazy built-in pack exists. Only registry entries count.

```ts
import { hasRegisteredLocale, registerI18n } from '@videojs/html/i18n';

hasRegisteredLocale('fr'); // false until registered
registerI18n('fr', { buttons: { play: 'Lecture' } });
hasRegisteredLocale('fr'); // true
```

## API Reference

`hasRegisteredLocale(locale): boolean`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag to test. |

### Return Value

`boolean`

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/on-i18n-registry-change -->

# onI18nRegistryChange

Subscribe to global i18n registry mutations

## Import

```ts
import { onI18nRegistryChange } from "@videojs/html/i18n";
```

`onI18nRegistryChange` registers a callback that runs whenever any locale layer changes, for example after `registerI18n` or browser translation prefetch. Returns an unsubscribe function.

## API Reference

`onI18nRegistryChange(callback): (() => void)`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `callback` (required) | `(() => void)` | — | Invoked when any locale layer changes. |

### Return Value

| Type |
| --- |
| `(() => void)` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/create-translator -->

# createTranslator

Build a typed translator from a resolved translation map

## Import

```ts
import { createTranslator } from "@videojs/html/i18n";
```

`createTranslator` wraps the flat map returned by `getI18nTranslations` and returns a typed `Translator` function. Providers call this internally after merging registry, lazy-loaded built-in packs, browser-translated fallback copy, and provider layers. Use it directly for custom UI outside built-in controls.

```ts
import { createTranslator, getI18nTranslations } from '@videojs/html/i18n';

const t = createTranslator(getI18nTranslations('fr'), 'fr');
t('buttons.play', { default: 'Play' });
t('seek.forward', { seconds: 5, default: 'Seek forward {seconds} seconds' });
```

## API Reference

`createTranslator(translations, locale): Translator`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `translations` (required) | `{ [Key in TranslationKey]?: TranslationParams[Key] extends never ? string : Key extends keyof ParametricTranslations ? ParametricTranslations[Key] : string; } & Record<string, string \| undefined>` | — | Merged translation map for the active locale. |
| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag associated with the map (reserved for future locale-aware behavior). |

### Return Value

| Type |
| --- |
| `{ <Key extends string>(key: Key, ...args: Key extends TranslationKey ? TranslationParams[Key] extends never ? [params?: TranslationOptions] : [params: TranslationParams[Key] & TranslationOptions] : [params?: TextParams & TranslationOptions]): string; (text: Text, params?: TextParams): string }` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/translate-text -->

# translateText

Translate a text descriptor, or fall back to its English default

## Import

```ts
import { translateText } from "@videojs/html/i18n";
```

`translateText` translates a text descriptor with a translator from [`createTranslator`](https://videojs.org/docs/framework/html/reference/api/create-translator). Without one, it fills the descriptor’s English default with the params. A plain string is returned as is, so a label can be either.

```ts
import { createTranslator, getI18nTranslations, translateText } from '@videojs/html/i18n';
import { forwardText } from '@videojs/html/i18n/text/seek';

translateText(forwardText, { seconds: 10 }); // 'Seek forward 10 seconds'

const t = createTranslator(getI18nTranslations('fr'), 'fr');
translateText(forwardText, t, { seconds: 10 });
```

## API Reference

### Overload 1

`translateText(text, params?): string`

Translate a text descriptor with a translator, or interpolate its English default without one. A plain string is returned as is.

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `text` (required) | `{ key: string; text: string } \| string` | — | Text descriptor, or a string returned unchanged. |
| `params` | `Record<string, string \| number>` | — | Values for the text's `{placeholders}`. |

#### Return Value

`string`

### Overload 2

`translateText(text, translator, params?): string`

#### Parameters

| Parameter | Type | Default |
| --- | --- | --- |
| `text` (required) | `{ key: string; text: string } \| string` | — |
| `translator` (required) | `{ <Key extends string>(key: Key, ...args: Key extends TranslationKey ? TranslationParams[Key] extends never ? [params?: TranslationOptions] : [params: TranslationParams[Key] & TranslationOptions] : [params?: TextParams & TranslationOptions]): string; (text: Text, params?: TextParams): string } \| undefined` | — |
| `params` | `Record<string, string \| number>` | — |

#### Return Value

`string`

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/resolve-translation -->

# resolveTranslation

Translate a key with the params its English default requires

## Import

```ts
import { resolveTranslation } from "@videojs/html/i18n";
```

`resolveTranslation` calls a translator from [`createTranslator`](https://videojs.org/docs/framework/html/reference/api/create-translator) with a key and its params. Unlike calling the translator directly with a variable key, its type requires the params that key’s English default interpolates, such as `seconds` for `seek.forward`.

```ts
import { createTranslator, getI18nTranslations, resolveTranslation } from '@videojs/html/i18n';

const t = createTranslator(getI18nTranslations('fr'), 'fr');

resolveTranslation(t, 'buttons.play');
resolveTranslation(t, 'seek.forward', { seconds: 10 });
```

## API Reference

`resolveTranslation<Key extends string>(translator, key, ...args): string`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `translator` (required) | `{ <Key extends string>(key: Key, ...args: Key extends TranslationKey ? TranslationParams[Key] extends never ? [params?: TranslationOptions] : [params: TranslationParams[Key] & TranslationOptions] : [params?: TextParams & TranslationOptions]): string; (text: Text, params?: TextParams): string }` | — | Translator from `createTranslator`. |
| `key` (required) | `Key` | — | Translation key, such as `seek.forward`. |
| `args` | `Key extends TranslationKey ? TranslationParams[Key] extends never ? [params?: TranslationOptions] : [params: TranslationParams[Key] & TranslationOptions] : [params?: Record<string, string \| number> & TranslationOptions]` | — | The key's template params, plus an optional `default` string. |

### Return Value

`string`

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/is-text -->

# isText

Check whether a value is a text descriptor

## Import

```ts
import { isText } from "@videojs/html/i18n";
```

`isText` returns whether a value is a text descriptor: an object with a translation `key` and its English default `text`. Use it to accept either a descriptor or a plain string, as [`translateText`](https://videojs.org/docs/framework/html/reference/api/translate-text) does. See [Translation phrases](https://videojs.org/docs/framework/html/reference/api/translation-phrases) for the built-in descriptors.

```ts
import { isText } from '@videojs/html/i18n';
import { playText } from '@videojs/html/i18n/text/buttons';

isText(playText); // true
isText('Play'); // false
```

## API Reference

`isText(value): value is Text`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `unknown` | — | Value to check. |

### Return Value

`value is Text`

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/load-locale -->

# loadLocale

Lazy-load the built-in translation pack for a locale

## Import

```ts
import { loadLocale } from "@videojs/html/i18n";
```

`loadLocale` imports the built-in pack for a tag, or for the closest tag in its [`findLocaleKeys`](https://videojs.org/docs/framework/html/reference/api/find-locale-keys) chain, and resolves to its flat translations. It resolves to `undefined` when that chain reaches a locale registered with [`registerI18n`](https://videojs.org/docs/framework/html/reference/api/register-i18n) first, or when no built-in pack matches. Providers call it for you; use it to translate UI outside a provider without bundling every pack.

```ts
import { createTranslator, getI18nTranslations, loadLocale } from '@videojs/html/i18n';

const pack = await loadLocale('fr-CA');
const t = createTranslator({ ...pack, ...getI18nTranslations('fr-CA') }, 'fr-CA');

t('buttons.play'); // 'Lecture'
```

## API Reference

`loadLocale(tag): Promise<Partial<FlatTranslations> | undefined>`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `tag` (required) | `string` | — | BCP 47 tag to load, such as `fr-CA`. |

### Return Value

| Type |
| --- |
| `Promise<Partial<FlatTranslations> \| undefined>` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/get-locale-key -->

# getLocaleKey

Normalize a locale tag to the key the i18n registry stores it under

## Import

```ts
import { getLocaleKey } from "@videojs/html/i18n";
```

`getLocaleKey` lowercases a BCP 47 tag, replaces underscores with hyphens, and removes Unicode extensions such as `-u-nu-latn`. The registry stores [`registerI18n`](https://videojs.org/docs/framework/html/reference/api/register-i18n) layers under this key, so use it to compare a tag with one you have registered or to key your own per-locale data the same way.

```ts
import { getLocaleKey } from '@videojs/html/i18n';

getLocaleKey('en_US-u-nu-latn'); // 'en-us'
getLocaleKey('zh-Hant'); // 'zh-hant'
```

## API Reference

`getLocaleKey(locale): Locale`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag to normalize. |

### Return Value

`(typeof LOCALES)[number] | string & {}`

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/find-locale-keys -->

# findLocaleKeys

List the locale tags a lookup falls back through, most specific first

## Import

```ts
import { findLocaleKeys } from "@videojs/html/i18n";
```

`findLocaleKeys` returns the fallback chain the player resolves a locale through: the normalized tag from [`getLocaleKey`](https://videojs.org/docs/framework/html/reference/api/get-locale-key), then each shorter prefix, ending with `en`. A Chinese tag with a script, such as `zh-Hant-HK`, also falls back through `zh-tw` or `zh-cn` before `zh`. A translation missing from one locale is looked up in the next.

```ts
import { findLocaleKeys } from '@videojs/html/i18n';

findLocaleKeys('es-419-u-nu-latn'); // ['es-419', 'es', 'en']
findLocaleKeys('fr'); // ['fr', 'en']
```

## API Reference

`findLocaleKeys(locale): Locale[]`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `locale` (required) | `(typeof LOCALES)[number] \| string & {}` | — | BCP 47 tag to resolve. |

### Return Value

`Locale[]`

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/i18n-controller -->

# I18nController

Reactive controller for consuming translator and locale values from an HTML i18n context

## Import

```ts
import { I18nController } from "@videojs/html";
```

## Usage

Create the controller with a reactive host and an i18n context. `i18nContext` is the default context that `<media-i18n>` provides; its `I18nContextValue` holds the active `translator` and `locale`. Read the `Translator` from `value` and the active locale from `locale`.

```ts
import { I18nController, UIElement, i18nContext } from "@videojs/html";

class LocalizedPlayLabel extends UIElement {
  readonly #i18n = new I18nController(this, i18nContext);

  get label() {
    return this.#i18n.value("buttons.play", { default: "Play" });
  }
}
```

The controller requests a host update when its context changes. Without a provider, it falls back to the default English locale and updates when registered translations change.

## API Reference

`new I18nController(host, context)`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | Reactive host updated when the i18n value changes. |
| `context` (required) | `Context<symbol, I18nContextValue>` | — | I18n context to consume. |

### Return Value

| Property | Type |
| --- | --- |
| `value` | `Translator` |
| `locale` | `(typeof LOCALES)[number] \| string & {}` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/resolve-adapter-type -->

# resolveAdapterType

Resolve which type of adapter plays a source URL, from its host, MIME type, or file extension

## Import

```ts
import { resolveAdapterType } from '@videojs/html';
```

`resolveAdapterType` reads a source URL and returns the type of adapter that plays it, so an app that plays sources from a catalog or from user input can pick the matching [media component](https://videojs.org/docs/framework/html/guides/media-sources). It returns `null` for sources it doesn’t recognize.

Resolution is a pure string check. It doesn’t fetch the source, load an engine, or touch the DOM. It doesn’t rewrite the source either: every source it recognizes, [shorthands](https://videojs.org/docs/framework/html/reference/api/resolve-adapter-type#shorthands) included, is one the matching media component accepts as its `src`.

## Usage

Look up the media component for the result and give it the same `src`:

```ts
import { resolveAdapterType } from '@videojs/html';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/media/vimeo-video';
import '@videojs/html/media/youtube-video';

const TAGS = { youtube: 'youtube-video', vimeo: 'vimeo-video', hls: 'hlsjs-video', video: 'video' } as const;

function createMedia(src: string) {
  const type = resolveAdapterType(src);
  const tag = type && type in TAGS ? TAGS[type as keyof typeof TAGS] : null;
  if (!tag) return null;

  const media = document.createElement(tag);
  media.setAttribute('src', src);
  return media;
}
```

Each media module you import adds its engine to your bundle, so import the rarely used ones dynamically.

### Adapter types

| Adapter type | Recognized sources | Media component |
| --- | --- | --- |
| `youtube` | `youtube.com`, `youtu.be`, and `youtube-nocookie.com` video and playlist URLs | `<youtube-video>` |
| `vimeo` | `vimeo.com` and `player.vimeo.com` URLs | `<vimeo-video>` |
| `wistia` | `wistia.com`, `wistia.net`, and `wi.st` URLs, and pages with a `wvideo` parameter | `<wistia-video>` |
| `mux` | `stream.mux.com` stream URLs, with or without `.m3u8` | `<mux-video>` or `<mux-audio>` |
| `cloudflare` | `cloudflarestream.com` and `videodelivery.net` URLs | `<cloudflare-video>` |
| `spotify` | `open.spotify.com` URLs and `spotify:` URIs | `<spotify-audio>` |
| `tiktok` | `tiktok.com` video URLs | `<tiktok-video>` |
| `twitch` | `twitch.tv` video and channel URLs | `<twitch-video>` |
| `hls` | `.m3u8` files and HLS MIME types | `<hls-video>`, `<hlsjs-video>`, or `<native-hls-video>` |
| `dash` | `.mpd` files and `application/dash+xml` | `<dash-video>` or `<shaka-video>` |
| `video` | `.mp4`, `.webm`, `.mov`, and `.ogv` files, and `video/*` MIME types | `<video>` |
| `audio` | `.mp3`, `.m4a`, `.wav`, `.ogg`, `.flac`, and `.aac` files, and `audio/*` MIME types | `<audio>` |

`hls` covers every HLS adapter and `dash` every DASH adapter, so an HLS stream comes back as `hls` whichever one you play it with; see [Media sources](https://videojs.org/docs/framework/html/guides/media-sources) to choose one. Mux streams served from a custom domain are recognized as plain `hls`.

### MIME types

Pass a MIME type as the second argument when the URL doesn’t end in a file extension, such as an extensionless manifest or a `blob:` URL. The MIME type takes precedence over the extension; service URLs, such as YouTube or Mux, resolve the same either way.

```ts
resolveAdapterType('https://example.com/manifest', 'application/vnd.apple.mpegurl'); // 'hls'
```

To get the MIME type a file extension implies, use [`resolveMimeType`](https://videojs.org/docs/framework/html/reference/api/resolve-mime-type).

### Bare ids

A bare id returns `null`. An 11-character YouTube id and a 10-character Wistia id look alike, so services are only recognized from URLs, `spotify:` URIs, and [shorthands](https://videojs.org/docs/framework/html/reference/api/resolve-adapter-type#shorthands). If you already know the service, pass the id to its media component directly.

### Shorthands

`resolveAdapterType` recognizes these shorthands, and the YouTube and Vimeo media accept them as `src`:

| Shorthand | Plays |
| --- | --- |
| `youtube/<id>`, `youtube/shorts/<id>` | The YouTube video, from the privacy-enhanced `youtube-nocookie.com` host |
| `vimeo/<id>` | The Vimeo video |
| `vimeo/<id>?hash=<hash>`, `vimeo/<id>?h=<hash>`, `vimeo/<id>/<hash>` | The unlisted Vimeo video |

## API Reference

`resolveAdapterType(src, type?): AdapterType | null`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` | — | The source URL, or a `youtube/<id>` or `vimeo/<id>` shorthand. |
| `type` | `string` | — | The source's MIME type, when known. It takes precedence over the file extension, so manifests and files without one can still be resolved. Parameters such as `codecs` are ignored. |

### Return Value

| Type |
| --- |
| `'youtube' \| 'vimeo' \| 'wistia' \| 'mux' \| 'cloudflare' \| 'spotify' \| 'tiktok' \| 'twitch' \| 'hls' \| 'dash' \| 'video' \| 'audio' \| null` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/resolve-mime-type -->

# resolveMimeType

Resolve a source's MIME type from its file extension

## Import

```ts
import { resolveMimeType } from '@videojs/html';
```

`resolveMimeType` returns the MIME type a source URL’s file extension implies, ignoring the query string and hash. It returns `null` when the URL has no extension or one it doesn’t recognize.

```ts
resolveMimeType('https://example.com/live/stream.m3u8?token=abc'); // 'application/x-mpegurl'
resolveMimeType('/media/podcast.mp3'); // 'audio/mpeg'
resolveMimeType('https://youtu.be/_cMxraX_5RE'); // null
```

| Extension | MIME type |
| --- | --- |
| `.m3u8` | `application/x-mpegurl` |
| `.mpd` | `application/dash+xml` |
| `.mp4` | `video/mp4` |
| `.webm` | `video/webm` |
| `.mov` | `video/quicktime` |
| `.ogv` | `video/ogg` |
| `.mp3` | `audio/mpeg` |
| `.m4a` | `audio/mp4` |
| `.wav` | `audio/wav` |
| `.ogg` | `audio/ogg` |
| `.flac` | `audio/flac` |
| `.aac` | `audio/aac` |

To find which media component plays a source, use [`resolveAdapterType`](https://videojs.org/docs/framework/html/reference/api/resolve-adapter-type).

## API Reference

`resolveMimeType(src): string | null`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` | — | The source URL. |

### Return Value

`string | null`

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/aria-key-shortcuts-controller -->

# AriaKeyShortcutsController

Reactive controller that exposes registered hotkey shortcut metadata

## Import

```ts
import { AriaKeyShortcutsController } from "@videojs/html";
```

## Usage

Create the controller on a reactive element inside a player container. It follows the container’s hotkey registrations and requests a host update when they change.

```ts
class CustomPlayButton extends UIElement {
  readonly #shortcut = new AriaKeyShortcutsController(this, "togglePaused");

  get ariaKeyShortcuts() {
    return this.#shortcut.aria;
  }

  get shortcutLabel() {
    return this.#shortcut.shortcut;
  }
}
```

Use `aria` for the element’s `aria-keyshortcuts` value and `shortcut` for display text. Both are `undefined` until the matching action has a registered shortcut.

## API Reference

`new AriaKeyShortcutsController(host, action, options?)`

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise<boolean> } & HTMLElement` | — | Host element whose nearest player container supplies hotkey registrations. |
| `action` (required) | `string` | — | Registered hotkey action to look up. |
| `options` | `{ value?: (() => number \| undefined) }` | `{}` | Optional value resolver for value-dependent shortcuts. |

### Return Value

| Property | Type |
| --- | --- |
| `value` | `string \| undefined` |
| `aria` | `string \| undefined` |
| `shortcut` | `string \| undefined` |
| `details` | `{ aria?: string; shortcut?: string }` |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/error-codes -->

# Error Codes

Error codes emitted by the video.js package and how to resolve them

Playback failures use the [error feature](https://videojs.org/docs/framework/html/reference/api/feature-error) instead. See [Handle playback errors](https://videojs.org/docs/framework/html/guides/playback-errors) for application handling.

## Video.js 8 Error Codes

The `video.js` package throws these `VJS8_LEGACY_*` errors when code calls a Video.js 8 API that does not exist in Video.js 10. Each code identifies the old API and its Video.js 10 equivalent.

- [VJS8_LEGACY_INIT](https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-init)

  `videojs()` was the Video.js 8 API. Video.js 10 has no factory; players are components you compose.
- [VJS8_LEGACY_PLUGIN](https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-plugin)

  `videojs.registerPlugin()` was the Video.js 8 plugin system. Video.js 10 has no plugin registry.
- [VJS8_LEGACY_COMPONENT](https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-component)

  `videojs.registerComponent()` was the Video.js 8 component tree. Video.js 10 components are custom elements and React components.
- [VJS8_LEGACY_GET_PLAYER](https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-get-player)

  `videojs.getPlayer()` looked players up by id. Video.js 10 has no registry; hold a reference to the element.
- [VJS8_LEGACY_OPTIONS](https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-options)

  `videojs.options` held Video.js 8 global defaults. Video.js 10 has no global; configuration lives on the components you render.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-init -->

# VJS8_LEGACY_INIT

Legacy Video.js 8 player initialization error

`videojs()` was the Video.js 8 API. Video.js 10 has no factory; players are components you compose.

## Trigger

```javascript
const player = videojs('my-video', { controls: true });
```

## Video.js 10 equivalent

Keep `import 'video.js'`, remove the factory call, and render `<video-player><video-skin><video src></video></video-skin></video-player>`.

See [Migrate from Video.js 8](https://videojs.org/docs/framework/html/guides/migrate-from-video-js-8) for the full setup.

## Video.js 8

Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-plugin -->

# VJS8_LEGACY_PLUGIN

Legacy Video.js 8 plugin registration error

`videojs.registerPlugin()` was the Video.js 8 plugin system. Video.js 10 has no plugin registry.

## Trigger

```javascript
videojs.registerPlugin('myPlugin', function () { /* ... */ });
```

## Video.js 10 equivalent

Compose behavior as components inside `<video-player>`, or add an extension such as `@videojs/google-cast`.

See [Migrate from Video.js 8](https://videojs.org/docs/framework/html/guides/migrate-from-video-js-8) for the full setup.

## Video.js 8

Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-component -->

# VJS8_LEGACY_COMPONENT

Legacy Video.js 8 component registration error

`videojs.registerComponent()` was the Video.js 8 component tree. Video.js 10 components are custom elements and React components.

## Trigger

```javascript
videojs.registerComponent('MyButton', MyButton);
```

## Video.js 10 equivalent

Define a custom element and place it inside `<video-skin>` or your own skin markup.

See [Migrate from Video.js 8](https://videojs.org/docs/framework/html/guides/migrate-from-video-js-8) for the full setup.

## Video.js 8

Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-get-player -->

# VJS8_LEGACY_GET_PLAYER

Legacy Video.js 8 player lookup error

`videojs.getPlayer()` looked players up by id. Video.js 10 has no registry; hold a reference to the element.

## Trigger

```javascript
const player = videojs.getPlayer('my-video');
```

## Video.js 10 equivalent

`document.querySelector('video-player')` and call actions on its `store.state`.

See [Migrate from Video.js 8](https://videojs.org/docs/framework/html/guides/migrate-from-video-js-8) for the full setup.

## Video.js 8

Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/api/vjs8-legacy-options -->

# VJS8_LEGACY_OPTIONS

Legacy Video.js 8 global options error

`videojs.options` held Video.js 8 global defaults. Video.js 10 has no global; configuration lives on the components you render.

## Trigger

```javascript
videojs.options.autoplay = true;
```

## Video.js 10 equivalent

Set attributes on `<video-player>`, `<video-skin>`, and the media component.

See [Migrate from Video.js 8](https://videojs.org/docs/framework/html/guides/migrate-from-video-js-8) for the full setup.

## Video.js 8

Video.js 8 continues to receive security patches. Its documentation is at [legacy.videojs.org](https://legacy.videojs.org). Pin the major version with `npm install video.js@8` to keep using it.