VoiceActingChannel class

VoiceActingChannel — Voice Acting Manager

Handles VO (voice-over) playback for in-game characters. Supports ducking background music (BGM) at start and restoring it on finish, with persisted per-channel volume.

Key Features

One-shot voice playback using mediaPlayer
Streamed audio via UrlSource (CDN-friendly)
Optional onDucking / onRestore hooks to coordinate with BGM
Persists voice volume (and active flag) via AudioStorage

Usage

VoiceActingChannel.initialize(AudioStorage.instance, audioContext);

VoiceActingChannel.instance.onDucking = () => BgmChannel.instance.fadeTo(0.3);
VoiceActingChannel.instance.onRestore = () => BgmChannel.instance.fadeTo(1.0);

await VoiceActingChannel.instance.playVoice(voiceUrl); // ducks, plays, restores

Notes

Call playVoice for duck/restore semantics.
play only sets the source and starts playback (no ducking).

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

Inheritance

Object
BaseAudioChannel
VoiceActingChannel

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
onCompleted ↔ Future<void> Function()?: getter/setter pair
onDucking ↔ Future<void> Function()?: Hooks
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
onRestore ↔ Future<void> Function()?: getter/setter pair
playerId → String: Stable Identifier
finalinherited
playerMode → PlayerMode: Mode: mediaPlayer
no setteroverride
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
withDucking ↔ bool: Ducking Flag
getter/setter pair

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
inherited
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
mute() → Future<void>: Mute (Persistent)
override
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
onStateChanged(PlayerState state) → void: onStateChanged
override
pause() → Future<void>: Pause
inherited
play(String path) → Future<void>: Play (Override)
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
playVoice(String path, [bool withDucking = true]) → Future<void>: Play a Voice Line (URL)
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? fadeIn}) → Future<void>: withFade
inherited

Operators

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

Static Properties

instance ↔ VoiceActingChannel: Singleton Instance
latefinal

Static Methods

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