Vimeo Javascript API Basics

With the ability to customize the video player to your heart's content, Vimeo has to be the best video hosting service for designers and developers. In addition to the customizable player, there are viewing and embedding permissions to set, the ability to download the original file, and cross-platform viewing built in.

But this isn't a post about why you should use Vimeo. (If you want that, check out Why I Use Vimeo for Web Video Hosting).

An Intro to the Vimeo Javascript API (via Froogaloop)

Sometimes, you may need to control a Vimeo video through separate HTML buttons. Sometimes you might want the video playback to determine other actions on the page. The Vimeo Javascript API allows for both of these situations.

While many of these functions are complicated to set up and configure, Vimeo has created a small Javascript library called Froogaloop to handle the complexities for us. The Froogaloop library can be found on GitHub here.

In the example below, we will be blacking out the rest of the page when the video plays, allowing for an immersive, movie theater-esque experience.

View Demo

Setting Up Our Page Content (The HTML)

While you could conceivably add any amount of markup to the page, we'll just stick to our overlay div (for blacking out the page) and our Vimeo video.

<!DOCTYPE html>
<html>
<head>
	<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
	<script src="froogaloop.min.js"></script>
</head>

<body>

<div class="blankOverlay">&nbsp;</div>

<div class="vimeo-container">
		<iframe id="vplayer" src="http://player.vimeo.com/video/71501596?title=0&byline=0&portrait=0&color=ffcc00&api=1&player_id=vplayer" width="610" height="344" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
		<p><a href="http://vimeo.com/71501596">NIGHTVISION</a> from <a href="http://vimeo.com/lukeshep">Luke Shepard</a> on <a href="https://vimeo.com">Vimeo</a>.</p>
	</div>

</body>
</html>

All we've done so far is set up a standard HTML page with an empty overlay div (this will darken our window behind the video) and our Vimeo video. To give us a little bit of help, Vimeo has created Froogaloop, a jQuery-based library to handle the complex stuff. We've added jQuery and the Froogaloop libraries to get us started.

The important piece to note here is that, for this to work correctly, we need to add "api=1" and "player_id=vplayer" to the end of the source URL for the video. In addition, we've added an ID of "vplayer" to the iframe as well. The ID and the "player_id" need to match.

Next, let's take a look at the minimal amount of CSS that is required.

Stylin' It Up

All we need to do here is set up the styles for our overlay div and do a bit of "z-index" work to make sure our video ends up above the overlay.


.vimeo-container {
	position: relative;
}

#vplayer {
	position: relative;
	z-index: 2;
}

.blankOverlay {
	position: fixed;
	background: rgba(0,0,0,0.75);
	top: 0;
	left: 0;
	bottom: 0;
	right: 0;
	z-index: 1;
	display: none;
}

We told the overlay to stretch the entire window and be 75% opaque. Then we told it to be hidden by default. Now we need to do the dirty work of setting up our Vimeo Javascript API functions and get our overlay working.

The Vimeo Javascript API

Because this is the more complex part, we'll step through each piece below. At the very end, we'll look at it all together. Let's get started.


var animSpeed = 400;

For consistency sake, we want to make sure that our animations all happen at the same speed. If we want things to take half/twice as long for effect, we can always use mathematical multipliers (*2 or /2).


function onPlay(id) {
	jQuery('.blankOverlay').fadeIn(animSpeed);
}

function onPause(id) {
	jQuery('.blankOverlay').fadeOut(animSpeed);
}

function onFinish(id) {
	jQuery('.blankOverlay').fadeOut(animSpeed);
}

The first thing we want to do is set up our functions for what we want to do under each circumstance. The name of the function can be anything that makes sense to you, but here I've used "onPlay", "onPause", and "onFinish" to control the overlay when the video plays, pauses, or finishes respectively.


jQuery(function($) {

Check to see if the document is ready for our jQuery.


	var iframe = $('#vplayer')[0],
	player = $f(iframe);

Right up front, we want to cache our video player to a variable and use Froogaloop's $f function to tell our script which iframe is the player we want to control/receive triggers from.


	player.addEvent('ready', function() {
		player.addEvent('play', onPlay);
		player.addEvent('pause', onPause);
		player.addEvent('finish', onFinish);
	});

When the player is ready, add listeners for play, pause, and finish. Make sure that you replace the function names you set up earlier where I've used "onPlay", "onPause", and "onFinish".


	$('.blankOverlay').click(function(){ $(this).fadeOut(animSpeed);  player.api('pause'); });

As a nice UX bonus, we want to tell the player to pause the video and fade out the overlay if the overlay is clicked. We can do all that in one line. While it's outside the scope of this tutorial, you can control your player now as well using the "player.api();" function and passing the action you want to occur. Ex: "player.api('play');" or "player.api('pause');"


});

Don't forget to close your jQuery ready initiation function!

And that's all there really is to it. At this point you should have a Vimeo video and an overlay on the page that fades in as the video plays and fades out as the video is paused or finishes.

The Entire Javascript


var animSpeed = 400;

function onPlay(id) {
	jQuery('.blankOverlay').fadeIn(animSpeed);
}

function onPause(id) {
	jQuery('.blankOverlay').fadeOut(animSpeed);
}

function onFinish(id) {
	jQuery('.blankOverlay').fadeOut(animSpeed);
}

jQuery(function($) {

	var iframe = $('#vplayer')[0],
	player = $f(iframe);

	player.addEvent('ready', function() {
		player.addEvent('play', onPlay);
		player.addEvent('pause', onPause);
		player.addEvent('finish', onFinish);
	});

	$('.blankOverlay').click(function(){ $(this).fadeOut(animSpeed);  player.api('pause'); });

});

Drupal Paradise Ad