@sluby/player reference

@sluby/player plays Sluby videos in React: an hls.js player with adaptive quality, bounded error recovery, renewal of signed URLs, Safari's native HLS and direct-from-Sia delivery. Its @sluby/player/hls entry gives the same Sia loaders to apps that run hls.js without React. For a walkthrough, see Play videos in React and Play videos without React.

InstallCopy Anchor Link

npm install @sluby/player react react-dom

For the @sluby/player/hls entry alone, React is not needed:

npm install @sluby/player hls.js

To resolve playback URLs from an asset id or to stream from Sia, also install @sluby/sdk and pass a SlubyClient as client.

PackageCopy Anchor Link

ExportsCopy Anchor Link

SlubyPlayerCopy Anchor Link

import { SlubyPlayer } from '@sluby/player';

<SlubyPlayer client={client} assetId={assetId} title="Launch video" />;

SlubyPlayer renders a <div> around a <video> and forwards a ref of type SlubyPlayerHandle. The <video> always has playsInline.

Choose the sourceCopy Anchor Link

assetId takes an asset id or a pb_... playback id.

Without src, client needs a playback member (a SlubyClient has one). Otherwise the player fails with SlubyPlayer needs a client with playback (a SlubyClient) to play an assetId without src.

Source propsCopy Anchor Link

Passing signed or expiresIn together with src logs a console warning: Sluby: signed and expiresIn are ignored when src is given; sign src on your server and pass refreshSrc to renew it before it expires.

Display propsCopy Anchor Link

Recovery propsCopy Anchor Link

Delivery propsCopy Anchor Link

CallbacksCopy Anchor Link

Changing a callback, autoPlay, refreshSrc, the retry limits or hybridPolicy does not reload the video.

StatesCopy Anchor Link

Retry resolves the source again and continues from the same position.

Error recoveryCopy Anchor Link

The retry counters reset each time a segment is buffered. A new load of the same video (after Retry or a renewal that reloads) resumes at the same position and play state.

When hls.js is unsupported and the browser has no native HLS, the player fails with HLS is not supported in this browser and native HLS is unavailable. When hls.js is unsupported but the browser plays HLS natively (such as Safari on an iPhone without Managed Media Source), the player sets the URL on the <video> and plays through the gateway. Quality callbacks and getQualities() have nothing to report there.

Signed URL renewalCopy Anchor Link

The player renews a signed URL when it knows the expiry and either it signed the URL itself (client + assetId) or you passed refreshSrc. The expiry comes from expiresAt of getSignedUrl, or from the expires query parameter (Unix seconds) of the URL.

Direct-from-Sia playback from client + assetId does not depend on the signed URL's expiry: the session renews its share map on its own.

DeliveryCopy Anchor Link

A load uses Sia only when there is a viewer session (client.sia) and hls.js runs in the browser. Playback and delivery explains the three modes.

HandleCopy Anchor Link

interface SlubyPlayerHandle {
  getVideoElement: () => HTMLVideoElement | null;
  getHlsInstance: () => Hls | null;
  getQualities: () => QualityLevel[];
  setQuality: (levelIndex: number) => void;
  isAutoQuality: () => boolean;
}

useVideoCopy Anchor Link

function useVideo(player: RefObject<SlubyPlayerHandle | null>): UseVideoReturn;
function useVideo(
  videoRef: RefObject<HTMLVideoElement | null>,
  hlsRef: RefObject<Hls | null>,
): UseVideoReturn;

A headless hook for custom controls. Pass the ref of a SlubyPlayer, or a <video> ref and an hls.js instance ref for a player of your own. The hook follows the element once it mounts and every hls.js instance attached to it.

import { useRef } from 'react';
import { SlubyPlayer, useVideo, type SlubyPlayerHandle } from '@sluby/player';

function Player({ src }: { src: string }) {
  const player = useRef<SlubyPlayerHandle>(null);
  const video = useVideo(player);
  return (
    <>
      <SlubyPlayer ref={player} src={src} controls={false} />
      <button onClick={video.isPlaying ? video.pause : video.play}>
        {video.isPlaying ? 'Pause' : 'Play'}
      </button>
    </>
  );
}

The hook updates from <video> events and hls.js events; it runs no timer.

