API

This document outlines the core design principles behind the VisionPlayer API. It explains key methods and special behaviors in detail, and finally provides a consolidated overview of all core API calls.

API Namespaces

While the core API of the Player class itself is directly available on the instance, APIs provided by component are typically using their own namespace. For example, the media API is available under the namespace media so media related functions use the signature media.play, media.loop etc. As the player API is dynamic and can be extended by any component, this minimises nameclashing and ensures better scalability and maintainability.

The VisionPlayer components use the following namespaces:

• player - core player API (addComponent, setConfig)
• player.media - all media‐related operations (load, play, pause…)
• player.data - loading and parsing of mediaData
• player.dom - Access to the players root element
• player.ui - UI‐control (show, hide, autoHide…)
• player.audio - audio operations (getAudioContext, add or remove audio nodes)

Instance vs. Static API

The VisionPlayer API is divided into two categories:

Instance API

• The majority of the VisionPlayer API functions operate on a specific player instance.
• You call them on an instance you have created. Example:

const vip = new VisionPlayer(...);
vip.getConfig('media');
vip.media.play();
vip.ui.show();

Static API

• These functions are called directly on the Player class.

• They typically only have effect before creating new instances.

• They typically affect global player behavior, manage shared resources (such as global styles or locale data), or provide system-wide information. Example:

Player.addComponent(...);
Player.setGlobalConfig(...);

Some data (like global style sheets or supported codecs) are also stored and managed centrally using static class members. This means changes apply to all player instances, not just one. If a function in the documentation starts with Player, it's part of the Static API. Otherwise, it belongs to the Instance API.

Asynchronous API

Some core API methods (media.load, setMediaData, setMediaIndex) are designed as async functions and always return a Promise. While you can call them just like regular methods, it is recommended to handle them as any other async function, i.e. use await, catch() etc. They will return some payload if executed and also throw exceptions in case something goes wrong.

Promise Reuse & Cancellation

If an asynchronous function is called repeatedly with the same arguments while a previous call is still pending, the previous call is not cancelled; instead, both calls resolve or reject identically with the same payload. However, if you call it with different arguments, the previous request is cancelled and its promise is rejected. Make sure to handle these cases correctly in your application logic.

Examples

// Start loading a video
const promise1 = player.media.load(( src: 'video.mp4' ));
// Another call with the same source while still pending
const promise2 = player.media.load(( src: 'video.mp4' ));
// -> Both promises resolve/reject identically with the same payload

// Cancellation example
const p1 = player.media.load(( src: 'video1.mp4' ));
const p2 = player.media.load(( src: 'video2.mp4' )); // cancels p1

p1.catch(e => (
    if (e.name === 'AbortError') (
        // Task was cancelled
    )
));

Always await or .catch() errors, including cancellations. If not handled, cancellation rejections will still propagate (and may show as uncaught Promise rejections).

Protected API Pattern with Symbols

VisionPlayer applies a protected API pattern by leveraging ES2022 Symbols. This ensures certain internal methods remain inaccessible to external scripts or manual invocation from the browser console.

From a users perspective, some API methods which may return sensitive data or objects, or allow a userland script to extend or modify the player are completely blocked when the players secureApi config is enabled. Usage of this API is restricted to components which are - and should be! - the only ones receiving the players' secret API key. For more information about security, see Security regarding API access control and best practices.

From a components perspective, those methods have to be called with the apiKey provided by the player at instantiation. Regardless of other optional arguments, the apiKey is always the last one.

Core API Overview

For more information about additional APIs from non-core components, consult the components documentation.

Player API

Data API

Dom API

Media API

Locale API

UI API

Audio API