audioplayers
a flutter plugin to play multiple simultaneously au,dio files, works for android and ios.
install
this was orginally forked from rxlabz’s audioplayer, but the name was changed to audioplayers
(mind the ‘s’); so, to add the dependency:
dependencies:
au,dioplayers: ^0.8.0
usage
an aud,ioplayer
instance can play a single au,io at a time. to create it, simply call the constructor:
aud,ioplayer au,dioplayer = new audi,oplayer();
you can create multiple instances to play au,dio simultaneously.
for all methods that return a future<int>
: that’s the status of the operation. if 1
, the operation was successful. otherwise it’s the platform native error code.
logs are disable by default! to debug, run:
au,dioplayer.logenabled = true;
playing audio
there are three possible sources of a,udio:
- remote file on the internet
- local file on the user’s device
- local asset from your flutter project
both for remote files or local files, use the play
method, just setting appropriately the flag islocal
.
for local assets, you have to use the au,diocache
class (see below).
to play a remote file, just call play
with the url (the islocal
parameter is false by default):
play() async {
int result = await aud,ioplayer.play(url);
if (result == 1) {
// success
}
}
for a local file, add the islocal
parameter:
playlocal() async {
int result = await au,dioplayer.play(localpath, islocal: true);
}
the islocal
flag is required only because ios makes a difference about it (android doesn’t care either way).
there is also an optional named double volume
parameter, that defaults to 1.0
. it can go from 0.0
(mute) to 1.0
(max), varying linearly.
the volume can also be changed at any time using the setvolume
method.
controlling
after playing, you can control the a,udio with pause, stop and seek commands.
pause will pause the aud,io but keep the cursor where it was. subsequently calling play will resume from this point.
int result = await au,oplayer.pause();
stop will stop the a,udio and reset the cursor. subsequently calling play will resume from the beginning.
int result = await audi,oplayer.stop();
finally, use seek to jump through your aud,io:
int result = await au,dioplayer.seek(new duration(milliseconds: 1200));
also, you can resume (like play, but without new parameters):
int result = await aud,ioplayer.resume();
finer control
by default, the player will be release once the playback is finished or the stop method is called.
this is because on android, a mediaplayer instance can be quite resource-heavy, and keep it unreleased would cause performance issues if you play lots of different audios.
on ios this doesn’t apply, so release does nothing.
you can change the release mode to determine the actual behavior of the mediaplayer once finished/stopped. there are three options:
- release: default mode, will release after stop/completed.
- stop: will never release; calling play should be faster.
- loop: will never release; after completed, it will start playing again on loop.
if you are not on release mode, you should call the release method yourself; for example:
await audioplayer.seturl('clicking.mp3'); // prepare the player with this audio but do not start playing
await audioplayer.setreleasemode(releasemode.stop); // set release mode so that it never releases
// on button click
await audioplayer.resume(); // quickly plays the sound, will not release
// on exiting screen
await audioplayer.release(); // manually release when no longer needed
despite the complex state diagram of android’s mediaplayer, an audioplayer instance should never have an invalid state. even if it’s released, if resume is called, the data will be fetch again.
handlers
you can register callbacks for several event handlers, like so:
duration handler
this handler returns the duration of the file, when it’s available (it might take a while because it’s being downloaded or buffered).
player.durationhandler = (duration d) {
print('max duration: $d');
setstate(() => duration = d);
};
position handler
this handler updates the current position of the audio. you can use it to make a progress bar, for instance.
player.positionhandler = (duration p) => {
print('current position: $d');
setstate(() => duration = d);
};
completion handler
this handler is called when the audio finishes playing; it’s used in the loop method, for instance.
it does not fire when you interrupt the audio with pause or stop.
player.completionhandler = () {
oncomplete();
setstate(() {
position = duration;
});
};
error handler
this is called when an unexpected error is thrown in the native code.
player.errorhandler = (msg) {
print('audioplayer error : $msg');
setstate(() {
playerstate = playerstate.stopped;
duration = new duration(seconds: 0);
position = new duration(seconds: 0);
});
};
audiocache
in order to play local assets, you must use the audiocache
class.
flutter does not provide an easy way to play audio on your assets, but this class helps a lot. it actually copies the asset to a temporary folder in the device, where it is then played as a local file.
it works as a cache because it keep track of the copied files so that you can replay then without delay.
you can find the full documentation for this class here.
supported formats
you can check a list of supported formats below:
:warning: ios app transport security
by default ios forbids loading from non-https url. to cancel this restriction you must edit your .plist
and add:
<key>nsapptransportsecurity</key>
<dict>
<key>nsallowsarbitraryloads</key>
<true/>
</dict>
Comments are closed.