@sluby/player/hlsCopy Anchor Link

The loaders that SlubyPlayer uses, for apps that create hls.js themselves. Each returns a loader class for hls.js's loader config option.

createSiaLoaderCopy Anchor Link

function createSiaLoader(
  session: SiaPlaybackSession,
  assetId: string,
  source?: SiaShareSource,
): { new (config: HlsConfig): Loader<LoaderContext> };

import Hls from 'hls.js';
import { createSiaLoader } from '@sluby/player/hls';

const src = client.playback.streamUrl(assetId);
await client.sia!.prepare(assetId, { src });
const hls = new Hls({ loader: createSiaLoader(client.sia!, assetId, { src }) });
hls.attachMedia(video);
hls.loadSource(src);

A /v1/stream/... URL with a session that has no masterObjectId fails with status 502 and SiaLoader: this session cannot resolve a /v1/stream master url; use a SlubyClient session or play the /v1/objects/{id} master url.

createHybridLoaderCopy Anchor Link

function createHybridLoader(options: HybridLoaderOptions): {
  new (config: HlsConfig): Loader<LoaderContext>;
};

interface HybridLoaderOptions {
  session: SiaPlaybackSession;
  assetId: string;
  source?: SiaShareSource;
  media: () => HTMLMediaElement | null;
  urls?: { readonly current: Map<string, string> };
  policy?: Partial<HybridPolicy>;
  onStats?: (stats: HybridDeliveryStats) => void;
}

The loader extends hls.js's default loader:

• Playlists, keys and anything that is not a media segment with a /v1/objects/ id go through the gateway.
• A media segment comes from Sia only when no other Sia read is running, Sia is not paused, a 1-byte warm-up read of that object succeeded, and at least minBufferSec seconds are buffered ahead. Otherwise it comes from the gateway.
• A Sia read gets min(maxSiaWaitMs, (bufferAhead - safetyMarginSec) × 1000) milliseconds. When it fails or runs out of time, the gateway fetches the segment and the segment counts as a fallback.
• maxFailures failed reads in a row, warm-up reads included, pause Sia for pauseMs. A successful segment read resets the count.
• When session.prepare() fails, the console shows Sluby: Sia is unavailable for now, playing through the gateway. and Sia is paused for pauseMs, then tried again.

Every loader of one class shares the same state (warm objects, failures, totals). Create a new class for every hls.js instance.

HybridPolicy and HybridDeliveryStatsCopy Anchor Link

The totals count the media segments of one load and leave out playlists.

TypesCopy Anchor Link

QualityLevelCopy Anchor Link

TextTrackSourceCopy Anchor Link

PlaybackResolver and SiaPlaybackClientCopy Anchor Link

Structural types, so the player has no hard dependency on @sluby/sdk. A SlubyClient fits both.

interface SiaPlaybackClient {
  sia?: SiaPlaybackSession;
}

interface PlaybackResolver extends SiaPlaybackClient {
  playback: {
    getUrl(assetId: string): Promise<{
      playbackUrl: string;
      posterUrl: string | null;
      accessTier?: 'public' | 'private';
    }>;
    getSignedUrl(
      assetId: string,
      options?: { expiresIn?: number },
    ): Promise<{ signedUrl: string; expiresAt?: string; posterUrl?: string | null }>;
  };
}

SiaPlaybackSession and SiaShareSourceCopy Anchor Link

interface SiaShareSource {
  src?: string;
}

interface SiaPlaybackSession {
  prepare(assetId: string, source?: SiaShareSource): Promise<void>;
  resolveObjectId(assetId: string, objectId: string, source?: SiaShareSource): Promise<unknown>;
  download(object: unknown, options?: { offset?: number; length?: number }): ReadableStream;
  masterObjectId?(assetId: string, source?: SiaShareSource): Promise<string>;
}

The SDK's SiaSession (client.sia) implements it. masterObjectId is needed only to play a /v1/stream/{id}/master.m3u8 URL.

Overlay markupCopy Anchor Link

The built-in overlay renders no <style> element, so it needs no style-src 'unsafe-inline' in a Content Security Policy. The spinner turns through the Web Animations API, slower under prefers-reduced-motion. Style the overlay with these attributes: