Registry / web-framework / webvtt-parser

webvtt-parser

library2.2.0jsnpmunverified

The `webvtt-parser` package provides a robust, specification-compliant parser and serializer for WebVTT (Web Video Text Tracks) files. Maintained by the W3C, it allows developers to programmatically parse WebVTT strings into a JavaScript object tree and serialize such trees back into WebVTT formatted strings. The current stable version is 2.2.0, and releases generally follow W3C specification updates or bug fixes, without a fixed cadence. Its primary differentiator is its direct adherence to the official WebVTT specification, making it a reliable choice for applications requiring strict compliance, such as browser implementations or media processing tools. It supports both Node.js environments via npm and browser environments through a UMD build.

web-framework serialization

npm install webvtt-parser

github ↗package ↗

INSTALL

IMPORT

SIG · WEBVTT-PARSER

webvtt-parser

web-frameworkjavascriptv2.2.0

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.

WebVTTParser

✓ import { WebVTTParser } from 'webvtt-parser';

✗ const WebVTTParser = require('webvtt-parser').WebVTTParser;

Use named import for ESM. For CJS, access as a property of the require result. In browsers, it's available as `window.WebVTTParser`.

WebVTTSerializer

✓ import { WebVTTSerializer } from 'webvtt-parser';

✗ const WebVTTSerializer = require('webvtt-parser').WebVTTSerializer;

Use named import for ESM. For CJS, access as a property of the require result. In browsers, it's available as `window.WebVTTSerializer`.

ParserOptions

✓ import type { ParserOptions } from 'webvtt-parser';

✗ import { ParserOptions } from 'webvtt-parser';

This is a TypeScript type and should be imported using `import type` to avoid bundling issues and ensure correct type-checking.

Demonstrates how to initialize WebVTTParser, parse a basic VTT string, and optionally load HTML entities for full specification compliance.

import { WebVTTParser } from 'webvtt-parser'; // In a real application, fetch this from a URL or file system const someVTT = `WEBVTT FILE\n\n00:00:00.000 --> 00:00:05.000 Hello, world!\n 00:00:06.000 --> 00:00:10.000 This is a test subtitle.`; // Optionally load HTML entities for full spec compliance // In a real application, you'd fetch this file content const htmlEntitiesContent = JSON.stringify({ "amp": "&", "lt": "<", "gt": ">", "quot": "\"", "apos": "'", "nbsp": "\u00A0" }); // Placeholder, content of html-entities.json const parser = new WebVTTParser(); // Load HTML entities if full spec compliance is needed // This would typically involve an async import/fetch of html-entities.json // For demonstration, we'll use a simplified approach. if (htmlEntitiesContent) { parser.loadHTMLSerializerEntities(JSON.parse(htmlEntitiesContent)); } const tree = parser.parse(someVTT, 'metadata'); console.log(JSON.stringify(tree, null, 2)); /* Example of parsing a malformed VTT const malformedVTT = `WEBVTT\n 00:00:00.000 --> 00:00:05.000 This is a subtitle.`; const malformedTree = parser.parse(malformedVTT, 'metadata'); console.log('Errors:', malformedTree.errors); // Errors are reported on the tree object */

Debug

Known issues

gotchaFor full spec-compliant parsing of named character entities (e.g., `&`), you must explicitly load the content of `html-entities.json` into the `WebVTTParser` instance using `loadHTMLSerializerEntities()` or pass it to the constructor. Without this, only a small subset of common entities will be recognized.

fix

Obtain the `html-entities.json` file (typically from the `webvtt-parser` package itself or its GitHub repo) and pass its parsed content to `parser.loadHTMLSerializerEntities(entities)` after instantiation, or to the `WebVTTParser` constructor.

affects: >=1.0.0

breakingThe package primarily uses named exports for ESM (`import { WebVTTParser } from 'webvtt-parser'`). Direct `require('webvtt-parser')` in CommonJS environments will return an object containing the exports, not the default export, which could lead to `TypeError: WebVTTParser is not a constructor` if invoked incorrectly.

fix

For CommonJS, use `const { WebVTTParser } = require('webvtt-parser');` or `const WebVTTParser = require('webvtt-parser').WebVTTParser;`. For ESM, consistently use `import { Name } from 'pkg';`.

affects: >=1.0.0

gotchaErrors encountered during parsing (e.g., malformed WebVTT syntax) do not throw exceptions by default. Instead, they are accumulated in an `errors` array on the returned parse tree object. Developers should always inspect this array to ensure the VTT was parsed correctly.

fix

After calling `parser.parse()`, always check `tree.errors` to identify and handle any parsing issues. Example: `if (tree.errors && tree.errors.length > 0) { console.error('Parsing errors:', tree.errors); }`

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: WebVTTParser is not a constructor

Attempting to instantiate `WebVTTParser` after importing it incorrectly, most commonly when using CommonJS `require` syntax with an ESM-style import expectation, or vice-versa.

fix

Ensure correct import/require syntax for your module environment. For ESM: `import { WebVTTParser } from 'webvtt-parser';`. For CommonJS: `const { WebVTTParser } = require('webvtt-parser');`

ReferenceError: WebVTTParser is not defined

The `webvtt-parser` module was not correctly imported or included in the execution context, or attempting to use browser globals in Node.js or vice-versa without proper bundling/transpilation.

fix

Verify the import statement is present and correct at the top of your file. If in a browser, ensure `parser.js` is loaded via a `<script>` tag before your code runs. If using a bundler, confirm `webvtt-parser` is correctly resolved.

Expected an object for HTMLSerializerEntities

The `loadHTMLSerializerEntities` method or the `WebVTTParser` constructor was called with an invalid argument (e.g., `null`, `undefined`, or a non-object) when attempting to load HTML entities.

fix

Ensure that the `html-entities.json` content is correctly read and parsed into a JavaScript object before being passed to `loadHTMLSerializerEntities` or the constructor. It should be a plain object.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/w3c/webvtt.js ↗

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