Initial Commit

packages/media/audio/audio-sprite-packer/README.md

@@ -0,0 +1,54 @@
+# @suaveplan/audio-sprite-packer - Binary audio sprite map packer with 80%+ compression versus individual files: pack multiple audio clips into a single concatenated binary with a compact JSON manifest.
+
+Universal audio sprite packer with injectable adapter, Zod-validated boundaries, and OpenTelemetry instrumentation. Zero browser or Node.js dependencies.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [__benchmarks__](./src/__benchmarks__/audio-sprite-packer.bench.md) — This benchmark suite measures the throughput of `AudioSpritePacker.pack` under varying clip counts using `NullAudioAdap…
+  - [audio-sprite-packer.bench](./src/__benchmarks__/audio-sprite-packer.bench.md) — This benchmark suite measures the throughput of `AudioSpritePacker.pack` under varying clip counts using `NullAudioAdap…
+- [null-adapter](./src/adapters/null-adapter/null-adapter.md) — `NullAudioAdapter` is a deterministic, test-only implementation of the `AudioAdapter` interface. It produces predictabl…
+  - [null-adapter](./src/adapters/null-adapter/null-adapter.md) — `NullAudioAdapter` is a deterministic, test-only implementation of the `AudioAdapter` interface. It produces predictabl…
+- [audio-sprite-packer](./src/core/audio-sprite-packer/audio-sprite-packer.md) — `AudioSpritePacker` is the primary orchestrator for combining multiple audio clips into a single concatenated buffer wi…
+  - [audio-sprite-packer](./src/core/audio-sprite-packer/audio-sprite-packer.md) — `AudioSpritePacker` is the primary orchestrator for combining multiple audio clips into a single concatenated buffer wi…
+- [error-codes](./src/error-codes/error-codes.md) — This module centralises every error code, metadata description, and severity level that the `@suaveplan/audio-sprite-pa…
+  - [error-codes](./src/error-codes/error-codes.md) — This module centralises every error code, metadata description, and severity level that the `@suaveplan/audio-sprite-pa…
+- [types](./src/types/common.md) — This module defines the public-facing TypeScript interfaces, Zod boundary schemas, and runtime types shared across the…
+  - [common](./src/types/common.md) — This module defines the public-facing TypeScript interfaces, Zod boundary schemas, and runtime types shared across the…
+- [manifest](./src/utils/manifest/manifest.md) — This module assembles and validates `AudioSpriteManifest` objects. `buildManifest` creates a manifest from packed entri…
+  - [manifest](./src/utils/manifest/manifest.md) — This module assembles and validates `AudioSpriteManifest` objects. `buildManifest` creates a manifest from packed entri…
+<!-- end:auto-docs -->
+
+## Install
+
+```bash
+bun add @suaveplan/audio-sprite-packer
+```
+
+## Quick start
+
+```ts
+import { AudioSpritePacker, NullAudioAdapter } from "@suaveplan/audio-sprite-packer";
+
+const packer = new AudioSpritePacker({ adapter: new NullAudioAdapter() });
+
+const sprite = await packer.pack([
+  { name: "jump", data: jumpBytes },
+  { name: "land", data: landBytes },
+  { name: "coin", data: coinBytes },
+]);
+
+// Retrieve individual clips by name.
+const jump = packer.unpack(sprite, "jump");
+console.log(jump.length); // encoded byte length
+```
+
+## Modules
+
+- [`src/core/audio-sprite-packer/audio-sprite-packer.md`](src/core/audio-sprite-packer/audio-sprite-packer.md) — `AudioSpritePacker` class and `createAudioSpritePacker` factory
+- [`src/utils/manifest/manifest.md`](src/utils/manifest/manifest.md) — `buildManifest` and `validateManifest`
+- [`src/adapters/null-adapter/null-adapter.md`](src/adapters/null-adapter/null-adapter.md) — `NullAudioAdapter` for testing
+- [`src/types/common.md`](src/types/common.md) — `AudioAdapter` interface, Zod schemas, and public types
+- [`src/error-codes.md`](src/error-codes.md) — Error codes and `AudioSpriteError` class
+- [`src/__benchmarks__/audio-sprite-packer.bench.md`](src/__benchmarks__/audio-sprite-packer.bench.md) — Benchmark suite notes
+