first commit

docs/foundation/data/mime/src/detection/from-magic-bytes/signatures/audio.md

@@ -0,0 +1,37 @@
+# signatures/audio
+
+## Purpose
+
+Registers magic-byte signatures for audio formats with the global signature registry. Covers all major audio container and codec formats used in web and desktop applications. Each signature is registered as a side effect of importing this module.
+
+## Features
+
+- FLAC, MP3 (ID3 tag and sync word variants), OGG/Vorbis
+- WAV (RIFF container), AIFF/AIFF-C
+- AAC (ADTS), M4A (ISO BMFF with M4A brand)
+- WMA/WMV (ASF container), MIDI
+- Musepack (SV7/SV8), OptimFROG, Monkey's Audio
+- DFF/DSF (DSD audio), AC-3/E-AC-3, Dolby TrueHD
+- MOD tracker variants (4/6/8-channel patterns)
+
+## Usage
+
+```typescript
+import "@suaveplan/mime/detection/from-magic-bytes/signatures/audio";
+import { detectFromMagicBytes } from "@suaveplan/mime/detection/from-magic-bytes/from-magic-bytes";
+
+const flacBytes = new Uint8Array([0x66, 0x4c, 0x61, 0x43]); // "fLaC"
+console.log(detectFromMagicBytes(flacBytes)?.mime); // "audio/flac"
+```
+
+## API Reference
+
+No exported functions. All signatures are registered via `registerSignature` side effects.
+
+## Implementation Notes
+
+MP3 detection covers both the ID3v2 header (`49 44 33`) and raw MPEG sync words (`ff fb`, `ff f3`, `ff f2`). OGG files are further disambiguated by inspecting the codec type in the first OGG page header (bytes 28–35: `vorbis`, `FLAC`, `Opus`, `Theora`). The RIFF container is used by both WAV and AVI, with disambiguation on the RIFF type tag at offset 8.
+
+### Coverage
+
+The audio signature set covers MPEG audio (`ID3` tag and raw frame-sync variants at priority 80), WAV/RIFF with the `WAVE` subtype marker, FLAC (`fLaC`), Ogg (`OggS`), AIFF (`FORM` + `AIFF`), MIDI (`MThd`), AMR, and Opus. The RIFF family share a common `RIFF` container prefix which is why WAV specifically checks the subtype at offset 8 before claiming a match.