73 lines
2.5 KiB
Markdown
73 lines
2.5 KiB
Markdown
# `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`.
|