FleetPlayer 🚀

A high-performance, framework-agnostic, and headless HLS video player engine built with TypeScript and Media Source Extensions (MSE).

FleetPlayer is designed to be lightweight and modular, providing a powerful streaming core while giving developers complete control over the UI.

✨ Features

HLS Support: Play .m3u8 streams using Media Source Extensions (MSE).
Native Fallback: Automatically switches to the browser's native HLS pipeline (e.g., Safari, iOS) for maximum compatibility.
Adaptive Bitrate (ABR): Real-time quality switching based on measured network throughput.
Headless Core: No UI dependencies. Build your own controls or use a wrapper.
Web Worker Powered: Bandwidth estimation and segment fetching handled off the main thread.
TypeScript First: Full type definitions included for a superior developer experience.
Framework Agnostic: Works seamlessly with React, Vue, Angular, Svelte, or Vanilla JavaScript.

📦 Installation

npm install fleetplayer

🚀 Quick Start

1. Basic Usage (Vanilla JS)

<video id="my-video" controls></video>

<script type="module">
  import { FleetPlayer } from 'fleetplayer';

  const videoElement = document.getElementById('my-video');
  const player = new FleetPlayer(videoElement, {
    autoStart: true
  });

  // Load an HLS stream
  await player.load('https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8');
</script>

2. Usage in React

import React, { useEffect, useRef } from 'react';
import { FleetPlayer } from 'fleetplayer';

const VideoPlayer = () => {
  const videoRef = useRef<HTMLVideoElement>(null);
  const playerRef = useRef<FleetPlayer | null>(null);

  useEffect(() => {
    if (videoRef.current) {
      playerRef.current = new FleetPlayer(videoRef.current);
      playerRef.current.load('your-stream-url.m3u8');
    }

    return () => {
      playerRef.current?.destroy();
    };
  }, []);

  return <video ref={videoRef} controls style={{ width: '100%' }} />;
};

🛠️ API Reference

`new FleetPlayer(videoElement, config?)`

Initializes a new player instance.

videoElement: The HTMLVideoElement to attach to.
config: (Optional) { autoStart?: boolean }

`player.load(url: string): Promise<void>`

Parses the manifest and prepares the player for playback.

`player.play() / player.pause()`

Standard playback controls.

`player.setQuality(levelIndex: number)`

Manually set the quality level.

levelIndex: The index of the level from getStats().levels.
Pass -1 for Auto ABR (default).

`player.getStats()`

Returns an object containing real-time performance data:

{
  buffered: [{ start: number, end: number }],
  bitrate: number, // Current bitrate in bps
  level: number,   // Current quality level index
  levels: [...]    // Available quality levels
}

`player.destroy()`

Cleans up internal resources, stops workers, and resets the video source.

fleetplayer