Matroska and EBML Schema Definitions

Common errors

• TypeError: Cannot read properties of undefined (reading 'find')

  cause Attempting to call `find` on an undefined or incorrectly imported schema object.
  fix Ensure `matroska-schema` is correctly installed (`npm install matroska-schema`) and imported as a default export: `import matroskaSchema from 'matroska-schema';` or `const matroskaSchema = require('matroska-schema');`

• ERR_REQUIRE_ESM: require() of ES Module ... matroska-schema/schema.js not supported.

  cause Attempting to `require()` the package in an environment configured for ES Modules where the package might be treated as ESM-only, or when the `package.json` specifies `"type": "module"` and a direct `require()` is used on a file that only exposes ESM.
  fix If your project is ES Modules-based, use `import matroskaSchema from 'matroska-schema';`. If using CommonJS, ensure your Node.js version supports interop, or check if an older version of `matroska-schema` (if applicable) is strictly CommonJS.

• Cannot find module 'matroska-schema'

  cause The package is not installed or not resolvable from the current working directory or `NODE_PATH`.
  fix Run `npm install matroska-schema` or `yarn add matroska-schema` in your project directory.

Warnings

• gotcha This package was created as an MIT-licensed alternative to a GPL-licensed schema. If migrating from older `node-matroska` versions, ensure you are using this package for broader license compatibility.
  Fix: Ensure `matroska-schema` is installed and imported, replacing any direct references to a GPL-licensed schema file.
• breaking The schema is automatically generated from official Matroska and EBML specifications. While the package API remains stable, changes in the underlying specifications may alter the structure or available elements within the schema data itself. This could implicitly break parsers relying on a fixed schema structure.
  Fix: Periodically review the Matroska and EBML specifications and test your parsing logic against newer versions of `matroska-schema`.
• gotcha As a data-only package, `matroska-schema` doesn't enforce strict ESM/CJS compatibility beyond what Node.js provides. While `require()` and `import` generally work, ensure your project's module resolution is correctly configured, especially in bundled environments.
  Fix: For CommonJS, use `const schema = require('matroska-schema');`. For ES Modules, use `import schema from 'matroska-schema';`. If encountering issues, check your `tsconfig.json` (for TypeScript) or build tool configuration.

Install

• npm install matroska-schema npm
• yarn add matroska-schema yarn
• pnpm add matroska-schema pnpm

Imports

• matroskaSchema
  wrong:

  import { matroskaSchema } from 'matroska-schema';

  correct:

  import matroskaSchema from 'matroska-schema';

  The package exports the entire schema object as its default export.
• matroskaSchema

  const matroskaSchema = require('matroska-schema');

  CommonJS require style for Node.js environments.
• SchemaEntry

  import matroskaSchema from 'matroska-schema';
  const ebmlHeader = matroskaSchema.find(entry => entry.name === 'EBMLHeader');

  The imported `matroskaSchema` is typically an array of schema entries, requiring iteration or filtering to find specific definitions. It's not a direct object lookup by name.

Quickstart

Demonstrates how to import the Matroska schema and access a specific element definition within it.

import matroskaSchema from 'matroska-schema';

console.log('Successfully loaded Matroska schema. Total entries:', matroskaSchema.length);

// Example: Find the 'Segment' top-level element definition
const segmentElement = matroskaSchema.find(entry => entry.name === 'Segment');

if (segmentElement) {
  console.log('Found Segment element:', segmentElement.name, 'ID:', segmentElement.id.toString(16));
  console.log('Segment element description:', segmentElement.description.substring(0, 70) + '...');
} else {
  console.log('Segment element not found in schema.');
}

// To see a specific part of the schema, e.g., the EBML Header definition
const ebmlHeader = matroskaSchema.find(entry => entry.name === 'EBMLHeader');
if (ebmlHeader) {
    console.log('\nEBMLHeader definition:');
    console.dir(ebmlHeader, { depth: 2 });
}