Wistia Playlist API

Wistia Playlists have an API which give you access to its functionality and behavior!

Wistia playlists have a javascript API which gives you control over its behavior, and gives you access to the Player API for the currently embedded video.

The Playlist feature is being gradually deprecated from the Wistia UI. As we’re introducing a new design of the account, we’re phasing out the Playlists feature - although any existing Playlists that are embedded in the wild will continue to work. In additiona the Wistia Playlist API will remain functional. In order to create similar functionality for playing a sequence of videos, we would recomment taking a look at the Embed Links functionality, which essentially lets you build your own playlist of videos that include any videos in your account - you’re not constrained by the videos having to be in one project together. The second option is our Channels feature, available on the Advanced plan. It’s the next evolution of Playlists, and it’s perfect for episodic content.
The Wistia APIs were specifically built for videos in projects. We do not formally support using our APIs for audio files in projects, or audio or video episodes in Channels at this time. For the most reliable experience, we recommend continuing to use these for videos in projects.

The Methods

bind(event, function)Lets you bind a function to a playlist event. Check out the Playlist Events for more info.
currentVideo()Return a handle to the currently embedded video, which lets you access the Player API.
embed(sectionIndex, videoIndex)Embed the video in the playlist corresponding to the given indices.
embedNext()Embed the next video in the playlist.
height()Returns the height of the entire embed.
height(h)Sets the height of the entire embed.
onFirstVideo()Returns true if the current video is the first one in the playlist.
onLastVideo()Returns true if the current video is the last one in the playlist.
pause()Pause the current video.
play()Plays the current video.
play(sectionIndex)Plays the first video in the specified section.
play(sectionIndex, videoIndex)Plays a specific video by index.
ready(fn)Execute the function when the playlist is ready. A playlist may not be ready at various times during its lifecycle, usually while it’s removing the current video and embedding the next.
setEmail(email)Sets the email for all videos in the playlist.
setPlayerColor(hexColor)Sets a custom color for the player and playlist.
videoHeight()Returns the height of the video.
videoHeight(h)Sets the height of the video. The height of the entire embed will change to compensate.
videoWidth()Returns the width of the video.
videoWidth(w)Sets the width the of the video. The width of the entire embed will change to compensate.
volume()Get the volume of the current video in the playlist.
volume(v)Sets the volume of the playlist. This will carry over between videos in the playlist.
width()Returns the width of the entire embed.
width(w)Sets the width of the entire embed.

How to use the API

The Playlist API can only currently be accessed from an ’API' Playlist embed. It includes a variable '’wistiaPlaylist'' to make it easy.

# playlist_api.js
var wistiaPlaylist = Wistia.playlist("abcde12345", { ... options ... });

In this instance, you can reference the playlist object using the wistiaPlaylist variable. If you have multiple playlists on your page, you should update this variable to something specific to this playlist.

As an example, if the following JS code is executed, the email address "max@wistia.com" will be tracked for all the videos in the playlist.

# playlist_api.js

Or if I wanted to pause the current video:

# playlist_api.js

Embedding Options

In our example embed Wistia.playlist("abcde12345", { ... options ... }); there are two arguments: the playlist’s hashed ID, and a set of embedding options.

Here is a list of available options:

Option NameTypeDescription
autoAdvancebooleanWhen true, automatically embed the next video when the current video ends. Default is true.
containerstringThe container ID where the playlist will be embedded. Defaults to “wistia_{hashed_id}.”
loopbooleanWhen true, the playlist will begin again from the start when the last video ends. Default is false.
media_{si}_{vi}objectSpecify embedding options for a specific video by index as specified in the Player API. sectionIndex and videoIndex represent the indices for the video in the Project.
startVideointegerDesignates which video (in the given section) to start the playlist with. Defaults to 0.
startSectionintegerDesignates which section to start with. Defaults to 0.
themestringThe playlist’s theme. Current acceptable values are “trim,” “steam,” “tango,” or “bare.” For API embeds, this needs to correspond with the script included on the page.
versionstringMust be “v1.”
videoOptionsobjectSpecify embedding options for each video as specified in the Player API.

Playlist events

By default, all the standard player API events are available at the playlist level too. But we also have some playlist-specific events to let you do cool stuff on a per-video basis.

Event NameArgumentsDescription
afterembedsectionIndex, videoIndexFired after each video is embedded. This is helpful for targeting interactions for a specific video in the playlist. The arguments are the sectionIndex and videoIndex for the current video.
beforeembedsectionIndex, videoIndexFired after each video is embedded. This is helpful for targeting interactions for a specific video in the playlist. The secondIndex and videoIndex are for the next video.
endsectionIndex, videoIndexWhen the state of any video in the playlist changes to “ended.”
pausesectionIndex, videoIndexWhen the state of any video in the playlist changes to “paused.”
playsectionIndex, videoIndexWhen the state of any video in the playlist changes to “playing.” This can fire multiple times per video if the user pauses.
timechangesectionIndex, videoIndex, timeFired multiple times per second while the video is playing, or if the user seeks.

To control a specific video with the Player API, you’ll probably want to use “afterembed.” Here’s a quick example.

# playlist_api.js
wistiaPlaylist.bind("afterembed", function(sectionIndex, videoIndex) {
  if (sectionIndex === 1 && videoIndex === 4) {
    // This video was way louder than the others, so let's lower the volume to start.