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.
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
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
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
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.
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
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
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
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 ).
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
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
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
Calling the pause() method will emit a pause event.
Options
time [String
Number] - number of seconds or SMPTE format string. Optional parameter that will seek to a specified time and pause the media, short hand for currentTime( time ).pause();
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();
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
1varp=Popcorn("#video");23// returns the current playback rate4p.playbackRate();56// set the playback rate7p.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
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
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
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.
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
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