#PlayerJS compatibility

For pages written against PlayerJS, the UMD bundle exposes a compatible Playerjs constructor. It covers the PlayerJS option names below, the api(command, argument) interface, the global PlayerjsEvents callback, DOM events, PlayerjsAsync, ready, and the iframe postMessage protocol.

<div id="player"></div>
<script>
  // Optional PlayerJS-style hooks; define them before the bundle loads.
  function PlayerjsEvents(event, id, data) {
    if (event === 'end') console.log(id, 'finished');
  }
  function PlayerjsAsync() {
    window.player = new Playerjs({
      id: 'player',
      file: '[360p]https://cdn/360.mp4,[720p]https://cdn/720.mp4',
      title: 'My video',
      subtitle: '[English]https://cdn/en.vtt',
      default_quality: '360p',
      color1: '#22c55e',
      ready: 'onPlayerReady',
    });
  }
  function onPlayerReady(id) {
    player.api('seek', 10);
  }
</script>
<script src="https://cdn.jsdelivr.net/npm/composable-video-player@0.1/dist/player.umd.js" defer></script>

You can also call new Playerjs({...}) directly in a script that runs after the bundle. In ES modules: import { Playerjs } from 'composable-video-player'.

new Playerjs(options) returns an object with:

• api(cmd, arg?): the PlayerJS API (below);
• player: the underlying typed Player (player.player.on('time', …), player.player.command(...)).

It always installs defaultPlugins() and uses the default layout, or a click-only layout with nocontrols.

#Options mapping

Flags accept true, 1, '1', or 'true'. Anything else is false. Non-numeric numbers are dropped. Any other option is ignored with a console warning. That includes options with no PlayerJS equivalent here (muted, speeds, hotkeys, …) and PlayerJS design options.

mapPlayerjsOptions(options, logger) is exported if you want to convert options yourself.

#API commands

player.api(command) reads a value. player.api(command, argument) sets it or runs an action. Unknown commands, and commands whose plugin is missing, log a warning and return undefined. The typed Player has the same api() method.

Flag arguments accept true, 1, '1', 'true', or 'on'.

#Events

Every public event is delivered three ways:

1. PlayerjsEvents(event, id, data), if a global function with that name exists when the event fires.
2. DOM events on the container: CustomEvent(event, { detail: data }). They don't bubble, so listen on the container itself.
3. postMessage to the parent window, when the bridge is enabled (below).

document.getElementById('player').addEventListener('time', function (e) {
  console.log('time', e.detail);
});

init is delivered in a microtask, so the handler can already use the variable that new Playerjs(...) was assigned to. Events fired in the same tick are queued behind it to keep the order.

Event names and payloads are the same as the typed events: init, start, new, metadata, play, userplay, pause, userpause, stop, end, finish, time, quartile, duration, seek, userseek, mute, unmute, volume, quality, audiotrack, subtitle, speed, fullscreen, exitfullscreen, resize, ui, buffering, buffered, loaderror, error, playlist, next, previous, line, destroy. The ui:* events are internal and are not forwarded.

#postMessage (iframes)

With postmessage: 1, a player running inside an iframe can be controlled by its parent page.

Player page (inside the iframe):

new Playerjs({ id: 'player', file: 'https://cdn/video.mp4', postmessage: 1, postmessageOrigin: 'https://parent.example' });

Parent page:

const frame = document.querySelector('iframe').contentWindow;
const PLAYER_ORIGIN = 'https://player.example';

frame.postMessage({ api: 'play' }, PLAYER_ORIGIN);
frame.postMessage({ api: 'seek', set: 30 }, PLAYER_ORIGIN);
frame.postMessage({ api: 'time' }, PLAYER_ORIGIN); // getter: answered below

window.addEventListener('message', (e) => {
  if (e.origin !== PLAYER_ORIGIN) return;
  const msg = e.data; // events: { event, id, data }; answers: { event: 'time', answer: 12.5, id }
  if ('answer' in msg) console.log(msg.event, '=', msg.answer);
  else console.log('event', msg.event, msg.data);
});

Protocol:

Security:

• Only messages whose source is window.parent are accepted.
• Set postmessageOrigin. With it, messages from other origins are ignored and events are posted only to that origin. Without it, any page that embeds the player can control it, events are posted with target '*', and the player logs a warning.

#Migrating from PlayerJS

1. Replace the PlayerJS script with player.umd.js (see CDN and builds). Keep your new Playerjs({...}), PlayerjsEvents, PlayerjsAsync, and api() calls.
2. Check the console. Options this player doesn't know are reported as Playerjs: unknown option "…" ignored.
3. Move design settings to theme variables and a layout. Only color1–color3 map directly.

#Differences from PlayerJS

• Language. new Playerjs() keeps PlayerJS's Russian UI by default. Pass lang: 'en' for English, or i18n to override individual labels:

  var player = new Playerjs({ id: 'player', file: 'video.mp4', lang: 'en' });
  

• speed is asymmetric. Reading returns the rate, and setting takes an index into the speeds list.

• Builder/design options of PlayerJS (styles, logos, ads, and other features not listed above) are not implemented.

• HLS uses hls.js 1.x from jsDelivr wherever MSE is available, and the browser's native HLS otherwise (details). DASH is not supported out of the box.

• Memory stores positions and preferences under vp:* keys in localStorage, so values saved by PlayerJS are not picked up.