Features

A feature is a top-level capability of the player .

Features define what the player can do, what state exists, and how that state stays in sync with the underlying media element or player environment. Features are not UI. Buttons, menus, sliders, and skins are separate—they simply consume feature state and invoke feature requests.

You can think of features as the behavioral and stateful core of the player, independent of how it looks.

Mental Model

The player is composed of four layers:

Media element   ← native playback engine
Environment     ← container, input, layout, persistence
Features        ← state + behavior (this document)
UI              ← buttons, menus, skins

• Features observe the media element and the environment.
• Features expose state and requests.
• UI reads feature state and calls requests.
• UI never talks directly to the media element.

This separation lets you change UI freely without re-implementing playback logic, and compose players by mixing and matching features.

Two Tiers of Features

All features fall into one of two conceptual tiers. This distinction is about scope, not about separate stores.

Media Features

Describe playback and media behavior. They primarily observe and control the media element.

Examples:

• playback
• time
• volume
• captions
• fullscreen
• pictureInPicture
• live
• quality
• audioTracks

Environment Features

Describe how the player behaves as an interactive application. They primarily observe and control the player container and user input.

Examples:

• layout
• idle
• hotkeys
• gestures
• i18n
• preferences
• casting / airplay

Both tiers are configured and consumed the same way.

Feature Lifecycle

Every feature participates in the same lifecycle:

1. Initialization

   • Initial state is created
   • Defaults and policies are applied
   • Preferences may be restored

2. Subscription

   • The feature listens to relevant events (media, container, input, timers)

3. Snapshot updates

   • When something changes, the feature updates its state

4. Requests

   • The feature exposes commands that mutate behavior (e.g. play, seek, toggleFullscreen)

This lifecycle is what allows features to stay deterministic, debuggable, and UI-agnostic.

Using Features

Using a Preset (Recommended)

Presets return an array of configured features. Options are grouped by feature key.

const player = createPlayer(
  presets.website({
    playback: {
      autoplay: false,
    },
    time: {
      defaultDuration: 120,
    },
    captions: {
      defaultMode: 'auto',
    },
    idle: {
      autohideSeconds: 2,
    },
    hotkeys: {
      seekForwardSeconds: 15,
      seekBackwardSeconds: 5,
    },
    layout: {
      breakpoints: 'sm:320 md:768',
    },
    i18n: {
      lang: 'en',
      t: (key) => key,
    },
  })
);

Extending a Preset

Presets are just arrays. You can spread them and add or override features.

const features = [
  ...presets.website({
    playback: { autoplay: false },
  }),
  qualityFeature({ defaultSelection: 'auto' }),
];

const player = createPlayer({ features });

Without a Preset

You can always configure features directly.

const player = createPlayer({
  features: [
    playbackFeature({ autoplay: false }),
    timeFeature({ defaultDuration: 120 }),
    captionsFeature({ defaultMode: 'auto' }),
    idleFeature({ autohideSeconds: 2 }),
    hotkeysFeature({ seekForwardSeconds: 15 }),
  ],
});

Media Features Reference

playback

Controls core playback behavior and exposes play/pause state and requests.

What it does:

• Tracks paused / playing / ended
• Issues play() and pause() requests
• Applies startup playback policy

Options:

playbackFeature({
  autoplay: 'muted',
  preload: 'metadata',
});

time

Tracks current playback time, duration, and seeking.

What it does:

• Tracks currentTime and duration
• Exposes seek requests
• Supports optimistic duration before metadata loads

Options:

volume

Tracks volume and mute state.

Options:

captions

Manages text tracks and subtitle state.

Options:

fullscreen

Manages fullscreen state.

Options:

pictureInPicture

Controls Picture-in-Picture state.

No options.

live

Handles live vs on-demand behavior.

Options:

quality

Manages rendition and quality selection.

Options:

Environment Features Reference

Environment features attach to the player container and describe layout, interaction, and application behavior.

layout

Controls responsive and structural behavior.

Options:

idle

Tracks user activity and idle state.

Options:

hotkeys

Handles keyboard shortcuts.

Options:

gestures

Controls pointer-based gestures.

Options:

i18n

Provides language selection and translation.

Options:

preferences

Handles persistence of user preferences.

Options:

casting / airplay

Controls external playback targets.

No options.

Summary

• Features define capabilities, not UI.
• Media and environment features share the same model.
• Options configure policy and defaults, not reactive state.
• Presets are composable helpers, not abstractions you’re locked into.
• UI reads feature state and issues requests—nothing more.

See Also

• Presets — Curated feature collections for common use cases
• Architecture — How features fit in the three-pillar model
• UI Components — How UI consumes feature state