node-vtt/README.md

node-vtt

A node wrapper for vtt.js. It runs vtt.js on PhantomJS from Node.

###Table of Contents###

• Install
• API
  • NodeVTT's Web Page
  • ready
  • cues
  • regions
  • vtt
  • errors
  • init(options, onInit)
  • shutdown()
  • parse(data, onParsed)
  • parseFile(file, onParsed)
  • flush(onFlush)
  • processParsedData(data, onProcessed)
  • processFile(file, onProcessed)
  • clear(onClear)
  • setupParser(encoding, onSetup)
  • error
• License

Install

node-vtt is on npm. To install run:

$ npm install node-vtt

You'll need to install PhantomJS if you haven't already. You can download it from its website or simply use npm:

$ npm install -g phantomjs

Or include it in your package.json dependencies.

API

node-vtt has a simple async API:

var NodeVTT = require("node-vtt"),
    nodeVTT = new NodeVTT();

nodeVTT.init(function() {
  nodeVTT.parseFile("someVTTFile", function(error) {
    if (error) {
      // Do something with error.
    }
    // Do something with the vtt we parsed.
    var vtt = nodeVTT.vtt;
    nodeVTT.processParsedData(function(error, divs) {
      if (error) {
        // Do something with error.
      }
      console.log(divs);
    });
  });
});

####NodeVTT's Web Page####

node-vtt uses PhantomJS to run vtt.js on a web page. Therefore, you need to have a simple HTML file for node-vtt to load. There is a default one provided for you, so read no further if you're not interested in customizing the page it uses.

If you provide your own page the page must have a few things.

• It must have the WebVTT, VTTCue, and VTTRegion shims provided by vtt.js. Doing this is most easily accomplished by using the vtt.js bower distributable and including it as a script on the page. However, if you want more granularity in what is included on the page from vtt.js you can also npm install vtt.js and have access to the individual source files through that.

• The page must also have the vttcue-extended and vttregion-extended versions of the VTTCue and VTTRegion shims on the page.

• If you'd like to run the processing model the page must have a div element on it with an id property of overlay and a positioning of relative. node-vtt uses this div as the container to display subtitles.

See the default page provided for you for more information.

Once you've created your own customized page check out how you can load it with the init function.

####ready####

The ready property describes whether or not node-vtt is ready to parse or process WebVTT. To get node-vtt ready you must call init. It will become "un-ready" when you all shutdown.

####cues####

The cues property contains an array of the aggregated VTTCues that have been parsed from a WebVTT file. Calling clear will empty the cues array.

var cues = nodeVTT.cues;

####regions####

The regions property contains an array of the aggregated VTTRegions that have been parsed from a WebVTT file. Calling clear will empty the regions array.

var regions = nodeVTT.regions;

####vtt####

The vtt property contains an object that is the cues and regions properties. This provides an easy way to get all the VTTCues and VTTRegions data parsed from a file.

var vtt = nodeVTT.vtt,
    cues = vtt.cues,
    regions = vtt.regions;

####errors####

The errors property contains an array of the aggregated ParsingErrors from vtt.js that have been received while parsing some WebVTT file. Calling clear will empty the errors array.

var errors = nodeVTT.errors;

####init(options, onInit)####

Initializes the node-vtt object. It optionally takes an options object that can contain two config properties—uri and encoding. uri points at a custom page that you want node-vtt to load and run on. The page must have the WebVTT shim from vtt.js included on the page as well as the shims for VTTCue (extended) and VTTRegion (extended). If you don't want to pass a uri a default page will be provided for you. The encoding property specifies the encoding of the data that you want to parse. node-vtt currently supports two types—string or utf8.

If you'd like to make a custom page for node-vtt to work with then check out more information on that here.

Using the default config of type utf8 and the basic page provided for you.

nodeVTT.init(function(error) {
  if (error) {
    return console.log(error.message);
  }
  // Run some node-vtt code.
});

Or with an options object:

nodeVTT.init({ uri: "my-web-page.html", encoding: "string" }, function(error) {
  if (error) {
    return console.log(error.message);
  }
  // Run some node-vtt code
});

####shutdown()####

Shuts node-vtt down. This is necessary as node-vtt will keep a PhantomJS instance alive until this method is called.

nodeVTT.shutdown();

####parse(data, onParsed)####

