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

Documentation tree

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

Install

bun add @suaveplan/audio-sprite-player

Quickstart

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/:

5.3 KiB Raw Blame History