Building a custom video player on the web can be a frustrating experience. You often find yourself wrestling with bulky, pre-packaged libraries that inject their own DOM elements, styles, and bloated UI components. If you just want complete control over your player's look and feel while relying on a solid streaming engine under the hood, your options are surprisingly limited.
That’s exactly why I built FleetPlayer.
FleetPlayer is a high-performance, framework-agnostic, and completely headless HLS video player engine built with TypeScript and Media Source Extensions (MSE).
Here is a look at what it does, why a "headless" approach matters, and how you can use it in your next project.
Why Headless?
In modern frontend development, the "headless" architecture has taken over UI components (think Headless UI or Radix). It separates the complex state management and business logic from the visual representation.
FleetPlayer brings this exact philosophy to video streaming. It handles the heavy lifting of fetching segments, parsing playlists, and pushing bytes to the video element, but it renders absolutely zero UI. You provide a standard
Key Features
HLS Support: Plays HTTP Live Streaming (HLS) streams seamlessly using native Media Source Extensions (MSE).
100% Headless Core: Zero UI dependencies. Build your own controls or wrap them in your favourite framework's UI library.
Web Worker Powered: Bandwidth estimation and segment fetching are handled entirely off the main thread, keeping your UI buttery smooth.
Adaptive Bitrate (ABR): Real-time, automatic quality switching based on the user's network throughput.
Native Fallback: Automatically detects and switches to the browser's native HLS pipeline on iOS and Safari for maximum compatibility.
TypeScript-First: Shipped with full type definitions for a superior, error-free developer experience.
Framework Agnostic: Works perfectly with React, Vue, Angular, Svelte, or vanilla JavaScript.
Getting Started
You can drop FleetPlayer into any project with a quick NPM install:
npm install fleetplayer
Example 1: Vanilla JavaScript
Because it's framework-agnostic, initialising the player in standard JavaScript is incredibly straightforward:
<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 player.load("https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"); </script>
Example 2: React Integration
Using FleetPlayer in a React environment is just as easy as using standard refs and the useEffect hook.
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_HLS_STREAM_URL.m3u8"); } return () => { // Clean up internal resources and web workers playerRef.current?.destroy(); }; }, []); return ( <video ref={videoRef} controls style={{ width: "100%" }} /> ); }; export default VideoPlayer;
Powerful API for Custom Experiences
Because you are building your own UI, you need access to the player's internal data. FleetPlayer provides a clean API to build advanced features:
player.setQuality(levelIndex): Build a custom quality-selector menu for your users. Press -1 to re-enable Auto (ABR) mode.
player.getStats(): Returns real-time performance data (buffered ranges, current bitrate, active quality level). Perfect for building an "Stats for Nerds" overlay!
Try It Out!
If you are building a custom VOD platform, a streaming application, or just want to break free from rigid video player libraries, give FleetPlayer a spin.
📦 NPM: https://www.npmjs.com/package/fleetplayer
I'm actively maintaining this and would love to hear your thoughts, feature requests, or see the custom UIs you build with it! Let me know in the comments below.
Top comments (0)