on_audio_query

Pub.dev Platforms Languages

on_audio_query is a Flutter Plugin used to query audios/songs 🎶 infos title, artist, album, etc.. from device storage.

Help:

Any problem? Issues
Any suggestion? Pull request

Extensions:

Translations:

NOTE: Feel free to help with readme translations

Topics:

Platforms:

MethodsAndroidIOSWeb
querySongs✔️✔️✔️
queryAlbums✔️✔️✔️
queryArtists✔️✔️✔️
queryPlaylists✔️✔️
queryGenres✔️✔️✔️
queryAudiosFrom✔️✔️✔️
queryWithFilters✔️✔️✔️
queryArtwork✔️✔️✔️
createPlaylist✔️✔️
removePlaylist✔️
addToPlaylist✔️✔️
removeFromPlaylist✔️
renamePlaylist✔️
moveItemTo✔️
permissionsRequest✔️✔️
permissionsStatus✔️✔️
queryDeviceInfo✔️✔️✔️

✔️ -> Supported
❌ -> Not Supported

See all platforms methods support

How to Install:

Add the following code to your pubspec.yaml:

dependencies:
  on_audio_query: ^2.5.2

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 READ and WRITE permission 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

MethodsParametersReturn
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

MethodsParametersReturn
createPlaylist(PlaylistName, RequestPermission)bool
removePlaylist(PlaylistId, RequestPermission)bool
addToPlaylistBG(PlaylistId, AudioId, RequestPermission)bool
removeFromPlaylist(PlaylistId, AudioId, RequestPermission)bool
renamePlaylist(PlaylistId, NewName, RequestPermission)bool
moveItemToNT(PlaylistId, From, To, RequestPermission)bool

Permissions/Device methods

MethodsParametersReturn
permissionsRequest(retryRequest)bool
permissionsStatusbool
queryDeviceInfoDeviceModel

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:

SongsAlbumsPlaylistsArtists

LICENSE:

Libraries

on_audio_query