on_audio_query
on_audio_query is a Flutter Plugin used to query audios/songs
Help:
Any problem? Issues
Any suggestion? Pull request
Extensions:
- on_audio_edit - Used to edit audio metadata.
- on_audio_room - Used to store audio [Favorites, Most Played, etc..].
Translations:
NOTE: Feel free to help with readme translations
Topics:
Platforms:
| Methods | Android | IOS | Web |
|---|---|---|---|
querySongs |
✔️ |
✔️ |
✔️ |
queryAlbums |
✔️ |
✔️ |
✔️ |
queryArtists |
✔️ |
✔️ |
✔️ |
queryPlaylists |
✔️ |
✔️ |
❌ |
queryGenres |
✔️ |
✔️ |
✔️ |
queryAudiosFrom |
✔️ |
✔️ |
✔️ |
queryWithFilters |
✔️ |
✔️ |
✔️ |
queryArtwork |
✔️ |
✔️ |
✔️ |
createPlaylist |
✔️ |
✔️ |
❌ |
removePlaylist |
✔️ |
❌ |
❌ |
addToPlaylist |
✔️ |
✔️ |
❌ |
removeFromPlaylist |
✔️ |
❌ |
❌ |
renamePlaylist |
✔️ |
❌ |
❌ |
moveItemTo |
✔️ |
❌ |
❌ |
permissionsRequest |
✔️ |
✔️ |
❌ |
permissionsStatus |
✔️ |
✔️ |
❌ |
queryDeviceInfo |
✔️ |
✔️ |
✔️ |
See all platforms methods support
How to Install:
Add the following code to your pubspec.yaml:
dependencies:
on_audio_query: ^2.5.3
Request Permission:
Android:
To use this plugin add the following code to your AndroidManifest.xml
<manifest> ...
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
</manifest>
IOS:
To use this plugin add the following code to your Info.plist
<key>NSAppleMusicUsageDescription</key>
<string>..Add a reason..</string>
Web:
Since Web Browsers don't offer direct access to their user's file system, this plugin will use the assets folder to "query" the audios files. So, will totally depend of the developer.
# You don't need add every audio file path, just define the folder.
assets:
- assets/
# If your files are in another folder inside the `assets`:
- assets/audios/
# - assets/audios/animals/
# - assets/audios/animals/cat/
# ...
Some Features:
- Optional and Built-in storage
READandWRITEpermission request - Get all audios/songs.
- Get all albums and album-specific audios.
- Get all artists and artist-specific audios.
- Get all playlists and playlists-specific audios.
- Get all genres and genres-specific audios.
- Get all query methods with specific
keys[Search]. - Create/Delete/Rename playlists.
- Add/Remove/Move specific audios to playlists.
- Specific sort types for all query methods.
TODO:
- Add better performance for all plugin.
- Add support to Windows/MacOs/Linux.
- Option to remove songs.
- Fix bugs.
How to use:
OnAudioQuery() // The main method to start using the plugin.
All types of methods on this plugin:
Query methods
| Methods | Parameters | Return |
|---|---|---|
querySongs |
(SortType, OrderType, UriType, RequestPermission) |
List<SongModel> |
queryAlbums |
(SortType, OrderType, UriType, RequestPermission) |
List<AlbumModel> |
queryArtists |
(SortType, OrderType, UriType, RequestPermission) |
List<ArtistModel> |
queryPlaylists |
(SortType, OrderType, UriType, RequestPermission) |
List<PlaylistModel> |
queryGenres |
(SortType, OrderType, UriType, RequestPermission) |
List<GenreModel> |
queryAudiosFrom |
(Type, Where, RequestPermission) |
List<SongModel> |
queryWithFilters |
(ArgsVal, WithFiltersType, Args, RequestPermission) |
List<dynamic> |
queryArtwork |
(Id, Type, Format, Size, RequestPermission) |
Uint8List? |
Playlist methods
| Methods | Parameters | Return |
|---|---|---|
createPlaylist |
(PlaylistName, RequestPermission) |
bool |
removePlaylist |
(PlaylistId, RequestPermission) |
bool |
addToPlaylist |
[BG](PlaylistId, AudioId, RequestPermission) |
bool |
removeFromPlaylist |
(PlaylistId, AudioId, RequestPermission) |
bool |
renamePlaylist |
(PlaylistId, NewName, RequestPermission) |
bool |
moveItemTo |
[NT](PlaylistId, From, To, RequestPermission) |
bool |
Permissions/Device methods
| Methods | Parameters | Return |
|---|---|---|
permissionsRequest |
(retryRequest) |
bool |
permissionsStatus |
bool |
|
queryDeviceInfo |
DeviceModel |
Artwork Widget
Widget someOtherName() async {
return QueryArtworkWidget(
id: SongId,
type: ArtworkType.AUDIO,
);
}
See more: QueryArtworkWidget
Abbreviations
[NT] -> Need Tests
[BG] -> Bug on Android 10/Q
Examples:
OnAudioQuery
final OnAudioQuery _audioQuery = OnAudioQuery();
querySongs
someName() async {
// DEFAULT:
// SongSortType.TITLE,
// OrderType.ASC_OR_SMALLER,
// UriType.EXTERNAL,
List<SongModel> something = await _audioQuery.querySongs();
}
queryAlbums
someName() async {
// DEFAULT:
// AlbumSortType.ALBUM,
// OrderType.ASC_OR_SMALLER
List<AlbumModel> something = await _audioQuery.queryAlbums();
}
queryArtists
someName() async {
// DEFAULT:
// ArtistSortType.ARTIST,
// OrderType.ASC_OR_SMALLER
List<ArtistModel> something = await _audioQuery.queryArtists();
}
queryPlaylists
someName() async {
// DEFAULT:
// PlaylistSortType.NAME,
// OrderType.ASC_OR_SMALLER
List<PlaylistModel> something = await _audioQuery.queryPlaylists();
}
queryGenres
someName() async {
// DEFAULT:
// GenreSortType.NAME,
// OrderType.ASC_OR_SMALLER
List<GenreModel> something = await _audioQuery.queryGenres();
}
queryArtwork
someName() async {
// DEFAULT: ArtworkFormat.JPEG, 200 and false
Uint8List something = await _audioQuery.queryArtwork(
SongId,
ArtworkType.AUDIO,
...,
);
}
Or you can use a basic and custom Widget. See example QueryArtworkWidget
queryAudiosFrom
You can use this method to 'query' the songs from any section(Album, Artist, Playlist or Genre).
someName() async {
List<SongModel> something = await _audioQuery.queryAudiosFrom(
AudiosFromType.ALBUM_ID,
albumId,
// You can also define a sortType
sortType: SongSortType.TITLE, // Default
orderType: OrderType.ASC_OR_SMALLER, // Default
);
}
queryWithFilters
someName() async {
// Here we'll search for a [song](WithFiltersType.AUDIOS) using his
// [artist](AudiosArgs.ARTIST)
List<dynamic> something = await _audioQuery.queryWithFilters(
// The [text] to search
"Sam Smith",
// The type of search you want.
// All types:
// * WithFiltersType.AUDIOS
// * WithFiltersType.ALBUMS
// * WithFiltersType.PLAYLISTS
// * WithFiltersType.ARTISTS
// * WithFiltersType.GENRES
WithFiltersType.AUDIOS,
// This method has [args] as parameter. With this value you can create
// a more 'advanced' search.
args: AudiosArgs.ARTIST,
);
// Other example:
// Here we'll search for a [song](WithFiltersType.AUDIOS) using his
// [album](AudiosArgs.ALBUM)
List<dynamic> something = await _audioQuery.queryWithFilters(
// The [text] to search
"In the Lonely Hour",
// The type of search you want.
// All types:
// * WithFiltersType.AUDIOS
// * WithFiltersType.ALBUMS
// * WithFiltersType.PLAYLISTS
// * WithFiltersType.ARTISTS
// * WithFiltersType.GENRES
WithFiltersType.AUDIOS,
// This method has [args] as parameter. With this value you can create
// a more 'advanced' search.
args: AudiosArgs.ALBUM,
);
// After getting the result from [queryWithFilters], convert this list using:
List<TypeModel> convertedList = something.toTypeModel();
// Example:
List<SongModel> convertedSongs = something.toSongModel();
}
ArgsTypes: AudiosArgs, AlbumsArgs, PlaylistsArgs, ArtistsArgs and GenresArgs
Gif Examples:
 |
 |
 |
 |
|---|---|---|---|
 |
 |
 |
 |
| Songs | Albums | Playlists | Artists |
88 Aug 1, 2022
2 Oct 13, 2022
261 Dec 11, 2022
5 Feb 5, 2022
11 Dec 16, 2022
30 Dec 28, 2022
4 Apr 6, 2021
38 Dec 25, 2022
300 Dec 8, 2022
1 Jan 9, 2022
4 Oct 17, 2022
20 Nov 1, 2022
224 Dec 21, 2022
3 Apr 1, 2021
3 Mar 16, 2022
2 Nov 15, 2022
6 Oct 23, 2022
51 Dec 13, 2021
8 Nov 26, 2022