# Detection

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

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

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

## Usage: Advanced

```ts
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.