node-webvtt

library1.9.4jsnpmunverified

node-webvtt is a JavaScript library designed for comprehensive handling of WebVTT (Web Video Text Tracks) files. It provides functionalities for parsing WebVTT input into a structured JavaScript object, compiling such objects back into WebVTT format, and segmenting WebVTT content. A key differentiator is its integrated support for HLS (HTTP Live Streaming), enabling the generation of HLS playlists and segments directly from WebVTT data, which is crucial for delivering timed text tracks alongside adaptive video streams. The library is currently at version 1.9.4 (as of the last recorded release in early 2022) and maintains an active release cadence, primarily focusing on bug fixes, dependency updates, and minor feature enhancements. It offers both strict and non-strict parsing options, allowing developers to control error handling behavior when processing potentially malformed VTT files, and also supports parsing of WebVTT metadata.

serialization http-networking web-framework

npm install node-webvtt

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-WEBVTT

node-webvtt

serializationjavascriptv1.9.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

webvtt

✓ import webvtt from 'node-webvtt';

✗ const webvtt = require('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

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

✗ import { parse } from 'node-webvtt';

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

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

✗ import { hlsSegmentPlaylist } from 'node-webvtt';

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

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); }

Debug

Known issues

gotchaThe `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.

affects: >=1.0.0

breakingThe 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.

affects: >=1.6.1

gotchaSupport 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()`.

affects: <1.3.0

gotchaThe `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.

affects: >=1.2.0

Errors

Common errors & fixes

ParserError: Invalid cue timestamp (cue #X)

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

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')

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).

Upgrade

Version history

1.9.4latest on npm

Audit

Dependencies

lodashrequiredUtility belt dependency, used for various internal operations.

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/osk/node-webvtt ↗

packagehttps://www.npmjs.com/package/node-webvtt ↗