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     // Pattern 1
  2     // Provide a function that returns an object
  3     (function( Popcorn ) {
  4       Popcorn.plugin( "pluginName" , function( options ) {
  5         // do stuff
  6         // this refers to the popcorn object
  7 
  8         // You are required to return an object
  9         // with a start and end property
 10         return {
 11           _setup: function( track ) {
 12             // setup code, fire on initialization
 13 
 14             // |track| refers to the TrackEvent created by the options passed
 15             // into the plugin on init
 16 
 17             // this refers to the popcorn object
 18           },
 19           _update: function( track, updates ) {
 20             // update code, fire on update/modification of a plugin created track event.
 21 
 22             // |track| refers to the TrackEvent created by the options passed
 23             // into the plugin on init
 24 
 25             // |updates| refers to the new plugin data to be applied,
 26             // loop through this and apply the necessary updates to track
 27 
 28             // this refers to the popcorn object
 29           },
 30           _teardown: function( track ) {
 31             // teardown code, fire on removal of plugin or destruction of instance
 32 
 33             // |track| refers to the TrackEvent created by the options passed
 34             // into the plugin on init
 35 
 36             // this refers to the popcorn object
 37           },
 38           start: function( event, track ) {
 39             // fire on track.start
 40 
 41             // |event| refers to the event object
 42 
 43             // |track| refers to the TrackEvent created by the options passed
 44             // into the plugin on init
 45 
 46             // this refers to the popcorn object
 47           },
 48           end: function( event, track ) {
 49             // fire on track.end
 50 
 51             // |event| refers to the event object
 52 
 53             // |track| refers to the TrackEvent created by the options passed
 54             // into the plugin on init
 55 
 56             // this refers to the popcorn object
 57           },
 58           frame: function( event, track ) {
 59             // when frameAnimation is enabled, fire on every frame between start and end
 60 
 61             // |event| refers to the event object
 62 
 63             // |track| refers to the TrackEvent created by the options passed
 64             // into the plugin on init
 65 
 66             // this refers to the popcorn object
 67           },
 68           toString: function() {
 69             // provide a custom toString method for each plugin
 70             // defaults to return start, end, id, and target
 71             // this refers to the popcorn object
 72           }
 73         };
 74       });
 75     })(Popcorn);
 76 
 77 
 78     // Pattern 2
 79     // Provide an object
 80     // Popcorn will manage the events
 81     (function( Popcorn ) {
 82       Popcorn.plugin( "pluginName" , {
 83         _setup: function( track ) {
 84           // setup code, fire on initialization
 85 
 86           // |track| refers to the TrackEvent created by the options passed
 87           // into the plugin on init
 88 
 89           // this refers to the popcorn object
 90         },
 91         _update: function( track ) {
 92           // update code, fire on update/modification of a plugin created track event.
 93 
 94           // |track| refers to the TrackEvent created by the options passed
 95           // into the plugin on init
 96 
 97           // this refers to the popcorn object
 98         },
 99         _teardown: function( track ) {
100           // teardown code, fire on removal of plugin or destruction of instance
101 
102           // |track| refers to the TrackEvent created by the options passed
103           // into the plugin on init
104 
105           // this refers to the popcorn object
106         },
107         start: function( event, track ) {
108           // fire on track.start
109 
110           // |event| refers to the event object
111 
112           // |track| refers to the TrackEvent created by the options passed
113           // into the plugin on init
114 
115           // this refers to the popcorn object
116         },
117         end: function( event, track ) {
118           // fire on track.end
119 
120           // |event| refers to the event object
121 
122           // |track| refers to the TrackEvent created by the options passed
123           // into the plugin on init
124 
125           // this refers to the popcorn object
126         },
127         frame: function( event, track ) {
128           // when frameAnimation is enabled, fire on every frame between start and end
129 
130           // |event| refers to the event object
131 
132           // |track| refers to the TrackEvent created by the options passed
133           // into the plugin on init
134 
135           // this refers to the popcorn object
136         },
137         toString: function() {
138           // provide a custom toString method for each plugin
139           // defaults to return start, end, id, and target
140           // this refers to the popcorn object
141         }
142       });
143     })(Popcorn);
144 
145 
146     // Pattern 3
147     // Provide an object with a plugin wide name space
148     // Popcorn will manage the events
149     (function( Popcorn ) {
150       Popcorn.plugin( "pluginName", (function() {
151 
152         // Define plugin wide variables out here
153 
154         return {
155           _setup: function( track ) {
156             // setup code, fire on initialization
157 
158             // |track| refers to the TrackEvent created by the options passed
159             // into the plugin on init
160 
161             // this refers to the popcorn object
162           },
163           _update: function( track ) {
164             // update code, fire on update/modification of a plugin created track event.
165 
166             // |track| refers to the TrackEvent created by the options passed
167             // into the plugin on init
168 
169             // this refers to the popcorn object
170           },
171           _teardown: function( track ) {
172             // teardown code, fire on removal of plugin or destruction of instance
173 
174             // |track| refers to the TrackEvent created by the options passed
175             // into the plugin on init
176 
177             // this refers to the popcorn object
178           },
179           start: function( event, track ) {
180             // fire on track.start
181 
182             // |event| refers to the event object
183 
184             // |track| refers to the TrackEvent created by the options passed
185             // into the plugin on init
186 
187             // this refers to the popcorn object
188           },
189           end: function( event, track ) {
190             // fire on track.end
191 
192             // |event| refers to the event object
193 
194             // |track| refers to the TrackEvent created by the options passed
195             // into the plugin on init
196 
197             // this refers to the popcorn object
198           },
199           frame: function( event, track ) {
200             // when frameAnimation is enabled, fire on every frame between start and end
201 
202             // |event| refers to the event object
203 
204             // |track| refers to the TrackEvent created by the options passed
205             // into the plugin on init
206 
207             // this refers to the popcorn object
208           },
209           toString: function() {
210             // provide a custom toString method for each plugin
211             // defaults to return start, end, id, and target
212             // this refers to the popcorn object
213           }
214         };
215       })();
216     })(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     // Pattern 3
 2     // Provide a plugin manifest with your plugin
 3     // This allows for butter to register your plugin
 4     (function( Popcorn ) {
 5       Popcorn.plugin( "pluginName", (function() {
 6 
 7         // Define plugin wide variables out here
 8 
 9         return {
10           // Define a manifest for the butter authoring tool to use
11           manifest: {
12             // Plugin meta data
13             // will be used in the butter ui
14             about: {
15               name: "name of plugin",
16               version: "semantic version",
17               author: "author name",
18               website: "author url"
19             },
20             // Object representation of the plugin options
21             // a form will be constructed against this object
22             options: {
23               start: { elem: "input", type: "text", label: "In" },
24               end: { elem: "input", type: "text", label: "Out" },
25               target: "id-selector",
26               text: { elem: "input", type: "text", label: "Text" }
27             }
28           },
29           _setup: function( options ){...},
30           start: function( options ){...},
31           end: function( options ){...},
32           frame: function( options ){...},
33           toString: function( options ){...}
34       })());
35     })(Popcorn);