metabeam (Node.js)

Point it at any file and read everything inside.

metabeam is a metadata extraction engine for any file type. It detects formats by their magic bytes (never the file extension), runs every applicable parser, and returns a structured report as a plain JavaScript object: hashes and entropy, image geometry, EXIF and GPS, audio tags, video timing, document properties, archive contents, and binary headers.

The package is a native Rust addon (built with napi-rs), so parsing is fast and the result matches the CLI and Python packages exactly.

Install

npm install metabeam

A prebuilt binary is installed for your platform (Linux, macOS, Windows; x64 and arm64), so there is no compile step. Requires Node.js 16 or newer.

Usage

const metabeam = require("metabeam");
const fs = require("fs");

// Parse a file from disk. Throws if it cannot be read.
const report = metabeam.parse("photo.jpg");

console.log(report.file.mime_detected);   // "image/jpeg"
console.log(report.file.sha256);          // full hex digest
console.log(report.jpeg.quality_estimate);
console.log(report.exif.gps_decimal);     // { latitude: ..., longitude: ... }

// Parse a Buffer directly (for example, an HTTP upload body).
const fromBytes = metabeam.parseBytes(fs.readFileSync("photo.jpg"));

ESM / TypeScript (type definitions are bundled):

import { parse, parseBytes } from "metabeam";

const report = parse("photo.jpg");

Reject a mismatched upload in Express

Because detection is by content, not extension, metabeam is a reliable way to reject spoofed uploads:

const metabeam = require("metabeam");

app.post("/upload", (req, res) => {
  const report = metabeam.parseBytes(req.body);          // req.body is a Buffer
  if (report.file.mime_detected !== "image/png") {
    return res.status(400).send("expected a PNG");
  }
  // ... store it ...
});

API

• parse(path: string): object - parse a file on disk.
• parseBytes(data: Buffer | Uint8Array): object - parse an in-memory buffer.

Every result contains a file namespace (size, detected MIME, SHA-256, CRC-32, entropy). Format-specific namespaces (jpeg, png, exif, id3, mp4, pdf, zip, elf, and more) are added when they apply, so a single file can produce several at once.

Supported formats

JPEG, PNG, GIF, BMP, WebP/WAV/AVI (RIFF), TIFF/HEIC EXIF, MP3 (ID3), MP4/MOV/M4A/HEIF, ELF binaries, PDF, gzip, and the ZIP family (docx, xlsx, pptx, jar, apk, epub). The universal file namespace runs on everything.

Links

• Source, docs, and issues: https://github.com/rgcsekaraa/metabeam
• Also available as a CLI (cargo install metabeam) and for Python (pip install metabeam).

License

Licensed under either of MIT or Apache-2.0 at your option.