Popcorn.js Documentation

Media Wrappers

Media wrappers allow Popcorn to be used with various other types of media other than HTML5 video and audio. This means it can be used with YouTube, Vimeo, and SoundCloud. This creates the potential for various media to be incorporated with Popcorn.js.

Media wrappers require the popcorn._MediaElementProto.js file to be included in the document, popcorn-complete.js does this for you.

smart( id, url )

Purpose

The Smart player allows the use of any existing player without specifying which player.

The idea is that Smart will try to find an acceptable player, given the id and url. Smart requires players to implement a _canPlayType( containerType, url ) function, along side _setup. This function returns true or false if the player can play this, given the container and url. A player that does not implement a _canPlayType will return undefined, which is inconclusive if the player can play it or not. Each player also exposes a _canPlayType( container, url ) function that developer can use to query if their data can be played or not.

Smart will also work with video elements, and attempt to create an HTML5 video experience if possible. In this case, the container can be a video element or a div. If it is a div, a video element will be created and appended to the supplied div.

The url paramter can be a string representing the media url, or an array of strings if multiple urls are applicable. For instance, different browsers support different codecs for HTML5 video, so different encodings of the same video they can be listed in sequence as the url parameter – much like they can with the video tag by adding multiple <source> children. This function will test each url to see if Popcorn (and the browser) is capable of playing it, and select the first applicable url to be the player’s source. Note that it is not necessary to use a list of media urls of the same type; using HTML5 media mixed with youtube, vimeo, etc. is acceptable.

Options

  • id [String] - the id of the HTML element that the appropriate player will populate
  • url [String | Array] - the url of the media you wish to use. If this parameter is an array, each entry will be analyzed to see if Popcorn has the ability to play it through standard HTML5 video/audio, or through a registered Popcorn player (using _canPlayType as mentioned above).

Examples

 1     var pop = Popcorn.smart( "#container", "http://www.youtube.com/watch?v=9oar9glUCL0" );
 2 
 3     pop.footnote({
 4       start: 1,
 5       end: 5,
 6       text: "Works with youtube!",
 7       target: "footnote-div"
 8     });
 9 
10     pop.play();
 1     var pop = Popcorn.smart( "#video", "media.webm" );
 2 
 3     pop.footnote({
 4       start: 1,
 5       end: 5,
 6       text: "Works with webm!",
 7       target: "footnote-div"
 8     });
 9 
10     pop.play();
 1     var pop = Popcorn.smart( "#video", [ "media.webm", "media.ogv", "media.mp4" ] );
 2 
 3     pop.footnote({
 4       start: 1,
 5       end: 5,
 6       text: "Works with multiple video sources!",
 7       target: "footnote-div"
 8     });
 9 
10     pop.play();
 1     var pop = Popcorn.smart( "#video", [ "media.webm", "http://www.youtube.com/watch?v=9oar9glUCL0", "media.ogv", "media.mp4" ] );
 2 
 3     pop.footnote({
 4       start: 1,
 5       end: 5,
 6       text: "Works with mixed multiple video sources!",
 7       target: "footnote-div"
 8     });
 9 
10     pop.play();

Live demo of the Smart player

HTMLNullVideoElement( id )

Purpose

The null wrapper is used to provide the user with an empty shell which emulates the HTML5 video element. This allows the user to use Popcorn.js even without a media element ( video or audio ) which allows for events to be fired off just like your typical Popcorn instance. All events, functions, and properties that Popcorn provides are extended onto the null wrapper for convenience.

Options

  • id [String] - just like using a video or audio source, you pass along the id of the HTML element which the null wrapper will use ( in the form of “#id”, where id is the id of your element )

Use Cases

The null wrapper has numerous use cases, such as :

  • Wanting to use popcorn without a media
  • Creating a bigger global timeline in which numerous smaller popcorn instances are created from

Examples

 1     var wrapper = Popcorn.HTMLNullVideoElement( "#elementID" );
 2 
 3     // This is 60 in seconds, if you want fractions of a second, use 60.5
 4     wrapper.src = "#t=,60";
 5 
 6     var pop = Popcorn( wrapper );
 7 
 8     pop.play();
 9 
10     // Add popcorn events here and other functionality
11     pop.footnote({
12       start: 1,
13       end: 5,
14       text: "Works with the wrapper!",
15       target: "footnote-div"
16     });

HTMLSoundCloudAudioElement( id )

Purpose

The SoundCloud wrapper allows the use of any SoundCloud audio tracks with the Popcorn.js framework.

Options

  • id [String] - the id of the HTML element that the SoundCloud wrapper will populate

  • Note - Currently SoundCloud does not support all of the events that the HTML5 media elements do, view the full list of events for more details

Examples

 1     var wrapper = Popcorn.HTMLSoundCloudAudioElement( "#video" );
 2 
 3     wrapper.src = "http://soundcloud.com/lilleput/popcorn";
 4 
 5     var pop = Popcorn( wrapper );
 6 
 7     pop.footnote({
 8       start: 1,
 9       end: 5,
10       text: "Works with SoundCloud!",
11       target: "footnote-div"
12     });
13 
14     pop.play();

HTMLVimeoVideoElement( id )

Purpose

The Vimeo wrapper allows the use of any vimeo video with the Popcorn.js framework.

Options

  • id [String] - the id of the HTML element that the youtube wrapper will populate

  • Note - Things like width and height are inherited from the HTML element that the wrapper is populating, and if are not present, default to a width of 350px and a height of 300px

Examples

 1     var wrapper = Popcorn.HTMLVimeoVideoElement( "#video" );
 2 
 3     wrapper.src = "vimeoUrl";
 4 
 5     var pop = Popcorn( wrapper );
 6 
 7     pop.footnote({
 8       start: 1,
 9       end: 5,
10       text: "Works with Vimeo!",
11       target: "footnote-div"
12     });
13 
14     pop.play();

HTMLYouTubeVideoElement( id )

Purpose

The YouTube wrapper allows the use of any Youtube video with the Popcorn.js framework.

Options

  • id [String] - the id of the HTML element that the YouTube wrapper will populate

  • Note - Things like width and height are inherited from the HTML element that the wrapper is populating, and if are not present, default to a width of 350px and a height of 300px

  • Other YouTube options such as showing Youtube controls, showing related links at the end and so on, are passed in via the query string that is appended to the YouTube video url. Take a look at this documentation for further information.

Examples

 1     var wrapper = Popcorn.HTMLYouTubeVideoElement( "#video" );
 2 
 3     wrapper.src = "http://www.youtube.com/watch?v=9oar9glUCL0";
 4 
 5     var pop = Popcorn( wrapper );
 6 
 7     pop.footnote({
 8       start: 1,
 9       end: 5,
10       text: "Works with YouTube!",
11       target: "footnote-div"
12     });
13 
14     pop.play();