Video Player

Installation

There is a single registry item, @videocn/player. The CLI copies its source into your project: the code is yours.

1. Declare the registry

In your project's components.json:

{
  "registries": {
    "@videocn": "https://videocn.dev/r/{name}.json"
  }
}

2. Install the player

pnpm dlx shadcn@latest add @videocn/player

Or skip step 1 and install straight from the URL:

pnpm dlx shadcn@latest add https://videocn.dev/r/player.json

What the CLI adds

• The player files, in components/ui/video-player/ (your ui alias).
• The npm dependencies shaka-player, cn and lucide-react.
• The shadcn button component, if you don't have it yet.
• Two CSS variables, --player-scrim and --player-backdrop, for the gradient under the controls and the frame around the video.

Usage

Import the component and give it a source.

import { VideoCn } from "@/components/ui/video-player/video-cn"

export function Demo() {
  return <VideoCn src="/clip.mp4" />
}

Adjust the import path if your ui alias differs. Everything else is a prop: you never have to edit the files you received.

Examples

Chapters

Pass a list of { time, label }, with time in seconds. Chapters split the progress bar into segments and fill a menu.

chapters

const chapters = [
  { time: 0, label: "Prologue" },
  { time: 100, label: "The village" },
  { time: 210, label: "Searching for Scales" },
  { time: 350, label: "The shaman's tale" },
  { time: 490, label: "Crossing the mountains" },
  { time: 640, label: "The lair" },
  { time: 770, label: "The duel" },
  { time: 830, label: "Credits" },
]

<VideoCn
  src="https://archive.org/download/Sintel/sintel-2048-stereo.mp4"
  poster="/examples/sintel-poster.jpg"
  chapters={chapters}
/>

Copy

• A chapter ends where the next one starts. The last one ends with the video.
• The first chapter always starts at 0, whatever time you give it.
• Order does not matter. Duplicate times keep the first entry. Empty labels and times outside the video are dropped.
• Chapters have no effect on a live stream.

Without chapters, the chapter menu is not rendered at all. controls.chapters: false removes the menu, and controls.scrubber: { chapters: false } keeps the bar in one piece while leaving the menu in place.

<VideoCn
  src="https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"
  type="hls"
/>

<VideoCn
  src="https://cdn.example.com/stream?token=abc123"
  type="hls"
/>

<VideoCn src="https://demo.unified-streaming.com/k8s/live/stable/scte35.isml/.m3u8" />

Poster

An image shown until playback starts. Without one, the player shows the first frame, often black.

poster

<VideoCn
  src="https://archive.org/download/Tears-of-Steel/tears_of_steel_1080p.webm"
  poster="/examples/tears-of-steel-poster.jpg"
/>

Copy

Configured controls

No Picture-in-Picture, three speeds instead of seven, a bar that hides after one second, no keyboard shortcuts, and chapters kept out of the progress bar.

controls

<VideoCn
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="/examples/big-buck-bunny-poster.jpg"
  chapters={chapters}
  controls={{
    pictureInPicture: false,
    playbackRate: { rates: [1, 1.5, 2] },
    autoHideDelay: 1000,
    keyboard: false,
    scrubber: { chapters: false },
  }}
/>

Copy

Square corners

The radius follows --radius everywhere: frame, menus, progress bar, volume slider and Live badge. Here it is set on a wrapper; in your app, set it on :root.

--radius: 0

globals.css

:root {
  --radius: 0;
}

Copy

<VideoCn
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="/examples/big-buck-bunny-poster.jpg"
  chapters={chapters}
/>

Copy

Some shadcn styles, such as lyra and sera, hard-code square corners in each component instead of setting --radius. With those styles, set it yourself. The rest of your project does not read it, so nothing else changes.

Custom palette

The player has no colors of its own: these are your theme tokens. Change them and the progress bar, focus rings and menus follow, in light and dark mode.

--primary

globals.css

:root {
  --primary: oklch(0.488 0.243 264.376);
  --primary-foreground: oklch(0.97 0.014 254.604);
  --accent: oklch(0.932 0.032 255.585);
  --accent-foreground: oklch(0.379 0.146 265.522);
  --ring: oklch(0.623 0.214 259.815);
}

.dark {
  --primary: oklch(0.623 0.214 259.815);
  --primary-foreground: oklch(0.97 0.014 254.604);
  --accent: oklch(0.379 0.146 265.522);
  --accent-foreground: oklch(0.97 0.014 254.604);
  --ring: oklch(0.488 0.243 264.376);
}

Copy

<VideoCn
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="/examples/big-buck-bunny-poster.jpg"
  chapters={chapters}
/>

Copy

API Reference

Props

<VideoCn> takes no children. The control bar is always the player's own, driven by the props below.

Controls

Every option of controls is boolean | options. Missing or true, the control is there with its defaults. false, it is gone. An object, it is there and configured.

Keyboard shortcuts

Active once the player has focus: one click on the picture is enough. On a focused slider, seek or volume, the arrows drive that slider.

Shortcuts are ignored while focus is in an input, a textarea, a select or an editable element. If your app already has its own, turn them off with controls={{ keyboard: false }}.

Theming

The player reads your shadcn tokens. It has no hard-coded colors, so light and dark mode work without configuration. See Square corners and Custom palette.

Two variables are the player's own, added by the CLI: --player-scrim for the gradient under the controls and --player-backdrop for the frame around the video.

Bundle size

Measured, not estimated.

The core excludes React, lucide-react, cn and the shadcn button, which your app already ships. Shaka is a separate chunk, never downloaded for an MP4.

shaka-player is still listed in the dependencies, so it is installed in every project. This is deliberate: a dynamic import of a missing package breaks the build, not just the runtime. It sits in node_modules, not in your bundle.

Accessibility

• The progress bar and volume are role="slider" elements with a label and a readable value, such as a time or a percentage.
• Every button has a label. Play, mute and fullscreen announce their shortcut with aria-keyshortcuts.
• A click on the video gives the player focus without adding it to the tab order, and without drawing an outline. Keyboard focus inside the bar keeps its focus ring.