Wistia Video Player API
Javascript Player API
The Wistia video player has a Javascript API which supports a number of ways to interact with and control the video player. It uses the same interface for both Flash and HTML5 versions of the player, and provides convenience functions to accomplish common goals.
| Method | Description |
|---|---|
| play() | This causes the video player to start (or continue playing from a paused state) playing the video. |
| pause() | This causes the video player to pause the video if it is currently playing. |
| time(t) | This causes the video player to seek to time specified by the t parameter (in seconds). |
| time() | This returns the viewer's current position in the video (in seconds). |
| state() | This returns the current state of the video player: “unknown” (a.k.a not started), “ended”, “playing”, “paused”. |
| volume() | Returns the current volume level. Value between 0 and 1. |
| volume(level) | Sets the current volume level. 'level' is a decimal value between 0 and 1. |
| duration() | Returns the length of the video in seconds. |
| bind(event, function) | This lets you execute a function when a video event occurs. Possible values for “event” are: “play”, “pause”, “end”, and “timechange”. |
| unbind(event, function) | Lets you remove a previously binded function from an event. If function is not specified, all bindings for the event will be removed. |
| ready(function) | This method is only necessary for advanced use cases. It lets you run a function as soon as the video is loaded and ready to be played. |
Using These Methods
To use these methods, you will need to reference the video. The 'API' version of the Wistia embed codes includes a variable wistiaEmbed to make this easy.
var wistiaEmbed = Wistia.embed("bfc34aa023", { ... options ... });
In this instance, you can reference the video object using the wistiaEmbed variable. If you have multiple videos on your page, you should update this variable to something specific to this video.
As an example, if the following JS code is executed, the video will start to play:
wistiaEmbed.play();
Example: Trigger an event at a specific time
Wistia's video player API provides functionality to easily accomplish common goals.
In this example, let's assume that we want to fire a Javascript function when the viewer gets 60 seconds into the video. In order to accomplish this, we only need the bind method from the API. The Javascript code can be seen below:
<script type="text/javascript">
wistiaEmbed.bind("timechange", function (t) {
if(t > 60 && t < 62) {
// Insert code to be executed here
}
});
</script>
The bind function monitors the state of the video in an event loop. Every 500 milliseconds, it checks to see if the video's time position has changed. If it has, it runs your function with the current time (t) as the only argument.
Example: Alert when the video ends
<script type="text/javascript">
wistiaEmbed.bind("end", function () {
alert("Hello world!");
});
</script>
Example: Alert on play just once
With the bind method, every time “play” is triggered, your function will be executed. But sometimes a user will scroll back to the beginning and hit Play again. If you want to avoid your function being executed again, you need to unbind it.
<script type="text/javascript">
function playFunc() {
alert("Played the first time!");
wistiaEmbed.unbind("play", playFunc);
}
wistiaEmbed.bind("play", playFunc);
</script>
Embedding Options
In our example embed Wistia.embed(“bfc34aa023”, { … options … }); there are two arguments: the media's hashed ID, and a set of embedding options. Here is a list of available options:
| Option Name | Description |
|---|---|
| platformPreference | Determines the type of embed to prefer, but falls back gracefully to other types. Possible values are “flash”, “html5”, and “external”. Default is “flash” |
| force | Forces a specific type of embed. Possible values are “flash”, “html5”, and “external”. |
| playButton | When set to true, a play button is displayed over the video when paused. Affects flash player only. Defaults to true. |
| container | The DOM element where the video should be placed. Accepts a DOM element or an ID string. Defaults to “wistia_{hashed_id}”. |
| chromeless | When set to true, no player controls will be available for the video. Defaults to false. |
| controlsVisibleOnLoad | Flash only. When set to true, controls will be visible before play is clicked. Defaults to false. |
| autoPlay | When set to true, the video will automatically play as soon as the page loads. |
| endVideoBehavior | Flash only. Determines the behavior of the video when it is playing and reaches the end. Possible values are “default”, “reset”, and “loop”. By default, the last frame of the video is displayed. |
| wmode | Flash only. Set the window mode of the flash player. May be useful for z-index issues. Default is opaque. |
| trackEmail | The email address to associate with the viewing session. By default null or the value of the wemail URL param. |
| uuid | A unique identifier string for the video. Used internally and randomly generated on page load by default. |
Example: Miscellaneous Options
To show how options work, suppose I want to embed a video that defaults to the HTML5 player, plays automatically on page load, and bypasses some z-index issues with menus on the page. I might alter the embed javascript to look like this:
<div id="my_container"></div>
<script type="text/javascript">
var wistiaEmbed = Wistia.embed("bfc34aa023", {
platformPreference: "html5",
autoPlay: true,
wmode: "transparent",
container: "my_container"
});
</script>
