@aspect-build/hls-player-react

A React component for playing HLS (m3u8) video streams, built on hls.js.

Designed for EVENT-type progressive HLS playlists where segments are generated on-the-fly (e.g. AI video generation pipelines). Handles the common pitfalls: polls for playlist completion before playback, buffers enough content to avoid stalls, and gracefully handles end-of-stream.

Install

npm install @aspect-build/hls-player-react

Usage

import { HlsPlayer } from "@aspect-build/hls-player-react";

function App() {
  return (
    <HlsPlayer
      src="https://example.com/video.m3u8"
      className="w-full rounded-xl"
      onEnded={() => console.log("done")}
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string \| undefined | — | m3u8 URL. Falsy hides the player. | | className | string | — | CSS class for the <video> element. | | style | CSSProperties | — | Inline styles for the <video> element. | | autoPlay | boolean | true | Auto-play once buffer threshold is met. | | muted | boolean | false | Mute audio. | | loop | boolean | false | Loop playback. | | controls | boolean | true | Show native video controls. | | pollInterval | number | 2000 | Interval (ms) for polling playlists for #EXT-X-ENDLIST. | | pollTimeout | number | 60000 | Max time (ms) to poll before loading anyway. | | bufferThreshold | number | 0.8 | Buffer ratio (0–1) of known duration before auto-play. | | fetchCredentials | RequestCredentials | "include" | Fetch credentials mode for playlist polling. | | onEnded | () => void | — | Called when playback ends. | | onError | (msg: string) => void | — | Called on fatal error. | | onReady | () => void | — | Called when playback starts. |

How it works

1. Poll for completion — Fetches the master m3u8, extracts media playlist URLs, and polls each until #EXT-X-ENDLIST appears (or timeout).
2. Smart buffering — Prefers hls.js over native HLS. Tracks known duration from LEVEL_LOADED / AUDIO_TRACK_LOADED events. Delays playback until buffer reaches the configured threshold.
3. End-of-stream detection — When the playlist transitions from live to VOD and the buffer is nearly exhausted, pauses playback and fires onEnded.

License

MIT