Shelby Media Player

The Shelby Media Player is a lightweight React wrapper around Shaka Player for adaptive HLS/DASH streaming. This comprehensive reference covers all available components, hooks, and utilities.

Installation

npm install @shelby-protocol/player

Prerequisites

The Shelby Media Player requires TailwindCSS 4 to be installed in your project for the default styles to work.

Setting up TailwindCSS

The player uses custom sp-* (Shelby Player) color utilities for controls that appear over video content. You have two options:

Option 1: Quick Setup - Import the provided stylesheet (may conflict with existing themes):

globals.css

@import "@shelby-protocol/player/styles/shadcn.css";

Option 2: Manual Setup (Recommended) - Define the theme variables yourself for full control:

globals.css

@import "tailwindcss";

@source "../node_modules/@shelby-protocol/player";

@theme inline {
  --color-sp-foreground: var(--sp-foreground);
  --color-sp-accent: var(--sp-accent);
  --color-sp-popover: var(--sp-popover);
  --color-sp-popover-foreground: var(--sp-popover-foreground);
}

:root {
  --sp-foreground: oklch(1 0 0);
  --sp-accent: oklch(0.6 0.18 240);
  --sp-popover: oklch(0.2 0 0 / 90%);
  --sp-popover-foreground: oklch(1 0 0);
}

See the Styling Guide for a complete explanation of the theme variables and configuration options.

Quick Start

Basic Usage

The simplest way to use the player is with the VideoPlayer component, which includes default controls:

import { VideoPlayer } from "@shelby-protocol/player";

function MyVideoPlayer() {
  return (
    <VideoPlayer
      src="https://example.com/video.m3u8"
      poster="https://example.com/poster.jpg"
      title="My Video"
    />
  );
}

Custom Layout

You can also build a custom player layout using the primitive components:

import {
  MediaProvider,
  PlayerProvider,
  PlayerContainer,
  ShakaVideo,
  ControlsContainer,
  ControlsGroup,
  FullscreenButton,
  PlayButton,
  MuteButton,
  CurrentTimeDisplay,
  MediaTitle,
  Seekbar,
  useVideo,
  useShaka,
} from "@shelby-protocol/player";

function CustomLayout({ title }: { title?: string }) {
  return (
    <ControlsContainer>
      <ControlsGroup className="px-4">
        <Seekbar />
      </ControlsGroup>
      <ControlsGroup className="pb-1 px-2">
        <PlayButton />
        <MuteButton />
        <MediaTitle title={title} />
        <div className="flex-1" />
        <CurrentTimeDisplay />
        <FullscreenButton />
      </ControlsGroup>
    </ControlsContainer>
  );
}

function CustomVideoPlayer() {
  return (
    <MediaProvider>
      <PlayerProvider>
        <PlayerContainer>
          <ShakaVideo
            src="https://example.com/video.m3u8"
            poster="https://example.com/poster.jpg"
            className="w-full"
          />
          <CustomLayout title="My Video" />
        </PlayerContainer>
      </PlayerProvider>
    </MediaProvider>
  );
}

Getting Started