BgmChannel class

BGM Channel

Controls background music playback, including persistent playlist management, shuffle logic, reactive crossfade transitions, and volume storage.

Key Features:

Loads a default playlist with shuffle and resume support
Persists playlist and index between sessions
Crossfades before track ends using onPositionChanged
Fires onDefaultPlaylistComplete when default playlist loops
Fires onTrackAboutToChange before transitioning to next track
Manual controls: playNext, playAtIndex, playCustomPlaylist
Persists volume and active state via AudioStorage

Usage:

await BgmChannel.initialize(storage, audioContext);
await BgmChannel.instance.loadDefaultPlaylist(['assets/bgm/a.mp3', 'assets/bgm/b.mp3']);
await BgmChannel.instance.resumeDefaultPlaylist();

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

Inheritance

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: Whether this channel may spawn multiple concurrent players. Mixins like SFX pooling should override this automatically.
no setterinherited
isActive → bool: Active Flag
no setterinherited
isMuted → bool: Muted Flag
no setterinherited
isPlaying → bool: Current Status
no setterinherited
onDefaultPlaylistComplete ↔ VoidCallback?: Default Playlist Completed
getter/setter pair
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
onTrackAboutToChange ↔ VoidCallback?: Track About to Change
getter/setter pair
playerId → String: Stable Identifier
finalinherited
playerMode → PlayerMode: Player Mode
no setteroverride
releaseMode → ReleaseMode: Release Mode
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
enableLifecycle([ChannelLifecycleConfig? cfg]) → void: Enable per-channel lifecycle handling
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
loadDefaultPlaylist(List<String> paths, {bool shuffle = false}) → Future<void>: Load Default Playlist
mute() → Future<void>: Mute (Persistent)
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
onStateChanged(PlayerState state) → void: State Change Hook
override
pause() → Future<void>: Pause
inherited
play(String path) → Future<void>: Play a Track by Path
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
playAtIndex(int index) → Future<void>: Play at Specific Index
playCustomPlaylist(List<String> paths) → Future<void>: Play a Custom (Non-Persistent) Playlist
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
playNext() → Future<void>: Play Next Track (Looping)
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
resumeDefaultPlaylist() → Future<void>: Resume Default Playlist
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? fadeIn}) → Future<void>: withFade
inherited

Operators

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

Static Properties

instance ↔ BgmChannel: Singleton Instance
latefinal

Static Methods

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