Popcorn.js Documentation

Popcorn Methods

Popcorn methods for adding, removing, getting or updating popcorn track events. This allows the user to dynamically author a popcorn instance, such as changing the start time of a text event, even while the video is playing.

add

Purpose

Builds popcorn track events from popcorn plugins. Example, popcorn.subtitle( options ) would create a subtitle track event from the subtitle plugin.

Options

  • id [Integer] - optional id assigned to your new track event, if omitted a random id is assigned to your track event.
  • options [object] - object of properties to create a track event from, like start, end or text.
  • options.id [Integer] - optional id assigned to your new track event, if omitted a random id is assigned to your track event.

Use Cases

You want to add some extra content to your media. Example: display a subtitle or image at a certain time.

Examples

1
2
3
4
5
6
7
8
9
10
11
12

    // Create your plugin
    Popcorn.plugin( "example", {
      start: function() {}
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // create an example track event from the example plugin
    pop.example({ start: 1 });
    pop.example("example-id", { start: 1 });
    pop.example({ start: 1, id: "another-id" });

popcorn.getLastTrackEventId()

Purpose

popcorn.getLastTrackEventId() returns the id of the most recently added track event.

Use Cases

You just created a track event and want to store its id with all the other track events for future update or removal.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

    // Create your plugin
    Popcorn.plugin( "example", {
      start: function() {}
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // create an example track event from the example plugin
    pop.example({ start: 1 });

    // id is now a randomly assigned id
    var id = pop.getLastTrackEventId();

    // create an example track event from the example plugin
    pop.example({ start: 1, id: "example-id" });

    // now id is "example-id"
    id = pop.getLastTrackEventId();

popcorn.getTrackEvent( id )

Purpose

popcorn.getTrackEvent() returns the track event assigned to the id parameter.

Options

  • id [String] - the id assigned to the desired track event.

Use Cases

You want to check values stored in a track event, and have the id.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

    // Create your plugin
    Popcorn.plugin( "example", {
      start: function() {}
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // create an example track event from the example plugin
    pop.example({ start: 1 });

    // id is now a randomly assigned id
    var id = pop.getLastTrackEventId();

    var trackEvent = pop.getTrackEvent( id );

    pop.example({ start: 1, id: "example-id" });

    trackEvent = pop.getTrackEvent( "example-id" );

popcorn.getTrackEvents()

Purpose

popcorn.getTrackEvents() returns an array track event objects attached to the popcorn instance.

Use Cases

You need to look through all track events attached to an instance, or you need the number of track events attached to an instance.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13

    // Create your plugin
    Popcorn.plugin( "example", {
      start: function() {}
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // create an example track event from the example plugin
    pop.example({ start: 1 });

    // trackEvents[ 0 ] is the example track event, and trackEvents.length is 1
    var trackEvents = pop.getTrackEvents();

popcorn.removeTrackEvent( id )

Purpose

popcorn.removeTrackEvent() removes an existing track event from the popcorn instance, via a track event’s id.

Options

  • id [String] - id assigned to the track event you wish to remove.

Use Cases

You want to remove a track event from the poporn instance.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

    // Create your plugin
    Popcorn.plugin( "example", {
      start: function() {}
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // create an example track event from the example plugin
    pop.example({ start: 1 });

    // id is now a randomly assigned id
    var id = pop.getLastTrackEventId();

    pop.removeTrackEvent( id );

    pop.example({ start: 1, id: "example-id" });

    pop.removeTrackEvent( "example-id" );

update

Purpose

Updates popcorn track event properties on existing track events, like the start time or end time. This can be done dynamically while the video is playing.

Options

  • id [Integer] - id assigned to the track event you wish to update
  • options [object] - new options object you wish to apply to the existing track event, existing values on the track event that are not in the update options object are left unchanged.

Use Cases

You want to change a track events data on the fly, instead of removing and adding a new modified version of the track event.

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

    // Create your plugin
    Popcorn.plugin( "example", {
      start: function() {}
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // traditional, unchanging plugin call
    pop.example({
      start: 12,
      end: 13
    });

    // set up a new changeable trackevent
    pop.example( "plugin-id", {
      start: 10,
      end: 11,
      content: "Hi!"
    });

    // change it to start at 11
    pop.example( "plugin-id", {
      start: 11,
      content: "Hola!"
    });

    // change it to end at 12
    pop.example( "plugin-id", {
      end: 12
    });