webm-meta-lite

A lightweight, functional TypeScript library for parsing WebM metadata.

Features

• Fast & Lightweight: Scans only necessary parts of the file (Header, Cues, Tail) to extract metadata.
• Robust: Handles files with missing duration (e.g., from MediaRecorder) by scanning the file tail.
• Browser & Node.js Compatible: Works with standard Blob objects.
• Zero Runtime Dependencies: Pure TypeScript implementation.

Demo

Try the demo here: https://ainoya.github.io/webm-meta-lite/

• Record & Analyze: Record audio directly in the browser and view its metadata.
• File Upload: Upload existing WebM files to inspect their structure and metadata.

Installation

npm install webm-meta-lite

Usage

Basic Usage

import { parseWebm } from "webm-meta-lite";

// Example: Parsing a file from an input element
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (event) => {
  const file = event.target.files[0];
  if (file) {
    const metadata = await parseWebm(file);
    console.log(metadata);
  }
});

Node.js Usage

In Node.js (v19.8.0+), you can use openAsBlob to efficiently read files without loading the entire file into memory.

import { openAsBlob } from "node:fs";
import { parseWebm } from "webm-meta-lite";

const blob = await openAsBlob("./video.webm");
const metadata = await parseWebm(blob);
console.log(metadata);

Reading from URL (S3, etc.)

To read a file from a URL efficiently (using HTTP Range Requests), use createFetchReader. This is ideal for large files stored on S3 or other cloud storage.

import { parseWebm, createFetchReader } from "webm-meta-lite";

const url = "https://example.com/large-video.webm";
const reader = await createFetchReader(url);
const metadata = await parseWebm(reader);
console.log(metadata);

Output Example

{
  "durationMilliSeconds": 120500,
  "durationSource": "header",
  "fileSize": 15000000,
  "mimeType": "video/webm; codecs=\"vp9, opus\"",
  "info": {
    "timecodeScale": 1000000,
    "muxingApp": "Chrome",
    "writingApp": "Chrome"
  },
  "tracks": [
    {
      "trackNumber": 1,
      "trackType": 1,
      "codecId": "V_VP9",
      "video": { "width": 1920, "height": 1080 }
    },
    {
      "trackNumber": 2,
      "trackType": 2,
      "codecId": "A_OPUS",
      "audio": { "sampleRate": 48000, "channels": 2 }
    }
  ]
}

Where each field comes from

Most fields are reported exactly as stored in the file; only the duration is resolved by the library.

Field	Source
info.*, tracks[*]	Read from the file header as-is (Info / Tracks elements)
fileSize	The size of the source Blob or file, not a value stored in the file
mimeType	Assembled by this library from the track codec IDs
durationMilliSeconds	Resolved through the Header → Cues → Tail pipeline below
durationSource	Which of the three methods produced the duration

Duration resolution

The three methods are tried in order, stopping at the first one that yields a value. durationSource reports the one that produced durationMilliSeconds, so callers can tell an exact value from an estimate. It is undefined when no method found a duration.

durationSource	Method	Accuracy
"header"	The Duration element of the Info header	Exact. Absent in files written by MediaRecorder and other live muxers
"cues"	The last CueTime of the Cues index	Estimate: points at the last indexed cluster, not at the end of the last frame
"tail"	The last Cluster/Block timecode found by scanning the file tail	Estimate: excludes the play time of the last frame itself

License

MIT