PooledPlayback mixin

PooledPlayback

Opt-in audio pooling for instant retrigger/overlap of short sounds. Intended for SFX-style channels that often replay the same clip rapidly.

What it does

• Keeps a tiny pool of pre-prepared AudioPlayers per sound key.
• Inherits the channel’s AudioContext so focus/ducking rules match.
• Supports assets, device files, URLs, and bytes sources.
• Automatically marks the channel as multi-player capable, so BaseAudioChannel.waitUntilStopped() / playAndWait() will throw (waiting is ambiguous when multiple players can run).

Typical usage

class SfxChannel extends BaseAudioChannel with PooledPlayback {
  SfxChannel() : super('sfx_player');

  @override PlayerMode get playerMode => PlayerMode.lowLatency;
  @override ReleaseMode get releaseMode => ReleaseMode.stop;

  // Make pooling transparent for .play(path)
  @override
  Future<void> play(String path) async {
    await playPooledPath(path, key: path, volume: volume);
  }

  @override
  Future<void> dispose() async {
    await disposePools();  // ← clean pooled players
    return super.dispose();
  }
}

// Configure pooling (optional; defaults shown)
SoundEngine.instance.sfx.enablePooling(
  enabled: true,
  poolSizePerSound: 4,     // max concurrent players for a given sound
  minPlayersPerSound: 1,   // pre-warmed instances per sound
);

// Fire-and-forget retriggers (instant overlaps)
await SoundEngine.instance.sfx.play('assets/sfx/click.mp3');

When to refresh pools

If you change a channel’s AudioContext after some pools were built, call refreshPoolsAudioContext to recreate existing pools with the new context:

await sfx.setAudioContext(newCtx);
await sfx.refreshPoolsAudioContext();

Waiting caveat

Pooling enables concurrent playbacks; a single “wait until stop” has no unambiguous target. The mixin reports concurrency via hasMultipleConcurrentPlayers, so waitUntilStopped / playAndWait will throw UnsupportedError. If you need blocking behavior, disable pooling (globally or for the duration) or use a dedicated non-pooled channel.