node-vtt
v1.1.7
Published
A node wrapper for vtt.js
Downloads
184
Maintainers
Readme
node-vtt
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
, andVTTRegion
shims provided by vtt.js. Doing this is most easily accomplished by using thevtt.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 fromvtt.js
you can alsonpm install vtt.js
and have access to the individual source files through that.The page must also have the
vttcue-extended
andvttregion-extended
versions of theVTTCue
andVTTRegion
shims on the page.If you'd like to run the processing model the page must have a
div
element on it with anid
property ofoverlay
and a positioning ofrelative
.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 recieved 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 occured. 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.