Registry / serialization / matroska

matroska

JSON →
library0.0.0jsnpmunverified

The `matroska` package provides a Node.js library for parsing Matroska (MKV), WebM, and EBML streams and files. It is a fork of `node-ebml`, emphasizing fast parsing with an option for incomplete metadata extraction (info tags and attachments) or a complete parse of the entire document structure. The current stable version is 2.2.5, with its last publish approximately three years ago, indicating a maintenance-focused release cadence rather than active feature development. Recent updates have included fixes for `cueClusterPosition` problems and improved resilience when handling invalid MKV formats, alongside stream support introduced in older versions. Its key differentiators include its speed and the ability to process potentially malformed Matroska files, making it suitable for applications that require robust media metadata extraction in a Node.js environment.

serialization
npm install matroska
github ↗package ↗
INSTALL
IMPORT
SIG · MATROSKA
M
matroska
serializationjavascriptv0.0.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.

Decoder
✓ const { Decoder } = require('matroska');
✗ import { Decoder } from 'matroska';
This package is primarily CommonJS (`require()`) based, as indicated by the README examples. Using ESM `import` syntax will result in errors unless transpiled or configured for dual module support, which is not explicitly provided by the package.
parseInfoTagsAndAttachments
✓ const { Decoder } = require('matroska'); Decoder.parseInfoTagsAndAttachments(url, callback);
✗ const matroska = require('matroska'); matroska.parseInfoTagsAndAttachments(url, callback);
This static method for fast, incomplete metadata parsing is accessed directly through the `Decoder` class exported by the package.
matroska (entire module)
✓ const matroska = require('matroska');
✗ import matroska from 'matroska';
The main package export is an object containing the `Decoder` class and other utilities. Direct default ESM imports (`import matroska from 'matroska'`) are not supported.

This code demonstrates how to perform a complete parse of a Matroska (MKV) file from a URL using the `Decoder` class and its `parse` method, logging the full document structure and extracting some common info tags.

const matroska = require('matroska'); const url = 'http://download.wavetlan.com/SVV/Media/HTTP/mkv/H264_mp3(mkvmerge).mkv'; const decoder = new matroska.Decoder(); decoder.parse(url, function(error, document) { if (error) { console.error('Error parsing Matroska file:', error); return; } console.log('Successfully parsed Matroska document:'); // The document object represents the parsed Matroska structure. // You can access its properties, e.g., document.print() for a tree representation. console.log(document.print()); console.log('\nExtracted Info:'); const info = document.findTag('Info'); // Assuming a method to find tags, or traverse the document tree if(info) { console.log('Timecode Scale:', info.findTag('TimecodeScale')?.value); console.log('Muxing App:', info.findTag('MuxingApp')?.value); console.log('Duration:', info.findTag('Duration')?.value); } else { console.log('Info tag not found in document.'); } });
Debug
Known issues
gotchaThe `matroska` package primarily uses CommonJS (`require()`) for module loading. Attempting to use ECMAScript Modules (`import`) directly without proper transpilation or Node.js module resolution configuration will lead to errors like 'require is not defined' or 'ERR_REQUIRE_ESM'.
fix
Ensure your project is configured for CommonJS, or use dynamic `import()` in an async context if running in an ESM module (`await import('matroska')`). Consider `createRequire` for specific scenarios in ESM files.
affects: >=1.0.0
gotchaThe package offers two main parsing modes: `parseInfoTagsAndAttachments` for a 'VERY Fast' but 'incomplete' metadata-only parse, and the `Decoder().parse()` method for a 'COMPLETE' parse. Users must explicitly choose the appropriate method based on their needs, as `parseInfoTagsAndAttachments` will not yield full video/audio block data.
fix
For full access to all Matroska elements, including media blocks, instantiate `new matroska.Decoder()` and call its `parse()` method. For just metadata like duration, muxing app, etc., use the static `Decoder.parseInfoTagsAndAttachments()`.
affects: >=1.0.0
gotchaThis package is a fork of `node-ebml`. While this offers specialized Matroska parsing, it's essential to consider the maintenance status of both the fork and its upstream. The `matroska` package itself has not been published in approximately three years, suggesting potentially slower updates compared to actively developed libraries.
fix
Monitor the GitHub repository for activity. If long-term maintenance or new features are critical, evaluate alternative Matroska/EBML parsing libraries or be prepared to contribute to the project.
affects: >=1.0.0
gotchaThe API is callback-based, which can be challenging to integrate into modern asynchronous JavaScript codebases that primarily use Promises or `async/await`. Direct usage with `async/await` will require wrapping the callback functions in Promises.
fix
Wrap the `parse` and `parseInfoTagsAndAttachments` methods with `util.promisify` or manually create a Promise-based wrapper to use them with `async/await` syntax for cleaner asynchronous code.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use `require()` syntax in a JavaScript file that is treated as an ECMAScript Module (ESM). This happens if your `package.json` contains `"type": "module"` or the file has a `.mjs` extension.
fix
Either rename your file to use a `.cjs` extension, remove `"type": "module"` from your `package.json` to revert to CommonJS default, or use dynamic `import()` (`const matroska = await import('matroska');`).
TypeError: matroska.Decoder is not a constructor
This error occurs if `matroska.Decoder` is not correctly imported or accessed as a constructor. This can happen with incorrect destructuring or if `matroska` itself is not the expected object.
fix
Ensure you are using `const { Decoder } = require('matroska');` or `const matroska = require('matroska'); const decoder = new matroska.Decoder();` to correctly access the `Decoder` class. Double-check for typos.
Error: EMFILE, too many open files
When parsing numerous files or streams rapidly without proper resource management, Node.js can hit the operating system's limit for open file descriptors. This is common in I/O heavy operations.
fix
Implement a queueing mechanism or process files in batches to control concurrency. Ensure that file descriptors are properly closed after parsing is complete. On Linux, you might temporarily increase the `ulimit -n` for development.
Upgrade
Version history
0.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources
githubhttps://github.com/oeuillot/node-matroska ↗
packagehttps://www.npmjs.com/package/matroska ↗
matroska — npm install matroska · libregistry