LIGHTBIRD

Why LightBird?

Installation

npm install @lightbird/core @lightbird/player-react

"use client"
import { LightBirdPlayer } from '@lightbird/player-react'

export default function VideoPage() {
  return <LightBirdPlayer />
}

All Features

API Reference

// Player factory
createVideoPlayer(
  file: File,
  subtitleFiles?: File[],
  onProgress?: (n: number) => void
): VideoPlayer

interface VideoPlayer {
  initialize(videoElement: HTMLVideoElement): Promise<ProcessedFile>
  getAudioTracks(): AudioTrack[]
  getSubtitles(): Subtitle[]
  getChapters?(): Chapter[]
  switchAudioTrack(trackId: string): Promise<void>
  switchSubtitle(trackId: string): Promise<void>
  destroy(): void
  cancel?(): void
  tracksReady?: Promise<void>
}

// Utilities
validateFile(file: File): { valid: boolean; reason?: string }
parseMediaError(error: MediaError): ParsedMediaError
configureLightBird({ ffmpegCDN: string }): void

Web Component — @lightbird/player

The <lightbird-player> custom element wraps @lightbird/core as a framework-agnostic Web Component — usable in Vue, Svelte, Angular, Solid, or plain HTML with no React dependency. It uses Shadow DOM for style encapsulation and lazy-loads the core engine (and FFmpeg.wasm, for MKV) only when an HLS or MKV source is first encountered.

<!-- Register the element once, anywhere in your app -->
<script type="module">
  import '@lightbird/player';
</script>

<!-- Then use it like any other element -->
<lightbird-player
  src="video.mp4"
  controls
  poster="cover.jpg"
></lightbird-player>

Bundle Size

LightBird's “lightweight” promise is enforced, not assumed. The base @lightbird/core entry contains zero FFmpeg.wasm code — FFmpeg is reached only through a dynamic import() and a lazily-created Web Worker. An app that only plays MP4/WebM downloads none of the multi-megabyte FFmpeg payload. A CI bundle-size budget fails the build if the base entry grows past its threshold or regains a static FFmpeg import.

Sizes are gzipped transfer sizes measured from the latest build.

Browser Support

MKV playback requires Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp headers.