Player API Reference

Control your VideoNest player programmatically via JavaScript events and methods.

Last updated March 2026

Overview

The VideoNest Player API enables programmatic control of embedded players from your page's JavaScript — triggering playback, responding to events, and reading playback state without interacting with the player controls directly.

How it works

The player communicates with the parent page via the browser's postMessage API. You send commands to the player iframe and listen for event messages it emits. This works across all modern browsers and does not require any additional library beyond a standard script tag.

Getting started

Add your VideoNest player iframe to the page and give it an id so you can reference it from JavaScript. Append ?api=1 to the embed URL to enable the postMessage API. Then add a message event listener on window to receive events from the player, and use iframe.contentWindow.postMessage() to send commands.

<iframe
  id="vn-player"
  src="https://embed.videonest.co/v/vid_abc123?api=1"
  width="640" height="360"
  frameborder="0" allowfullscreen
></iframe>

<script>
const player = document.getElementById('vn-player');

// Listen for events from the player
window.addEventListener('message', function(event) {
  if (event.origin !== 'https://embed.videonest.co') return;
  const msg = JSON.parse(event.data);
  console.log(msg.event, msg.data);
});

// Send a command to the player
function sendCommand(method, value) {
  player.contentWindow.postMessage(
    JSON.stringify({ method, value }),
    'https://embed.videonest.co'
  );
}
</script>

Methods reference

Call any method by passing its name as the method field in a postMessage payload. Methods that accept a parameter pass it as value.

Method	Parameter	Description
`play()`	—	Starts or resumes playback.
`pause()`	—	Pauses playback.
`seek(seconds)`	Number (seconds)	Seeks to the specified position in the video.
`setVolume(level)`	Number (0–1)	Sets the playback volume. 0 is silent, 1 is full volume.
`mute()`	—	Mutes the player.
`unmute()`	—	Unmutes the player.
`getCurrentTime()`	—	Requests the current playback position. Player responds with a `currentTime` event.
`getDuration()`	—	Requests the total video duration. Player responds with a `duration` event.

// Examples
sendCommand('play');
sendCommand('seek', 30);        // seek to 30 seconds
sendCommand('setVolume', 0.5);  // set volume to 50%
sendCommand('getCurrentTime');  // triggers a currentTime event in response

Events reference

The player emits events via postMessage to the parent window. Each event message is a JSON string with an event field and a data object where applicable.

Event	Data	Description
`ready`	—	The player has loaded and is ready to accept commands.
`play`	—	Playback started or resumed.
`pause`	—	Playback paused.
`timeupdate`	`{ currentTime, duration }`	Fires periodically during playback with the current position and total duration in seconds.
`ended`	—	Playback reached the end of the video.
`error`	`{ code, message }`	A playback error occurred. Includes an error code and human-readable message.

window.addEventListener('message', function(event) {
  if (event.origin !== 'https://embed.videonest.co') return;
  const msg = JSON.parse(event.data);

  switch (msg.event) {
    case 'ready':
      console.log('Player ready');
      break;
    case 'timeupdate':
      console.log('Current time:', msg.data.currentTime);
      break;
    case 'ended':
      console.log('Video ended');
      break;
    case 'error':
      console.error('Player error:', msg.data.code, msg.data.message);
      break;
  }
});

URL parameters

Many player behaviors can be configured at embed time via URL parameters, without any JavaScript. Append parameters to the embed URL:

https://embed.videonest.co/v/vid_abc123?autoplay=1&muted=1&loop=0&controls=1&start=30

Parameter	Values	Description
`autoplay`	1 / 0	Start playback automatically when the player loads. Requires `muted=1` in most browsers.
`muted`	1 / 0	Start the player in a muted state.
`loop`	1 / 0	Restart the video automatically when it ends.
`controls`	1 / 0	Show or hide the player control bar. Default is 1 (controls visible).
`start`	Number (seconds)	Start playback from the specified position rather than from the beginning.
`api`	1 / 0	Enable the postMessage API. Required to use methods and receive events.

💡

Combine URL params and JavaScript

URL parameters and the JavaScript API are complementary. Use URL parameters for static configuration at embed time (autoplay, start position) and the JavaScript API for dynamic control in response to user interactions on the parent page.

Was this article helpful?

Thanks for your feedback.

Need help now? Contact support