Popcorn.js Documentation

Media Methods

Media methods get or set the current state of the media element. This allows the user to programmatically control the media element as well as perform various actions at specific points in time, such as calling a function at 5 seconds.

autoplay( flag )

Purpose

autoplay() is defined as a passthrough accessor to the HTMLMediaElement property of the same name. Use autoplay( flag ) to set the media to automatically play when loaded.

Options

  • flag [Boolean] - when set to true will automatically play the media once it is loaded. When set to false, the media will not play until the play() method is called, or the user clicks the play button on the media player interface.

Use Cases

Begin playing the media as soon as it is able to. This can also be achieved by calling play() once the media has loaded.

Examples

Live demo setting the video to autoplay as soon as it is able to

play

buffered()

Purpose

buffered() is a passthrough accessor to the HTMLMediaElement property of the same name. buffered() returns a timeranges object that describes to the user how much of the video has been loaded. The function takes no arguements.

Use Cases

You want to wait until a certain amount of the video has been loaded before beginning playback or allowing the user to interact with the video

Examples

compose( name, definitionObject [, manifest] )

Purpose

compose() provides the base logic for effects and works similarly to a traditional Popcorn.js plugin. Create start and end functions as you would in a typical plugin and add an appropriate effect that will be triggered in each block. Typically this means add an effect on start and remove it on end, but is in no way limited to this. Compose creates the huge potential for CSS transitions between Popcorn events and depth to the user’s experience. compose() is not limited to effects.

Plugins events will be fired first, followed by composed events.

Options

  • name [String]- given name for the compose plugin
  • definitionObject [Object]- object containing typical plugin methods ( setup, start, end ) where the compose logic will live
  • manifest [Object]- an optional manifest can be included

Use Cases

  • You want a unique effect to be displayed alongside an already existing plugin
  • Create transitions

Examples

controls( flag )

Purpose

controls() is a passthrough accessor to the HTMLMediaElement property of the same name. If controls( true ) is called, the video will be shown with its native set of controls ( play, timebar, volume, ect ). controls( false ) will conceal the native control elements bar.

Options

  • flag [Boolean]- true to show or false hide the controls

Use Cases

  • Autoplay the video, showing no controls
  • Show controls initially, then on play, hide the controls from the user

Examples

cue( time, callback )

Purpose

cue() is a preferred alias to exec().

cue() was created with film makers in mind by using a familiar keyword in order to make developing Popcorn.js projects simpler.

Options

  • time [String Number] - number of seconds or SMPTE format string. The time in which the cue will be fired at
  • callback [Function]- callback function to execute at the given time

Use Cases

  • Perform an action at some point in the video
  • Unique functionality that is not big enough to warrant a plugin

Example

Log data at points in the video

currentTime( [time] )

Purpose

Set or get the currentTime() of a Popcorn Instances media element.

Options

  • time [String Number] - number of seconds or SMPTE format string. If a time parameter is passed, set the media’s current time to this value. If no time parameter, return the value of the currentTime() property in seconds.

Use Case

  • Navigate to a certain point in the video
  • Figure out what time we are at in the video

Examples

defaults( pluginName, options )

Purpose

Set defaults for any property of a plugin.

This allows numerous plugins of a single type to use the same default values. This can be done by either calling the instance method or by defining properties in the Popcorn constructors options object parameter.

Options

  • pluginName [String] - The name of the plugin in which you want to set default values for
  • options [Object] - Property list and values that will be defaulted for the named plugin.

Use Cases

  • Use the same default values for numerous plugin calls
  • Reduce code size

Examples

destroy()

Purpose

Stops the instance’s timeUpdate loop and removes any associated events.

Use Case

Your web application needs to create a new instance of Popcorn, using the same video source as the first.

Examples

Destroying a popcorn instance

    // Create the instance
    var pop = Popcorn( "video" );

    // Add event
    pop.exec( 5, function() { console.log( "exec" ); } );

    // Destroy instance
    pop.destroy();

emit( eventName [, dataObject] )

Purpose

Trigger an event; optionally pass an object of data through to the event handling callback. Allows custom events.

