Control the player

What the Player API is#

The Wolvy player lives in an iframe, which normally keeps your page and the player apart. With the Player API switched on, the two can talk: your page sends commands, and the player reports events. It is what you need to build:

• Your own buttons — a “Play lesson” button, a “Jump to chapter 3” link, keyboard shortcuts.
• Resume where they stopped — remember the position and go back to it.
• Course completion — mark a lesson done when a student has watched 90% of it.
• Your own analytics — play, pause and end events, next to the rest of your page’s events.

Nothing changes for viewers: it is the same player, with the same controls, protection and watermark.

Turn it on#

1. Switch it on for the accountIn the dashboard, open Settings → Player and turn on Player API. It is off by default, and it applies to every video on the account.
2. Embed as usualUse the normal iframe. Nothing is added to the embed URL.
3. Load the script on your pagehttps://embed.wolvy.stream/sdk/wolvy-player.js defines WolvyPlayer. It is about 8 KB and has no dependencies.

The player only listens to the page that embeds it — the same page the domain rules checked. Another site, another frame on your page, or a browser extension’s frame gets no answer.

Quick start#

<iframe
  id="lesson"
  src="https://embed.wolvy.stream/a1b2c3d4e5f60718293a/NDI=?vt=…"
  allow="autoplay; fullscreen; encrypted-media; picture-in-picture"
  allowfullscreen
  referrerpolicy="strict-origin-when-cross-origin"
></iframe>
<button id="play">Play</button>

<script src="https://embed.wolvy.stream/sdk/wolvy-player.js"></script>
<script>
  const player = new WolvyPlayer('#lesson');

  player.on('ready', ({ duration }) => {
    console.log('Player ready, the video is', duration, 'seconds long');
  });

  // play() must come from a click unless the player is muted
  document.querySelector('#play').addEventListener('click', () => {
    player.play().catch((error) => console.warn(error.code));
  });
</script>

import { useEffect, useRef } from 'react';

// Load https://embed.wolvy.stream/sdk/wolvy-player.js once, in your page <head>.
export function Lesson({ embedUrl, onProgress }) {
  const frame = useRef(null);

  useEffect(() => {
    const player = new window.WolvyPlayer(frame.current);
    player.on('progress', onProgress);
    return () => player.destroy();
  }, [embedUrl, onProgress]);

  return (
    <iframe
      ref={frame}
      src={embedUrl}
      allow="autoplay; fullscreen; encrypted-media; picture-in-picture"
      allowFullScreen
      referrerPolicy="strict-origin-when-cross-origin"
    />
  );
}

• new WolvyPlayer(iframe) takes the iframe element or a CSS selector. Create it any time: before or after the iframe has loaded.
• Every method returns a promise. Calls made before the player is ready wait for it.
• player.ready() resolves once the player can take commands, with its starting state.
• player.on(event, fn), player.off(event, fn) and player.once(event, fn) subscribe to events.
• player.destroy() stops listening. Call it when you remove the iframe.

Methods#

Control

Read

const player = new WolvyPlayer('#lesson');

await player.ready();

await player.setVolume(0.5);          // 0 to 1; does not unmute
await player.setPlaybackRate(1.5);    // 0.5, 0.75, 1, 1.25, 1.5 or 2

const { available } = await player.getQualities();   // e.g. [1080, 720, 480, 360]
if (available.includes(720)) await player.setQuality(720);
await player.setQuality('auto');

const captions = await player.getCaptions();         // { available: [{ language, label }], active }
if (captions.available.some((t) => t.language === 'ar')) await player.setCaptions('ar');
await player.setCaptions('off');

Each control method does exactly what the matching button in the player does, so the player’s own menus stay in step with your page.

Events#

Events fire whoever caused them: your page, the viewer using the player’s controls, or the player itself.

const KEY = 'lesson-42-position';
const player = new WolvyPlayer('#lesson');

// Remember where the viewer is (timeupdate arrives at most 4 times a second).
player.on('timeupdate', ({ currentTime }) => {
  localStorage.setItem(KEY, String(Math.floor(currentTime)));
});

// Go back there next time.
player.ready().then(() => {
  const saved = Number(localStorage.getItem(KEY));
  if (saved > 5) player.seek(saved);
});

Course completion#

The progress event answers “how much of this video has this viewer actually watched?”

• percent counts seconds that were played, each one once. Skipping to the end does not reach 100%, and replaying the first minute ten times counts as one minute.
• seconds is that count; duration is the video’s length.
• It is sent as the number changes, at most once a second, and once more when the video ends.
• It starts from zero on every page load. To add up a lesson across visits, store it on your side.

const player = new WolvyPlayer('#lesson');
let reported = false;

player.on('progress', async ({ percent }) => {
  if (reported || percent < 90) return;
  reported = true;

  // Your own endpoint. Decide completion on your server, for the signed-in student.
  await fetch('/lessons/42/complete', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ percent }),
  });
});

Errors#

A rejected promise carries an Error with a code. The error event carries the same kind of code, and nothing else.

try {
  await player.play();
} catch (error) {
  if (error.code === 'play_blocked') {
    // The browser wants a click first. Either wait for one, or:
    await player.mute();
    await player.play();
  } else {
    console.warn('Player refused:', error.code);
  }
}

// Something went wrong inside the player (it is already showing its own message).
player.on('error', ({ code }) => showFallback(code));

After an error event the read methods still answer, and the control methods reject with that error’s code.

Without the script#

The script is optional. Underneath, your page and the player exchange plain postMessage objects:

• id is yours: a number, or a string of up to 64 characters. The answer repeats it.
• method is one of the names above, without brackets: "seek", "getDuration". Its argument goes in value.
• A message the player does not recognise gets no answer. So does everything while the Player API is off.
• Send { method: "ping" } to ask a player that may already be running whether it is ready; it answers with its state.

const frame = document.querySelector('#lesson');
const PLAYER = 'https://embed.wolvy.stream';

// 1. Listen. Check BOTH the origin and the window the message came from.
window.addEventListener('message', (event) => {
  if (event.origin !== PLAYER || event.source !== frame.contentWindow) return;
  const message = event.data;
  if (!message || message.type !== 'wolvy:player') return;

  if (message.event) console.log('event', message.event, message.data);
  else console.log('answer to', message.id, message.ok ? message.value : message.error);
});

// 2. Ask. Always name the player's origin as the target, never "*".
frame.contentWindow.postMessage(
  { type: 'wolvy:player', v: 1, id: 1, method: 'seek', value: 120 },
  PLAYER,
);

What it cannot do#

• It never exposes protected data. No method returns, and no event carries, a DRM licence, a CDN token, a session id, the viewer id, the watermark text, a manifest or segment URL, or a key.
• It only talks to the embedding page. The player answers the one origin that embedded it, and sends its messages to that origin only. Your own listener should check event.origin and event.source the same way; the script does.
• It cannot remove the protection. The watermark, the domain rules, App-Only mode and DRM are not reachable from the API.
• It is opt-in. Off by default for every account, and silent while off.

Limits#

Common questions#