Awesome
๐ง assets_audio_player ๐
<a href="https://github.com/Solido/awesome-flutter">
<img alt="Awesome Flutter" src="https://img.shields.io/badge/Awesome-Flutter-blue.svg?longCache=true&style=flat" />
</a>
<img src="https://img.shields.io/badge/platform-android%20%7C%20ios%20%7C%20macos%20%7C%20web%20-%23989898" />
Play music/audio stored in assets files (simultaneously) directly from Flutter (android / ios / web / macos).
You can also use play audio files from network using their url, radios/livestream and local files
Notification can be displayed on Android & iOS, and bluetooth actions are handled
flutter:
assets:
- assets/audios/
AssetsAudioPlayer.newPlayer().open(
Audio("assets/audios/song1.mp3"),
autoStart: true,
showNotification: true,
);
๐ฅ Import
dependencies:
assets_audio_player: ^3.0.8
Works with flutter: ">=3.3.0"
, be sure to upgrade your sdk
You like the package ? buy me a kofi :)
<a href='https://ko-fi.com/A160LCC' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://az743702.vo.msecnd.net/cdn/kofi1.png?v=0' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
<table> <thead> <tr> <th>Audio Source</th> <th>Android</th> <th>iOS</th> <th>Web</th> <th>MacOS</th> </tr> </thead> <tbody> <tr> <td>๐๏ธ Asset file (asset path)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ Network file (url)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ Local file (path)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ป Network LiveStream / radio (url) <br/> (<b>Default, HLS, Dash, SmoothStream</b>)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> </tbody> </table> <table> <thead> <tr> <th>Feature</th> <th>Android</th> <th>iOS</th> <th>Web</th> <th>MacOS</th> </tr> </thead> <tbody> <tr> <td>๐ถ Multiple players</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฝ Open Playlist</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฌSystem notification</td> <td>โ </td> <td>โ </td> <td>๐ซ</td> <td>๐ซ</td> </tr> <tr> <td>๐ง Bluetooth actions</td> <td>โ </td> <td>โ </td> <td>๐ซ</td> <td>๐ซ</td> </tr> <tr> <td>๐ Respect System silent mode</td> <td>โ </td> <td>โ </td> <td>๐ซ</td> <td>๐ซ</td> </tr> <tr> <td>๐ Pause on phone call</td> <td>โ </td> <td>โ </td> <td>๐ซ</td> <td>๐ซ</td> </tr> </tbody> </table> <table> <thead> <tr> <th>Commands</th> <th>Android</th> <th>iOS</th> <th>Web</th> <th>MacOS</th> </tr> </thead> <tbody> <tr> <td>โถ Play</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โธ Pause</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โน Stop</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โฉ Seek(position)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โชโฉ SeekBy(position)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โฉ Forward(speed)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โช Rewind(speed)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โญ Next</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โฎ Prev</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> </tbody> </table> <table> <thead> <tr> <th>Widgets</th> <th>Android</th> <th>iOS</th> <th>Web</th> <th>MacOS</th> </tr> </thead> <tbody> <tr> <td>๐ฆ Audio Widget</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฆ Widget Builders</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฆ AudioPlayer Builders Extension</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> </tbody> </table> <table> <thead> <tr> <th>Properties</th> <th>Android</th> <th>iOS</th> <th>Web</th> <th>MacOS</th> </tr> </thead> <tbody> <tr> <td>๐ Loop</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ Shuffle</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ get/set Volume</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โฉ get/set Play Speed</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>โฉ get/set Pitch</td> <td>โ </td> <td>๐ซ</td> <td>๐ซ</td> <td>๐ซ</td> </tr> </tbody> </table> <table> <thead> <tr> <th>Listeners</th> <th>Android</th> <th>iOS</th> <th>Web</th> <th>MacOS</th> </tr> </thead> <tbody> <tr> <td>๐ฆป Listener onReady(completeDuration)</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฆป Listener currentPosition</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฆป Listener finished</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฆป Listener buffering</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฆป Listener volume</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฆปListener Play Speed</td> <td>โ </td> <td>โ </td> <td>โ </td> <td>โ </td> </tr> <tr> <td>๐ฆปListener Pitch</td> <td>โ </td> <td>๐ซ</td> <td>๐ซ</td> <td>๐ซ</td> </tr> </tbody> </table>๐ Import assets files
No needed to copy songs to a media cache, with assets_audio_player you can open them directly from the assets.
- Create an audio directory in your assets (not necessary named "audios")
- Declare it inside your pubspec.yaml
flutter:
assets:
- assets/audios/
๐ ๏ธ Getting Started
final assetsAudioPlayer = AssetsAudioPlayer();
assetsAudioPlayer.open(
Audio("assets/audios/song1.mp3"),
);
You can also play network songs from url
final assetsAudioPlayer = AssetsAudioPlayer();
try {
await assetsAudioPlayer.open(
Audio.network("http://www.mysite.com/myMp3file.mp3"),
);
} catch (t) {
//mp3 unreachable
}
LiveStream / Radio from url
The main difference with network, if you pause/play, on livestream it will resume to present duration
final assetsAudioPlayer = AssetsAudioPlayer();
try {
await assetsAudioPlayer.open(
Audio.liveStream(MY_LIVESTREAM_URL),
);
} catch (t) {
//stream unreachable
}
And play songs from file
//create a new player
final assetsAudioPlayer = AssetsAudioPlayer();
assetsAudioPlayer.open(
Audio.file(FILE_URI),
);
for file uri, please look at https://pub.dev/packages/path_provider
assetsAudioPlayer.playOrPause();
assetsAudioPlayer.play();
assetsAudioPlayer.pause();
assetsAudioPlayer.seek(Duration to);
assetsAudioPlayer.seekBy(Duration by);
assetsAudioPlayer.forwardRewind(double speed);
//if positive, forward, if negative, rewind
assetsAudioPlayer.stop();
Notifications
on iOS, it will use MPNowPlayingInfoCenter
- Add metas inside your audio
final audio = Audio.network("/assets/audio/country.mp3",
metas: Metas(
title: "Country",
artist: "Florent Champigny",
album: "CountryAlbum",
image: MetasImage.asset("assets/images/country.jpg"), //can be MetasImage.network
),
);
- open with
showNotification: true
_player.open(audio, showNotification: true)
Custom notification
Custom icon (android only)
By ResourceName
Make sure you added those icons inside your android/res/drawable
!!! not on flutter assets !!!!
await _assetsAudioPlayer.open(
myAudio,
showNotification: true,
notificationSettings: NotificationSettings(
customStopIcon: AndroidResDrawable(name: "ic_stop_custom"),
customPauseIcon: AndroidResDrawable(name:"ic_pause_custom"),
customPlayIcon: AndroidResDrawable(name:"ic_play_custom"),
customPrevIcon: AndroidResDrawable(name:"ic_prev_custom"),
customNextIcon: AndroidResDrawable(name:"ic_next_custom"),
)
And don't forget tell proguard to keep those resources for release mode
(part Keeping Resources)
https://sites.google.com/a/android.com/tools/tech-docs/new-build-system/resource-shrinking
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
tools:keep="@drawable/ic_next_custom, @drawable/ic_prev_custom, @drawable/ic_pause_custom, @drawable/ic_play_custom, @drawable/ic_stop_custom"/>
By Manifest
-
Add your icon into your android's
res
folder (android/app/src/main/res) -
Reference this icon into your AndroidManifest (android/app/src/main/AndroidManifest.xml)
<meta-data
android:name="assets.audio.player.notification.icon"
android:resource="@drawable/ic_music_custom"/>
You can also change actions icons
<meta-data
android:name="assets.audio.player.notification.icon.play"
android:resource="@drawable/ic_play_custom"/>
<meta-data
android:name="assets.audio.player.notification.icon.pause"
android:resource="@drawable/ic_pause_custom"/>
<meta-data
android:name="assets.audio.player.notification.icon.stop"
android:resource="@drawable/ic_stop_custom"/>
<meta-data
android:name="assets.audio.player.notification.icon.next"
android:resource="@drawable/ic_next_custom"/>
<meta-data
android:name="assets.audio.player.notification.icon.prev"
android:resource="@drawable/ic_prev_custom"/>
Handle notification click (android)
Add in main
AssetsAudioPlayer.setupNotificationsOpenAction((notification) {
//custom action
return true; //true : handled, does not notify others listeners
//false : enable others listeners to handle it
});
Then if you want a custom action on widget
AssetsAudioPlayer.addNotificationOpenAction((notification) {
//custom action
return false; //true : handled, does not notify others listeners
//false : enable others listeners to handle it
});
Custom actions
You can enable/disable a notification action
open(AUDIO,
showNotification: true,
notificationSettings: NotificationSettings(
prevEnabled: false, //disable the previous button
//and have a custom next action (will disable the default action)
customNextAction: (player) {
print("next");
}
)
)
Update audio's metas / notification content
After your audio creation, just call
audio.updateMetas(
player: _assetsAudioPlayer, //add the player if the audio is actually played
title: "My new title",
artist: "My new artist",
//if I not provide a new album, it keep the old one
image: MetasImage.network(
//my new image url
),
);
Bluetooth Actions
You have to enable notification to make them work
Available remote commands :
- Play / Pause
- Next
- Prev
- Stop
HeadPhone Strategy
(Only for Android for now)
while opening a song/playlist, add a strategy
assetsAudioPlayer.open(
...
headPhoneStrategy: HeadPhoneStrategy.pauseOnUnplug,
//headPhoneStrategy: HeadPhoneStrategy.none, //default
//headPhoneStrategy: HeadPhoneStrategy.pauseOnUnplugPlayOnPlug,
)
If you want to make it work on bluetooth too, you'll have to add the BLUETOOTH permission inside your AndroidManifest.xml
<uses-permission android:name="android.permission.BLUETOOTH" />
โ Play in parallel / simultaneously
You can create new AssetsAudioPlayer using AssetsAudioPlayer.newPlayer(), which will play songs in a different native Media Player
This will enable to play two songs simultaneously
You can have as many player as you want !
///play 3 songs in parallel
AssetsAudioPlayer.newPlayer().open(
Audio("assets/audios/song1.mp3")
);
AssetsAudioPlayer.newPlayer().open(
Audio("assets/audios/song2.mp3")
);
//another way, with create, open, play & dispose the player on finish
AssetsAudioPlayer.playAndForget(
Audio("assets/audios/song3.mp3")
);
Each player has an unique generated id
, you can retrieve or create them manually using
final player = AssetsAudioPlayer.withId(id: "MY_UNIQUE_ID");
๐๏ธ Playlist
assetsAudioPlayer.open(
Playlist(
audios: [
Audio("assets/audios/song1.mp3"),
Audio("assets/audios/song2.mp3")
]
),
loopMode: LoopMode.playlist //loop the full playlist
);
assetsAudioPlayer.next();
assetsAudioPlayer.prev();
assetsAudioPlayer.playlistPlayAtIndex(1);
Audio Widget
If you want a more flutter way to play audio, try the AudioWidget
!
//inside a stateful widget
bool _play = false;
@override
Widget build(BuildContext context) {
return AudioWidget.assets(
path: "assets/audios/country.mp3",
play: _play,
child: RaisedButton(
child: Text(
_play ? "pause" : "play",
),
onPressed: () {
setState(() {
_play = !_play;
});
}
),
onReadyToPlay: (duration) {
//onReadyToPlay
},
onPositionChanged: (current, duration) {
//onPositionChanged
},
);
}
How to ๐ stop ๐ the AudioWidget ?
Just remove the Audio from the tree !
Or simply keep play: false
๐ง Listeners
All listeners exposes Streams Using RxDart, AssetsAudioPlayer exposes some listeners as ValueObservable (Observable that provides synchronous access to the last emitted item);
๐ต Current song
//The current playing audio, filled with the total song duration
assetsAudioPlayer.current //ValueObservable<PlayingAudio>
//Retrieve directly the current played asset
final PlayingAudio playing = assetsAudioPlayer.current.value;
//Listen to the current playing song
assetsAudioPlayer.current.listen((playingAudio){
final asset = playingAudio.assetAudio;
final songDuration = playingAudio.duration;
})
โ Current song duration
//Listen to the current playing song
final duration = assetsAudioPlayer.current.value.duration;
โณ Current position (in seconds)
assetsAudioPlayer.currentPosition //ValueObservable<Duration>
//retrieve directly the current song position
final Duration position = assetsAudioPlayer.currentPosition.value;
return StreamBuilder(
stream: assetsAudioPlayer.currentPosition,
builder: (context, asyncSnapshot) {
final Duration duration = asyncSnapshot.data;
return Text(duration.toString());
}),
or use a PlayerBuilder !
PlayerBuilder.currentPosition(
player: _assetsAudioPlayer,
builder: (context, duration) {
return Text(duration.toString());
}
)
or Player Builder Extension
_assetsAudioPlayer.builderCurrentPosition(
builder: (context, duration) {
return Text(duration.toString());
}
)
โถ IsPlaying
boolean observable representing the current mediaplayer playing state
assetsAudioPlayer.isPlaying // ValueObservable<bool>
//retrieve directly the current player state
final bool playing = assetsAudioPlayer.isPlaying.value;
//will follow the AssetsAudioPlayer playing state
return StreamBuilder(
stream: assetsAudioPlayer.isPlaying,
builder: (context, asyncSnapshot) {
final bool isPlaying = asyncSnapshot.data;
return Text(isPlaying ? "Pause" : "Play");
}),
or use a PlayerBuilder !
PlayerBuilder.isPlaying(
player: _assetsAudioPlayer,
builder: (context, isPlaying) {
return Text(isPlaying ? "Pause" : "Play");
}
)
or Player Builder Extension
_assetsAudioPlayer.builderIsPlaying(
builder: (context, isPlaying) {
return Text(isPlaying ? "Pause" : "Play");
}
)
๐ Volume
Change the volume (between 0.0 & 1.0)
assetsAudioPlayer.setVolume(0.5);
The media player can follow the system "volume mode" (vibrate, muted, normal)
Simply set the respectSilentMode
optional parameter as true
_player.open(PLAYABLE, respectSilentMode: true);
https://developer.android.com/reference/android/media/AudioManager.html?hl=fr#getRingerMode()
https://developer.apple.com/documentation/avfoundation/avaudiosessioncategorysoloambient
Listen the volume
return StreamBuilder(
stream: assetsAudioPlayer.volume,
builder: (context, asyncSnapshot) {
final double volume = asyncSnapshot.data;
return Text("volume : $volume");
}),
or use a PlayerBuilder !
PlayerBuilder.volume(
player: _assetsAudioPlayer,
builder: (context, volume) {
return Text("volume : $volume");
}
)
โ Finished
Called when the current song has finished to play,
it gives the Playing audio that just finished
assetsAudioPlayer.playlistAudioFinished //ValueObservable<Playing>
assetsAudioPlayer.playlistAudioFinished.listen((Playing playing){
})
Called when the complete playlist has finished to play
assetsAudioPlayer.playlistFinished //ValueObservable<bool>
assetsAudioPlayer.playlistFinished.listen((finished){
})
๐ Looping
final LoopMode loopMode = assetsAudioPlayer.loop;
// possible values
// LoopMode.none : not looping
// LoopMode.single : looping a single audio
// LoopMode.playlist : looping the fyll playlist
assetsAudioPlayer.setLoopMode(LoopMode.single);
assetsAudioPlayer.loopMode.listen((loopMode){
//listen to loop
})
assetsAudioPlayer.toggleLoop(); //toggle the value of looping
๐ Play Speed
assetsAudioPlayer.setPlaySpeed(1.5);
assetsAudioPlayer.playSpeed.listen((playSpeed){
//listen to playSpeed
})
//change play speed for a particular Audio
Audio audio = Audio.network(
url,
playSpeed: 1.5
);
assetsAudioPlayer.open(audio);
๐๏ธ Pitch
assetsAudioPlayer.setPitch(1.2);
assetsAudioPlayer.pitch.listen((pitch){
//listen to pitch
})
//change pitch for a particular Audio
Audio audio = Audio.network(
url,
pitch: 1.2
);
assetsAudioPlayer.open(audio);
Error Handling
By default, on playing error, it stop the audio
BUT you can add a custom behavior
_player.onErrorDo = (handler){
handler.player.stop();
};
Open another audio
_player.onErrorDo = (handler){
handler.player.open(ANOTHER_AUDIO);
};
Try to open again on same position
_player.onErrorDo = (handler){
handler.player.open(
handler.playlist.copyWith(
startIndex: handler.playlistIndex
),
seek: handler.currentPosition
);
};
Network Policies (android/iOS/macOS)
Android only allow HTTPS calls, you will have an error if you're using HTTP,
don't forget to add INTERNET permission and seet usesCleartextTraffic="true"
in your AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
<uses-permission android:name="android.permission.INTERNET" />
<application
...
android:usesCleartextTraffic="true"
...>
...
</application>
</manifest>
iOS only allow HTTPS calls, you will have an error if you're using HTTP,
don't forget to edit your info.plist and set NSAppTransportSecurity
to NSAllowsArbitraryLoads
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
To enable http calls on macOs, you have to add input/output calls capabilities into info.plist
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
<key>UIBackgroundModes</key>
<array>
<string>audio</string>
<string>fetch</string>
</array>
<key>com.apple.security.network.client</key>
<true/>
and in your
Runner/DebugProfile.entitlements
add
<key>com.apple.security.network.client</key>
<true/>
Complete Runner/DebugProfile.entitlements
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.cs.allow-jit</key>
<true/>
<key>com.apple.security.network.server</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
</dict>
</plist>
๐ถ Musics
All musics used in the samples came from https://www.freemusicarchive.org/