use-shaka-player

React hooks and components for Shaka Player — the library for adaptive media streaming (DASH, HLS, and more).

Features

• 🎣 useShakaPlayer hook — full control over the player lifecycle, state, and controls
• 🎬 <ShakaPlayer> component — drop-in video element with a ref-based API
• ▶️ Adaptive streaming — DASH, HLS, and other formats via Shaka Player
• ⚡ Reactive state — buffering, playback, volume, time, and errors as React state
• 🎛️ Track management — variant and text track selection
• 📦 Tiny — thin wrapper, no extra dependencies beyond React and shaka-player
• 🔄 React 18 & 19 compatible

Install

npm install use-shaka-player shaka-player react react-dom

react, react-dom, and shaka-player are peer dependencies.

Quick Start

Hook

import { useShakaPlayer } from "use-shaka-player";

function Player() {
  const { videoRef, state, controls } = useShakaPlayer({
    src: "https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8",
    autoPlay: true,
    onError: (error) => console.error(error),
  });

  return (
    <div>
      <video ref={videoRef} style={{ width: "100%" }} />
      <p>
        {state.isPlaying ? "Playing" : "Paused"} —{" "}
        {Math.floor(state.currentTime)}s / {Math.floor(state.duration)}s
      </p>
      <button
        onClick={() => (state.isPlaying ? controls.pause() : controls.play())}
      >
        {state.isPlaying ? "Pause" : "Play"}
      </button>
    </div>
  );
}

Component

import { useRef } from "react";
import { ShakaPlayer, type ShakaPlayerRef } from "use-shaka-player";

function Player() {
  const playerRef = useRef<ShakaPlayerRef>(null);

  return (
    <ShakaPlayer
      ref={playerRef}
      src="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd"
      autoPlay
      onError={(e) => console.error(e)}
      style={{ width: "100%" }}
    />
  );
}

API

useShakaPlayer(options)

Returns { videoRef, playerRef, state, controls }.

Options

| Option | Type | Description | | ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | src | string \| ShakaSource | Media URI, or { uri, mimeType?, startTime? } | | autoPlay | boolean | Start playback after loading | | config | shaka.extern.PlayerConfiguration | Shaka Player configuration | | onError | (error) => void | Error callback | | onLoad | () => void | Fires when media is loaded | | onBuffering | (isBuffering) => void | Buffering state changes | | onPlay | () => void | Playback started | | onPause | () => void | Playback paused | | onEnded | () => void | Playback ended | | onTimeUpdate | (currentTime, duration) => void | Time progress | | onVolumeChange | (volume, muted) => void | Volume or mute changed | | onAdaptation | (event) => void | Shaka adaptation event | | onTracksChanged | (event) => void | Tracks changed event |

State

| Field | Type | | ------------- | ----------------------------------- | | isBuffering | boolean | | isPlaying | boolean | | isPaused | boolean | | isEnded | boolean | | currentTime | number | | duration | number | | volume | number | | muted | boolean | | error | shaka.util.Error \| Error \| null |

Controls

| Method | Description | | ----------------------------------------- | ------------------------------- | | play() | Start playback | | pause() | Pause playback | | seek(time) | Seek to time (seconds) | | setVolume(volume) | Set volume (0–1) | | setMuted(muted) | Mute / unmute | | load(uri, startTime?, mimeType?) | Load a new source | | unload() | Unload the current source | | getVariantTracks() | Get available variant tracks | | getTextTracks() | Get available text tracks | | selectVariantTrack(track, clearBuffer?) | Select a variant track | | selectTextTrack(track?) | Select a text track | | getStats() | Get playback statistics | | getBufferedInfo() | Get buffered ranges | | configure(config) | Update player configuration | | retryStreaming() | Retry after a streaming failure | | destroy() | Destroy the player instance |

<ShakaPlayer>

Accepts all the same options as the hook plus any standard <video> HTML attributes (e.g., style, className, controls, poster).

Expose methods via ref (ShakaPlayerRef), which includes all controls above plus:

| Method | Description | | ------------------- | --------------------------------------------- | | getVideoElement() | Access the underlying <video> element | | getPlayer() | Access the underlying shaka.Player instance |

License

MIT