{"id":13100,"library":"ebml","title":"EBML Parser","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/node-ebml/node-ebml","tags":["javascript","ebml","webm","mkv","matroska","format"],"install":[{"cmd":"npm install ebml","lang":"bash","label":"npm"},{"cmd":"yarn add ebml","lang":"bash","label":"yarn"},{"cmd":"pnpm add ebml","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { Decoder } = require('ebml');","symbol":"Decoder","correct":"import { Decoder } from 'ebml';"},{"note":"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.","symbol":"Decoder.on('data', ...)","correct":"decoder.on('data', chunk => { /* process chunk */ });"},{"note":"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).","symbol":"Stream Piping","correct":"fs.createReadStream('file.webm').pipe(ebmlDecoder);"}],"quickstart":{"code":"import { Decoder } from 'ebml';\nimport fs from 'fs';\nimport path from 'path';\n\nconst ebmlDecoder = new Decoder();\nconst counts = {};\nconst mediaFilePath = path.join(process.cwd(), 'media', 'test.webm');\n\n// Ensure the directory exists and create a minimal dummy WebM file if none is found\nconst dir = path.dirname(mediaFilePath);\nif (!fs.existsSync(dir)) {\n  fs.mkdirSync(dir, { recursive: true });\n}\nif (!fs.existsSync(mediaFilePath)) {\n  // A very minimal, somewhat valid EBML header to allow the decoder to start parsing\n  // and emit at least the EBML and Segment tags.\n  const dummyEbmlData = Buffer.from([\n    0x1A, 0x45, 0xDF, 0xA3, // EBML Header ID (4 bytes)\n    0x82,                   // Size of header (2 bytes = 2^1 - 1 = 1 byte for 0x01)\n    0x42, 0x82, 0x81, 0x01, // EBMLVersion: 1\n    0x42, 0x87, 0x81, 0x01, // EBMLReadVersion: 1\n    0x42, 0x86, 0x81, 0x01, // DocTypeVersion: 1\n    0x42, 0x85, 0x81, 0x02, // DocTypeReadVersion: 2\n    0x42, 0x81, 0x81, 0x04, // DocType: 'webm'\n    \n    0x18, 0x53, 0x80, 0x67, // Segment ID (4 bytes)\n    0x81,                   // Size of Segment (1 byte for 0x01 length, which is too small for real data but for demo)\n    // Add a minimal TimecodeScale element inside the segment\n    0x2A, 0xD7, 0xB1, // TimecodeScale ID\n    0x84,             // Size of value (4 bytes)\n    0x00, 0x0F, 0x42, 0x40  // Value: 1,000,000 (standard for WebM)\n  ]);\n  fs.writeFileSync(mediaFilePath, dummyEbmlData);\n  console.warn(`Created a dummy '${mediaFilePath}' for demonstration purposes.`);\n} else {\n  console.log(`Using existing '${mediaFilePath}'.`);\n}\n\nfs.createReadStream(mediaFilePath)\n    .pipe(ebmlDecoder)\n    .on('data', chunk => {\n        const { name } = chunk[1];\n        if (name) { // Ensure name exists for counting\n          if (!counts[name]) {\n              counts[name] = 0;\n          }\n          counts[name] += 1;\n        }\n    })\n    .on('error', (err) => {\n        console.error('Stream processing error:', err);\n    })\n    .on('finish', () => {\n        console.log('Finished decoding. Element counts:');\n        console.log(counts);\n    });\n\nconsole.log(`Starting EBML stream decoding for: ${mediaFilePath}`);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Since 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Version 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.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Manually parse `d`-type element values into desired JavaScript timestamp formats, accounting for the `2001-01-01T00:00UTC` epoch.","message":"`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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"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.","error":"ERR_REQUIRE_ESM: require() of ES Module ... ebml.js not supported."},{"fix":"Ensure you are using a named import: `import { Decoder } from 'ebml';` and then instantiate with `new Decoder();`.","cause":"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.","error":"TypeError: Decoder is not a constructor"},{"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)`.","cause":"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`.","error":"UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'pipe' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}