translate

node-vtt


node-vtt

Build Status npm-version Dependency Status
devDependency Status

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

###Table of Contents###

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.

Rating

ABOUT

LESS COMMENTS

MESSAGE REVIEW OK

Ok