on_audio_query 2.6.1

Flutter Plugin used to query audios/songs infos [title, artist, album, etc..] from device storage.

on_audio_query

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:

• 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

• English
• Portuguese

Topics:

• How to Install
• Platforms
• How to use
• Examples
• Gif Examples
• License

Platforms:

Methods	Android	IOS	Web
querySongs	✔️	✔️	✔️
queryAlbums	✔️	✔️	✔️
queryArtists	✔️	✔️	✔️
queryPlaylists	✔️	✔️	❌
queryGenres	✔️	✔️	✔️
queryAudiosFrom	✔️	✔️	✔️
queryWithFilters	✔️	✔️	✔️
queryArtwork	✔️	✔️	✔️
createPlaylist	✔️	✔️	❌
removePlaylist	✔️	❌	❌
addToPlaylist	✔️	✔️	❌
removeFromPlaylist	✔️	❌	❌
renamePlaylist	✔️	❌	❌
moveItemTo	✔️	❌	❌
permissionsRequest	✔️	✔️	❌
permissionsStatus	✔️	✔️	❌
queryDeviceInfo	✔️	✔️	✔️
scanMedia	✔️	❌	❌

✔️ -> Supported
❌ -> Not Supported

See all platforms methods support

How to Install:

Add the following code to your pubspec.yaml:

dependencies:
  on_audio_query: ^2.6.0

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

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

Others methods

Methods	Parameters	Return
scanMedia	(Path)	bool

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();
  }

scanMedia

You'll use this method when updating a media from storage. This method will update the media 'state' and Android MediaStore will be able to know this 'state'.

  someName() async {
    OnAudioQuery _audioQuery = OnAudioQuery();
    File file = File('path');
    try {
      if (file.existsSync()) {
        file.deleteSync();
        _audioQuery.scanMedia(file.path); // Scan the media 'path'
      }
    } catch (e) {
      debugPrint('$e');
    }
  }

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

LICENSE:

• LICENSE

• Back to top