# @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