@scarlett-player/native

Native video playback plugin for Scarlett Player. Supports MP4, WebM, MOV, MKV, and OGV formats.

Docs: scarlettplayer.com/documentation · For AI coding agents: llms.txt (index) and llms-full.txt (every guide as one Markdown file)

Installation

npm install @scarlett-player/core @scarlett-player/native

Usage

import { createPlayer } from '@scarlett-player/core';
import { createNativePlugin } from '@scarlett-player/native';

const player = await createPlayer({
  container: document.getElementById('player'),
  src: 'https://example.com/video.mp4',
  plugins: [createNativePlugin()],
});

Supported Formats

Video:

• MP4 / M4V - H.264/AAC (most common)
• WebM - VP8/VP9/Opus
• MOV - QuickTime (H.264/AAC)
• MKV - Matroska (browser support varies)
• OGV/OGG - Theora/Vorbis

Audio:

• MP3, WAV, OGG, FLAC, AAC, M4A, Opus, WebA (pairs with @scarlett-player/audio-ui and @scarlett-player/media-session for a full audio player)

The plugin claims a source by extension, then asks the browser whether it can play that MIME type, so an .mkv in a browser without Matroska support is declined rather than played into a black frame.

Seek state and events

On the media element's seeking event, the provider publishes its new currentTime before setting seeking: true, for both video and audio. State subscribers therefore see the seek target before the next timeupdate. It does not emit playback:seeking from that handler: that event is an incoming seek command and re-emitting it would loop. On completion it sets seeking: false and emits playback:seeked { time }. The analytics plugin uses this state transition to track native/element-driven seeks without duplicating recent player-requested seeks.

Configuration

createNativePlugin({
  preload: 'metadata',  // 'none' | 'metadata' | 'auto'
  loadTimeoutMs: 30000, // Load watchdog; 0 disables
});

Diagnostics

The plugin implements the optional getDiagnostics() hook for troubleshooting snapshots:

const native = player.getPlugin<INativePlugin>('native-provider');
const diag = native.getDiagnostics();

console.log(diag.readyState);   // HTMLMediaElement.readyState
console.log(diag.networkState); // HTMLMediaElement.networkState
console.log(diag.dimensions);   // { width, height } or null
console.log(diag.buffered);     // Bounded buffered time ranges (max 32)
console.log(diag.seekable);     // Bounded seekable time ranges (max 32)

Never exposes currentSrc, raw URLs or track locations.

License

MIT