Control the player.
React to playback.

Quick start

Load the script, point it at your iframe, and call methods on the returned player. Every method returns a promise.

<iframe id="video" src="https://visiroll.com/v/VIDEO_ID"
        title="Campaign video" width="1920" height="1080"
        allow="autoplay; fullscreen"
        loading="lazy"
        style="border:0;aspect-ratio:1920/1080;width:100%;height:auto"></iframe>

<script src="https://visiroll.com/player.js"></script>
<script>
  var player = new Visiroll.Player(document.getElementById("video"));

  player.on("ended", function () {
    console.log("playback reached the end of a pass");
  });

  // Use the player’s Play button to start playback.
</script>

Commands sent before the iframe finishes loading are queued and delivered as soon as it is ready. Every call has a 30-second timeout, including time spent waiting for a lazy iframe. Catch rejected promises; retry after the iframe loads if necessary.

The iframe

The constructor accepts an iframe, a container with options, or a CSS selector. The allowattribute delegates autoplay permission to the iframe. It does not override browser policies or guarantee that play() will succeed.

var player = new Visiroll.Player("#video");        // selector
var player = new Visiroll.Player(iframeElement);   // element

// Create a responsive iframe inside a container:
var player = new Visiroll.Player("#video-container", {
  id: "YOUR-VIDEO-UUID", muted: true, loop: true,
  controls: true, autopause: true, start: 0
});
player.ready().then(function () { return player.play(); }).catch(console.error);

The repository also provides @visiroll/player with ESM, CommonJS and TypeScript definitions. It is not yet published to the npm registry. Imports are safe during server rendering; construct the player in the browser.

Repeated construction for the same iframe returns the same instance. Load the SDK before running integration code. An asynchronously loaded script may not exist yet when your next inline script runs.

Add ?autopause=1 to each participating iframe URL to pause the others when one starts. This is opt-in and requires player.js on the hosting page. Add dnt=1 to disable player analytics events for that embed; media authorization and delivery still operate. Combine options as ?autopause=1&dnt=1. Optional autoplay, muted,loop and controls accept 1/0 or true/false. start is a non-negative position in seconds. These apply to this embed only; omitted or invalid options retain defaults. Mandatory branding and domain authorization cannot be overridden.

preload accepts viewport (default: prepare near the screen),none (wait for play), hover (prepare on pointer entry or keyboard focus), or auto (prepare once the iframe loads). Visible autoplay and explicit play take precedence. Preloading prepares a small initial buffer; it does not download the entire video. Iframe loading is separate: most Share presets use lazy loading; Hero uses eager loading.

initial_quality=360p, for example, requests the starting rendition while keeping adaptive quality enabled afterwards. Supported values: 240p, 360p, 480p, 540p, 720p, 1080p, 1440p and 2160p. Unavailable sizes use the nearest lower rendition, or the smallest available one. Native HLS browsers such as Safari choose their own quality. The SDK option is initialQuality; use auto or omit it for the existing automatic selection.

Copy a ready-made embed from the video’s Share tab in the studio.

Presets and background video

Choose a preset in the studio’s Share tab. It changes the copied embed and preview without changing the video’s saved settings.

• Saved: saved playback settings, viewport preparation, automatic quality, lazy iframe.
• Normal video: manual playback, controls, no loop, autopause, hover/focus preparation, automatic quality, lazy iframe.
• Hero / background: muted autoplay and loop, hidden title and controls, no autopause, automatic preparation, 360p starting hint, eager iframe.
• Video list: manual playback, controls, no loop, autopause, viewport preparation, 360p starting hint, lazy iframe.

The URL option background=1 supplies autoplay, muted, loop and hidden-control defaults. Explicit autoplay, muted, loop and controls flags take precedence. Set loading, starting quality and autopause separately when building a URL yourself. Background presentation preserves the video aspect ratio and mandatory branding; it does not crop video to cover an arbitrary container.

If autoplay is blocked, the player keeps a fallback Play action. Native HLS may ignore the starting-quality hint. Autopause requires the SDK and autopause=1 on each participating embed.

Publish in WordPress or Webflow

The iframe is enough for normal playback. The JavaScript API is optional and is needed only when the surrounding page must control playback or react to player events.

Keep the script tag even when you never call the API. Safari gives the iframe only your site’s origin as referrer, and the script tells every Visiroll player on the page its exact URL, so the analytics report names the page rather than the site root. The script reads nothing but the page address, passes on only its origin, path and UTM values, sets no cookies and loads nothing else.

• WordPress guide — Custom HTML block, permissions, domains and common sanitization problems.
• Webflow guide — Code Embed, staging hostname, components and CMS use.

Both guides preserve the video’s real aspect ratio, including square and vertical content.

Methods

player.getDuration().then(function (seconds) {
  console.log("duration", seconds);
});

player.setVolume(0.4)
  .then(function (volume) { console.log("volume is now", volume); })
  .catch(function (error) { console.error(error); });

Events

Subscribe with on(name, listener) and remove with off(name, listener), or off(name) to drop every listener for that event. Each listener receives a single data object.

Unlike Vimeo, Visiroll emits ended during loop playback. Existing currentTimefields are preserved; seconds, percent (0–1) and duration are additive aliases. On a loop completion, seconds describes the completed pass while currentTime is the actual restarted position.

Call player.destroy() when removing the iframe. Pending calls reject withDestroyedError. Reloading an initialized iframe rejects in-flight calls withPlayerReloadedError; await ready() before retrying. Unanswered calls reject withTimeoutError. Invalid arguments reject with TypeError or RangeError.

Rewards must be validated and deduplicated on your server. A browser completion event can follow a seek and may recur on every loop; it is not proof of uninterrupted viewing.

Worked example

Custom buttons can request playback and sound. Keep the player’s own controls available as a fallback. Initialize before the click and send the command directly from its handler; waiting for a request, timer or state getter first can lose user activation. SDK commands cross an iframe boundary, so browser policies still apply.

<button id="play-video" disabled>Play video</button>
<button id="enable-sound" disabled>Enable sound</button>
<p id="player-status" role="status"></p>

<script>
  // Load player.js and the #video iframe as shown in Quick start.
  var player = new Visiroll.Player("#video");
  var playButton = document.getElementById("play-video");
  var soundButton = document.getElementById("enable-sound");
  var status = document.getElementById("player-status");

  function reportError(error) {
    status.textContent = "Use the controls inside the video to play or enable sound.";
    console.error(error.name, error.message);
  }

  player.ready().then(function () {
    playButton.disabled = false;
    soundButton.disabled = false;
  }).catch(reportError);

  playButton.onclick = function () {
    player.play().then(function () { status.textContent = ""; }).catch(reportError);
  };
  soundButton.onclick = function () {
    player.setMuted(false).then(function (muted) {
      status.textContent = muted ? "Enable sound inside the video." : "Sound enabled.";
    }).catch(reportError);
  };
</script>

In a component or single-page application, remove your host-page listeners and call destroy()during cleanup. For a caller-owned iframe, pause first if it will remain on the page: destroying the SDK does not stop its playback. For an SDK-created iframe, destruction also removes the iframe. Do not start playback from every loaded event.

Domains and security

The player only accepts commands from pages whose origin appears in that website’s allowed domains, wildcards included. Replies and events are posted back to that exact origin, never to *. A page that is not on the list can neither embed the video nor control it.

Add every staging or production hostname that will contain the player. Remove obsolete hostnames as soon as a publishing destination is retired.

Troubleshooting