metabeam 0.1.0

Metadata extraction for any file type: detect MIME from magic bytes, read EXIF/GPS, image/audio/video tags, PDF info, archive contents, hashes, and entropy.

metabeam (Python)

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 Python dict: hashes and entropy, image geometry, EXIF and GPS, audio tags, video timing, document properties, archive contents, and binary headers.

The package is a compiled Rust extension (built with maturin and PyO3), so parsing is fast and the result matches the CLI and Node packages exactly.

Install

pip install metabeam

Supports CPython 3.8+ on Linux, macOS, and Windows.

Usage

import metabeam

# Parse a file from disk. Raises OSError if it cannot be read.
report = metabeam.parse("photo.jpg")

print(report["file"]["mime_detected"])    # "image/jpeg"
print(report["file"]["sha256"])           # full hex digest
print(report["jpeg"]["quality_estimate"]) # estimated JPEG quality
print(report["exif"]["gps_decimal"])      # {"latitude": ..., "longitude": ...}

Parse bytes that never touch disk (an upload, a download, a database blob):

with open("photo.jpg", "rb") as f:
    report = metabeam.parse_bytes(f.read())

The result is a plain dict, so it serializes directly:

import json
print(json.dumps(report, indent=2))

Validate that an upload is really the type it claims

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

import metabeam

def is_real_png(data: bytes) -> bool:
    report = metabeam.parse_bytes(data)
    return report["file"]["mime_detected"] == "image/png"

API

• metabeam.parse(path: str) -> dict - parse a file on disk.
• metabeam.parse_bytes(data: bytes) -> dict - 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 Node (npm install metabeam).

License

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