# `codecs/aac`

Lazy AAC codec — decode-only wrapper over `@audio/decode-aac` WASM
module loaded on first use.

## Purpose

AAC (Advanced Audio Coding) is the modern lossy audio successor to MP3,
used by every major streaming service and as the default audio format
in MP4/M4A containers. The codec is decode-only because (a) the AAC
encoder is complex and patent-encumbered in many jurisdictions, and
(b) the canonical lossy encode target  is Opus.

Implementation delegates to [`createWasmCodec`](./wasm-base.md) for the
lazy-load, error-wrapping, and missing-module behaviour shared by every
WASM wrapper.

## Features

- `name === "aac"`, extensions `["aac", "m4a"]`, MIME types
  `["audio/aac", "audio/mp4"]`.
- `canDecode(bytes)` — magic-byte sniff for the ADTS sync word
  (first byte `0xff`, second byte top 4 bits `0b1111`); rejects
  buffers shorter than 2 bytes.
- Decode supported via `@audio/decode-aac`.
- `supportsEncode: false` — encode throws `NOT_SUPPORTED`
  short-circuit.
- Streaming factory absent.

## Usage: Basic Example

```ts
import { AacCodec } from "@suaveplan/audio-codecs/codecs/aac";

const decoded = await AacCodec.decode(aacBytes);
```

## Usage: Advanced Example

```ts
import { CodecRegistry, AacCodec, OpusCodec } from "@suaveplan/audio-codecs";

const registry = new CodecRegistry({ codecs: [AacCodec, OpusCodec] });

// transcode AAC → Opus for downstream storage
const aacDoc = await registry.decode(aacBytes);
const opusBytes = await registry.encode(aacDoc, "opus");
```

## API Reference

- `AacCodec: AudioCodec` — frozen constant; decode-only.
- `canDecode(bytes)`, `decode(bytes, opts?)` — standard `AudioCodec`
  contract.
- `encode()` — always throws `AUDIO_CODECS.NOT_SUPPORTED`.

## Implementation Notes

- The ADTS sync word check (`0xff 0xf0`) covers raw ADTS-framed AAC.
  AAC inside an MP4/M4A container starts with `ftyp` instead; that
  case is currently NOT handled by `canDecode` — callers passing
  M4A files need to either use a separate MP4 demuxer first or call
  `decode` with `format: "aac"` to bypass detection. A future
  extension may add an MP4-container sniffer.
- Decode-only by design. suaveplan's preferred lossy encode target is
  Opus; AAC encoding requires non-trivial licensing in some
  jurisdictions and is intentionally out of scope.
- First decode lazily loads `@audio/decode-aac`; subsequent calls
  reuse the memoised module.
- Missing `@audio/decode-aac` → `AUDIO_CODECS.NOT_SUPPORTED`.
- Streaming factory absent — `CodecRegistry.decodeStream("aac", …)`
  throws `AUDIO_CODECS.STREAM_ERROR`.