Skip to content

Commit 542489f

Browse files
LucJosinLucJosin
authored
Update 2.7.0 (#105)
1 parent 740d3b6 commit 542489f

File tree

72 files changed

+2082
-2289
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+2082
-2289
lines changed

‎on_audio_query/CHANGELOG.md

Lines changed: 102 additions & 62 deletions
Large diffs are not rendered by default.

‎on_audio_query/README.md

Lines changed: 46 additions & 188 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,22 @@
1+
<div align=center>
2+
13
# on_audio_query
24
[![Pub.dev](https://img.shields.io/pub/v/on_audio_query?color=9cf&label=Pub.dev&style=flat-square)](https://pub.dev/packages/on_audio_query)
35
[![Platforms](https://img.shields.io/badge/Platforms-Android%20%7C%20IOS%20%7C%20Web-9cf?&style=flat-square)]()
46
[![Languages](https://img.shields.io/badge/Languages-Dart%20%7C%20Kotlin%20%7C%20Swift-9cf?&style=flat-square)]()
57

68
`on_audio_query` is a [Flutter](https://flutter.dev/) Plugin used to query audios/songs 🎶 infos [title, artist, album, etc..] from device storage. <br>
79

8-
## Help:
9-
1010
**Any problem? [Issues](https://github.com/LucJosin/on_audio_query/issues)** <br>
1111
**Any suggestion? [Pull request](https://github.com/LucJosin/on_audio_query/pulls)**
1212

13-
### Extensions:
14-
15-
* [on_audio_edit](https://github.com/LucJosin/on_audio_edit) - Used to edit audio metadata.
16-
* [on_audio_room](https://github.com/LucJosin/on_audio_room) - Used to store audio [Favorites, Most Played, etc..].
17-
18-
### Translations:
19-
20-
NOTE: Feel free to help with readme translations
21-
22-
* [English](https://github.com/LucJosin/on_audio_query/blob/main/on_audio_query/README.md)
23-
* [Portuguese](https://github.com/LucJosin/on_audio_query/blob/main/on_audio_query/README.pt-BR.md)
13+
</div>
2414

2515
### Topics:
2616

27-
* [How to Install](#how-to-install)
17+
* [Installation](#installation)
2818
* [Platforms](#platforms)
29-
* [How to use](#how-to-use)
19+
* [Overview](#overview)
3020
* [Examples](#examples)
3121
* [Gif Examples](#gif-examples)
3222
* [License](#license)
@@ -60,30 +50,44 @@ NOTE: Feel free to help with readme translations
6050

6151
**[See all platforms methods support](https://github.com/LucJosin/on_audio_query/blob/main/on_audio_query/PLATFORMS.md)**
6252

63-
## How to Install:
53+
## Installation:
54+
6455
Add the following code to your `pubspec.yaml`:
6556
```yaml
6657
dependencies:
67-
on_audio_query: ^2.6.0
58+
on_audio_query: ^2.7.0
6859
```
6960
7061
### Request Permission:
62+
7163
#### Android:
72-
To use this plugin add the following code to your `AndroidManifest.xml`
64+
To use this plugin add the following code to your [AndroidManifest.xml](https://github.com/LucJosin/on_audio_query/blob/main/on_audio_query/example/android/app/src/main/AndroidManifest.xml)
7365
```xml
74-
<manifest> ...
75-
76-
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
66+
<manifest>
67+
68+
<!-- Android 12 or below -->
7769
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
70+
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
71+
72+
<!-- Android 13 or greater -->
73+
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES"/>
74+
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO"/>
75+
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO"/>
7876

7977
</manifest>
8078
```
8179

8280
#### IOS:
83-
To use this plugin add the following code to your `Info.plist`
84-
```
81+
To use this plugin add the following code to your [Info.plist](https://github.com/LucJosin/on_audio_query/blob/main/on_audio_query/example/ios/Runner/Info.plist)
82+
```plist
83+
<dict>
84+
...
85+
8586
<key>NSAppleMusicUsageDescription</key>
86-
<string>..Add a reason..</string>
87+
<string>$(PROJECT_NAME) requires access to media library</string>
88+
89+
...
90+
</dict>
8791
```
8892

8993
#### Web:
@@ -113,136 +117,54 @@ Since Web Browsers **don't** offer direct access to their user's `file system`,
113117
* Add/Remove/Move specific audios to playlists.
114118
* Specific sort types for all query methods.
115119

116-
## TODO:
120+
## Overview:
117121

118-
* Add better performance for all plugin.
119-
* Add support to Windows/MacOs/Linux.
120-
* Option to remove songs.
121-
* Fix bugs.
122-
123-
## How to use:
124-
125-
```dart
126-
OnAudioQuery() // The main method to start using the plugin.
127-
```
128122
All types of methods on this plugin:
129123

130-
### Query methods
131-
132-
| Methods | Parameters | Return |
133-
|--------------|-----------------|-----------------|
134-
| [`querySongs`](#querysongs) | `(SortType, OrderType, UriType, RequestPermission)` | `List<SongModel>` | <br>
135-
| [`queryAlbums`](#queryalbums) | `(SortType, OrderType, UriType, RequestPermission)` | `List<AlbumModel>` | <br>
136-
| [`queryArtists`](#queryartists) | `(SortType, OrderType, UriType, RequestPermission)` | `List<ArtistModel>` | <br>
137-
| [`queryPlaylists`](#queryplaylists) | `(SortType, OrderType, UriType, RequestPermission)` | `List<PlaylistModel>` | <br>
138-
| [`queryGenres`](#querygenres) | `(SortType, OrderType, UriType, RequestPermission)` | `List<GenreModel>` | <br>
139-
| [`queryAudiosFrom`](#queryaudiosfrom) | `(Type, Where, RequestPermission)` | `List<SongModel>` | <br>
140-
| [`queryWithFilters`](#querywithfilters) | `(ArgsVal, WithFiltersType, Args, RequestPermission)` | `List<dynamic>` | <br>
141-
| [`queryArtwork`](#queryArtwork) | `(Id, Type, Format, Size, RequestPermission)` | `Uint8List?` | <br>
142-
143-
### Playlist methods
144-
145-
| Methods | Parameters | Return |
146-
|--------------|-----------------|-----------------|
147-
| [`createPlaylist`]() | `(PlaylistName, RequestPermission)` | `bool` | <br>
148-
| [`removePlaylist`]() | `(PlaylistId, RequestPermission)` | `bool` | <br>
149-
| [`addToPlaylist`]() | **[BG]**`(PlaylistId, AudioId, RequestPermission)` | `bool` | <br>
150-
| [`removeFromPlaylist`]() | `(PlaylistId, AudioId, RequestPermission)` | `bool` | <br>
151-
| [`renamePlaylist`]() | `(PlaylistId, NewName, RequestPermission)` | `bool` | <br>
152-
| [`moveItemTo`]() | **[NT]**`(PlaylistId, From, To, RequestPermission)` | `bool` | <br>
153-
154-
### Permissions/Device methods
155-
156-
| Methods | Parameters | Return |
157-
|--------------|-----------------|-----------------|
158-
| [`permissionsRequest`]() | `(retryRequest)` | `bool` | <br>
159-
| [`permissionsStatus`]() | | `bool` | <br>
160-
| [`queryDeviceInfo`]() | | `DeviceModel` | <br>
161-
162-
### Others methods
163-
| Methods | Parameters | Return |
164-
|--------------|-----------------|-----------------|
165-
| [`scanMedia`](#scanmedia) | `(Path)` | `bool` | <br>
166-
167124
### Artwork Widget
168125

169126
```dart
170127
Widget someOtherName() async {
171128
return QueryArtworkWidget(
172-
id: SongId,
129+
id: <audioId>,
173130
type: ArtworkType.AUDIO,
174131
);
175132
}
176133
```
177134

178135
**See more: [QueryArtworkWidget](https://pub.dev/documentation/on_audio_query/latest/on_audio_query/QueryArtworkWidget-class.html)**
179136

180-
### Abbreviations
181-
182-
**[NT]** -> Need Tests <br>
183-
**[BG]** -> Bug on Android 10/Q
184-
185137
## Examples:
186138

187139
#### OnAudioQuery
188-
```dart
189-
final OnAudioQuery _audioQuery = OnAudioQuery();
190-
```
191140

192-
#### querySongs
193141
```dart
194-
someName() async {
195-
// DEFAULT:
196-
// SongSortType.TITLE,
197-
// OrderType.ASC_OR_SMALLER,
198-
// UriType.EXTERNAL,
199-
List<SongModel> something = await _audioQuery.querySongs();
200-
}
142+
final OnAudioQuery _audioQuery = OnAudioQuery();
201143
```
202144

203-
#### queryAlbums
204-
```dart
205-
someName() async {
206-
// DEFAULT:
207-
// AlbumSortType.ALBUM,
208-
// OrderType.ASC_OR_SMALLER
209-
List<AlbumModel> something = await _audioQuery.queryAlbums();
210-
}
211-
```
145+
#### Query methods:
212146

213-
#### queryArtists
214-
```dart
215-
someName() async {
216-
// DEFAULT:
217-
// ArtistSortType.ARTIST,
218-
// OrderType.ASC_OR_SMALLER
219-
List<ArtistModel> something = await _audioQuery.queryArtists();
220-
}
221-
```
147+
- queryAudios();
148+
- queryAlbums();
149+
- queryArtists();
150+
- queryPlaylists();
151+
- queryGenres().
222152

223-
#### queryPlaylists
224153
```dart
225154
someName() async {
226-
// DEFAULT:
227-
// PlaylistSortType.NAME,
228-
// OrderType.ASC_OR_SMALLER
229-
List<PlaylistModel> something = await _audioQuery.queryPlaylists();
230-
}
231-
```
155+
// Query Audios
156+
List<AudioModel> audios = await _audioQuery.queryAudios();
232157
233-
#### queryGenres
234-
```dart
235-
someName() async {
236-
// DEFAULT:
237-
// GenreSortType.NAME,
238-
// OrderType.ASC_OR_SMALLER
239-
List<GenreModel> something = await _audioQuery.queryGenres();
158+
// Query Albums
159+
List<AlbumModel> albums = await _audioQuery.queryAlbums();
240160
}
241161
```
242162

243163
#### scanMedia
164+
244165
You'll use this method when updating a media from storage. This method will update the media 'state' and
245166
Android `MediaStore` will be able to know this 'state'.
167+
246168
```dart
247169
someName() async {
248170
OnAudioQuery _audioQuery = OnAudioQuery();
@@ -259,12 +181,13 @@ Android `MediaStore` will be able to know this 'state'.
259181
```
260182

261183
#### queryArtwork
184+
262185
```dart
263186
someName() async {
264187
// DEFAULT: ArtworkFormat.JPEG, 200 and false
265188
Uint8List something = await _audioQuery.queryArtwork(
266-
SongId,
267-
ArtworkType.AUDIO,
189+
<audioId>,
190+
ArtworkType.AUDIO,
268191
...,
269192
);
270193
}
@@ -273,71 +196,6 @@ Android `MediaStore` will be able to know this 'state'.
273196
Or you can use a basic and custom Widget.
274197
**See example [QueryArtworkWidget](#artwork-widget)**
275198

276-
#### queryAudiosFrom
277-
You can use this method to 'query' the songs from any section(Album, Artist, Playlist or Genre).
278-
```dart
279-
someName() async {
280-
List<SongModel> something = await _audioQuery.queryAudiosFrom(
281-
AudiosFromType.ALBUM_ID,
282-
albumId,
283-
// You can also define a sortType
284-
sortType: SongSortType.TITLE, // Default
285-
orderType: OrderType.ASC_OR_SMALLER, // Default
286-
);
287-
}
288-
```
289-
290-
#### queryWithFilters
291-
```dart
292-
someName() async {
293-
// Here we'll search for a [song](WithFiltersType.AUDIOS) using his
294-
// [artist](AudiosArgs.ARTIST)
295-
List<dynamic> something = await _audioQuery.queryWithFilters(
296-
// The [text] to search
297-
"Sam Smith",
298-
// The type of search you want.
299-
// All types:
300-
// * WithFiltersType.AUDIOS
301-
// * WithFiltersType.ALBUMS
302-
// * WithFiltersType.PLAYLISTS
303-
// * WithFiltersType.ARTISTS
304-
// * WithFiltersType.GENRES
305-
WithFiltersType.AUDIOS,
306-
// This method has [args] as parameter. With this value you can create
307-
// a more 'advanced' search.
308-
args: AudiosArgs.ARTIST,
309-
);
310-
311-
// Other example:
312-
313-
// Here we'll search for a [song](WithFiltersType.AUDIOS) using his
314-
// [album](AudiosArgs.ALBUM)
315-
List<dynamic> something = await _audioQuery.queryWithFilters(
316-
// The [text] to search
317-
"In the Lonely Hour",
318-
// The type of search you want.
319-
// All types:
320-
// * WithFiltersType.AUDIOS
321-
// * WithFiltersType.ALBUMS
322-
// * WithFiltersType.PLAYLISTS
323-
// * WithFiltersType.ARTISTS
324-
// * WithFiltersType.GENRES
325-
WithFiltersType.AUDIOS,
326-
// This method has [args] as parameter. With this value you can create
327-
// a more 'advanced' search.
328-
args: AudiosArgs.ALBUM,
329-
);
330-
331-
// After getting the result from [queryWithFilters], convert this list using:
332-
List<TypeModel> convertedList = something.toTypeModel();
333-
334-
// Example:
335-
List<SongModel> convertedSongs = something.toSongModel();
336-
}
337-
```
338-
339-
ArgsTypes: [AudiosArgs](https://pub.dev/documentation/on_audio_query_platform_interface/latest/on_audio_query_helper/AudiosArgs-class.html), [AlbumsArgs](https://pub.dev/documentation/on_audio_query_platform_interface/latest/on_audio_query_helper/AlbumsArgs-class.html), [PlaylistsArgs](https://pub.dev/documentation/on_audio_query_platform_interface/latest/on_audio_query_helper/PlaylistsArgs-class.html), [ArtistsArgs](https://pub.dev/documentation/on_audio_query_platform_interface/latest/on_audio_query_helper/ArtistsArgs-class.html) and [GenresArgs](https://pub.dev/documentation/on_audio_query_platform_interface/latest/on_audio_query_helper/GenresArgs-class.html)
340-
341199
## Gif Examples:
342200
| <img src="https://user-images.githubusercontent.com/76869974/129740857-33f38b27-06a3-4959-bb31-2ae97d6b66ff.gif"/> | <img src="https://user-images.githubusercontent.com/76869974/129741012-1215b292-d700-466f-9c41-552df0ad5e89.gif"/> | <img src="https://user-images.githubusercontent.com/76869974/129741188-e6803432-24d7-4e39-bfde-cc6765e13663.gif"/> | <img src="https://user-images.githubusercontent.com/76869974/129741151-b820edc9-ddbf-4446-b67a-6e254cb5a46d.gif"/> |
343201
|:---:|:---:|:---:|:---:|

0 commit comments

Comments
 (0)