81 lines
5.3 KiB
Markdown
81 lines
5.3 KiB
Markdown
# @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)
|
|
|