Any of the follow event types may be used with emit() : loadstart, progress, suspend, emptied, stalled, play, pause, loadedmetadata, loadeddata, waiting, playing, canplay, canplaythrough, seeking, seeked, timeupdate, ended, ratechange, durationchange, volumechange. Take a look at our event documentation for more information on events.

Trigger also accepts custom events.

Options

  • eventName [String] - name of the event to be emitted
  • dataObject [Object] - optional data object

Use Cases

Forcefully emit an event when something happens, i.e., the video reaches halfway done, so emit custom event “halfdone” which can be listened for

Examples

exec( time, callback )

Warning - exec is deprecated, please use cue instead

Purpose

Execute an arbitrary function at a specific time

Options

  • time [String Number] - number of seconds or SMPTE format string. The time in which the cue will be fired at
  • callback [Function]- a callback function to execute at the given time

Use Cases

  • Perform an action at some point in the video
  • Unique functionality that is not big enough to warrant a plugin

Example

Live demo of how to console.log some data at 1 second

listen( eventName, callback )

Warning - listen is deprecated, please use on instead

Purpose

Bind an event handling callback to an event. Allows custom events.

Any of the follow event types may be used with listen() : loadstart, progress, suspend, emptied, stalled, play, pause, loadedmetadata, loadeddata, waiting, playing, canplay, canplaythrough, seeking, seeked, timeupdate, ended, ratechange, durationchange, volumechange. Take a look at the events section of our documentation for further information on events.

Options

  • eventName [String] - name of the event to listen for
  • callback [Function] - the function to execute when an event matching eventName is emitted.

Use Cases

Perform an action when an event occurs, i.e, show a googlemap when the video is paused

Examples

Live demo of how to console.log some information when the play event is emitted

load()

Purpose

load() is a passthrough accessor to the HTMLMediaElement property of the same name. The load() method allows the user to force a reload of the current video, making it play from the beginning. The function takes no arguments. Once the video has loaded it will take its default state as it was set when the video was instantiated ( if it was muted, if autoplay was set, etc ).

Use cases

  • Start the video from the beginning again
  • Change a video source mid way through playback

Examples

loop( flag )

loop() is a passthrough accessor to the HTMLMediaElement property of the same name. When loop( true ) is called the video will automatically start playing from the beginning each time it reaches the end. By default Popcorn media will not loop.

Options

  • flag [Boolean] - specifies whether or not to loop the video

Use Cases

  • Continuosly play the video
  • Perform different actions on each playthrough

Examples

muted( flag )

Purpose

muted() is a passthrough accessor to the HTMLMediaElement property of the same name. Depending on the state of the flag, muted will either start playing muted or unmuted ( default is unmuted ).

Recommend using the Popcorn instances methods: mute() and unmute()

Options

  • flag [Boolean] - value stating whether to mute the video or not

on( eventName, callback )

Purpose

Bind an event handling callback to an event. Allows custom events.

Any of the follow event types may be used with on() : loadstart, progress, suspend, emptied, stalled, play, pause, loadedmetadata, loadeddata, waiting, playing, canplay, canplaythrough, seeking, seeked, timeupdate, ended, ratechange, durationchange, volumechange. Take a look at the events section of our documentation for further information on events.

Options

  • eventName [String] - name of the event to listen for
  • callback [Function] - the function to execute when an event matching eventName is emitted.

Use Cases

Perform an action when an event occurs, i.e, show a googlemap when the video is paused

Examples

Live demo of how to console.log some information when the play event is emitted

play( [time] )

Purpose

Play the video.

  • Calling the .play() method will emit a play event.
  • Calling the .play() method will emit a playing event.
  • Calling the .play() method will emit timeupdate events.

Options

  • time [String Number] - number of seconds or SMPTE format string. Optional parameter that will seek to a specified time and play the media, short hand for currentTime( time ).play();

Example

playbackRate( [rate] )

Purpose

Get or set playbackRate of calling Popcorn instance. Default rate is 1. Note: It does not always mute the sound and negative values are not supported yet.

Options

  • rate [Number] - optional parameter that will set the playback rate if provided and return the playback rate if not.

Example

1
2
3
4
5
6
7

    var p = Popcorn( "#video" );

    // returns the current playback rate
    p.playbackRate();

    // set the playback rate
    p.playbackRate( 30 );

