BgmChannel class

BGM Channel

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

Key Features:

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