Detection

(no submodules)

Purpose

Byte-level and filename-level media type detection. The module pairs the pluggable SignatureRegistry from signatures/ with the MIME database exposed by @suaveplan/mime so consumers can identify image, video, and audio artefacts whether they have the bytes, the filename, or both.

Features

detectMediaType(input, opts?) — magic-byte detection via the registry.
detectSignature(input, opts?) — return the matched MediaSignature record, not just its type.
detectMediaTypeFromName(filename, opts?) — MIME-database lookup.
inferMimeFromSignature(sig) — canonical MIME for a matched signature with a sane fallback when no signature matched.
defaultMimeForType(type) — coarse fallback when only the category is known.
Counters and latency histograms emitted on every invocation.

Usage: Basic

import { detectMediaType } from "@suaveplan/media";

const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d]);
detectMediaType(png); // "image"

Usage: Advanced

import {
    detectSignature,
    inferMimeFromSignature,
    SignatureRegistry,
} from "@suaveplan/media";

const reg = new SignatureRegistry();
reg.register({
    type: "image",
    label: "AVIF",
    bytes: [0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69, 0x66],
    offset: 4,
});
const sig = detectSignature(myBytes, { registry: reg });
const mime = inferMimeFromSignature(sig); // canonical MIME

API Reference

DetectOptions — { registry?, observability? }.
detectMediaType(input, opts?) — MediaType.
detectSignature(input, opts?) — MediaSignature | null.
detectMediaTypeFromName(filename, opts?) — MediaType.
inferMimeFromSignature(sig) — canonical MIME string.
defaultMimeForType(type) — coarse fallback MIME.

Implementation Notes

detectMediaType and detectMediaTypeFromName both record an op_latency_ms histogram entry in a finally block so the cost of a detection call is always measured, even when the registry throws. The filename pathway uses @suaveplan/mime's getMimeType so the database behind detection stays in lock-step with the rest of the project.

2.2 KiB Raw Blame History