Vibe Player

Video players are easy, right up until they are not.

vibe-player is a cinematic React player package for teams that want polished playback without inheriting someone else's product app. Files, HLS, YouTube iframe playback, compliant YouTube external handoff, captions, keyboard shortcuts, volume, quality, PiP, fullscreen, tooltips, and a clean headless path all live behind one provider-agnostic API.

Built by Vibe Code. Say hi at [email protected].

Install

npm install vibe-player
pnpm add vibe-player
bun add vibe-player

import "vibe-player/styles.css";
import { VibePlayerStage } from "vibe-player";

export function Film() {
  return (
    <VibePlayerStage
      source={{
        id: "launch-film",
        manifestUrl: "https://example.com/video/master.m3u8",
        posterUrl: "https://example.com/video/poster.jpg",
        title: "Launch film",
        type: "hls",
      }}
    />
  );
}

What You Get

• direct MP4/WebM playback through native video
• adaptive HLS through managed hls.js, with native fallback
• official YouTube iframe playback
• compliant YouTube external handoff when iframe chrome is the wrong answer
• package-owned controls, timeline, captions, volume, quality, PiP, fullscreen
• keyboard shortcuts and real tooltips instead of browser-default mystery meat
• exported controller, volume, and quality helpers for custom/headless UI
• ambient preview primitives and a neutral cinematic skin
• media delivery audit CLI for catching bad MP4/CDN/CORS decisions early

Docs

• Usage Guide: setup, sources, autoplay, audio, captions, headless controls, demo, and media audit.
• Integration Guide: app contract, media rules, CORS, hooks, and replacement checklist.
• Media Delivery Audit: CLI output, CI mode, rollout decisions, CORS credentials, and size policy.
• Contributing: repo rules, PR shape, tests, and API changes.

Local Demo

bun run demo:vite
bun run demo:vite:packaged

The demo exercises file, HLS, YouTube iframe, and YouTube external handoff modes through the real package player. No pretend product shell required.

Media Audit

npx --package vibe-player vibe-player-media-audit https://cdn.example.com/video.mp4 --origin https://app.example.com

Use this before blaming the player for a slow, frozen, non-faststart, CORS-bent MP4. The CLI checks range delivery, MP4 moov/mdat ordering, CORS, size, and direct-file rollout readiness.

Sponsor

If Vibe Player saves you from writing this stack again, consider sponsoring Vibe Code: github.com/sponsors/vcode-sh

License

Apache-2.0