ebml

library3.0.0jsnpmunverified

The `ebml` library provides a JavaScript parser for the Extensible Binary Meta-Language (EBML) format, which is a binary equivalent to XML. It's prominently used in multimedia container formats such as WebM and Matroska (MKV). The library implements a Node.js Transform stream, enabling the decoding of EBML streams into a sequence of JavaScript objects that represent individual EBML elements. The current stable version, 3.0.0, represents a substantial rewrite to ES2018, aligning with modern JavaScript module standards and now builds with RollupJS. The project is actively maintained, with recent updates addressing live streaming issues and prior security releases. Its key differentiator is its efficient stream-based parsing, which is ideal for processing large media files without requiring them to be loaded entirely into memory.

serialization data

npm install ebml

github ↗package ↗

INSTALL

IMPORT

SIG · EBML

ebml

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

✓ import { Decoder } from 'ebml';

✗ const { Decoder } = require('ebml');

Since v3.0.0, the package primarily supports ES Modules (ESM). Using `require()` may lead to `ERR_REQUIRE_ESM` errors, especially in environments not configured for CommonJS-ESM interop.

Decoder.on('data', ...)

✓ decoder.on('data', chunk => { /* process chunk */ });

The primary way to consume parsed EBML elements is by listening to the 'data' event on the `Decoder` stream, which emits two-element arrays representing EBML tags.

Stream Piping

✓ fs.createReadStream('file.webm').pipe(ebmlDecoder);

As a Node.js Transform stream, `Decoder` is designed to be piped with Readable streams (input) and to other Writable streams (output, if re-encoding or transforming).

Demonstrates streaming EBML data from a file, piping it through the `Decoder` transform stream, and counting the occurrences of each EBML element name as it's parsed. Includes a helper to create a dummy WebM file if none exists to ensure the example is runnable.

import { Decoder } from 'ebml'; import fs from 'fs'; import path from 'path'; const ebmlDecoder = new Decoder(); const counts = {}; const mediaFilePath = path.join(process.cwd(), 'media', 'test.webm'); // Ensure the directory exists and create a minimal dummy WebM file if none is found const dir = path.dirname(mediaFilePath); if (!fs.existsSync(dir)) { fs.mkdirSync(dir, { recursive: true }); } if (!fs.existsSync(mediaFilePath)) { // A very minimal, somewhat valid EBML header to allow the decoder to start parsing // and emit at least the EBML and Segment tags. const dummyEbmlData = Buffer.from([ 0x1A, 0x45, 0xDF, 0xA3, // EBML Header ID (4 bytes) 0x82, // Size of header (2 bytes = 2^1 - 1 = 1 byte for 0x01) 0x42, 0x82, 0x81, 0x01, // EBMLVersion: 1 0x42, 0x87, 0x81, 0x01, // EBMLReadVersion: 1 0x42, 0x86, 0x81, 0x01, // DocTypeVersion: 1 0x42, 0x85, 0x81, 0x02, // DocTypeReadVersion: 2 0x42, 0x81, 0x81, 0x04, // DocType: 'webm' 0x18, 0x53, 0x80, 0x67, // Segment ID (4 bytes) 0x81, // Size of Segment (1 byte for 0x01 length, which is too small for real data but for demo) // Add a minimal TimecodeScale element inside the segment 0x2A, 0xD7, 0xB1, // TimecodeScale ID 0x84, // Size of value (4 bytes) 0x00, 0x0F, 0x42, 0x40 // Value: 1,000,000 (standard for WebM) ]); fs.writeFileSync(mediaFilePath, dummyEbmlData); console.warn(`Created a dummy '${mediaFilePath}' for demonstration purposes.`); } else { console.log(`Using existing '${mediaFilePath}'.`); } fs.createReadStream(mediaFilePath) .pipe(ebmlDecoder) .on('data', chunk => { const { name } = chunk[1]; if (name) { // Ensure name exists for counting if (!counts[name]) { counts[name] = 0; } counts[name] += 1; } }) .on('error', (err) => { console.error('Stream processing error:', err); }) .on('finish', () => { console.log('Finished decoding. Element counts:'); console.log(counts); }); console.log(`Starting EBML stream decoding for: ${mediaFilePath}`);

Debug

Known issues

breakingVersion 3.0.0 represents a 'massive rewrite' to ES2018, significantly changing the library's internal structure and potentially its public API, breaking compatibility with previous major versions.

fix

Review the usage examples and documentation for v3.x, as code written for v2.x will likely require adaptation. Specifically, update import statements to ES Module syntax.

affects: >=3.0.0

breakingSince v3.0.0, the package primarily supports ES Modules (ESM). Direct `require()` statements in CommonJS contexts may lead to `ERR_REQUIRE_ESM` or other import resolution issues.

fix

Adopt ES Module syntax (`import { Decoder } from 'ebml';`) in your projects. If you must use CommonJS, ensure Node.js is configured for interoperability or transpile your code.

affects: >=3.0.0

deprecatedVersion 2.2.4 is explicitly stated as the last version to have guaranteed legacy semantics. This means behavior and API in v3.0.0 and above may differ significantly from prior versions.

fix

Migrate to version 3.x and update code to the new API and semantics. Do not rely on undocumented behavior from 2.x releases.

affects: >=3.0.0

gotcha`d`-type (timestamp) elements, which represent a 64-bit signed timestamp in nanoseconds, are not yet decoded to native JavaScript `Date` or `BigInt` values. They are currently provided as raw values or strings.

fix

Manually parse `d`-type element values into desired JavaScript timestamp formats, accounting for the `2001-01-01T00:00UTC` epoch.

affects: All versions

gotchaThe `value` member of parsed EBML elements represents the data's value as a number or string. Integers stored in 6 bytes or less are numbers, but longer integers are represented as hexadecimal text strings, requiring manual conversion for numerical operations.

fix

Implement logic to detect and convert hexadecimal string representations of large integers to `BigInt` or other suitable numerical types if numerical operations are needed.

affects: All versions

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module ... ebml.js not supported.

Attempting to import the `ebml` package using `require()` in a CommonJS module context when the package is distributed as an ES Module since v3.0.0.

fix

Change your import statement to `import { Decoder } from 'ebml';` in an ESM context (e.g., `"type": "module"` in `package.json` or a `.mjs` file).

TypeError: Decoder is not a constructor

The `Decoder` class is being imported incorrectly, likely as a default import or a CommonJS module export that doesn't match the actual named export structure in ESM.

fix

Ensure you are using a named import: `import { Decoder } from 'ebml';` and then instantiate with `new Decoder();`.

UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'pipe' of undefined

This typically occurs if the input stream to `pipe()` is not properly initialized or is not a readable stream before being passed to the `Decoder`.

fix

Verify that `fs.createReadStream()` or any other readable stream source is correctly set up and returning a valid stream object before calling `.pipe(ebmlDecoder)`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/node-ebml/node-ebml ↗

packagehttps://www.npmjs.com/package/ebml ↗