# bobine docs

> The media player your browser should have shipped. Swap `<video>` for `<VideoPlayer>`. Same props and calmer controls. The shadcn CLI puts the source in your repo, so you own every line.

## Install

```bash
npx shadcn@latest add https://bobine.fyi/r/video-player.json
```

# Getting started

## Video

Every attribute you would put on a native video element works unchanged. Controls fade away while it plays and return the moment you move.

```tsx
import { VideoPlayer } from "@/components/ui/video-player"

<VideoPlayer
  src="/clip.mp4"
  poster="/clip.jpg"
  tracks={[{ src: "/clip.en.vtt", label: "English", srcLang: "en" }]}
  persistKey="bobine"
/>
```

## Audio

Built from the same parts and styled with your theme tokens, so it matches your app in light and dark mode.

```bash
npx shadcn@latest add https://bobine.fyi/r/audio-player.json
```

```tsx
import { AudioPlayer } from "@/components/ui/audio-player"

<AudioPlayer src="/episode.mp3" title="Episode 12" description="Field notes" />
```

## Or install the package

Prefer a dependency over owning the source? The same components ship as bobine, with a framework-agnostic core.

```bash
pnpm add bobine
```

```tsx
/* globals.css */
@import "tailwindcss";
@import "bobine/styles.css";

import { VideoPlayer, AudioPlayer } from "bobine"
import { hlsLoader } from "bobine/hls"
import { createMediaStore } from "bobine/core"
```

## Use with agents

Install the bobine skill so your coding agent knows the components, props and pitfalls. The full docs are also plain text at /llms-full.txt.

```bash
npx skills add SanyamPunia/bobine
```

Or paste this prompt into an agent to install bobine in a project.

```text
Add bobine media players to this React project.

1. Read https://bobine.fyi/llms-full.txt for the full bobine docs before you change code.
2. Install the video player with the shadcn CLI:
   npx shadcn@latest add https://bobine.fyi/r/video-player.json
   For audio, also run: npx shadcn@latest add https://bobine.fyi/r/audio-player.json
   For HLS streams, also run: npx shadcn@latest add https://bobine.fyi/r/media-hls.json
3. Replace each <video controls> element with <VideoPlayer> from "@/components/ui/video-player". Keep src, poster, tracks and the other native props. Remove the controls attribute.
4. Replace each <audio controls> element with <AudioPlayer> from "@/components/ui/audio-player" in the same way.
5. For .m3u8 sources, pass loader={hlsLoader} from "@/lib/media-hls" in a client component.
6. Do not restyle the installed components unless I ask. They use the project's shadcn theme tokens.
```

# Guides

## Compose your own

Both players are a few lines on top of unstyled primitives. Rearrange them, restyle them, or add what you need.

```bash
npx shadcn@latest add https://bobine.fyi/r/media.json
```

```tsx
<MediaRoot className="aspect-video bg-media-scrim text-media-foreground">
  <MediaVideo src="/clip.mp4" className="size-full object-cover" />
  <MediaSurface />
  <MediaControls className="absolute inset-x-3 bottom-3 flex-col gap-1">
    <MediaSeek />
    <div className="flex items-center gap-1">
      <MediaPlayButton />
      <MediaMuteButton />
      <MediaVolume />
      <MediaTime /> / <MediaTime type="duration" />
      <span className="grow" />
      <MediaPlaybackRateButton />
      <MediaPictureInPictureButton />
      <MediaFullscreenButton />
    </div>
  </MediaControls>
</MediaRoot>
```

## Streaming

Pass a loader for adaptive streams. Safari plays HLS natively. Other browsers fetch hls.js only when an .m3u8 source appears.

```bash
npx shadcn@latest add https://bobine.fyi/r/media-hls.json
```

```tsx
"use client"
import { VideoPlayer } from "@/components/ui/video-player"
import { hlsLoader } from "@/lib/media-hls"

<VideoPlayer src="https://example.com/stream.m3u8" loader={hlsLoader} />
```

## Custom loaders

A loader attaches a source the browser cannot play natively, such as DASH. When you pass one, bobine leaves src off the element, so the loader must set media.src itself for any source it does not handle. Return a cleanup function. It runs when src changes or the player unmounts.

