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
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.
-
handleCancelBackGesture(
) → void -
Called when a predictive back gesture is canceled, indicating that no
navigation should occur.
inherited
-
handleCommitBackGesture(
) → void -
Called when a predictive back gesture is finished successfully, indicating
that the current route should be popped.
inherited
-
handleStartBackGesture(
PredictiveBackEvent backEvent) → bool -
Called at the start of a predictive back gesture.
inherited
-
handleUpdateBackGestureProgress(
PredictiveBackEvent backEvent) → void -
Called when a predictive back gesture moves.
inherited
-
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.