Node WebVTT Parser, Compiler, and Segmenter

Common errors

• ParserError: Invalid cue timestamp (cue #X)

  cause A cue in the WebVTT input has a malformed or invalid timestamp format (e.g., missing milliseconds, incorrect separators, start time greater than or equal to end time) and the parser is in strict mode.
  fix Review and correct the timestamp format in the WebVTT file. Alternatively, call `webvtt.parse(input, { strict: false })` to allow parsing with errors and inspect the `result.errors` array.

• ParserError: Header is incorrect

  cause The WebVTT input string does not begin with 'WEBVTT' followed by a newline, or has other header-related issues, and the parser is in strict mode.
  fix Ensure the WebVTT file strictly adheres to the WebVTT specification, starting with 'WEBVTT' on the first line. For files with potential header variations, consider using `{ strict: false }`.

• TypeError: Cannot read properties of undefined (reading 'hlsSegmentPlaylist')

  cause This typically occurs if `webvtt.hls` is `undefined`, often due to incorrect import (`import { hls } from 'node-webvtt';` instead of `import webvtt from 'node-webvtt';`) or using an outdated version of the library that did not yet include HLS segmentation features.
  fix Ensure you are using `import webvtt from 'node-webvtt';` (ESM) or `const webvtt = require('node-webvtt');` (CJS) and accessing `hls` as a property of the default export: `webvtt.hls.hlsSegmentPlaylist(...)`. Verify your `node-webvtt` version supports HLS features (added in v1.2).

Warnings

• gotcha The `parse` function operates in strict mode by default. If the WebVTT input is malformed (e.g., incorrect header, invalid cue timestamps), it will throw a `ParserError` exception, requiring developers to wrap calls in `try/catch` blocks.
  Fix: Use a `try/catch` block around `webvtt.parse()` calls or pass `{ strict: false }` as an option to tolerate malformed cues and receive errors in an `errors` array instead of an exception.
• breaking The README indicates that the parser will not categorize cues starting and ending at the same time as an error when `strict` is `false`. However, changing this behavior to be `true` (i.e., treating `start === end` as an error) would constitute a breaking change in a 1.x version. Users relying on this lenient behavior should be aware of potential future changes.
  Fix: Ensure WebVTT cues have distinct start and end times (`start < end`) for maximum compatibility and future-proofing, especially if `strict: true` is desired.
• gotcha Support for parsing metadata from WebVTT files (e.g., `Kind: captions`) was added in version 1.3. Older versions will not correctly parse or return metadata, even if the `{ meta: true }` option is provided.
  Fix: Upgrade `node-webvtt` to version 1.3.0 or higher to enable WebVTT metadata parsing via the `{ meta: true }` option in `webvtt.parse()`.
• gotcha The `webvtt.hls.hlsSegment` function's `startOffset` parameter (for MPEG TS timestamp mapping) defaults to `900000`. This default might not align with specific HLS stream requirements or expected subtitle timings if not explicitly set.
  Fix: Explicitly define the `startOffset` parameter when calling `webvtt.hls.hlsSegment()` to ensure correct timestamp mapping for your HLS workflow, especially if not using the default 0 for `LOCAL` timestamp.

Install

• npm install node-webvtt npm
• yarn add node-webvtt yarn
• pnpm add node-webvtt pnpm

Imports

• webvtt
  wrong:

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

  correct:

  import webvtt from 'node-webvtt';

  The package supports both ES Module (ESM) `import` and CommonJS `require()`. For modern Node.js and browser environments, `import` is recommended.
• webvtt.parse
  wrong:

  import { parse } from 'node-webvtt';

  correct:

  import webvtt from 'node-webvtt';
  const parsed = webvtt.parse(input, { strict: true });

  The `parse` function is a method of the default `webvtt` object, not a named export. It can throw `ParserError` in strict mode.
• webvtt.hls.hlsSegmentPlaylist
  wrong:

  import { hlsSegmentPlaylist } from 'node-webvtt';

  correct:

  import webvtt from 'node-webvtt';
  const playlist = webvtt.hls.hlsSegmentPlaylist(input, segmentDuration);

  HLS-related functions are nested under the `hls` property of the main `webvtt` export.

Quickstart

This quickstart demonstrates parsing a WebVTT string (including metadata), compiling a parsed object back to WebVTT, and then segmenting the input to generate HLS-compatible WebVTT segments and an associated M3U8 playlist. It also highlights the use of `strict: false` and `meta: true` options for parsing.

import webvtt from 'node-webvtt';

const webvttInput = `WEBVTT
Kind: captions
Language: en

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

00:00:02.500 --> 00:00:04.000 align:start line:0%
This is a subtitle example.

00:00:05.000 --> 00:00:06.000
Foo bar.
`;

const segmentDuration = 2; // segments will be 2 seconds long

try {
  // 1. Parse the WebVTT input with metadata option
  const parsed = webvtt.parse(webvttInput, { strict: false, meta: true });
  console.log('--- Parsed WebVTT (Non-strict with Meta) ---');
  console.log(JSON.stringify(parsed, null, 2));

  // 2. Compile the parsed object back to WebVTT string
  // Note: For compilation, the input typically matches the parsed output structure.
  const compiledInput = {
    valid: true,
    meta: parsed.meta,
    cues: parsed.cues.filter(cue => cue.start < cue.end) // Filter out malformed cues if strict:false was used
  };
  const compiled = webvtt.compile(compiledInput);
  console.log('\n--- Compiled WebVTT ---');
  console.log(compiled);

  // 3. Segment the WebVTT for HLS and generate a playlist
  const segments = webvtt.hls.hlsSegment(webvttInput, segmentDuration);
  console.log('\n--- HLS Segments ---');
  segments.forEach((seg, i) => console.log(`Segment ${i}: ${seg.filename}\n${seg.content}`));

  const playlist = webvtt.hls.hlsSegmentPlaylist(webvttInput, segmentDuration);
  console.log('\n--- HLS Playlist (M3U8) ---');
  console.log(playlist);

} catch (error) {
  console.error('An error occurred during WebVTT processing:', error.message);
}