Popcorn.js Documentation

Addon Development

Interested in writing a cool new addon for Popcorn.js? This is the place to look. You will find in depth information on how to implement a new feature, what tests need to be written, and the style guide the project conforms to.

Players

In addition to Popcorn’s plugin factory, Popcorn also provides a way for users to create their own media player ( other than the HTML5 one ) to create and fire events off of.

Document and Directory Setup

  1. Create a folder popcorn-js/players/playername
  2. Create 4 files:
    • popcorn.playername.html – The demo file, contains html to run player
    • popcorn.playername.js – The code file, contains player
    • popcorn.playername.unit.html – The demo test file, contains html test framework
    • popcorn.playername.unit.js – The code test file, contains unit tests

Making the player

Developing a player for Popcorn is a bit more complicated than creating a plugin. In order for a player to work correctly you need to handle all events that the HTML5

Plugins

Popcorn offers a plugin factory that allows user to create their own plugins to synchronize with the playable media timeline.

Document and Directory Setup

  1. Create a folder popcorn-js/plugins/pluginname
  2. Create 4 files:
    • popcorn.pluginname.html – The demo file, contains html to run plugin
    • popcorn.pluginname.js – The code file, contains plugin
    • popcorn.pluginname.unit.html – The demo test file, contains html test framework
    • popcorn.pluginname.unit.js – The code test file, contains unit tests

Making the plugin

Choose a pattern from the Popcorn Plugin API section below.

Be sure to eliminate dependencies. A plugin should not require jQuery to run. We have also written a best practices guide for plugin development.

Making unit tests

qunit is used for unit tests. The unit test files are only necessary if you wish to make your plugin an official popcorn.js plugin and get it reviewed.

Popcorn Plugin API

Popcorn also offers a plugin factory. Popcorn plugins are a way for developers to wrap functionality that responds to a point in a video. Pattern 1 below lets you manage time updating by your self, where as patterns 2 and 3 offer a structure to manage your video events for you.

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
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216

    // Pattern 1
    // Provide a function that returns an object
    (function( Popcorn ) {
      Popcorn.plugin( "pluginName" , function( options ) {
        // do stuff
        // this refers to the popcorn object

        // You are required to return an object
        // with a start and end property
        return {
          _setup: function( track ) {
            // setup code, fire on initialization

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          _update: function( track, updates ) {
            // update code, fire on update/modification of a plugin created track event.

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // |updates| refers to the new plugin data to be applied,
            // loop through this and apply the necessary updates to track

            // this refers to the popcorn object
          },
          _teardown: function( track ) {
            // teardown code, fire on removal of plugin or destruction of instance

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          start: function( event, track ) {
            // fire on track.start

            // |event| refers to the event object

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          end: function( event, track ) {
            // fire on track.end

            // |event| refers to the event object

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          frame: function( event, track ) {
            // when frameAnimation is enabled, fire on every frame between start and end

            // |event| refers to the event object

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          toString: function() {
            // provide a custom toString method for each plugin
            // defaults to return start, end, id, and target
            // this refers to the popcorn object
          }
        };
      });
    })(Popcorn);


    // Pattern 2
    // Provide an object
    // Popcorn will manage the events
    (function( Popcorn ) {
      Popcorn.plugin( "pluginName" , {
        _setup: function( track ) {
          // setup code, fire on initialization

          // |track| refers to the TrackEvent created by the options passed
          // into the plugin on init

          // this refers to the popcorn object
        },
        _update: function( track ) {
          // update code, fire on update/modification of a plugin created track event.

          // |track| refers to the TrackEvent created by the options passed
          // into the plugin on init

          // this refers to the popcorn object
        },
        _teardown: function( track ) {
          // teardown code, fire on removal of plugin or destruction of instance

          // |track| refers to the TrackEvent created by the options passed
          // into the plugin on init

          // this refers to the popcorn object
        },
        start: function( event, track ) {
          // fire on track.start

          // |event| refers to the event object

          // |track| refers to the TrackEvent created by the options passed
          // into the plugin on init

          // this refers to the popcorn object
        },
        end: function( event, track ) {
          // fire on track.end

          // |event| refers to the event object

          // |track| refers to the TrackEvent created by the options passed
          // into the plugin on init

          // this refers to the popcorn object
        },
        frame: function( event, track ) {
          // when frameAnimation is enabled, fire on every frame between start and end

          // |event| refers to the event object

          // |track| refers to the TrackEvent created by the options passed
          // into the plugin on init

          // this refers to the popcorn object
        },
        toString: function() {
          // provide a custom toString method for each plugin
          // defaults to return start, end, id, and target
          // this refers to the popcorn object
        }
      });
    })(Popcorn);


    // Pattern 3
    // Provide an object with a plugin wide name space
    // Popcorn will manage the events
    (function( Popcorn ) {
      Popcorn.plugin( "pluginName", (function() {

        // Define plugin wide variables out here

        return {
          _setup: function( track ) {
            // setup code, fire on initialization

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          _update: function( track ) {
            // update code, fire on update/modification of a plugin created track event.

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          _teardown: function( track ) {
            // teardown code, fire on removal of plugin or destruction of instance

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          start: function( event, track ) {
            // fire on track.start

            // |event| refers to the event object

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          end: function( event, track ) {
            // fire on track.end

            // |event| refers to the event object

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          frame: function( event, track ) {
            // when frameAnimation is enabled, fire on every frame between start and end

            // |event| refers to the event object

            // |track| refers to the TrackEvent created by the options passed
            // into the plugin on init

            // this refers to the popcorn object
          },
          toString: function() {
            // provide a custom toString method for each plugin
            // defaults to return start, end, id, and target
            // this refers to the popcorn object
          }
        };
      })();
    })(Popcorn);

Plugin Manifest Interface for Butter

Butter, popcorn’s point and click authoring tool offers plugin authors a turnkey interface to it’s UI through plugin manifests as demonstrated below:

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
32
33
34
35

    // Pattern 3
    // Provide a plugin manifest with your plugin
    // This allows for butter to register your plugin
    (function( Popcorn ) {
      Popcorn.plugin( "pluginName", (function() {

        // Define plugin wide variables out here

        return {
          // Define a manifest for the butter authoring tool to use
          manifest: {
            // Plugin meta data
            // will be used in the butter ui
            about: {
              name: "name of plugin",
              version: "semantic version",
              author: "author name",
              website: "author url"
            },
            // Object representation of the plugin options
            // a form will be constructed against this object
            options: {
              start: { elem: "input", type: "text", label: "In" },
              end: { elem: "input", type: "text", label: "Out" },
              target: "id-selector",
              text: { elem: "input", type: "text", label: "Text" }
            }
          },
          _setup: function( options ){...},
          start: function( options ){...},
          end: function( options ){...},
          frame: function( options ){...},
          toString: function( options ){...}
      })());
    })(Popcorn);