```ts
import type { MediaSourceLoader } from "@/components/ui/media"

export const dashLoader: MediaSourceLoader = (media, src) => {
  if (!src.endsWith(".mpd")) {
    // not a DASH source: hand it to the browser
    media.src = src
    return () => media.removeAttribute("src")
  }
  const player = attachYourDashPlayer(media, src)
  return () => player.destroy()
}
```

## Theming

The players read your shadcn theme tokens (background, foreground, muted, primary, border), so they follow your light and dark mode. Video controls use two more tokens that stay the same in both modes. Requires React 19 and Tailwind CSS 4.

```css
/* globals.css: constant across light and dark */
:root {
  --media-foreground: oklch(1 0 0); /* icons and text over video */
  --media-scrim: oklch(0 0 0); /* video ground and control glass */
}
```

# Reference

## API

Each player takes every native prop of the element it wraps, except controls. These are the extra props.

### VideoPlayer

| Prop | Type | Description |
| --- | --- | --- |
| `className` | `string` | Classes for the <video> element itself. |
| `frameClassName` | `string` | Classes for the outer frame. Use this for size, radius and placement. |
| `tracks` | `VideoTrack[]` | WebVTT caption or subtitle files: { src, label, srcLang, kind?, default? }. |
| `loader` | `MediaSourceLoader` | Adapter for sources the browser cannot play natively, such as HLS. |
| `metadata` | `MediaInfo` | Title, artist, album and artwork for lock screens and OS media controls. |
| `persistKey` | `string` | Remember volume, mute and speed in localStorage under this key. |
| `tooltips` | `boolean` | Small labels with their shortcut over the controls on hover and focus. On by default. |

### AudioPlayer

| Prop | Type | Description |
| --- | --- | --- |
| `title` | `ReactNode` | The main line beside the controls. |
| `description` | `ReactNode` | The muted line after the title. |
| `artwork` | `string` | Cover image beside the controls and in OS media controls. |
| `showSpeed` | `boolean` | Show a playback speed toggle, for podcasts and voice notes. |
| `tooltips` | `boolean` | Same as on VideoPlayer. On by default. |
| `frameClassName` | `string` | Classes for the outer frame. className targets the <audio> element. |
| `loader` | `MediaSourceLoader` | Same as on VideoPlayer. |
| `metadata` | `MediaInfo` | Overrides the metadata built from title, description and artwork. |
| `persistKey` | `string` | Same as on VideoPlayer. |

## Parts

Everything is exported from `components/ui/media.tsx`.

- `MediaRoot`: Owns the store. Exposes data-paused, data-started, data-waiting, data-idle, data-fullscreen.
- `MediaVideo / MediaAudio`: The native element. Every native prop passes through.
- `MediaSurface`: Full-bleed click target. First tap on touch reveals controls.
- `MediaControls`: Reveals on pointer activity, pause, or keyboard focus.
- `MediaSeek / MediaVolume`: Accessible sliders with scrubbing, buffering and keyboard steps. MediaVolume takes orientation="vertical" for a popover.
- `MediaTime`: current, duration or remaining. toggle lets a click switch to remaining time and back.
- `MediaButton`: The base button the others are built from. Use it for your own controls.
- `Media*Button`: MediaPlayButton, MediaMuteButton, MediaCaptionsButton, MediaFullscreenButton, MediaPictureInPictureButton, MediaPlaybackRateButton.
- `MediaSettings`: Speed and caption track menu.
- `MediaCaptions`: Renders the active cue with your styles instead of the browser's.
- `MediaLoading / MediaErrorMessage`: Buffering indicator and a retryable error state.
- `useMedia(selector)`: Subscribe to any slice of state. Re-renders only when it changes.
- `useMediaStore()`: Imperative access: play, seek, setVolume, setTextTrack and more.

## Keyboard

Shortcuts apply to the focused player only, so several can live on one page.

| Keys | Action |
| --- | --- |
| Space, K | Play or pause |
| J, L | Seek 10 seconds |
| Left arrow, Right arrow | Seek 5 seconds |
| Up arrow, Down arrow | Volume |
| 0, 9 | Jump to 0–90% |
| Home, End | Start or end |
| M | Mute |
| C | Captions |
| I | Picture-in-picture |
| F | Fullscreen |