Audio class

A plugin for audio playback.

Example usage:

// Play a sound as a one-shot.
Audio.load('assets/foo.wav')..play()..dispose();

// Play a sound, with the ability to play it again, or stop it later.
var audio = Audio.load('assets/foo.wav')..play();
// ...
audio.play();
// ...
audio.pause();
// ...
audio.resume();
// ...
audio.pause();
audio.dispose();

// Do something when playback finishes.
var audio = Audio.load('assets/foo.wav', onComplete = () { ... });
audio.play();
// Note that after calling [dispose], audio playback will continue, and
// onComplete will still be run.
audio.dispose();

A note on sync and async usage. The async methods below (play, pause, etc) may be used sync'ly or async'ly. If used with 'await', they return when the native layer has finished executing the desired operation. This may be useful for synchronizing aural and visual elements. For example:

final audio = Audio.load('foo.wav');
audio.play();
animationController.forward()

would send messages to the native layer to begin loading and playback, but return (and start the animation) immediately. Wheras:

final audio = Audio.load('foo.wav');
await audio.play();
animationController.forward()

would wait until the native command to play returned, and the audio actually began playing. The animation is therefore more closely synchronized with the start of audio playback.

A note on Audio lifecycle. Audio objects, and the underlying native audio resources, have different lifespans, depending on usage. Instances of Audio may be kept alive after calls to dispose (and, if they are ivars, after their containing parents are dealloc'ed), so that they may continue to receive and handle callbacks (e.g. onComplete). The underlying native audio classes may be kept alive after dispose and the deallocation of the parent Audio object, so that audio may continue to play. This command would let the Audio instance deallocate immediately; the underlying resources are released once the file finishes playing.

Audio.load('x.wav')..play()..dispose();

This command would keep the Audio instance alive for the duration of the playback (so that its onComplete can be called); the underlying resources are released once the file finishes playing.

Audio.load('x.wav', looping:true, onComplete:()=>{...})..play()..dispose();

This command would let the Audio instance deallocate immediately; underlying
native resources keep playback going forever.
```dart
Audio.load('x.wav', looping:true)..play()..dispose();

While this command would keep the Audio instance alive forever (waiting to run onComplete), and also keep native resources playing forever:

Audio.load('x.wav', looping:true, onComplete:()=>{...})..play()..dispose();

Usage with State objects. If your Audio object is an ivar in a State object and it uses a callback (e.g. onComplete) which refers the surrounding class (e.g. a call to setState() or using a sibling ivar), then the callback keeps a strong reference to the surrounding class. Since Audio instances can outlast their parent State objects, that means that the parent State object may be kept alive unnecessarily, unless that strong reference is broken. In State.dispose(), do either: A) If you want the audio to stop playback on parent State disposal, call pause():

 void dispose() {
   _audio.pause();
   _audio.dispose();
   super.dispose();
 }

or B) If you want audio to continue playing back after parent State disposal, call removeCallbacks:

 void dispose() {
   _audio.removeCallbacks();
   _audio.dispose();
   super.dispose();
 }

In both cases, pause or removeCallbacks will signal that the Audio instance need not stay alive (after dispose) to call its callbacks. The Audio instance and the parent State will be dealloced.

Background audio. See README.md for additional per-platform setup for background audio. Use the 'playInBackground' flag on Audio load.

Audio.load('foo.wav', playInBackground = true);

and use all the methods in AudioSystem to communicate desired state and supported behavior to the OS's background audio system.

Mixed in types

WidgetsBindingObserver

Properties

hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
volume → double: Gets/Sets volume. Note that this is a linear amplitude multiplier; callers should use a sqrt value of 0-1 to get an equal-power fade, e.g. 'half volume' should be audio.setVolume(sqrt(.5)), to get something that 'sounds' half as loud as 'full' volume.
no setter

Methods

didChangeAccessibilityFeatures() → void: Called when the system changes the set of currently active accessibility features.
inherited
didChangeAppLifecycleState(AppLifecycleState state) → void: Handle audio lifecycle changes.
override
didChangeLocales(List<Locale>? locales) → void: Called when the system tells the app that the user's locale has changed. For example, if the user changes the system language settings.
inherited
didChangeMetrics() → void: Called when the application's dimensions change. For example, when a phone is rotated.
inherited
didChangePlatformBrightness() → void: Called when the platform brightness changes.
inherited
didChangeTextScaleFactor() → void: Called when the platform's text scale factor changes.
inherited
didHaveMemoryPressure() → void: Called when the system is running low on memory.
inherited
didPopRoute() → Future<bool>: Called when the system tells the app to pop the current route, such as after a system back button press or back gesture.
inherited
didPushRoute(String route) → Future<bool>: Called when the host tells the application to push a new route onto the navigator.
inherited
didPushRouteInformation(RouteInformation routeInformation) → Future<bool>: Called when the host tells the application to push a new RouteInformation and a restoration state onto the router.
inherited
didRequestAppExit() → Future<AppExitResponse>: Called when a request is received from the system to exit the application.
inherited
dispose() → Future<void>: Dispose this Audio.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
pause() → Future<void>: Pauses playing audio.
play({double? endpointSeconds}) → Future<void>: Plays this Audio content from the beginning.
removeCallbacks() → void: Remove callbacks from this Audio.
resume({double? endpointSeconds}) → Future<void>: Resumes audio playback from the current playback position.
seek(double positionSeconds) → Future<void>: Seeks to a playback position.
setVolume(double volume) → Future<void>
toString() → String: A string representation of this object.
inherited

Operators

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

Static Properties

awaitingOnCompleteAudiosCount → int: no setter
awaitingOnDurationAudiosCount → int: no setter
playingAudiosCount → int: no setter
undisposedAudiosCount → int: no setter
usingOnPositionAudiosCount → int: no setter

Static Methods

handleMethodCall(MethodCall call) → Future<void>: Handle method callbacks from the native layer.
load(String path, {void onComplete()?, void onDuration(double duration)?, void onPosition(double position)?, void onError(String? message)?, bool looping = false, bool playInBackground = false}) → Audio: Creates an Audio from an asset.
loadFromAbsolutePath(String path, {void onComplete()?, void onDuration(double duration)?, void onPosition(double position)?, void onError(String? message)?, bool looping = false, bool playInBackground = false}) → Audio: Creates an Audio from an absolute path to a file.
loadFromByteData(ByteData byteData, {void onComplete()?, void onDuration(double duration)?, void onPosition(double position)?, void onError(String? message)?, bool looping = false, bool playInBackground = false}) → Audio: Creates an Audio from a ByteData.
loadFromRemoteUrl(String url, {void onComplete()?, void onDuration(double duration)?, void onPosition(double position)?, void onError(String? message)?, bool looping = false, bool playInBackground = false}) → Audio?: Creates an Audio from a remote URL.