played()

Purpose

played() is a passthrough accessor to the HTMLMediaElement property of the same name. played() returns information of how much of the video has been played so far in the form of a TimeRanges object. It takes no arguements

Use Cases

  • Update the user on how much of the video they have watched so far
  • Show content depending on how much of the video the user has watched

Examples

preload( state )

Purpose

preload() is a passthrough accessor to the HTMLMediaElement property of the same name. Preload provides a hint to the user agent as to how much of the video to preloaded. If autoplay is set to true, preload is ignored ( autoplay will try and play the video right away ). If an incorrect value is given, it defaults to auto.

Options

  • state [String] - state takes the form of one of the following values:

    • auto - begins loading data as soon as possible
    • metadata - only loads the videos metadata (dimensions, first frame, track list, duration, etc)
    • none - loads no data

Use Cases

  • There is a high chance your users are on a very slow connection and want to ensure the rest of the webpage loads quickly ( state = none )
  • Begin loading the video ASAP to ensure a smooth playback
  • We want to get metadata from the video because we may be performing calculations on the videos duration, size, etc

Examples

readyState()

Purpose

readyState() is a Popcorn instance media method. readystate() returns a value from 0 - 4 describing at which state in loading the video is at. readystate() takes no arguements.

returns:

  • 0 ( HAVE_NOTHING ) - no information regarding the media source is available
  • 1 ( HAVE_METADATA ) - duration and dimensions of the video are available
  • 2 ( HAVE_CURRENT_DATA ) - enough data for the immediate playback of the current position
  • 3 ( HAVE_FUTURE_DATA ) - same as readyState 2 but the the video can seek forwards at least a small bit before returning to readyState 2
  • 4 ( HAVE_ENOUGH_DATA ) = same as readyState 3 but the user agent has estimated that data is being fetched at a rate that it will not stall playback before the end of the video

See the HTML5 Video spec for readyStates for more details

Use Cases

Perform tasks as soon as data is available by checking readyStates

Examples

Live demo of basic example showcasing readyStates

seekable()

Purpose

seekable() is a passthrough accessor to the HTMLMediaElement property of the same name. seekable() provides the user with information on how much of the media they can currently seek through. seekable() takes no arguments.

returns - TimeRanges object

Use Cases

Dont show the timeline until the user is able to seek through a certain amount of the video

Examples

Live demo of how to hide timeline until the user can seek through over half of the video

seeking()

Purpose

seeking() is a Popcorn instance media method that describes whether or not the current media is seeking or not. seeking() takes no arguments.

returns - boolean value ( true/false )

Use Cases

Perform actions while the user seeks through your video

Examples

Live example to show when the user is seeking

toggle( pluginName )

Purpose

toggle() allows you to easily turn plugin events of a specified type on and off. Note that toggling events on/off does not mean that they will be hidden when toggled off. It simply means that events of that type will no longer be fired, i.e start, end, frame will not be fired if toggled off.

Options

  • pluginName [String] - the name of the plugin, i.e. “footnote”

Use Cases

  • Toggle a plugin on and off because of a user interaction
  • Play the video through once without popcorn events and once with popcorn events

Examples

trigger( eventName [, dataObject] )

Warning - trigger is deprecated, please use emit instead

Purpose

Trigger an event; optionally pass an object of data through to the event handling callback. Allows custom events.

Any of the follow event types may be used with trigger() : loadstart, progress, suspend, emptied, stalled, play, pause, loadedmetadata, loadeddata, waiting, playing, canplay, canplaythrough, seeking, seeked, timeupdate, ended, ratechange, durationchange, volumechange. Take a look at our event documentation for more information on events.

Trigger also accepts custom events.

Options

  • eventName [String] - name of the event to be triggered
  • dataObject [Object] - optional data object

Use Cases

Forcefully trigger an event when something happens, i.e., the video reaches halfway done, so trigger custom event “halfdone” which can be listened for

Examples

volume( [value] )

Purpose

Get or Set the volume of a Popcorn instance.

Calling the volume( value ) method will emit a volumechange event.

Options

  • value [Number] - Passing a value (0 - 1.0) parameter will update the media’s current volume.

Examples

Live demo showing how to get and set the volume