Initial Commit
This commit is contained in:
80
packages/media/audio/audio-sprite-player/README.md
Normal file
80
packages/media/audio/audio-sprite-player/README.md
Normal file
@@ -0,0 +1,80 @@
|
||||
# @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)
|
||||
|
||||
Reference in New Issue
Block a user