Popcorn.js Documentation

Getting started

If this is your first time using Popcorn.js this is place to start. Here you can find information on how to create your first instance, add some extra data to your media with a plugin, and understand how to write some simple Popcorn.js code.

First time using Popcorn.js

What is Popcorn.js?

Popcorn.js is a JavaScript library that allows video, audio and other media to control and be controlled by arbitrary elements of a webpage. Combining open source web technologies, authors can let their media be the “conductor” of interactive and immersive experiences.

While no prior HTML or JavaScript experience and knowledge is necessary — it is helpful and will make the process of creating your first Popcorn experience easier.

To get started, you’ll first include the Popcorn.js script in a basic HTML file — you may use just the core or the fully loaded Popcorn.js (includes modules, effects, plugins, players, parsers, etc). Alternatively, you can create your own Popcorn.js script using build tool.

Including the script is simple, take a look:

1 <html>
2     <head>
3       <script src="http://popcornjs.org/code/dist/popcorn-complete.js"></script>
4     </head>
5     <body>
6     </body>
7   </html>

Note: All Popcorn.js code is available in both production (minified) and development (source) form, these can be found on the downloads page.

Next, you’ll add a video (or audio) to your page - this example will use an HTML5 video (Popcorn.js also works with YouTube and Vimeo). Building on the previous example, add your video markup as shown below:

 1 <html>
 2     <head>
 3       <script src="http://popcornjs.org/code/dist/popcorn-complete.min.js"></script>
 4     </head>
 5     <body>
 6       <video height="180" width="300" id="ourvideo">
 7         <source src="http://videos.mozilla.org/serv/webmademovies/popcornplug.mp4">
 8         <source src="http://videos.mozilla.org/serv/webmademovies/popcornplug.ogv">
 9         <source src="http://videos.mozilla.org/serv/webmademovies/popcornplug.webm">
10       </video>
11       <div id="footnote"></div>
12     </body>
13   </html>

This will create a video player element with an ID of “ourvideo”, the ID will be used to tell Popcorn which video to control.

The example shows 3 video source elements: .mp4, .ogv, and .webm — this is done to ensure that the video will play across all major modern browsers. Keep in mind that the .mp4 version needs to be included first if the video is going to work in Safari. These sources can be local or remote video sources, so feel free to use your own!

In addition to the video element, there is a div with the ID of “footnote” – you will use this later to display some text that is synchronized to the video’s playback.

Next, you will need to write a few lines of JavaScript to create your Popcorn instance and do something with it. The code will simply show some text at the 2 second point in the video. Building on the previous example, add the following code:

 1 <html>
 2     <head>
 3       <script src="http://popcornjs.org/code/dist/popcorn-complete.js"></script>
 4       <script>
 5         document.addEventListener( "DOMContentLoaded", function() {
 6 
 7           var popcorn = Popcorn( "#ourvideo" );
 8 
 9           popcorn.footnote({
10             start: 2,
11             end: 5,
12             target: "footnote",
13             text: "Pop!"
14           });
15 
16         }, false );
17       </script>
18     </head>
19     <body>
20       <video height="180" width="300" id="ourvideo">
21         <source src="http://videos.mozilla.org/serv/webmademovies/popcornplug.mp4">
22         <source src="http://videos.mozilla.org/serv/webmademovies/popcornplug.ogv">
23         <source src="http://videos.mozilla.org/serv/webmademovies/popcornplug.webm">
24       </video>
25       <div id="footnote"></div>
26     </body>
27   </html>

Inside your script block, you’ll start by adding an event listener to the document that will execute the code within when it is ready to do so. Next, you’ll create a variable called popcorn whose value is a new Popcorn instance. The Popcorn constructor requires at least one argument, which in this case is the ID “#ourvideo”. This lets Popcorn know what video it will control or be controlled by. Once the popcorn instance is created, you’ll use the “footnote” plugin to add some text to an area on the page. The footnote plugin is the simplest of all Popcorn plugins — all it does is display text on the page at specified times, synchronized to the video. In this example, the plugin will display “Pop!” from the 2 second mark to the 5 second mark in the target ID specified (“footnote”).

That’s it! You’ve created your first Popcorn.js project! For a live example of this work take a look here. We also have introduction videos for YouTube, Vimeo, and how to use the GoogleMaps plugin. Keep in mind, both YouTube and Vimeo need to be run from a web server.

As you can see, creating Popcorn projects is a painless experience, requiring about 7 lines of JavaScript to get it done. For those of you who are not comfortable with HTML and JavaScript, our visual authoring tool for Popcorn, called Popcorn-Maker, may be great alternative to check out.