Molecule.dev

← All @molecule/* packages · App templates

@molecule/app-video-hls

Provider bond · video · App (browser) · v1.0.1 · Apache-2.0

hls.js provider for @molecule/app-video — plays HLS (.m3u8) streams in every browser with adaptive bitrate (the built-in HTML5 default only plays HLS in Safari)

npm install @molecule/app-video-hls

npm · Source on GitHub · Implements @molecule/app-video

How it works

@molecule/app-video-hls is a provider bond on the app (browser) side: it implements the video core interface (@molecule/app-video) with a concrete vendor or library behind it.

Your code calls the core; you wire this provider once at startup. Swapping vendors later is one line in that wiring, not a rewrite.

// Wire once at startup:
import { setProvider, createPlayer } from '@molecule/app-video'
import { provider } from '@molecule/app-video-hls'
setProvider(provider)

// then anywhere (the container needs a size; the player fills it):
const el = document.getElementById('player') as HTMLElement
const player = await createPlayer({
  container: el,
  sources: [{ src: 'https://example.com/stream.m3u8', type: 'application/x-mpegurl' }],
  controls: true,
})
// adaptive bitrate is automatic; list variants via player.getQualityLevels()
// …later, on unmount: player.destroy()

Works with: @molecule/app-video

Reference

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

@molecule/app-video-hls — an hls.js-backed provider for @molecule/app-video that adds HLS (.m3u8) streaming playback in EVERY browser. The built-in HTML5 provider only plays HLS in Safari; this bond plays it everywhere via hls.js, with automatic adaptive bitrate. Progressive MP4/WebM still play through the native element.

Quick Start

// Wire once at startup:
import { setProvider, createPlayer } from '@molecule/app-video'
import { provider } from '@molecule/app-video-hls'
setProvider(provider)

// then anywhere (the container needs a size; the player fills it):
const el = document.getElementById('player') as HTMLElement
const player = await createPlayer({
  container: el,
  sources: [{ src: 'https://example.com/stream.m3u8', type: 'application/x-mpegurl' }],
  controls: true,
})
// adaptive bitrate is automatic; list variants via player.getQualityLevels()
// …later, on unmount: player.destroy()

Type

provider

Installation

npm install @molecule/app-video-hls @molecule/app-video hls.js

API

Functions

createHlsPlayer(config)

Create an hls.js-backed video player. The native HTML5 player owns the <video> element and every control; this only feeds the element via hls.js (or native HLS on Safari) and overrides source/quality accessors.

function createHlsPlayer(config: PlayerConfig): VideoPlayer
  • config — The player configuration (container, sources, controls, etc.).

Returns: A VideoPlayer that plays HLS streams in every browser.

createHlsVideoProvider()

Create an hls.js-backed VideoProvider.

function createHlsVideoProvider(): VideoProvider

Returns: A VideoProvider that adds HLS streaming to @molecule/app-video.

Constants

provider

The default hls.js video provider, ready to bond with setProvider(provider).

const provider: VideoProvider

Core Interface

Implements @molecule/app-video interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/app-video'
import { provider } from '@molecule/app-video-hls'

export function setupVideoHls(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

  • @molecule/app-video ^1.0.1

Runtime Dependencies

  • @molecule/app-video

  • hls.js

  • This provider REUSES the native HTML5 player for all controls (play/pause/ seek/volume/fullscreen/pip/text-tracks/events) and swaps in hls.js ONLY for loading the stream + exposing real adaptive quality levels — so behaviour matches the native provider everywhere except HLS source loading.

  • Mark the stream as a source with type: 'application/x-mpegurl' (or a URL ending in .m3u8). You may also list an MP4 fallback source for browsers with no HLS support at all.

  • On Safari/iOS, HLS plays through the native <video> element (hls.js is not used); getQualityLevels() then falls back to the native source list.

  • getQualityLevels() prepends { id: -1, label: 'Auto' }; pass it (or -1) to setQuality() to return to adaptive bitrate.

  • HLS only — .mpd (MPEG-DASH) is NOT supported (supportsDash() is false). For DASH, implement VideoProvider against Shaka Player or dash.js.

  • ALWAYS player.destroy() on unmount — it tears down the hls.js instance (network + buffers) as well as the video element.

  • BROWSER-ONLY: attaches to a DOM <video> element. Import + wire from app code.