skills/plugins/document-navigator/docs/foundation/data/media/README.md

@suaveplan/media - Universal media detection, metadata extraction, and constraint validation. Magic-byte signature registry (pluggable), MIME-keyed type detection via @suaveplan/mime, Zod-validated constraints, typed MediaError hierarchy with stable MEDIA.* codes, OTel counters + histogram, injectable observability bundle, and an async validation pipeline supporting custom predicates.

Universal media detection, metadata extraction, and constraint validation. Combines a pluggable magic-byte SignatureRegistry with the MIME database from @suaveplan/mime to identify image, video, and audio artefacts from raw bytes, filenames, or both. Ships typed errors via @suaveplan/error, OpenTelemetry instrumentation, Zod-validated constraints, and an async validation pipeline that supports custom predicates and format-specific metadata extractors.

Documentation tree

• detection — Byte-level and filename-level media type detection. The module pairs the pluggable SignatureRegistry from `signatures…
  • detection — Byte-level and filename-level media type detection. The module pairs the pluggable SignatureRegistry from `signatures…
• errors — Owns the stable error-code registry, per-code metadata table, and the MediaError class that every public entrypoint t…
  • errors — Owns the stable error-code registry, per-code metadata table, and the MediaError class that every public entrypoint t…
• metadata — Builds a MediaMetadata bundle (type, MIME, size, matched signature label) from raw bytes. The sync helper produces th…
  • metadata — Builds a MediaMetadata bundle (type, MIME, size, matched signature label) from raw bytes. The sync helper produces th…
• observability — Constructs the OpenTelemetry instrument bundle threaded through every public entrypoint in @suaveplan/media. Each det…
  • observability — Constructs the OpenTelemetry instrument bundle threaded through every public entrypoint in @suaveplan/media. Each det…
• signatures — Owns the magic-byte signature registry that powers byte-level detection. The module ships a frozen BUILTIN_SIGNATURES…
  • signatures — Owns the magic-byte signature registry that powers byte-level detection. The module ships a frozen BUILTIN_SIGNATURES…
• validation — Validates media bytes against a MediaConstraints rule set covering size floors and ceilings, type allowlists, MIME al…
  • validation — Validates media bytes against a MediaConstraints rule set covering size floors and ceilings, type allowlists, MIME al…

Install

bun add @suaveplan/media

Quick start

import {
    detectMediaType,
    getMetadata,
    validateMedia,
} from "@suaveplan/media";

const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a]);

detectMediaType(png); // "image"

const meta = getMetadata(png, { filename: "logo.png" });
// { type: "image", mimeType: "image/png", size: 6, signatureLabel: "PNG" }

const result = validateMedia(png, {
    maxSize: 1_000_000,
    allowedTypes: ["image"],
});
if (!result.valid) console.warn(result.errors);

Modules

• detection/detection.md — byte + filename detection helpers.
• metadata/metadata.md — sync + async metadata extraction.
• validation/validation.md — constraint checking, async predicate support, assert helper.
• signatures/signatures.md — pluggable magic-byte registry.
• errors/errors.md — MEDIA_CODES, MediaError, metadata table.
• observability/observability.md — OpenTelemetry bundle factory.
• types/media.types.md — public type contracts + Zod schemas.

Features

• Magic-byte detection covering PNG, JPEG, GIF, BMP, WEBP/RIFF, MP4/MOV, WebM/MKV, MP3 (ID3 + sync), FLAC, OGG.
• Pluggable SignatureRegistry with register / unregister / list / match / detect; duplicate labels rejected with MEDIA.DUPLICATE_SIGNATURE.
• MIME-keyed filename detection via @suaveplan/mime.
• Zod-validated MediaConstraints (minSize, maxSize, allowedTypes, allowedMimeTypes, minWidth/maxWidth, minHeight/maxHeight, maxDuration, custom predicate).
• Async metadata extractor hook for layering width / height / duration / codec onto the base bundle.
• assertValidMedia throwing variant for guard sites.
• Eight stable MEDIA.* error codes with per-code HTTP / severity / retryable metadata.
• Four counters + two histograms emitted from every public entrypoint.

Error codes

Code	HTTP	Retryable	Severity
MEDIA.EMPTY_INPUT	400	no	warning
MEDIA.INVALID_CONSTRAINTS	400	no	error
MEDIA.VALIDATION_FAILED	422	no	warning
MEDIA.UNSUPPORTED_TYPE	415	no	warning
MEDIA.PREDICATE_FAILED	500	no	error
MEDIA.DUPLICATE_SIGNATURE	409	no	error
MEDIA.METADATA_EXTRACTOR_FAILED	500	no	error
MEDIA.INVALID_SIGNATURE	400	no	error

Observability

Four counters: media_detect_total, media_metadata_total, media_validate_total, media_error_total. Two histograms: media_op_latency_ms, media_input_size_bytes. Wire your meter via createMediaObservability({ meter }) and thread the bundle into every call.