WebVTT parser and segmenter with HLS support

Usage no npm install needed!

<script type="module">
  import voctrolabsNodeWebvtt from 'https://cdn.skypack.dev/@voctrolabs/node-webvtt';


WebVTT parser and segmenter

Parse WebVTT files, segments and generates HLS playlists for them.


For a WebVTT file:


00:00:00.000 --> 00:00:01.000
Hello world!

00:00:30.000 --> 00:00:31.000 align:start line:0%
This is a subtitle

00:01:00.000 --> 00:01:01.000

00:01:50.000 --> 00:01:51.000

We can parse, segment and create HLS playlists:

const webvtt = require('node-webvtt');

const segmentDuration = 10; // default to 10
const startOffset = 0; // Starting MPEG TS offset to be used in timestamp map, default 900000

const parsed = webvtt.parse(input);
const segmented = webvtt.parse(input, segmentDuration);
const playlist = webvtt.hls.hlsSegmentPlaylist(input, segmentDuration);
const segments = webvtt.hls.hlsSegment(input, segmentDuration, startOffset);


Parses the WebVTT file and returns an object with valid === true if parsed correctly and an array of cues parsed.

Each cue can have:

  • identifier - Id, if any of the cue
  • start - Start time of cue in seconds
  • end - End time of cue in seconds
  • text - Text of the subtitle
  • styles - If any of the cue

If the WebVTT file is invalid, the parser will throw a ParserError exception. So for safety, calls to parse should be in try catch.

For the above example we'd get:

         "text":"Hello world!",
         "text":"This is a subtitle",
         "styles":"align:start line:0%"


Segments a subtitle according to how it should be segmented for HLS subtitles.

  • Does a one pass of the cues for segmenting, this might have been a good idea or bad, only time will tell
  • The One and Only Source of Truth is Apple's mediasubtitlesegmenter CLI

For the above example:

    { duration: 10, cues: [ [Object] ] },
    { duration: 30, cues: [ [Object] ] },
    { duration: 30, cues: [ [Object] ] },
    { duration: 41, cues: [ [Object] ] }

HLS playlist

Creates a subtitle playlist. For the above:


HLS Segments

Creates a list of HLS segments for the subtitles, returning an array of them with filename and content.

      "content":"WEBVTT\nX-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000\n\n00:00:00.000 --> 00:00:01.000\nHello world!\n"
      "content":"WEBVTT\nX-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000\n\n00:00:30.000 --> 00:00:31.000 align:start line:0%\nThis is a subtitle\n"
      "content":"WEBVTT\nX-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000\n\n00:01:00.000 --> 00:01:01.000\nFoo\n"
      "content":"WEBVTT\nX-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000\n\n00:01:50.000 --> 00:01:51.000\nBar\n"


For segmenting a WebVTT file quickly, you can use the included CLI tool:

$ ./webvtt-segment.js -v --target-duration 10 -o ./subs subs.vtt
% ./webvtt-segment.js --help

  Usage: webvtt-segment [options] <webvtt file>


    -h, --help                        output usage information
    -V, --version                     output the version number
    -t, --target-duration [duration]  Target duration for each segment in secods, defaults to 10
    -o, --output-directory [dir]      Output directory for segments and playlist
    -v, --verbose                     Chatty output
    -s, --silent                      No output


This has been written with TDD so we've got a good coverage of the features.

npm install
npm test
mocha -w
<write failing test>
<write passing code>
<lather, rinse, repeat>


  • Remove valid from parsing result, having a result means it's valid
  • Add more options to control output
  • Better parsing
  • Support more subtitles formats (at least SRT, maybe SSA/ASS)
  • Iron out segmenting bugs with real playlists
  • Refactor the mess that is the segmenter (yay, unit tests!)
  • Nicer interface, don't be parsing again and again
  • Do something to make the cli tool more accessible
  • Code coverage reporting