Parses data as a chunk of WebVTT data. data can either be a UTF8 Node ArrayBuffer or a string. Make sure to call init or setupParser with the appropriate encoding specified before calling this function. onParsed will return an error object that has a message property if an error occurred. The parsed VTTCues and VTTRegions are aggregated on the node-vtt object itself and can be accessed via the vtt, cues, or regions properties.

var fs = require("fs"),
    data = fs.readFileSync("vtt-file");

nodeVTT.parse(data, function(error) {
  if (error) {
    return console.log(error.message);
  }
  var vtt = nodeVTT.vtt;
});

####parseFile(file, onParsed)####

A version of parse(data, onParsed) that will read the WebVTT from a file for you and call flush where needed.

nodeVTT.parseFile("vtt-file", function(error) {
  if (error) {
    // Do something
  }
  var vtt = nodeVTT.vtt;
});

####flush(onFlush)####

Flushes the parser. This indicates that no more data will be coming to the parser and so it should parse any unparsed data it may have. This is necessary when parsing stream data. See flush on vtt.js for more information. onFlush will return an error if something went wrong, otherwise, it will return nothing.

nodeVTT.parse(data, function(){
  nodeVTT.parse(moreData, function() {
    nodeVTT.flush(function(error) {
      if (error) {
        console.log(error.message);
      }
      var vtt = nodeVTT.vtt;
    });
  });
});

####processParsedData(data, onProcessed)####

Runs the processing level steps of the WebVTT specification over the cues contained in data. data should be an object with a cues property on it that is an array of the VTTCues that should be processed. This turns the cues and regions into a series of div elements that have CSS and positioning applied to them and are ready to be shown on a video. These divs will be returned through the onProcessed callback and will also be automatically added as child elements to the overlay div. The overlay div is a div used as a container for the subtitles. This overlay div comes from the page that node-vtt loaded with the init function. The div on the page must have an id property set to 'overlay'.

var data = {
  cuse: [ /* VTTCues go in here */ ]
};
nodeVTT.processParsedData(data, function(error, divs) {
  if (error) {
    return console.log(error.message);
  }
  // Do something with divs.
});

Note: Processing regions isn't supported yet by vtt.js. It will be in the future though.

If you have just used the same instance of node-vtt to parse some data you can leave out the data parameter. The default is for it to use the cues and regions that it has aggregated already.

nodeVTT.parseFile("vtt-file", function() {
  // Leave out that 'data' parameter as we just parsed some WebVTT and we can use
  // the VTTCues and VTTRegions aggregated by this nodeVTT instance in its cues
  // and regions properties.
  nodeVTT.processParsedData(function(error, divs) {
    if (error) {
      return console.log(error.message);
    }
    // Do something with divs.
  });
});

####processFile(file, onProcessed)####

A version of processParsedData except that it will read and parse the WebVTT data contained within the file and process it for you in one go.

nodeVTT.processFile("vtt-file", function(error, divs) {
  if (error) {
    return console.log(error);
  }
  // Do something with divs
});

####clear(onClear)####

Clears the state of node-vtt. This will create a fresh parser and empty the vtt, cues, regions, and errors arrays. onClear will be called with an error if something went wrong.

This enables you to start parsing a new set of WebVTT data without creating a whole new node-vtt object which is epensive since it has to start PhantomJS and establish a connection.

nodeVTT.clear(function(error) {
  if (error) {
    console.log(error.message);
  }
  // Ready to do some more parsing.
});

Note: Calling clear is only necessary if you want to parse a new set of WebVTT data. You do not need to call it if you're just calling the processing functions.

####setupParser(encoding, onSetup)####

Clears the current state of node-vtt, see clear, and sets up a new parser that is configured to parse the encoding specified. Only string and utf8 are currently supported for encodings. If you don't pass encoding this function has the exact same behaviour as clear.

nodeVTT.setupParser("string", function() {
  var data = "WEBVTT\n00:00.000 --> 00:01.000\nI'm a Cue!";
  nodeVTT.parse(data, function() {
    console.log(nodeVTT.vtt);
  });
});

####error####

The error objects returned by node-vtt are simple JS objects with a message property on them describing the error.

nodeVTT.parseFile("wrong-file", function(error) {
  if (error) {
    console.log(error.message);
  }
});

License

Apache v2.0. See LICENSE.