@lightbird/player

@lightbird/player

A framework-agnostic <lightbird-player> Web Component — the LightBird video player as a standard custom element. Use it in Vue, Svelte, Angular, Solid, or plain HTML with no framework wrapper.

It is built on @lightbird/core: MP4/WebM play natively, while HLS streams and MKV files lazy-load the core engine (and FFmpeg.wasm, for MKV) only the first time they are needed.

Install

npm install @lightbird/player

Usage

Importing the package once registers the <lightbird-player> element:

import '@lightbird/player';

<lightbird-player
  src="https://example.com/video.mp4"
  controls
  poster="cover.jpg"
></lightbird-player>

That is the whole API surface for a basic player. For HLS or MKV, just point src at a .m3u8 or .mkv URL — the element loads the right engine itself.

Attributes & properties

SubtitleSource is { src, label?, srclang?, default? }. .vtt files are used directly; .srt files are converted to VTT automatically.

The styled control bar is themeable via the --lb-accent CSS custom property and exposes a controls CSS part, e.g.:

lightbird-player { --lb-accent: #e91e63; }
lightbird-player::part(controls) { padding-bottom: 16px; }

Read-only / live properties: duration, paused, ended. Read-write: currentTime, volume, playbackRate. mediaElement exposes the underlying <video>. Methods: play(), pause().

Events

The element re-dispatches the standard media events as CustomEvents: loadedmetadata, canplay, play, playing, pause, timeupdate, seeking, seeked, waiting, ended, ratechange, volumechange, durationchange, and error.

Each event's detail carries a snapshot: { currentTime, duration, paused, volume, muted, playbackRate }. The error event additionally includes an error message string.

const player = document.querySelector('lightbird-player');
player.addEventListener('timeupdate', (e) => {
  console.log(e.detail.currentTime, '/', e.detail.duration);
});

Styling

The player uses Shadow DOM for style encapsulation. Style the inner video via the video part:

lightbird-player::part(video) {
  border-radius: 12px;
}

Framework examples

Working examples live in examples/: plain HTML, Vue, and Svelte. Custom elements are first-class in every modern framework — bind attributes and listen for events exactly as you would for a <video>.

License

MIT