---
name: sp-audio-sprite-packer
description: Binary audio sprite map packer — 80%+ compression vs individual files. Concatenates clips into a single binary with a compact JSON manifest.
---

# sp-audio-sprite-packer

| Symbol | Kind | Responsibility |
|---|---|---|
| `AudioSpritePacker` | Class | Main packer — concatenates audio clips, emits binary + manifest |
| `createAudioSpritePacker` | Function | Factory for `AudioSpritePacker` with schema-validated options |
| `buildManifest` | Function | Builds a compact `AudioSpriteManifest` from packed clips |
| `validateManifest` | Function | Validates a manifest against `AudioSpriteManifestSchema` |
| `NullAudioAdapter` | Class | No-op audio adapter for testing / non-browser environments |
| `createNullAudioAdapter` | Function | Factory for the null adapter |
| `AUDIO_SPRITE_CODES` | Constant | Error-code registry via `@suaveplan/error` `defineCodes` |

**File Structure:** `packages/media/audio/audio-sprite-packer/src/{core,adapters,utils,error-codes}/`

**Sibling packages:**
- `@suaveplan/audio-sprite-player` — sprite player (unpacks and plays sprites)
- `@suaveplan/audio-core` — audio document model

**Patterns:**

*Quick Start:*
```ts
import { createAudioSpritePacker } from "@suaveplan/audio-sprite-packer";
const packer = createAudioSpritePacker({ format: "wav" });
const { binary, manifest } = await packer.pack(clips);
// binary: concatenated audio bytes
// manifest: { entries: [{ name, offset, duration }] }
```

*Validate manifest:*
```ts
import { validateManifest } from "@suaveplan/audio-sprite-packer/utils/manifest/manifest";
validateManifest(manifest); // throws on schema violation
```

**Constraints:**
- Universal — zero platform-only APIs
- Subpath exports: `/core/audio-sprite-packer`, `/adapters/null-adapter`, `/utils/manifest`, `/error-codes`
- `AudioSpritePackerOptionsSchema` validates format, sampleRate, and quality
- `AudioClipInputSchema` validates each clip (name, buffer, trim options)
- Manifest includes SHA-256 hashes for integrity verification
- Null adapter provided for server-side packing without audio hardware

**Checklist:**
- [ ] `pack()` produces a single binary and a JSON manifest
- [ ] Manifest entries include correct byte offsets and durations
- [ ] `validateManifest` rejects malformed manifests
- [ ] Null adapter works in non-browser environments
- [ ] SHA-256 hashes included for integrity