# @suaveplan/audio-sprite-player - Universal audio sprite playback engine: validates manifests, schedules voices, performs voice-stealing, and delegates output through an injectable SpritePlaybackAdapter.

Universal audio sprite playback engine. Consumes manifests produced by `@suaveplan/audio-sprite-packer`, validates them, schedules voices, runs voice-stealing under `maxConcurrentVoices`, and delegates actual audio output through an injectable `SpritePlaybackAdapter` implemented by engine-tier packages such as `@suaveplan/audio-engine-browser` and `@suaveplan/audio-engine-server`.

This package is **universal**: zero browser-only APIs, zero Node-only APIs. Every platform-specific concern (decode, gain ramps, pitch scheduling, mixer routing) is reached through the adapter seam.

<!-- begin:auto-docs -->
## Documentation tree

- [adapter](./src/adapter/adapter.md) — `SpritePlaybackAdapter` is the engine-tier seam that the universal `@suaveplan/audio-sprite-player` reaches through to…
  - [null](./src/adapter/null/null.md) — `NullSpritePlaybackAdapter` is the recording adapter that conforms to the `SpritePlaybackAdapter` contract without prod…
    - [null](./src/adapter/null/null.md) — `NullSpritePlaybackAdapter` is the recording adapter that conforms to the `SpritePlaybackAdapter` contract without prod…
  - [adapter](./src/adapter/adapter.md) — `SpritePlaybackAdapter` is the engine-tier seam that the universal `@suaveplan/audio-sprite-player` reaches through to…
- [error-codes](./src/error-codes/error-codes.md) — This module is the canonical registry of error codes for `@suaveplan/audio-sprite-player`. It defines a stable string i…
  - [error-codes](./src/error-codes/error-codes.md) — This module is the canonical registry of error codes for `@suaveplan/audio-sprite-player`. It defines a stable string i…
- [events](./src/events/events.md) — `SpritePlayerEvents` is the typed event surface a `SpritePlayer` exposes for downstream consumers — analytics, UI feedb…
  - [events](./src/events/events.md) — `SpritePlayerEvents` is the typed event surface a `SpritePlayer` exposes for downstream consumers — analytics, UI feedb…
- [schemas](./src/schemas/schemas.md) — This module owns every runtime Zod schema exposed at the public boundary of `@suaveplan/audio-sprite-player`. Universal…
  - [schemas](./src/schemas/schemas.md) — This module owns every runtime Zod schema exposed at the public boundary of `@suaveplan/audio-sprite-player`. Universal…
- [sprite-player](./src/sprite-player/sprite-player.md) — `SpritePlayer` is the public orchestrator for `@suaveplan/audio-sprite-player`. It accepts a validated `AudioSprite` (a…
  - [sprite-player](./src/sprite-player/sprite-player.md) — `SpritePlayer` is the public orchestrator for `@suaveplan/audio-sprite-player`. It accepts a validated `AudioSprite` (a…
- [telemetry](./src/telemetry/telemetry.md) — `SpritePlayerTelemetry` is the OTel-facing facade that `SpritePlayer` opens for every public invocation. It manages one…
  - [telemetry](./src/telemetry/telemetry.md) — `SpritePlayerTelemetry` is the OTel-facing facade that `SpritePlayer` opens for every public invocation. It manages one…
- [voice-manager](./src/voice-manager/voice-manager.md) — `VoiceManager` enforces the active-voice cap and runs the voice-stealing algorithm that keeps sprite playback bounded u…
  - [voice-manager](./src/voice-manager/voice-manager.md) — `VoiceManager` enforces the active-voice cap and runs the voice-stealing algorithm that keeps sprite playback bounded u…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/audio-sprite-player
```

## Quickstart

```ts
import {
  createSpritePlayer,
  NullSpritePlaybackAdapter,
} from "@suaveplan/audio-sprite-player";

const adapter = new NullSpritePlaybackAdapter(); // swap for a real engine adapter
const player = createSpritePlayer({ adapter, maxConcurrentVoices: 16 });

await player.load(sprite); // sprite produced by @suaveplan/audio-sprite-packer
const handle = await player.play("hit", { volume: 0.8, fadeInMs: 10 });

player.events.on("voice-stolen", (e) => {
  console.log(`voice ${e.stolenId} replaced by ${e.replacedBy}`);
});

await player.playSequence(["step", "step", "land"], { gapMs: 50 });
await player.stopAll(20);
await player.dispose();
```

## Public surface

- `SpritePlayer` / `createSpritePlayer` — the orchestrator.
- `SpritePlaybackAdapter` (type) — engine seam.
- `NullSpritePlaybackAdapter` — recording adapter for tests and baseline conformance.
- `VoiceManager` — voice cap + stealing primitive (exported for advanced use).
- `SpritePlayerEvents` — typed event subscriber on `play` / `stop` / `complete` / `voice-stolen` / `error`.
- `SpritePlayerTelemetry` — OTel tracer + counter + gauge + histogram.
- `AUDIO_SPRITE_PLAYER_CODES`, `AudioSpritePlayerError` — stable error contract.
- Zod schemas at `./schemas`.

## Documentation

See the co-located `.md` files inside `src/`:

- [`sprite-player/sprite-player.md`](./src/sprite-player/sprite-player.md)
- [`voice-manager/voice-manager.md`](./src/voice-manager/voice-manager.md)
- [`adapter/adapter.md`](./src/adapter/adapter.md)
- [`adapter/null/null.md`](./src/adapter/null/null.md)
- [`events/events.md`](./src/events/events.md)
- [`telemetry/telemetry.md`](./src/telemetry/telemetry.md)
- [`schemas.md`](./src/schemas.md)
- [`error-codes.md`](./src/error-codes.md)