@llamohank/custom-shaka-player

An opinionated wrapper around Shaka Player UI that delivers a streamlined HLS experience with custom rewind/forward controls, a center play overlay, and instant playback feedback. Perfect for quickly bootstrapping a polished browser player while keeping the full power of Shaka under the hood.

Features

• Custom rewind/forward controls (default ±10 s) rendered with SVG tooling tips.
• Centered splash play button that appears on first load.
• Animated play/pause feedback icons to reassure viewers after clicks.
• Safety guards that prevent seeking to 0 s or the stream tail where Shaka may stall.
• Keyboard seek distance automatically matches the configured skip length.
• Minimal API surface geared towards Cloud/VOD dashboards.

Installation

npm install @llamohank/custom-shaka-player

Note: shaka-player is declared as a peer dependency. The wrapper expects Shaka v4.16.x. Always import Shaka’s bundled UI build and stylesheet before instantiating the player.

Quick start

<div class="player-shell">
  <video muted playsinline></video>
</div>

import 'shaka-player/dist/shaka-player.ui.js';    // ensures the UI build is registered
import 'shaka-player/dist/controls.css';          // required styling for Shaka controls
import VideoPlayer from '@llamohank/custom-shaka-player';

const video = document.querySelector('video');
const player = new VideoPlayer(video, video.parentElement, {
  seekJumpSeconds: 15, // optional, defaults to 10
});

await player.initialize();
await player.play('https://example.com/path/to/manifest.m3u8', {
  posterUrl: 'https://example.com/poster.jpg', // optional, defaults with no poster
});

Once initialize() resolves, the player:

• hides the native <video> chrome and builds the Shaka overlay inside the container,
• injects custom rewind/forward buttons (±seekJumpSeconds),
• wires keyboard shortcuts and visual feedback.

Options

| Option | Type | Default | Description | |--------------------|--------|---------|------------------------------------------------------------| | seekJumpSeconds | number | 10 | Distance (in seconds) for the skip buttons and keyboard arrows. Values ≤0 are ignored. |

Public API

All methods are available on the VideoPlayer instance.

| Method | Description | |--------|-------------| | initialize() | Creates the underlying shaka.Player, attaches it to the supplied <video>, registers UI elements, and prepares overlays. Returns false if the browser is unsupported. | | play(manifestUrl, options?) | Loads the HLS/DASH manifest and shows the center play button. options.posterUrl sets the <video> poster. | | seekBy(seconds) | Relative seek with guard rails against 0 s and the stream tail. Used internally by the skip controls. | | pause() / resume() | Thin wrappers around the <video> element. resume() logs failures (e.g., autoplay restrictions). | | setPlaybackRate(rate) | Clamps to the 0.25–2× window before applying. | | getCurrentTime() / getDuration() | Proxies to the underlying media element. | | isPlaying() | Returns true if the media element exists and isn’t paused. | | unload() | Delegates to shakaPlayer.unload() so you can load a different manifest without rebuilding the UI. | | destroy() | Detaches every listener, tears down the Shaka overlay/player, clears overlays, and resets internal state so initialize() can be called again. |

Errors from play() are surfaced directly from Shaka. Wrap the promise in your own try/catch if you need custom toast messaging.

Customising the UI

• Skip button classes follow the pattern shaka-${CONTROL_ID}-button, e.g. .shaka-myRewind-button. Extend these selectors to tweak spacing or icons if needed.
• The floating feedback overlay is rendered as a div with the class custom-feedback-icon. Use CSS overrides to restyle the SVGs or animation.
• Provide your own container styling (aspect ratio, background, etc.) around the <video> element.

Keyboard behaviour

Shaka keeps its native hotkeys active. In this wrapper:

• Left/Right arrows jump by seekJumpSeconds (defaults to 10 s, configurable via the constructor or by editing DEFAULT_SEEK_JUMP_SECONDS).
• Shift + Arrow triggers the “large seek” distance, controlled by DEFAULT_LARGE_SEEK_JUMP_SECONDS (defaults to 60 s).

Adjust those constants (or pass a different seekJumpSeconds at construction) before bundling your own build if you need alternative keyboard behaviour.

Browser support

The wrapper relies on shaka-player v4.16.x, shaka-player/dist/shaka-player.ui.js build, which supports modern evergreen browsers (Chrome, Edge, Firefox, Safari) with Media Source Extensions. Legacy browsers without MSE are not supported.

License

ISC © Hank Cheng