Introduction

Stream your uploaded video from Shelby's decentralized storage network using the Shelby Video Player. The player handles adaptive bitrate streaming, quality selection, and provides a full-featured playback experience.

Prerequisites

Before playing a video, make sure you have:

A previously uploaded video with its account address and blob name
A React app with TailwindCSS 4

Step 1: Get Your Blob Key

When you uploaded your video, you received an account address and blob name. Retrieve these from your database or storage:

// From your database or upload response
const account = "7b1ada...3996";
const blobName = "video/playlist.m3u8";

Step 2: Construct the Playback URL

Combine the account and blob name with the Shelby storage API to create the playback URL:

const playbackUrl = `https://api.shelbynet.shelby.xyz/v1/blobs/${account}/${blobName}`;

Step 3: Install the Player

Install the Shelby Video Player package:

npm install @shelby-protocol/player

Step 4: Setup Styles

The player requires TailwindCSS 4. Add the player styles to your globals.css:

globals.css

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

Using shadcn/ui? Import @shelby-protocol/player/styles/shadcn.css instead to match your theme.

Step 5: Render the Player

Import and use the VideoPlayer component with your playback URL:

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

function MyPlayer({ account, blobName }) {
  const playbackUrl = `https://api.shelbynet.shelby.xyz/v1/blobs/${account}/${blobName}`;

  return (
    <VideoPlayer src={playbackUrl} poster="/thumbnail.jpg" title="My Video" />
  );
}

Configuring Shaka Player

The player is powered by Shaka Player for adaptive streaming. Pass Shaka configuration through the config prop to customize streaming behavior:

<VideoPlayer
  src={playbackUrl}
  title="My Video"
  config={{
    abr: {
      enabled: true,
      defaultBandwidthEstimate: 2_000_000, // 2 Mbps
    },
    streaming: {
      bufferingGoal: 30, // seconds
      rebufferingGoal: 2,
    },
  }}
/>

Common Configuration Options

Option	Description
`abr.enabled`	Enable/disable adaptive bitrate
`abr.defaultBandwidthEstimate`	Initial bandwidth estimate (bps)
`streaming.bufferingGoal`	Seconds of content to buffer ahead
`streaming.rebufferingGoal`	Seconds to buffer when rebuffering

For the full list of configuration options, see the Shaka Player Configuration documentation.

Accessing Shaka Player Directly

For advanced use cases, use the useShaka hook to access the Shaka Player API:

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

function CustomControls() {
  const player = useShaka();

  const tracks = player?.getVariantTracks() ?? [];
  const currentTrack = tracks.find((track) => track.active);

  return <div>Current quality: {currentTrack?.height}p</div>;
}

Playing a Video