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.

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

Properties

hashCode int
The hash code for this object. [...]
read-only, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited
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.
read-only

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> locale) → 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. For example, on Android, this is called when the user presses the back button. [...]
inherited
didPushRoute(String route) Future<bool>
Called when the host tells the app to push a new route onto the navigator. [...]
inherited
dispose() Future<void>
Dispose this Audio. [...]
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent 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
Returns a string representation of this object.
inherited

Operators

operator ==(dynamic other) bool
The equality operator. [...]
inherited

Static Properties

awaitingOnCompleteAudiosCount int
@visibleForTesting, read-only
awaitingOnDurationAudiosCount int
@visibleForTesting, read-only
playingAudiosCount int
@visibleForTesting, read-only
undisposedAudiosCount int
@visibleForTesting, read-only
usingOnPositionAudiosCount int
@visibleForTesting, read-only

Static Methods

handleMethodCall(MethodCall call) Future<void>
Handle method callbacks from the native layer.
@visibleForTesting
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. [...]