first commit

docs/media/audio/audio-codecs/src/codecs/flac.md

@@ -0,0 +1,80 @@
+# `codecs/flac`
+
+Lazy FLAC codec — thin wrapper over `@audio/decode-flac` WASM module
+loaded on first use.
+
+## Purpose
+
+FLAC (Free Lossless Audio Codec) is the canonical lossless format for
+high-quality audio archival. It compresses raw PCM by 30–60% with no
+quality loss, making it the standard format for music libraries that
+need to preserve every bit of the original signal.
+
+The package treats FLAC as a WASM-backed codec to keep the universal
+`audio-codecs` package size-constant — pure-JS FLAC implementations
+are large and slow, and bundling one would punish every consumer who
+never touches FLAC. The actual decode/encode work delegates to
+`@audio/decode-flac` loaded via dynamic `import()` on first call.
+
+Implementation delegates to [`createWasmCodec`](./wasm-base.md) which
+documents the shared lazy-load, missing-module, and error-wrapping
+contract.
+
+## Features
+
+- `name === "flac"`, extensions `["flac"]`, MIME types
+  `["audio/flac", "audio/x-flac"]`.
+- `canDecode(bytes)` — magic-byte sniff for `fLaC`
+  (`0x66 0x4c 0x61 0x43`) at byte 0; rejects buffers shorter than 4
+  bytes.
+- Decode + encode both supported (`supportsEncode: true`).
+- Streaming factory absent — single-pass full-buffer codec.
+
+## Usage: Basic Example
+
+```ts
+import { FlacCodec } from "@suaveplan/audio-codecs/codecs/flac";
+
+const decoded = await FlacCodec.decode(flacBytes);
+const reEncoded = await FlacCodec.encode(decoded.channelData, {
+    sampleRate: decoded.sampleRate,
+    bitDepth: 24,
+});
+```
+
+## Usage: Advanced Example
+
+Round-trip FLAC → WAV → FLAC via the shared registry:
+
+```ts
+import { CodecRegistry, FlacCodec, WavCodec } from "@suaveplan/audio-codecs";
+
+const registry = new CodecRegistry({ codecs: [FlacCodec, WavCodec] });
+
+const flacDoc = await registry.decode(flacBytes);
+const intermediate = await registry.encode(flacDoc, "wav", { bitDepth: 24, format: "pcm" });
+const wavDoc = await registry.decode(intermediate);
+const finalFlac = await registry.encode(wavDoc, "flac");
+```
+
+## API Reference
+
+- `FlacCodec: AudioCodec` — `name === "flac"`, frozen.
+- `canDecode(bytes)`, `decode(bytes, opts?)`, `encode(channelData,
+  opts?)` — see [`wasm-base.md`](./wasm-base.md) for the shared
+  contract.
+
+## Implementation Notes
+
+- Magic-byte sniff is cheap — no WASM load required for `canDecode`.
+- The first decode/encode call lazily loads `@audio/decode-flac`;
+  subsequent calls reuse the same memoised module instance.
+- Missing `@audio/decode-flac` → `AUDIO_CODECS.NOT_SUPPORTED` with the
+  module name in `context.module`.
+- FLAC's native streaming-decode form (`Subset` profile blocks) is
+  not exposed by this wrapper — adding it requires a per-block
+  callback API which is a future extension.
+- FLAC files commonly carry Vorbis comments and embedded artwork in
+  the same container; the codec emits PCM only — metadata extraction
+  is `@suaveplan/audio-metadata`'s responsibility via its own FLAC
+  parser, separate from this codec.