ViewedIt is now Vidyard GoVideo! Click here to learn more.

How to use the Vidyard Player API

The Vidyard Player API allows developers to control an embedded player via JavaScript.

Special notes:

  •  API calls must be run after the script for the Player Embed has run in order to properly reference loaded content
  • In order to use the Player API with lightbox embeds, the lightbox must be active and the player loaded on the page when the script runs. If the script runs without the lightbox active and the player loaded on the page, the script will not run and produce console errors.
  • The Player API cannot be used to control a player that has been embedded using the Vidyard Responsive Embed (aka. Embed v4.0)

Player API JavaScript library

The player API JavaScript library is located at:

//play.vidyard.com/v0/api.js

Referencing a Player

Players are referenced via their UUID which can be extracted from their embed code, or in the Vidyard sharing page URL.

For example:

When viewing a player at the URL http://embed.vidyard.com/share/oTDMPlUv--51Th455G5u7Q, the UUID of the player is oTDMPlUv--51Th455G5u7Q.

Code

/*Replace playerUUID with the UUID of the player you would like to control with the API*/
var video = new Vidyard.player("playerUUID"); 
video.function();

or

/*Replace playerUUID with the UUID of the player you would like to control with the API*/
var videos = new Vidyard.players(); 
videos["playerUUID"].function();

Methods

Note: The Vidyard platform has changed the term "Chapter" to "Video" in the platform User Interface. In the article below, where you see 'Chapter' it is referring to Videos.

Method
Description

.play()

Start the player from the beginning
.pause()
Pauses the player
.resume()
Resumes playback
.seek(position)

The player position will be changed to the desired time. The position value is the desired player position in seconds

.setVolume(volume)
The player volume is set. The volume value is the desired player volume represented between 0-1.
.playChapter(index)
Play the designated chapter in a player. The index value is the desired chapter beginning at 0 for the first chapter.
.getCurrentChapter()
Returns the index of the current chapter.
.enableCaption(language/label)
Enables captions. The language and label values allow you to specify which caption to enable. If a value is not specified then this method will enable the first caption.
.disableCaption(language/label)
Disables captions. The language and label values allow you to specify which captions to disable. If a value is not specified then this method will disable all captions that are showing.

Properties

Method
Description
.metadata

Metadata (title, length, description, public custom attributes, etc.) for the player is returned. This data is available after the ready has been fired. null is returned otherwise. Below is an example of a player's available metadata:

{
  "chapters_attributes": [
    {
      "video_attributes": {
        "description": null,
        "name": "nature",
        "tags": [],
        "thumbnail_urls": {}
      }
    }
  ],
  "custom_attributes": [
    {
      "attribute_type": "String",
      "is_public": true,
      "list_options": null,
      "name": "test_public",
      "value": "Test public"
    },
    {
      "attribute_type": "Number",
      "is_public": true,
      "list_options": null,
      "name": "test_public",
      "value": 10678
    }
  ],
  "description": "",
  "height": 360,
  "length_in_seconds": 123,
  "name": "player name",
  "tags": [],
  "visitorID": "string",
  "width": 640
}

Events

Event
Description
ready
Fired when the player has loaded on the web page.
play
This event fires when the play button is clicked on the player. Note: This function does not affect players when viewed on iOS devices.
pause
This event fires when the player is paused.
beforeSeek
This event fires immediately when the viewer seeks.

seek

This event fires when the viewer has completed a seek action to a new time in the player.
playerComplete
This event fires when the end of the player is reached regardless of any seeking or pauses.
chapterComplete
This event fires when the end of a chapter is reached regardless of any seeking or pauses.
timeupdate
This event fires every ~100ms.
volumeChange
This event fires when the volume is changed.

API Usage

/*Replace playerUUID with the UUID of the player you would like to control with the API*/
<script src="//play.vidyard.com/v0/api.js"></script>
<script type="text/javascript">
  var video = new Vidyard.player("playerUUID");
  video.on("playerComplete", function() { alert("Video completed") });
  video.play(); 
</script>

or take a look at our other code sample in adding a button to play/pause a video


See our documentation for additional player API examples.

Was this article helpful?

Can’t find what you’re looking for? Please contact us below.

Email Vidyard Support
Why you didn't like the article?

If you would like Vidyard to get in contact with you regarding your feedback, please enter your email address.

  • No, Thanks