www.aleph1.co.uk Git - yaffs-website/blob - node_modules/videojs-vtt.js/README.md

   1 vtt.js
   2 ======
   3
   4 [comment]: # ([![Build Status](https://travis-ci.org/mozilla/vtt.js.svg?branch=master)](https://travis-ci.org/mozilla/vtt.js) [![npm-version](http://img.shields.io/npm/v/vtt.js.svg)](https://www.npmjs.org/package/vtt.js) [![Dependency Status](https://david-dm.org/mozilla/vtt.js.svg?theme=shields.io)](https://david-dm.org/mozilla/vtt.js) [![devDependency Status](https://david-dm.org/mozilla/vtt.js/dev-status.svg?theme=shields.io)](https://david-dm.org/mozilla/vtt.js#info=devDependencies))
   5
   6 Implementation of the [WebVTT](https://developer.mozilla.org/en-US/docs/HTML/WebVTT) spec in JavaScript. Can be used
   7 in NodeJS, on the browser, and many other places. Mozilla uses this implementation for parsing and processing WebVTT
   8 files in Firefox/Gecko.
   9
  10 This is a fork of vttjs with some changes that are used by Video.js.
  11
  12 ##Table of Contents##
  13
  14 - [Spec Compliance](#spec-compliance)
  15 - [API](#api)
  16   - [WebVTT.Parser](#webvttparser)
  17     - [parse(data)](#parsedata)
  18     - [flush()](#flush)
  19     - [onregion(region)](#onregionregion)
  20     - [oncue(cue)](#oncuecue)
  21     - [onflush()](#onflush)
  22     - [onparsingerror(error)](#onparsingerrorerror)
  23     - [ontimestampmap(timestampmap)](#ontimestampmaptimestampmap)
  24   - [WebVTT.convertCueToDOMTree(window, cuetext)](#webvttconvertcuetodomtreewindow-cuetext)
  25   - [WebVTT.processCues(window, cues, overlay)](#webvttprocesscueswindow-cues-overlay)
  26   - [ParsingError](#parsingerror)
  27   - [VTTCue](#vttcue)
  28     - [Extended API](#extended-api)
  29       - [toJSON()](#tojson)
  30       - [VTTCue.fromJSON(json)](#vttcuefromjsonjson)
  31       - [VTTCue.create(options)](#vttcuecreateoptions)
  32   - [VTTRegion](#vttregion)
  33     - [Extended API](#extended-api-1)
  34         - [VTTRegion.fromJSON(json)](#vttregionfromjsonjson)
  35         - [VTTRegion.create(options)](#vttregioncreateoptions)
  36 - [Browser](#browser)
  37   - [Building Yourself](#building-yourself)
  38   - [Bower](#bower)
  39   - [Usage](#usage)
  40 - [Node](#node)
  41   - [vtt.js](#vttjs-1)
  42   - [node-vtt](#node-vtt)
  43 - [Developing vtt.js](#developing-vttjs)
  44   - [Tests](#tests)
  45     - [Writing Tests](#writing-tests)
  46   - [Grunt Run Task](#grunt-run-task)
  47
  48 Spec Compliance
  49 ===============
  50
  51 - [Parsing](http://dev.w3.org/html5/webvtt/#webvtt-file-format-parsing) (Completed)
  52   - [File](http://dev.w3.org/html5/webvtt/#webvtt-file-parsing) (Completed)
  53   - [Region](http://dev.w3.org/html5/webvtt/#webvtt-region-settings-parsing) (Completed)
  54   - [Cue Timings and Settings](http://dev.w3.org/html5/webvtt/#webvtt-cue-timings-and-settings-parsing) (Completed)
  55   - [WebVTT Cue Text](http://dev.w3.org/html5/webvtt/#dfn-webvtt-cue-text-parsing-rules) (Completed)
  56   - [Cue DOM Construction](http://dev.w3.org/html5/webvtt/#webvtt-cue-text-dom-construction-rules) (Completed)
  57 - [Rendering](http://dev.w3.org/html5/webvtt/#rendering) (In Progress)
  58   - [Processing Model](http://dev.w3.org/html5/webvtt/#processing-model) (In Progress) ***No VTTRegion or vertical text support***
  59     - [Apply WebVTT Cue Settings](http://dev.w3.org/html5/webvtt/#dfn-apply-webvtt-cue-settings) (In Progress)
  60       - Steps 1 - 11 (Completed)
  61       - Step 12 (In progress)
  62   - [Applying CSS Properties](http://dev.w3.org/html5/webvtt/#applying-css-properties-to-webvtt-node-objects) (Completed)
  63   - [CSS Extensions](http://dev.w3.org/html5/webvtt/#css-extensions) **(Won't Implement)**
  64 - [WebVTT API Shim](http://dev.w3.org/html5/webvtt/#webvtt-api-for-browsers) (Completed)
  65   - [VTTCue](http://dev.w3.org/html5/webvtt/#vttcue-interface) (Completed) ***Shims the TextTrackCue interface as well***
  66   - [VTTRegion](http://dev.w3.org/html5/webvtt/#vttregion-interface) (Completed)
  67
  68 ###Notes###
  69
  70 Our processing model portion of the specification makes use of a custom property, `hasBeenReset`. It allows us to detect
  71 when a VTTCue is dirty, i.e. one of its properties that affects display has changed and so we need to recompute its display
  72 state. This allows us to reuse a cue's display state if it has already been computed and nothing has changed to effect its
  73 position.
  74
  75 API
  76 ===
  77
  78 ####WebVTT.Parser####
  79
  80 The parser has a simple API:
  81
  82 ```javascript
  83 var parser = new WebVTT.Parser(window, stringDecoder);
  84 parser.onregion = function(region) {};
  85 parser.oncue = function(cue) {};
  86 parser.onflush = function() {};
  87 parser.onparsingerror = function(e) {};
  88 parser.parse(moreData);
  89 parser.parse(moreData);
  90 parser.flush();
  91 ```
  92
  93 The Parser constructor is passed a window object with which it will create new
  94 VTTCues and VTTRegions as well as an optional StringDecoder object which
  95 it will use to decode the data that the `parse()` function receives. For ease of
  96 use, a StringDecoder is provided via `WebVTT.StringDecoder()`. If a custom
  97 StringDecoder object is passed in it must support the API specified by the
  98 [#whatwg string encoding](http://encoding.spec.whatwg.org/#api) spec.
  99
 100 ####parse(data)####
 101
 102 Hands data in some format to the parser for parsing. The passed data format
 103 is expected to be decodable by the StringDecoder object that it has. The parser
 104 decodes the data and reassembles partial data (streaming), even across line breaks.
 105
 106 ```javascript
 107 var parser = new WebVTT.Parser(window, WebVTT.StringDecoder());
 108 parser.parse("WEBVTT\n\n");
 109 parser.parse("00:32.500 --> 00:33.500 align:start size:50%\n");
 110 parser.parse("<v.loud Mary>That's awesome!");
 111 parser.flush();
 112 ```
 113
 114 ####flush()####
 115
 116 Indicates that no more data is expected and will force the parser to parse any
 117 unparsed data that it may have. Will also trigger [onflush](#onflush).
 118
 119 ####onregion(region)####
 120
 121 Callback that is invoked for every region that is correctly parsed. Returns a [VTTRegion](#http://dev.w3.org/html5/webvtt/#dfn-vttregion)
 122 object.
 123
 124 ```js
 125 parser.onregion = function(region) {
 126   console.log(region);
 127 };
 128 ```
 129
 130 ####oncue(cue)####
 131
 132 Callback that is invoked for every cue that is fully parsed. In case of streaming parsing oncue is
 133 delayed until the cue has been completely received. Returns a [VTTCue](#http://dev.w3.org/html5/webvtt/#vttcue-interface) object.
 134
 135 ```js
 136 parser.oncue = function(cue) {
 137   console.log(cue);
 138 };
 139 ```
 140
 141 ####onflush()####
 142
 143 Is invoked in response to `flush()` and after the content was parsed completely.
 144
 145 ```js
 146 parser.onflush = function() {
 147   console.log("Flushed");
 148 };
 149 ```
 150
 151 ####onparsingerror(error)####
 152
 153 Is invoked when a parsing error has occured. This means that some part of the
 154 WebVTT file markup is badly formed. See [ParsingError](#parsingerror) for more
 155 information.
 156
 157 ```js
 158 parser.onparsingerror = function(e) {
 159   console.log(e);
 160 };
 161 ```
 162
 163 ####ontimestampmap(timestampmap)####
 164
 165 Is invoked when an `X-TIMESTAMP-MAP` metadata header ([defined here](https://tools.ietf.org/html/draft-pantos-http-live-streaming-20#section-3.5)) is parsed. This header maps WebVTT cue timestamps to MPEG-2 (PES) timestamps in other Renditions of the Variant Stream.
 166
 167 ```js
 168 parser.ontimestampmap = function(timestamp) {
 169   console.log('LOCAL:', timestamp.LOCAL);
 170   console.log('MPEGTS:', timestamp.MPEGTS);
 171 };
 172 ```
 173
 174 ####WebVTT.convertCueToDOMTree(window, cuetext)####
 175
 176 Parses the cue text handed to it into a tree of DOM nodes that mirrors the internal WebVTT node structure of
 177 the cue text. It uses the window object handed to it to construct new HTMLElements and returns a tree of DOM
 178 nodes attached to a top level div.
 179
 180 ```javascript
 181 var div = WebVTT.convertCueToDOMTree(window, cuetext);
 182 ```
 183
 184 ####WebVTT.processCues(window, cues, overlay)####
 185
 186 Converts the cuetext of the cues passed to it to DOM trees&mdash;by calling convertCueToDOMTree&mdash;and
 187 then runs the processing model steps of the WebVTT specification on the divs. The processing model applies the necessary
 188 CSS styles to the cue divs to prepare them for display on the web page. During this process the cue divs get added
 189 to a block level element (overlay). The overlay should be a part of the live DOM as the algorithm will use the
 190 computed styles (only of the divs to do overlap avoidance.
 191
 192 ```javascript
 193 var divs = WebVTT.processCues(window, cues, overlay);
 194 ```
 195
 196 ####ParsingError####
 197
 198 A custom JS error object that is reported through the
 199 [onparsingerror](#onparsingerror) callback. It has a `name`, `code`, and
 200 `message` property, along with all the regular properties that come with a
 201 JavaScript error object.
 202
 203 ```json
 204 {
 205   "name": "ParsingError",
 206   "code": "SomeCode",
 207   "message": "SomeMessage"
 208 }
 209 ```
 210
 211 There are two error codes that can be reported back currently:
 212
 213 - 0 BadSignature
 214 - 1 BadTimeStamp
 215
 216 **Note:** Exceptions other then `ParsingError` will be thrown and not reported.
 217
 218 ####VTTCue####
 219
 220 A DOM shim for the VTTCue. See the [spec](http://dev.w3.org/html5/webvtt/#vttcue-interface)
 221 for more information. Our VTTCue shim also includes properties of its abstract base class
 222 [TextTrackCue](http://www.whatwg.org/specs/web-apps/current-work/multipage/the-video-element.html#texttrackcue).
 223
 224 ```js
 225 var cue = new window.VTTCue(0, 1, "I'm a cue.");
 226 ```
 227
 228 **Note:** Since this polfyill doesn't implement the track specification directly the `onenter`
 229 and `onexit` events will do nothing and do not exist on this shim.
 230
 231 ####Extended API####
 232
 233 There is also an extended version of this shim that gives a few convenience methods
 234 for converting back and forth between JSON and VTTCues. If you'd like to use these
 235 methods then us `vttcue-extended.js` instead of `vttcue.js`. This isn't normally
 236 built into the `vtt.js` distributable so you will have to build a custom distribution
 237 instead of using bower.
 238
 239 ####toJSON()####
 240
 241 Converts a cue to JSON.
 242
 243 ```js
 244 var json = cue.toJSON();
 245 ```
 246
 247 ####VTTCue.fromJSON(json)####
 248
 249 Create and initialize a VTTCue from JSON.
 250
 251 ```js
 252 var cue = VTTCue.fromJSON(json);
 253 ```
 254
 255 ####VTTCue.create(options)####
 256
 257 Initializes a VTTCue from an options object where the properties in the option
 258 objects are the same as the properties on the VTTCue.
 259
 260 ```js
 261 var cue = VTTCue.create(options);
 262 ```
 263
 264 ####VTTRegion####
 265
 266 A DOM shim for the VTTRegion. See the [spec](http://dev.w3.org/html5/webvtt/#vttregion-interface)
 267 for more information.
 268
 269 ```js
 270 var region = new window.VTTRegion(0, 1, "I'm a region.");
 271 cue.region = region;
 272 ```
 273
 274 ####Extended API####
 275
 276 There is also an extended version of this shim that gives a few convenience methods
 277 for converting back and forth between JSON and VTTRegions. If you'd like to use these
 278 methods then us `vttregion-extended.js` instead of `vttregion.js`. This isn't normally
 279 built into the `vtt.js` distributable so you will have to build a custom distribution
 280 instead of using bower.
 281
 282 ####VTTRegion.fromJSON(json)####
 283
 284 Creates and initializes a VTTRegion from JSON.
 285
 286 ```js
 287 var region = VTTRegion.fromJSON(json);
 288 ```
 289
 290 ####VTTRegion.create(options)####
 291
 292 Creates a VTTRegion from an options object where the properties on the options
 293 object are the same as the properties on the VTTRegion.
 294
 295 ```js
 296 var region = VTTRegion.create(options);
 297 ```
 298
 299 Browser
 300 =======
 301
 302 In order to use the `vtt.js` in a browser, you need to get the built distribution of vtt.js. The distribution
 303 contains polyfills for [TextDecoder](http://encoding.spec.whatwg.org/), [VTTCue](http://dev.w3.org/html5/webvtt/#vttcue-interface),
 304 and [VTTRegion](http://dev.w3.org/html5/webvtt/#vttregion-interface) since not all browsers currently
 305 support them.
 306
 307 ###Building Yourself###
 308
 309 Building a browser-ready version of the library is done using `grunt` (if you haven't installed
 310 `grunt` globally, you can run it from `./node_modules/.bin/grunt` after running `npm install`):
 311
 312 ```bash
 313 $ grunt build
 314 $ Running "uglify:dist" (uglify) task
 315 $ File "dist/vtt.min.js" created.
 316
 317 $ Running "concat:dist" (concat) task
 318 $ File "dist/vtt.js" created.
 319
 320 $ Done, without errors.
 321 ```
 322
 323 Your newly built `vtt.js` now lives in `dist/vtt.min.js`, or alternatively, `dist/vtt.js` for an
 324 unminified version.
 325
 326 ###Bower###
 327
 328 You can also get the a prebuilt distribution from [Bower](http://bower.io/). Either run the shell
 329 command:
 330
 331 ```bash
 332 $ bower install vtt.js
 333 ```
 334
 335 Or include `vtt.js` as a dependency in your `bower.json` file. `vtt.js` should now
 336 live in `bower_components/vtt.js/vtt.min.js`. There is also an unminified
 337 version included with bower at `bower_components/vtt.js/vtt.js`.
 338
 339 ###Usage###
 340
 341 To use `vtt.js` you can just include the script on an HTML page like so:
 342
 343 ```html
 344 <html>
 345 <head>
 346   <meta charset="utf-8">
 347   <title>vtt.js in the browser</title>
 348   <script src="bower_components/vtt.js/vtt.min.js"></script>
 349 </head>
 350 <body>
 351   <script>
 352     var vtt = "WEBVTT\n\nID\n00:00.000 --> 00:02.000\nText",
 353         parser = new WebVTT.Parser(window, WebVTT.StringDecoder()),
 354         cues = [],
 355         regions = [];
 356     parser.oncue = function(cue) {
 357       cues.push(cue);
 358     };
 359     parser.onregion = function(region) {
 360       regions.push(region);
 361     }
 362     parser.parse(vtt);
 363     parser.flush();
 364
 365     var div = WebVTT.convertCueToDOMTree(window, cues[0].text);
 366     var divs = WebVTT.processCues(window, cues, document.getElementById("overlay"));
 367   </script>
 368   <div id="overlay" style="position: relative; width: 300px; height: 150px"></div>
 369 </body>
 370 </html>
 371 ```
 372
 373 Node
 374 ====
 375
 376 You have a couple of options if you'd like to run the library from Node.
 377
 378 ###vtt.js###
 379
 380 `vtt.js` is on npm. Just do:
 381
 382 ```
 383 npm install vtt.js
 384 ```
 385
 386 Require it and use it:
 387
 388 ```js
 389 var vtt = require("vtt.js"),
 390     WebVTT = vtt.WebVTT,
 391     VTTCue = vtt.VTTCue,
 392     VTTRegion = vtt.VTTRegion;
 393
 394 var parser = new WebVTT.Parser(window);
 395 parser.parse();
 396 // etc
 397
 398 var elements = WebVTT.processCues(window, cues, overlay);
 399 var element = WebVTT.convertCueToDOMTree(window, cuetext);
 400
 401 var cue = new VTTCue(0, 1, "I'm a cue.");
 402 var region = new VTTRegion();
 403 ```
 404
 405 See the [API](#api) for more information on how to use it.
 406
 407 **Note:** If you use this method you will have to provide your own window object
 408 or a shim of one with the necessary functionality for either the parsing or processing
 409 portion of the spec. The only shims that are provided to you are `VTTCue` and `VTTRegion`
 410 which you can attach to your global that is passed into the various functions.
 411
 412 ###node-vtt###
 413
 414 Use [node-vtt](https://github.com/mozilla/node-vtt). Node-vtt runs `vtt.js` on a PhantomJS page
 415 from Node so it has access to a full DOM and CSS layout engine which means you can run any part
 416 of the library you want. See the [node-vtt](https://github.com/mozilla/node-vtt) repo for more
 417 information.
 418
 419 Developing vtt.js
 420 =================
 421
 422 A few things to note:
 423
 424 * When bumping the version remember to use the `grunt release` task as this will
 425 bump `package.json` + `bower.json` and build the `dist` files for `vtt.js` in one
 426 go.
 427 * The [Grunt Run Task](#grunt-run-task) tool is handy for running the library without having
 428 to run the whole test suite or set of tests.
 429
 430 ####Tests####
 431
 432 Tests are written and run using [Mocha](http://visionmedia.github.io/mocha/) on node.js.
 433
 434 To run all the tests, do the following:
 435
 436 ```bash
 437 $ npm test
 438 ```
 439
 440 If you want to run individual tests, you can install the [Mocha](http://visionmedia.github.io/mocha/) command-line
 441 tool globally, and then run tests per-directory:
 442
 443 ```bash
 444 $ npm install -g mocha
 445 $ cd tests/some/sub/dir
 446 $ mocha --reporter spec --timeout 200000
 447 ```
 448
 449 See the [usage docs](http://visionmedia.github.io/mocha/#usage) for further usage info.
 450
 451 ###Writing Tests###
 452
 453 Tests are done by comparing live parsed output to a last-known-good JSON file. The JSON files
 454 can be easily generated using `vtt.js`, so you don't need to write these by hand
 455 (see details below about [Grunt Run Task](#grunt-run-task)).
 456
 457 ####TestRunner####
 458
 459 There's a prebuilt API in place for testing different parts of `vtt.js`. Simply
 460 require the [TestRunner](https://github.com/mozilla/vtt.js/blob/master/tests/test-runner.js)
 461 module in the `lib` directory and start writing tests using `mocha`. See an example of a test file
 462 [here](https://github.com/mozilla/vtt.js/blob/master/tests/cue-settings/align/test.js)
 463 with its first test's WebVTT file [here](https://github.com/mozilla/vtt.js/blob/master/tests/cue-settings/align/bad-align.vtt)
 464 and its corresponding [parsing JSON file](https://github.com/mozilla/vtt.js/blob/master/tests/cue-settings/align/bad-align.json)
 465 and [processing JSON file](https://github.com/mozilla/vtt.js/blob/master/tests/cue-settings/align/bad-align-proc.json).
 466 You can also check out the [tests](https://github.com/mozilla/vtt.js/tree/master/tests)
 467 directory for more examples on how to write tests.
 468
 469 ####jsonEqual(vttFile, jsonRefFile, message, onDone)####
 470
 471 First parses the WebVTT file as UTF8 and compares it to the reference JSON file
 472 and then parses the WebVTT file as a string and compares it to the reference JSON
 473 file.
 474
 475 ####jsonEqualStreaming(vttFile, jsonRefFile, message, onDone)####
 476
 477 Simulates parsing the file while streaming by splitting the WebVTT file into
 478 chunks. Will simulate parsing like this `n` times for a single WebVTT file where
 479 `n` is the length in unicode characters of the file, so use this only on small
 480 files or else you will get a timeout failure on your test.
 481
 482 ####jsonEqualParsing(vttFile, jsonRefFile, message, onDone)####
 483
 484 Runs `jsonEqual` and `jsonEqualStreaming` in one go.
 485
 486 ####jsonEqualProcModel(vttFile, jsonRefFile, message, onDone)####
 487
 488 Runs the processing model over the `VTTCues` and `VTTRegions` that are returned
 489 from parsing the WebVTT file.
 490
 491 ####jsonEqualAll(vttFile, jsonRefFile, message, onDone)####
 492
 493 Runs `jsonEqualParsing` and `jsonEqualProcModel`. Note that `jsonRefFile` should
 494 contain JSON that is generated from parsing. The processing model test will compare
 495 its results to a JSON file located at `[vttFile]-proc.json`. Therefore, if you
 496 have a WebVTT file named `basic.vtt` the JSON reference file for the processing
 497 model tests will be `basic-proc.json`.
 498
 499 ####jsonEqualAllNoStream(vttFile, jsonRefFile, message, onDone)####
 500
 501 Runs `jsonEqual` and `jsonEqualProcModel` use this if you want to do parsing
 502 and processing tests, but do not want to simulate streaming because you
 503 have too big of a WebVTT file.
 504
 505 ###Grunt Run Task###
 506
 507 You can automatically generate a JSON file for a given `.vtt` file using the
 508 `run` Grunt task.
 509
 510 To get parsed JSON output from some WebVTT file do:
 511
 512 ```bash
 513 $ grunt run:my-vtt-file.vtt
 514 $ grunt run:my-vtt-file.vtt > my-json-file.json
 515 ```
 516
 517 To get processed output from the WebVTT file do:
 518
 519 ```bash
 520 $ grunt run:my-vtt-file.vtt:p
 521 $ grunt run:my-vtt-file.vtt:p > my-json-file.json
 522 ```
 523
 524 By passing the `c` flag you can automatically copy the output into a JSON file
 525 with the same name as the WebVTT file:
 526
 527 ```bash
 528 $ grunt run:my-vtt-file.vtt:c
 529 $ grunt run:my-vtt-file.vtt:pc
 530 ```
 531
 532 The parsed JSON output now lives in `my-vtt-file.json` and the processing JSON
 533 output lives in `my-vtt-file-proc.json`.
 534
 535 You can also run it over a directory copying the output of parsing or
 536 processing each WebVTT file to a corresponding JSON file like so:
 537
 538 ```bash
 539 $ grunt run:my-vtt-file-directory
 540 $ grunt run:my-vtt-file-directory:p
 541 ```
 542
 543 This is useful when you've modified how `vtt.js` works and each JSON file needs
 544 a slight change.
 545
 546 The `run` task utilizes a script called `cue2json`, but
 547 does a few other things for you before each run like building a development
 548 build for `cue2json` to use. It's also a bit easier to type in the CL options
 549 for the task. If you want to know more about `cue2json` you can run it directly
 550 like so:
 551
 552 ```bash
 553 $ ./bin/cue2json.js
 554 $ Generate JSON test files from a reference VTT file.
 555 $ Usage: node ./bin/cue2json.js [options]
 556 $
 557 $ Options:
 558 $   -v, --vtt      Path to VTT file.
 559 $   -d, --dir      Path to test directory. Will recursively find all JSON files with matching VTT files and rewrite them.
 560 $   -c, --copy     Copies the VTT file to a JSON file with the same name.
 561 $   -p, --process  Generate a JSON file of the output returned from the processing model.
 562 ```
 563
 564 **Notes:**
 565
 566 * `cue2json` utilizes the last development build done. This is why the Grunt `run` task is
 567 good as you don't have to remember to build it yourself. If you don't build it yourself then you could
 568 potentially get incorrect results from it.
 569 * Since `cue2json` uses the actual parser to generate these JSON files there is the possibility that
 570 the generated JSON will contain bugs. Therefore, always check the generated JSON files to check that the
 571 parser actually parsed according to spec.