SfxChannel class

SfxChannel — Sound Effects Manager (pooled)

Handles ultra-snappy SFX playback with simple grouping and throttling. Adds pooled playback for instant retrigger/overlap across assets, device files, or URLs while preserving the channel's audio context.

Key Features

  • Sound groups (e.g., click, hover, hit) with randomized pick
  • Cooldown per group to prevent spam
  • Low-latency playback mode (best for short clips)
  • Pooling (opt-in, enabled by default): instant retrigger of same file
  • Persistent volume and active state via AudioStorage

Usage

// Bootstrap once
SfxChannel.initialize(AudioStorage.instance, audioContext);
SfxChannel.instance.enablePooling(enabled: true, poolSizePerSound: 4);

// Register sounds
SfxChannel.instance.registerGroup('click', [
  'assets/sfx/click1.wav',
  'assets/sfx/click2.wav',
]);

// Play randomized click (pooled)
await SfxChannel.instance.playGroup('click');

// Play a specific sfx (pooled; asset/file/url supported)
await SfxChannel.instance.playSfx('assets/sfx/button_tap.wav');

Notes

  • Uses the channel’s current source builder via resolveSource(path), so changeSource((p) => DeviceFileSource(p)) works seamlessly.
  • For long or streamed audio, use a non-lowLatency channel instead.

─────────────────────────────────────────────────────────────────────────────

Inheritance
Mixed-in types

Properties

currentAudioContext → AudioContext?
Current audio context getter (nullable if never set).
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
hasMultipleConcurrentPlayers → bool
Report concurrency to the base so wait-helpers throw automatically.
no setterinherited
isActive → bool
Active Flag
no setterinherited
isMuted → bool
Muted Flag
no setterinherited
isPlaying → bool
Current Status
no setterinherited
isPoolingEnabled → bool
Whether pooling is currently enabled.
no setterinherited
minPlayersPerSound → int
Pre-warmed players per sound key.
no setterinherited
onDurationChanged → Stream<Duration>
Duration Stream
no setterinherited
onIsPlayingChanged → Stream<bool>
Reactive isPlaying Stream
no setterinherited
onPlayerComplete → Stream<void>
Completion Event
no setterinherited
onPositionChanged → Stream<Duration>
Position Stream
no setterinherited
playerId → String
Stable Identifier
finalinherited
playerMode → PlayerMode
Mode: Low Latency
no setteroverride
poolSizePerSound → int
Maximum concurrent players per sound key.
no setterinherited
releaseMode → ReleaseMode
Release: Stop
no setteroverride
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
volume → double
Current Volume (0.0 → 1.0)
no setterinherited

Methods

activate() → void
Activate
inherited
changeSource(AudioSourceBuilder builder) → void
Swap Loader
inherited
deactivate() → void
Deactivate
inherited
disableLifecycle() → void
Disable lifecycle handling for this channel.
inherited
dispose() → Future<void>
Dispose
override
disposePools() → Future<void>
Dispose all pools.
inherited
enableLifecycle([ChannelLifecycleConfig cfg = const ChannelLifecycleConfig()]) → void
Enable per-channel lifecycle handling
inherited
enablePooling({bool enabled = true, int poolSizePerSound = 4, int minPlayersPerSound = 1}) → void
Enable/disable pooling and configure pool sizes.
inherited
ensureWaitSupported(String methodName) → void
Throws if waiting semantics are unsupported for this channel.
inherited
fadeIn({Duration duration = const Duration(seconds: 2), Curve curve = Curves.easeInOut}) → Future<void>
Fade In
inherited
fadeInVolume(FadePreset preset) → Future<void>
Helper: Fade In via FadePreset
inherited
fadeOut({Duration duration = const Duration(seconds: 2), Curve curve = Curves.easeOut}) → Future<void>
Fade Out
inherited
fadeOutVolume(FadePreset preset) → Future<void>
Helper: Fade Out via FadePreset
inherited
fadeTo(double targetVolume, {Duration duration = const Duration(seconds: 2), Curve curve = Curves.linear}) → Future<void>
Fade To Target Volume
inherited
getDuration() → Future<Duration?>
Current Media Duration
inherited
mute() → Future<void>
Mute (Persistent)
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onStateChanged(PlayerState state) → void
Subclass Hook: Player State Changed
inherited
pause() → Future<void>
Pause
inherited
play(String path) → Future<void>
Play a Specific SFX Path (pooled)
override
playAndWait(String path, {Duration startTimeout = const Duration(seconds: 3), Duration timeout = const Duration(minutes: 2), bool forceStopOnTimeout = true}) → Future<bool>
Convenience: play a path and wait for completion/stop
inherited
playFromSource(Source source) → Future<void>
Play from Source
inherited
playFromSourceAndWait(Source source, {Duration startTimeout = const Duration(seconds: 3), Duration timeout = const Duration(minutes: 2), bool forceStopOnTimeout = true}) → Future<bool>
Convenience: play a Source and wait for completion/stop
inherited
playGroup(String name) → Future<void>
Play a Random Sound from a Group
playPooled(String key, Source source, {double? volume}) → Future<StopFunction?>
Play using a pooled player (or fallback to the single channel player).
inherited
playPooledPath(String path, {String? key, double? volume}) → Future<StopFunction?>
Play a path using pooling, resolving the path with the channel’s current loader (respects changeSource(...)).
inherited
playSfxSource(Source source, {String? cacheKey}) → Future<void>
Play from an explicit Source (pooled)
refreshPoolsAudioContext() → Future<void>
Rebuild all pools so they inherit the channel’s current AudioContext. Useful after calling setAudioContext(...) at runtime.
inherited
registerGroup(String name, List<String> paths) → void
Register a Group
resolveSource(String path) → Source
Resolve a path into a Source using the current builder (assets/files/urls). Override via changeSource to switch the strategy at runtime.
inherited
resume() → Future<void>
Resume
inherited
seek(Duration position) → Future<void>
Seek
inherited
setAudioContext(AudioContext audioContext) → Future<void>
Apply Platform Audio Context
inherited
setVolume(double volume) → Future<void>
Set Volume (Persistent)
override
stop() → Future<void>
Stop
inherited
toggleActive() → void
Toggle Active (Persistent)
override
toString() → String
A string representation of this object.
inherited
unmute() → Future<void>
Unmute (Persistent)
override
waitUntilStarted({Duration timeout = const Duration(seconds: 3)}) → Future<bool>
Wait until playback starts (first true)
inherited
waitUntilStopped({Duration startTimeout = const Duration(seconds: 3), Duration timeout = const Duration(minutes: 2), bool forceStopOnTimeout = true}) → Future<bool>
Wait until playback stops/completes
inherited
withFade(Future<void> action(), {FadePreset fadeOut = FadePreset.fast, FadePreset fadeIn = FadePreset.normal}) → Future<void>
withFade
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

instance ↔ SfxChannel
Singleton Instance
latefinal

Static Methods

initialize(AudioStorage storage, [AudioContext? audioContext]) → void
Initialize