Registry / serialization / media-captions

media-captions

JSON →
library0.0.18jsnpmunverified

The `media-captions` library is a robust, lightweight, and zero-dependency solution for parsing and rendering various media caption formats on the modern web. It supports SubRip (SRT), WebVTT (VTT), and SubStation Alpha/Advanced SubStation Alpha (SSA/ASS) formats. Currently at version 0.0.18, it is actively maintained by the Vidstack team as a core component of their media player ecosystem, which ensures consistent and accessible caption experiences across different browsers and platforms, addressing limitations often found with native browser captioning. Key differentiators include its modular architecture for tree-shaking, a compact 5KB footprint, lazy-loaded parsers, efficient CSS-based style application, and adherence to WebVTT rendering specifications for features like regions, cues, and roll-up captions. It is built with TypeScript and designed to work both server-side and client-side, requiring Node.js version 16 or higher.

npm install media-captions
INSTALL
IMPORT
SIG · MEDIA-CAPTIONS
M
media-captions
serializationjavascriptv0.0.18
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

createParser
import { createParser } from 'media-captions';
const createParser = require('media-captions').createParser;
The `createParser` factory function is the primary way to instantiate a caption parser for a given format. ESM is the standard import style.
SRTParser
import { SRTParser } from 'media-captions';
import SRTParser from 'media-captions/parsers/srt'; // Incorrect path, direct import from package is preferred const SRTParser = require('media-captions').SRTParser; // CJS pattern for named export
Directly importing specific parser classes like `SRTParser` is also possible if you know the exact format you're dealing with and prefer not to use `createParser`.
CaptionsRenderer
import { CaptionsRenderer } from 'media-captions';
const CaptionsRenderer = require('media-captions/renderer');
The `CaptionsRenderer` class is used for visually rendering parsed cues onto a media player overlay, following WebVTT rendering specifications.
type CaptionsParser
import type { CaptionsParser } from 'media-captions';
Importing types like `CaptionsParser` requires the `type` keyword for type-only imports in TypeScript environments.

Demonstrates how to parse an SRT caption string using both the `createParser` factory and directly instantiating `SRTParser`, then logs the resulting cue objects. It also briefly mentions how a `CaptionsRenderer` would be used.

import { createParser, SRTParser } from 'media-captions'; async function parseSRTString() { const srtContent = `1 00:00:00,500 --> 00:00:02,500 Hello, world! 2 00:00:03,000 --> 00:00:05,000 This is a test caption.`; // Using createParser factory function const parser = createParser('srt'); const cuesFromFactory = await parser.parse(srtContent); console.log('Cues from factory:', cuesFromFactory); // Alternatively, instantiate a specific parser directly const srtParser = new SRTParser(); const cuesFromDirectInstance = await srtParser.parse(srtContent); console.log('Cues from direct instance:', cuesFromDirectInstance); // Each cue is a VTTCue-like object if (cuesFromFactory.length > 0) { console.log(`First cue text: ${cuesFromFactory[0].text}`); console.log(`First cue start time: ${cuesFromFactory[0].startTime}`); } // To render these, you would typically use a CaptionsRenderer instance // const renderer = new CaptionsRenderer(videoElement); // renderer.addCues(cuesFromFactory); // renderer.render(currentTime); } parseSRTString().catch(console.error);
Debug
Known issues
breakingAs a pre-1.0 release (current version 0.0.18), the API of `media-captions` is subject to frequent and potentially breaking changes in minor versions. Developers should pin exact versions or expect to adapt their code with updates.
fix
Review changelogs carefully before upgrading. Consider using a tool like `npm-check-updates` with care.
affects: <1.0.0
gotchaThis library is designed to work around limitations of native browser captioning. Incorrectly mixing its rendering logic with native HTML `track` elements or other custom solutions might lead to unexpected behavior or double rendering of captions.
fix
Ensure a clear separation between native caption handling and `media-captions` rendering. If using `CaptionsRenderer`, typically you would not use native HTML `track` elements for the same content.
affects: >=0.0.1
gotchaWhile parsers are lazy-loaded, if dynamically importing parsers (e.g., `import('media-captions/parsers/srt')`), ensure your build system is configured to handle dynamic imports correctly to prevent unexpected bundling or runtime errors.
fix
If experiencing issues with dynamically loaded parsers, ensure your bundler (Webpack, Rollup, Vite) is configured for code splitting and dynamic imports. The `createParser` factory handles this internally for standard usage.
affects: >=0.0.1
Errors
Common errors & fixes
TypeError: (0 , media_captions__WEBPACK_IMPORTED_MODULE_0__.createParser) is not a function
Attempting to use CommonJS `require()` syntax or incorrect destructuring in an ESM-only context, or a bundler misconfiguration.
fix
Ensure you are using ESM `import { createParser } from 'media-captions';` and your build environment supports ESM. Check your `tsconfig.json` `module` and `moduleResolution` settings.
Error: Unknown caption parser type: 'unsupported_format'
Attempting to create a parser for an unsupported or misspelled caption format type.
fix
Verify that the format string passed to `createParser()` is one of the supported types: 'vtt', 'srt', 'ssa', 'ass'.
Upgrade
Version history
0.0.18latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
3 hits · last 30 days
node
2
Amazon
1
Resources
media-captions — npm install media-captions · libregistry