Skip to content

VisionPlayer Documentation

License Version JSDoc npm package minimized gzipped size

VisionPlayer Logo

VisionPlayer

The VisionPlayer by alphanull is a highly modular, lightweight, and feature-rich JavaScript media player for the modern web. Designed as a flexible component system, the player allows for deep customization, simple integration, and full control over both appearance and functionality. Whether you're building a minimal player for a single video or a complex interface supporting multilingual, multi-quality streaming with overlays and playlist management — this player adapts to your needs.

Features

  • Fully modular architecture — Components can be easily added, removed, or replaced without modifying the core, with nearly 50 components already provided.
  • Native HTML5 video support — Plays MP4, WebM, and other browser-supported formats.
  • Multi-language and multi-quality stream selection — Each stream can offer multiple languages, resolutions, and encodings. Quality can be automatically selected depending on screen resolution.
  • Streaming support — DASH and HLS support, both VOD and Live Streaming, fully integrated into the player UI including subtitles, audio and quality selection.
  • FairPlay, Widevine, and PlayReady DRM — Encrypted media playback for premium content.
  • Chromecast and AirPlay — External device playback handling with full UI synchronization.
  • Playback Controls — Play/pause, scrubber, volume, playback rate, fullscreen, loop and more.
  • Playlist Management — Seamless navigation between multiple media items, with optional shuffle and loop modes.
  • Subtitle support — WebVTT rendering with support for positioning, all writing modes and built in HTML sanitiser, TTML (IMSC1/EBU-TT-D) handling, and native <track> integration for iOS compatibility.
  • Dynamic Overlays — Posters, images and other content at defined cue points.
  • Thumbnails — Display thumbnails in the scrubber tooltip or use them for a special scrubbing mode.
  • Chapters — Display Chapters in the controller or scrubber tooltip.
  • Picture-in-Picture — Play video in a separate overlay window.
  • Picture and Audio Controls — Adjust video brightness, contrast, and more, or fine-tune your audio with a multiband equalizer.
  • Advanced Accessibility — Comprehensive accessibility features including Picture & Audio Controls for visual/auditory impairments, keyboard navigation, and screen reader support.
  • Local playback — Play local media by selecting or dragging and dropping files.
  • Audio and Video Visualizations — Including bar visualizer, ambient light effects, and waveform displays.
  • Extensive Media Data Format — With support for extensible metadata and multiple media variants, representations, and encodings.
  • Extended Localization — Builds includes the following out‑of‑the‑box UI translations: English, German, Spanish, Portuguese, French, Italian, Russian, Chinese (Simplified), Japanese, Korean, Hindi, Arabic & Turkish.
  • Scalable, responsive UI — UI intelligently adapts to every player size, UI scale factor is dynamically changeable by the user.
  • Theme support — Built-in dark and light modes, with CSS custom properties for full theming flexibility.
  • Easy Embedding — Supports converting existing video tags and any other elements with data-vip attributes, optionally with autoloading.
  • Minimal global footprint — Only one exported class (VisionPlayer), with everything else modular and encapsulated.
  • Single, zero dependency bundle File — VisionPlayer bundles all code, styles, SVG assets and language files into a zero-dependency single build artifact – making integration seamless.
  • Optimized Performance — GPU-accelerated transitions, minimal reflows, and efficient DOM updates.
  • Security Features — Optional Secure Mode with Shadow DOM, API protection and XSS prevention.
  • 1-Minute Setup — Get from npm install to working demo in under 60 seconds with vite dev server.

Screenshot

screenshot

Demo

Just hop over to visionplayer.io to take a test drive or watch some feature demos. The documentation is also available there.

Installation

Install using npm

npm install @alphanull/visionplayer

Import

import VisionPlayer from '@alphanull/visionplayer'; // Default - full feature set
import VisionPlayerBasic from '@alphanull/visionplayer/basic'; // Basic - core features only
import VisionPlayerHeadless from '@alphanull/visionplayer/headless'; // Headless - no UI components
import VisionPlayerSecure from '@alphanull/visionplayer/secure'; // Secure - maximum security features

This imports the .mjs versions (found in /dist/mjs). Those act as as modules, exporting the main VisionPlayer class. These build versions are not minified - assuming you will do this yourself in the build process - and also include source maps for easier debugging, if necessary. Importing this way is optimal if you want to incorporate the player as a single packaged module in your own code.

Use as script

To directly embed the player using a <script> tag, use either the .js Version of the build (found in /dist/js). This version is minified and self executing, exposing a global window.VisionPlayer object. Or, just include the file directly from a CDN:

<script src="/dist/js/VisionPlayer.min.js"></script> <!-- default build -->
<script src="https://unpkg.com/@alphanull/visionplayer@1/dist/VisionPlayer.basic.min.js"></script> <!-- basic build -->
<script src="https://cdn.jsdelivr.net/npm/@alphanull/visionplayer@1/dist/VisionPlayer.secure.min.js"></script> <!-- secure build -->

For full setup instructions, see the Setup Documentation.

Examples

Basic usage

import VisionPlayer from '@alphanull/visionplayer';
new VisionPlayer(document.body, '/path/to/media.mp4');

Or via script tag and autoload:

<script data-vip-autoload src="/dist/js/VisionPlayer.min.js"></script>
<video data-vision-player controls src="/path/to/media.mp4"></video>

With mediaData object

const mediaData = {
    title: 'My Video',
    src: '/path/to/media.mp4'
};

new VisionPlayer(target, mediaData);

With custom playerConfig

const playerConfig = {
    ui: {
        autoHide: false
    }
};

new VisionPlayer(target, mediaData, playerConfig);

Documentation

Additional docs cover the following topics:

In addition, a detailed JSDoc documentation covering all modules and their methods, members and events can be generated using npm run doc, which then will reside in /docs/jsdoc. This generated documentation can also be accessed via the microsite: VisionPlayer JSDoc

Browser Support

VisionPlayer supports all major browsers on all platforms (i.e. macOS, iOS, Windows, Android & Linux) released since ~2019-2020 and later, including Chrome (v79+), Firefox (v75+) and Safari (v13+). Note: The Secure Build requires native ES2022 support.

Known Issues

  • Sharpen Video Filter does not work on Safari - see https://bugs.webkit.org. Not solvable unless Apple gets its act together - and it is generally recommended to use a "proper" browser anyways, like Firefox or Chrome.

  • If the ambient visualizer is enabled (as in the demo), you may get the warning Canvas2D: Multiple readback operations using getImageData are faster with the willReadFrequently attribute set to true. Actually, with that setting enabled, performance gets worse (up to five times!) on both a windows and a mac laptop. However, an Android tablet showed better performance with this setting, while an iPad did not show much difference. Not sure why exactly this is the case - seems like different rendering pipelines are triggered - and what would be the best heuristics to select the optimal setting. So for now, willReadFrequently is disabled until the situation is resolved.

License

MIT License

Copyright © 2025–present Frank Kudermann @ alphanull.de