react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.56
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -19
- package/lib/commonjs/CLAUDE.md +7 -2
- package/lib/commonjs/features/battery.js +16 -12
- package/lib/commonjs/features/battery.js.map +1 -1
- package/lib/commonjs/features/browser-config.js +1 -1
- package/lib/commonjs/features/browser.js +74 -24
- package/lib/commonjs/features/browser.js.map +1 -1
- package/lib/commonjs/features/carConnection.js +3 -4
- package/lib/commonjs/features/carConnection.js.map +1 -1
- package/lib/commonjs/features/equalizer.js +9 -5
- package/lib/commonjs/features/equalizer.js.map +1 -1
- package/lib/commonjs/features/errors.js +35 -21
- package/lib/commonjs/features/errors.js.map +1 -1
- package/lib/commonjs/features/favorites.js +15 -13
- package/lib/commonjs/features/favorites.js.map +1 -1
- package/lib/commonjs/features/gate.js +12 -6
- package/lib/commonjs/features/gate.js.map +1 -1
- package/lib/commonjs/features/metadata.js +16 -14
- package/lib/commonjs/features/metadata.js.map +1 -1
- package/lib/commonjs/features/network.js +5 -1
- package/lib/commonjs/features/network.js.map +1 -1
- package/lib/commonjs/features/nowPlaying.js +28 -14
- package/lib/commonjs/features/nowPlaying.js.map +1 -1
- package/lib/commonjs/features/output.js +8 -4
- package/lib/commonjs/features/output.js.map +1 -1
- package/lib/commonjs/features/playback/controls.js +10 -5
- package/lib/commonjs/features/playback/controls.js.map +1 -1
- package/lib/commonjs/features/playback/playWhenReady.js +6 -5
- package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
- package/lib/commonjs/features/playback/playing.js +5 -3
- package/lib/commonjs/features/playback/playing.js.map +1 -1
- package/lib/commonjs/features/playback/progress.js +11 -5
- package/lib/commonjs/features/playback/progress.js.map +1 -1
- package/lib/commonjs/features/playback/state.js +3 -3
- package/lib/commonjs/features/playback/state.js.map +1 -1
- package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
- package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
- package/lib/commonjs/features/playback/volume.js +6 -5
- package/lib/commonjs/features/playback/volume.js.map +1 -1
- package/lib/commonjs/features/player/options.js +20 -10
- package/lib/commonjs/features/player/options.js.map +1 -1
- package/lib/commonjs/features/player/setup.js +34 -38
- package/lib/commonjs/features/player/setup.js.map +1 -1
- package/lib/commonjs/features/queue/activeTrack.js +0 -1
- package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
- package/lib/commonjs/features/queue/queue.js +48 -20
- package/lib/commonjs/features/queue/queue.js.map +1 -1
- package/lib/commonjs/features/queue/repeatMode.js +2 -1
- package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
- package/lib/commonjs/features/queue/shuffle.js +0 -1
- package/lib/commonjs/features/queue/shuffle.js.map +1 -1
- package/lib/commonjs/features/remoteControls.js +59 -35
- package/lib/commonjs/features/remoteControls.js.map +1 -1
- package/lib/commonjs/features/sleepTimer.js +15 -6
- package/lib/commonjs/features/sleepTimer.js.map +1 -1
- package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
- package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
- package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
- package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
- package/lib/commonjs/utils/getTrackIdentity.js +6 -4
- package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
- package/lib/commonjs/utils/useDebug.js +16 -3
- package/lib/commonjs/utils/useDebug.js.map +1 -1
- package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
- package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
- package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
- package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
- package/lib/commonjs/web/browser/sections.js +1 -1
- package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
- package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
- package/lib/module/CLAUDE.md +7 -2
- package/lib/module/features/battery.js +16 -12
- package/lib/module/features/battery.js.map +1 -1
- package/lib/module/features/browser-config.js +1 -1
- package/lib/module/features/browser.js +74 -24
- package/lib/module/features/browser.js.map +1 -1
- package/lib/module/features/carConnection.js +3 -4
- package/lib/module/features/carConnection.js.map +1 -1
- package/lib/module/features/equalizer.js +9 -5
- package/lib/module/features/equalizer.js.map +1 -1
- package/lib/module/features/errors.js +35 -21
- package/lib/module/features/errors.js.map +1 -1
- package/lib/module/features/favorites.js +15 -13
- package/lib/module/features/favorites.js.map +1 -1
- package/lib/module/features/gate.js +12 -6
- package/lib/module/features/gate.js.map +1 -1
- package/lib/module/features/metadata.js +16 -14
- package/lib/module/features/metadata.js.map +1 -1
- package/lib/module/features/network.js +5 -1
- package/lib/module/features/network.js.map +1 -1
- package/lib/module/features/nowPlaying.js +28 -14
- package/lib/module/features/nowPlaying.js.map +1 -1
- package/lib/module/features/output.js +8 -4
- package/lib/module/features/output.js.map +1 -1
- package/lib/module/features/playback/controls.js +10 -5
- package/lib/module/features/playback/controls.js.map +1 -1
- package/lib/module/features/playback/playWhenReady.js +6 -5
- package/lib/module/features/playback/playWhenReady.js.map +1 -1
- package/lib/module/features/playback/playing.js +5 -3
- package/lib/module/features/playback/playing.js.map +1 -1
- package/lib/module/features/playback/progress.js +11 -5
- package/lib/module/features/playback/progress.js.map +1 -1
- package/lib/module/features/playback/state.js +3 -3
- package/lib/module/features/playback/state.js.map +1 -1
- package/lib/module/features/playback/trackPlaybackTime.js +6 -1
- package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
- package/lib/module/features/playback/volume.js +6 -5
- package/lib/module/features/playback/volume.js.map +1 -1
- package/lib/module/features/player/options.js +20 -10
- package/lib/module/features/player/options.js.map +1 -1
- package/lib/module/features/player/setup.js +34 -38
- package/lib/module/features/player/setup.js.map +1 -1
- package/lib/module/features/queue/activeTrack.js +0 -1
- package/lib/module/features/queue/activeTrack.js.map +1 -1
- package/lib/module/features/queue/queue.js +48 -20
- package/lib/module/features/queue/queue.js.map +1 -1
- package/lib/module/features/queue/repeatMode.js +2 -1
- package/lib/module/features/queue/repeatMode.js.map +1 -1
- package/lib/module/features/queue/shuffle.js +0 -1
- package/lib/module/features/queue/shuffle.js.map +1 -1
- package/lib/module/features/remoteControls.js +59 -35
- package/lib/module/features/remoteControls.js.map +1 -1
- package/lib/module/features/sleepTimer.js +15 -6
- package/lib/module/features/sleepTimer.js.map +1 -1
- package/lib/module/utils/LazyNativeEmitter.js +6 -9
- package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
- package/lib/module/utils/NativeUpdatedValue.js +13 -12
- package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
- package/lib/module/utils/getTrackIdentity.js +6 -4
- package/lib/module/utils/getTrackIdentity.js.map +1 -1
- package/lib/module/utils/useDebug.js +16 -3
- package/lib/module/utils/useDebug.js.map +1 -1
- package/lib/module/web/NativeAudioBrowser.js +2 -4
- package/lib/module/web/NativeAudioBrowser.js.map +1 -1
- package/lib/module/web/browser/parseSearchResponse.js +3 -4
- package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
- package/lib/module/web/browser/sections.js +1 -1
- package/lib/module/web/util/BrowserPathHelper.js +1 -3
- package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
- package/lib/typescript/src/features/battery.d.ts +17 -12
- package/lib/typescript/src/features/battery.d.ts.map +1 -1
- package/lib/typescript/src/features/browser.d.ts +64 -24
- package/lib/typescript/src/features/browser.d.ts.map +1 -1
- package/lib/typescript/src/features/carConnection.d.ts +3 -4
- package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
- package/lib/typescript/src/features/equalizer.d.ts +9 -5
- package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
- package/lib/typescript/src/features/errors.d.ts +37 -22
- package/lib/typescript/src/features/errors.d.ts.map +1 -1
- package/lib/typescript/src/features/favorites.d.ts +15 -13
- package/lib/typescript/src/features/favorites.d.ts.map +1 -1
- package/lib/typescript/src/features/gate.d.ts +14 -8
- package/lib/typescript/src/features/gate.d.ts.map +1 -1
- package/lib/typescript/src/features/metadata.d.ts +37 -17
- package/lib/typescript/src/features/metadata.d.ts.map +1 -1
- package/lib/typescript/src/features/network.d.ts +5 -1
- package/lib/typescript/src/features/network.d.ts.map +1 -1
- package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
- package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
- package/lib/typescript/src/features/output.d.ts +8 -4
- package/lib/typescript/src/features/output.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/controls.d.ts +10 -5
- package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
- package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/playing.d.ts +16 -3
- package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/progress.d.ts +11 -5
- package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/state.d.ts +8 -3
- package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
- package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/volume.d.ts +6 -5
- package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
- package/lib/typescript/src/features/player/options.d.ts +52 -37
- package/lib/typescript/src/features/player/options.d.ts.map +1 -1
- package/lib/typescript/src/features/player/setup.d.ts +65 -60
- package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
- package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/queue.d.ts +48 -20
- package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
- package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
- package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
- package/lib/typescript/src/features/remoteControls.d.ts +58 -25
- package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
- package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
- package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
- package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
- package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
- package/lib/typescript/src/types/browser.d.ts +181 -144
- package/lib/typescript/src/types/browser.d.ts.map +1 -1
- package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
- package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
- package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
- package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
- package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
- package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
- package/lib/typescript/src/utils/useDebug.d.ts +16 -3
- package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/CLAUDE.md +7 -2
- package/src/docs-floors.test.ts +71 -0
- package/src/features/battery.ts +17 -13
- package/src/features/browser-config.ts +1 -1
- package/src/features/browser.ts +65 -24
- package/src/features/carConnection.ts +3 -4
- package/src/features/equalizer.ts +9 -5
- package/src/features/errors.ts +37 -22
- package/src/features/favorites.ts +15 -13
- package/src/features/gate.ts +14 -8
- package/src/features/metadata.ts +37 -17
- package/src/features/network.ts +5 -1
- package/src/features/nowPlaying.ts +28 -14
- package/src/features/output.ts +8 -4
- package/src/features/playback/controls.ts +10 -5
- package/src/features/playback/playWhenReady.ts +6 -5
- package/src/features/playback/playing.ts +16 -3
- package/src/features/playback/progress.ts +11 -5
- package/src/features/playback/state.ts +8 -3
- package/src/features/playback/trackPlaybackTime.ts +9 -2
- package/src/features/playback/volume.ts +6 -5
- package/src/features/player/options.ts +54 -43
- package/src/features/player/setup.ts +67 -61
- package/src/features/queue/activeTrack.ts +0 -1
- package/src/features/queue/queue.ts +48 -20
- package/src/features/queue/repeatMode.ts +1 -1
- package/src/features/queue/shuffle.ts +0 -1
- package/src/features/remoteControls.ts +59 -35
- package/src/features/sleepTimer.ts +15 -7
- package/src/types/browser-nodes.ts +54 -57
- package/src/types/browser.ts +183 -146
- package/src/utils/LazyNativeEmitter.ts +6 -9
- package/src/utils/NativeUpdatedValue.ts +13 -12
- package/src/utils/getTrackIdentity.ts +6 -4
- package/src/utils/useDebug.ts +16 -3
- package/src/web/NativeAudioBrowser.ts +2 -4
- package/src/web/browser/parseSearchResponse.ts +3 -4
- package/src/web/browser/sections.ts +1 -1
- package/src/web/util/BrowserPathHelper.ts +1 -3
- package/website/guide/android-auto.md +25 -13
- package/website/guide/android-certificates.md +199 -120
- package/website/guide/artwork.md +93 -48
- package/website/guide/audio-output.md +86 -68
- package/website/guide/automotive.md +15 -10
- package/website/guide/basic-usage.md +5 -2
- package/website/guide/battery.md +50 -23
- package/website/guide/browser.md +155 -68
- package/website/guide/carplay.md +132 -49
- package/website/guide/configuration.md +85 -49
- package/website/guide/equalizer.md +36 -32
- package/website/guide/errors.md +106 -64
- package/website/guide/favorites.md +41 -31
- package/website/guide/gate.md +24 -10
- package/website/guide/getting-started.md +55 -2
- package/website/guide/hooks.md +53 -47
- package/website/guide/live-streams.md +80 -49
- package/website/guide/metadata.md +87 -53
- package/website/guide/migrating-from-track-player.md +94 -49
- package/website/guide/native-callback-fetch.md +46 -36
- package/website/guide/network.md +36 -20
- package/website/guide/now-playing.md +72 -44
- package/website/guide/playback.md +112 -35
- package/website/guide/queue.md +77 -43
- package/website/guide/remote-controls.md +87 -29
- package/website/guide/search.md +37 -22
- package/website/guide/sleep-timer.md +35 -14
- package/website/guide/track.md +59 -35
package/website/guide/queue.md
CHANGED
|
@@ -5,7 +5,7 @@ description: 'Build and edit the queue, move between tracks with next and previo
|
|
|
5
5
|
# Queue
|
|
6
6
|
|
|
7
7
|
The **queue** is the ordered list of tracks the player works through. The track
|
|
8
|
-
at the current position is the **active track
|
|
8
|
+
at the current position is the **active track**: what plays, and what
|
|
9
9
|
next/previous move between. This guide covers building the queue, editing it,
|
|
10
10
|
moving between tracks, and reading it back for an "up next" UI.
|
|
11
11
|
|
|
@@ -26,21 +26,23 @@ Optionally pass which track to make active and where to start it:
|
|
|
26
26
|
```ts
|
|
27
27
|
import { setQueue, play } from 'react-native-audio-browser'
|
|
28
28
|
|
|
29
|
-
setQueue(tracks) // replace; first track becomes active
|
|
29
|
+
setQueue(tracks, 0) // replace; first track becomes active
|
|
30
30
|
setQueue(tracks, 2) // start on index 2
|
|
31
31
|
setQueue(tracks, 2, 30) // ...30 seconds in
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
On iOS and Android, `startIndex` defaults to 0. iOS clamps an index outside
|
|
35
|
+
the queue to its first or last track, and Android throws. On the web, an
|
|
36
|
+
omitted or out-of-range `startIndex` leaves no track active, so pass one (0 for
|
|
37
|
+
the first track).
|
|
35
38
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
So the usual "load these and play" is two calls:
|
|
39
|
+
`setQueue` doesn't start playback. On iOS and Android it keeps the current
|
|
40
|
+
play/pause state; on the web it stops playback. Either way, call
|
|
41
|
+
[`play()`](/api/features/playback/#play) after it (see
|
|
42
|
+
[Playback](/guide/playback)):
|
|
41
43
|
|
|
42
44
|
```ts
|
|
43
|
-
setQueue(tracks) // or setQueue(tracks, startIndex)
|
|
45
|
+
setQueue(tracks, 0) // or setQueue(tracks, startIndex)
|
|
44
46
|
play() // start playback
|
|
45
47
|
```
|
|
46
48
|
|
|
@@ -70,7 +72,12 @@ Outside React, read a snapshot with
|
|
|
70
72
|
[`getTrack(index)`](/api/features/queue/#gettrack) (returns `undefined` if the
|
|
71
73
|
index is empty). To react to changes without a hook, subscribe to
|
|
72
74
|
[`onQueueChanged`](/api/features/queue/#onqueuechanged) — it fires with the new
|
|
73
|
-
queue on every add, remove,
|
|
75
|
+
queue on every add, remove, or reorder.
|
|
76
|
+
|
|
77
|
+
A favorite toggle also fires it on iOS
|
|
78
|
+
and Android, but on web it fires only
|
|
79
|
+
[`onFavoriteChanged`](/api/features/favorites/#onfavoritechanged), so listen to
|
|
80
|
+
both, as `useQueue` does.
|
|
74
81
|
|
|
75
82
|
## The active track
|
|
76
83
|
|
|
@@ -116,6 +123,9 @@ skipToPrevious() // previous track
|
|
|
116
123
|
skipToNext(10) // next track, starting 10 seconds in
|
|
117
124
|
```
|
|
118
125
|
|
|
126
|
+
On iOS and Android, if there is no next (or previous) track, the position
|
|
127
|
+
still applies: the active track seeks to it. On the web the call does nothing.
|
|
128
|
+
|
|
119
129
|
This is how you move _between_ tracks
|
|
120
130
|
([`skip`](/api/features/queue/#skip),
|
|
121
131
|
[`skipToNext`](/api/features/queue/#skiptonext),
|
|
@@ -144,7 +154,8 @@ add(track) // append one track (also accepts a Track[])
|
|
|
144
154
|
add(track, 0) // insert before index 0 (front of the queue)
|
|
145
155
|
|
|
146
156
|
move(4, 1) // move index 4 to index 1
|
|
147
|
-
// toIndex past the end moves the track to the end
|
|
157
|
+
// On iOS and Android, toIndex past the end moves the track to the end;
|
|
158
|
+
// the web throws.
|
|
148
159
|
|
|
149
160
|
remove(2) // remove index 2 (also accepts number[])
|
|
150
161
|
removeUpcomingTracks() // drop everything after the active track
|
|
@@ -162,19 +173,32 @@ const i = getActiveTrackIndex()
|
|
|
162
173
|
add(track, i === undefined ? 0 : i + 1)
|
|
163
174
|
```
|
|
164
175
|
|
|
165
|
-
|
|
166
|
-
|
|
176
|
+
With shuffle on, the inserted track goes to a random place in the shuffle
|
|
177
|
+
order, so it may not play next.
|
|
178
|
+
|
|
179
|
+
**Removing the active track** makes the track after it active. On iOS and the
|
|
180
|
+
web that is the next index, wrapping to the first track, and playback carries
|
|
181
|
+
on.
|
|
182
|
+
|
|
183
|
+
On Android it is the next track in playback order, with shuffle and repeat
|
|
184
|
+
applied. If you remove the last track there, the first track becomes active,
|
|
185
|
+
and with repeat `'off'` playback ends.
|
|
186
|
+
|
|
187
|
+
With several indexes, Android checks them all first and throws on a repeated
|
|
188
|
+
one. iOS removes from the highest index down. A repeated index then also removes
|
|
189
|
+
the track that moved into its place, and an invalid index can throw after some
|
|
190
|
+
tracks are already gone. Pass each index once.
|
|
167
191
|
|
|
168
192
|
## Repeat and shuffle
|
|
169
193
|
|
|
170
|
-
[Repeat mode](/api/features/queue/#
|
|
194
|
+
[Repeat mode](/api/features/queue/#repeatmode) is one of `'off'`, `'track'`,
|
|
171
195
|
or `'queue'`:
|
|
172
196
|
|
|
173
|
-
| Mode | Behavior
|
|
174
|
-
| --------- |
|
|
175
|
-
| `'off'` |
|
|
176
|
-
| `'track'` | Repeat the active track forever.
|
|
177
|
-
| `'queue'` | Loop the whole queue.
|
|
197
|
+
| Mode | Behavior |
|
|
198
|
+
| --------- | -------------------------------------------------------------------------- |
|
|
199
|
+
| `'off'` | Pause at the end of the last track; state becomes `'ended'` (the default). |
|
|
200
|
+
| `'track'` | Repeat the active track forever. |
|
|
201
|
+
| `'queue'` | Loop the whole queue. |
|
|
178
202
|
|
|
179
203
|
```tsx
|
|
180
204
|
import {
|
|
@@ -204,7 +228,16 @@ function ShuffleButton() {
|
|
|
204
228
|
```
|
|
205
229
|
|
|
206
230
|
[`setShuffle(true | false)`](/api/features/queue/#setshuffle) sets it directly;
|
|
207
|
-
[`toggleShuffle()`](/api/features/queue/#toggleshuffle) flips it.
|
|
231
|
+
[`toggleShuffle()`](/api/features/queue/#toggleshuffle) flips it. Outside
|
|
232
|
+
React, read the current values with
|
|
233
|
+
[`getRepeatMode()`](/api/features/queue/#getrepeatmode) and
|
|
234
|
+
[`getShuffle()`](/api/features/queue/#getshuffle), and subscribe to
|
|
235
|
+
[`onRepeatModeChanged`](/api/features/queue/#onrepeatmodechanged) and
|
|
236
|
+
[`onShuffleChanged`](/api/features/queue/#onshufflechanged).
|
|
237
|
+
|
|
238
|
+
Shuffle changes only the playback order. Indexes, `getQueue` and `useQueue`
|
|
239
|
+
keep list order, while `skipToNext` and `skipToPrevious` follow the shuffle
|
|
240
|
+
order.
|
|
208
241
|
|
|
209
242
|
## When the queue ends
|
|
210
243
|
|
|
@@ -233,6 +266,7 @@ import {
|
|
|
233
266
|
useQueue,
|
|
234
267
|
useActiveTrack,
|
|
235
268
|
getActiveTrackIndex,
|
|
269
|
+
getTrackIdentity,
|
|
236
270
|
skip,
|
|
237
271
|
move,
|
|
238
272
|
remove
|
|
@@ -240,16 +274,16 @@ import {
|
|
|
240
274
|
|
|
241
275
|
function UpNext() {
|
|
242
276
|
const queue = useQueue()
|
|
243
|
-
// `useActiveTrack` re-renders the list when the active track changes
|
|
244
|
-
//
|
|
245
|
-
//
|
|
277
|
+
// `useActiveTrack` re-renders the list when the active track changes.
|
|
278
|
+
// Compare by index: the same track can be queued twice.
|
|
279
|
+
// `getActiveTrackIndex()` is read fresh on each render.
|
|
246
280
|
const active = useActiveTrack()
|
|
247
281
|
const activeIndex = active ? getActiveTrackIndex() : undefined
|
|
248
282
|
|
|
249
283
|
return (
|
|
250
284
|
<FlatList
|
|
251
285
|
data={queue}
|
|
252
|
-
keyExtractor={(track, i) => track
|
|
286
|
+
keyExtractor={(track, i) => `${getTrackIdentity(track) ?? ''}:${i}`}
|
|
253
287
|
renderItem={({ item, index }) => (
|
|
254
288
|
<View style={{ flexDirection: 'row', alignItems: 'center' }}>
|
|
255
289
|
<Text
|
|
@@ -270,10 +304,9 @@ function UpNext() {
|
|
|
270
304
|
```
|
|
271
305
|
|
|
272
306
|
A `<Button>` can't be a child of `<Text>`, so each row is a `<View>` with the
|
|
273
|
-
title and buttons as siblings.
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
confuse row identity.
|
|
307
|
+
title and buttons as siblings. A key built from the track's `id` alone, or from
|
|
308
|
+
[`getTrackIdentity`](/api/utils/getTrackIdentity/) alone, collides when the same
|
|
309
|
+
track is queued twice, so the `keyExtractor` adds the index.
|
|
277
310
|
|
|
278
311
|
## A note on units
|
|
279
312
|
|
|
@@ -283,18 +316,19 @@ All position arguments are **seconds** — `seekTo`, `seekBy`, the
|
|
|
283
316
|
|
|
284
317
|
## API summary
|
|
285
318
|
|
|
286
|
-
| API
|
|
287
|
-
|
|
|
288
|
-
| `setQueue(tracks, startIndex?, startPosition?)`
|
|
289
|
-
| `add(track \| tracks, insertBeforeIndex?)`
|
|
290
|
-
| `load(track)`
|
|
291
|
-
| `move(from, to)`
|
|
292
|
-
| `remove(index \| indexes)`
|
|
293
|
-
| `removeUpcomingTracks()`
|
|
294
|
-
| `skip(index, initialPosition?)`
|
|
295
|
-
| `skipToNext()` / `skipToPrevious()`
|
|
296
|
-
| `useQueue()` / `getQueue()` / `getTrack(i)`
|
|
297
|
-
| `useActiveTrack()` / `getActiveTrack()` / `getActiveTrackIndex()`
|
|
298
|
-
| `onActiveTrackChanged` / `onQueueChanged` / `onQueueEnded`
|
|
299
|
-
| `setRepeatMode(mode)` / `useRepeatMode()`
|
|
300
|
-
| `setShuffle(bool)` / `toggleShuffle()` / `useShuffle()`
|
|
319
|
+
| API | Purpose |
|
|
320
|
+
| ------------------------------------------------------------------------ | ---------------------------------------------------------------- |
|
|
321
|
+
| `setQueue(tracks, startIndex?, startPosition?)` | Replace the queue (doesn't auto-play; position in **seconds**). |
|
|
322
|
+
| `add(track \| tracks, insertBeforeIndex?)` | Append, or insert before an index. |
|
|
323
|
+
| `load(track)` | Replace the active track (or start the queue if empty). |
|
|
324
|
+
| `move(from, to)` | Reorder; `to` past the end → end (iOS, Android; the web throws). |
|
|
325
|
+
| `remove(index \| indexes)` | Remove track(s); see Removing the active track above. |
|
|
326
|
+
| `removeUpcomingTracks()` | Drop everything after the active track. |
|
|
327
|
+
| `skip(index, initialPosition?)` | Jump to a track (position in **seconds**). |
|
|
328
|
+
| `skipToNext()` / `skipToPrevious()` | Step between tracks. |
|
|
329
|
+
| `useQueue()` / `getQueue()` / `getTrack(i)` | Read the queue. |
|
|
330
|
+
| `useActiveTrack()` / `getActiveTrack()` / `getActiveTrackIndex()` | Read the active track. |
|
|
331
|
+
| `onActiveTrackChanged` / `onQueueChanged` / `onQueueEnded` | Subscribe to changes. |
|
|
332
|
+
| `setRepeatMode(mode)` / `useRepeatMode()` / `getRepeatMode()` | `'off'` / `'track'` / `'queue'`. |
|
|
333
|
+
| `setShuffle(bool)` / `toggleShuffle()` / `useShuffle()` / `getShuffle()` | Shuffle order. |
|
|
334
|
+
| `onRepeatModeChanged` / `onShuffleChanged` | Subscribe to repeat and shuffle changes. |
|
|
@@ -1,21 +1,23 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: 'Override what the lock-screen, notification, car, and headset buttons do with handleRemote*,
|
|
2
|
+
description: 'Override what the lock-screen, notification, car, and headset buttons do with handleRemote*, observe presses with the onRemote* events, and resume the last session after the app is killed.'
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Remote Controls
|
|
6
6
|
|
|
7
7
|
**Remote controls** are the playback buttons on surfaces outside your app — the
|
|
8
8
|
iOS lock screen and Control Center, the Android notification, CarPlay and Android
|
|
9
|
-
Auto, and Bluetooth/headset buttons.
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
9
|
+
Auto, and Bluetooth/headset buttons.
|
|
10
|
+
|
|
11
|
+
By default they just work: the system play/pause/next/seek buttons drive the
|
|
12
|
+
player for you. This guide is for the two times you need more — **overriding**
|
|
13
|
+
what a button does, and **observing** when one is pressed.
|
|
13
14
|
|
|
14
15
|
There are two families:
|
|
15
16
|
|
|
16
17
|
- [`handleRemote*`](#overriding-a-control) — **override** a control's behavior.
|
|
17
18
|
A plain setter: `handleRemoteNext(cb)`, or `handleRemoteNext(undefined)` to
|
|
18
|
-
|
|
19
|
+
restore the default behavior. To remove a button on iOS or Android, turn off
|
|
20
|
+
its capability.
|
|
19
21
|
- [`onRemote*`](#listening-to-presses) — **listen** to presses without changing
|
|
20
22
|
behavior (analytics, logging). An emitter:
|
|
21
23
|
`onRemoteNext.addListener(cb)` returns an unsubscribe function.
|
|
@@ -36,7 +38,7 @@ Without any wiring, each control drives the player:
|
|
|
36
38
|
| play / pause / stop | `play()` / `pause()` / `stop()` |
|
|
37
39
|
| next / previous | `skipToNext()` / `skipToPrevious()` |
|
|
38
40
|
| seek | `seekTo(position)` |
|
|
39
|
-
| jump forward / backward |
|
|
41
|
+
| jump forward / backward | seek forward / back (see below) |
|
|
40
42
|
|
|
41
43
|
So you only reach for the APIs below to _change_ or _watch_ that behavior.
|
|
42
44
|
|
|
@@ -100,7 +102,11 @@ This catches people out, because `jumpForward` and `jumpBackward` default to
|
|
|
100
102
|
// ✗ Both jump buttons are silently dropped — no error, no warning.
|
|
101
103
|
updateOptions({
|
|
102
104
|
android: {
|
|
103
|
-
remoteButtonLayout: {
|
|
105
|
+
remoteButtonLayout: {
|
|
106
|
+
back: 'jump-backward',
|
|
107
|
+
forward: 'jump-forward',
|
|
108
|
+
overflow: []
|
|
109
|
+
}
|
|
104
110
|
}
|
|
105
111
|
})
|
|
106
112
|
|
|
@@ -108,7 +114,11 @@ updateOptions({
|
|
|
108
114
|
updateOptions({
|
|
109
115
|
capabilities: { jumpBackward: true, jumpForward: true },
|
|
110
116
|
android: {
|
|
111
|
-
remoteButtonLayout: {
|
|
117
|
+
remoteButtonLayout: {
|
|
118
|
+
back: 'jump-backward',
|
|
119
|
+
forward: 'jump-forward',
|
|
120
|
+
overflow: []
|
|
121
|
+
}
|
|
112
122
|
}
|
|
113
123
|
})
|
|
114
124
|
```
|
|
@@ -122,12 +132,12 @@ capability is enabled.
|
|
|
122
132
|
`overflow` is an ordered list, and each surface renders as many buttons as it
|
|
123
133
|
has room for, **taking them from the front**:
|
|
124
134
|
|
|
125
|
-
| Surface
|
|
126
|
-
|
|
|
127
|
-
| Collapsed notification
|
|
128
|
-
| Expanded notification
|
|
129
|
-
| Android 13+ media controls
|
|
130
|
-
| Android Auto
|
|
135
|
+
| Surface | Roughly how many |
|
|
136
|
+
| -------------------------------------------- | ----------------------------- |
|
|
137
|
+
| Collapsed notification | 3 — back, play/pause, forward |
|
|
138
|
+
| Expanded notification (Android 12 and below) | up to 5, play/pause included |
|
|
139
|
+
| Android 13+ media controls | about 5 |
|
|
140
|
+
| Android Auto | the head unit decides |
|
|
131
141
|
|
|
132
142
|
Two consequences worth knowing:
|
|
133
143
|
|
|
@@ -143,7 +153,7 @@ buttons so there's nothing to promote.
|
|
|
143
153
|
::: tip iOS
|
|
144
154
|
This option is Android-only. CarPlay's Now Playing buttons are configured
|
|
145
155
|
separately with `ios.carPlayNowPlayingButtons` — see
|
|
146
|
-
[CarPlay](/guide/carplay).
|
|
156
|
+
[CarPlay → Now Playing Buttons](/guide/carplay#now-playing-buttons).
|
|
147
157
|
:::
|
|
148
158
|
|
|
149
159
|
## Overriding a control
|
|
@@ -151,9 +161,10 @@ separately with `ios.carPlayNowPlayingButtons` — see
|
|
|
151
161
|
[`handleRemote*(callback)`](/api/features/remoteControls/#handleremotenext)
|
|
152
162
|
**replaces** a control's default action with your own. Pass `undefined` to remove
|
|
153
163
|
your override (restoring the default); the callback itself does nothing but what
|
|
154
|
-
you write — if you still want the normal action, call it yourself.
|
|
155
|
-
|
|
156
|
-
|
|
164
|
+
you write — if you still want the normal action, call it yourself.
|
|
165
|
+
|
|
166
|
+
Each control has a **single** override: calling `handleRemote*` again replaces
|
|
167
|
+
the previous one (unlike `onRemote*`, which supports multiple listeners).
|
|
157
168
|
|
|
158
169
|
The canonical use is gating a control — e.g. a radio product with a skip
|
|
159
170
|
allowance — paired with a [now-playing flash](/guide/now-playing#the-flash-transient-top-priority)
|
|
@@ -192,14 +203,25 @@ handleRemoteSeek(({ position }) => {
|
|
|
192
203
|
// position is in seconds
|
|
193
204
|
})
|
|
194
205
|
handleRemoteJumpForward(({ interval }) => {
|
|
195
|
-
// interval is in seconds
|
|
206
|
+
// interval is in seconds
|
|
196
207
|
})
|
|
197
208
|
```
|
|
198
209
|
|
|
199
|
-
|
|
200
|
-
[`capabilities`](/guide/configuration#capabilities)
|
|
201
|
-
|
|
202
|
-
|
|
210
|
+
On iOS and Android the jump controls only appear when `jumpForward` /
|
|
211
|
+
`jumpBackward` are enabled in [`capabilities`](/guide/configuration#capabilities)
|
|
212
|
+
(off by default); on web capabilities are ignored and the browser's seek
|
|
213
|
+
forward and back actions are always handled. On iOS and Android your handler
|
|
214
|
+
receives the `forwardJumpInterval` / `backwardJumpInterval` option (default
|
|
215
|
+
15s) as `interval`; on web it receives the offset the browser sends, or 10s
|
|
216
|
+
when it sends none. Without a handler, the distance of the default jump depends
|
|
217
|
+
on the platform:
|
|
218
|
+
|
|
219
|
+
- **iOS** seeks by the interval.
|
|
220
|
+
- **Android** seeks by Media3's default increments (15s forward, 5s back),
|
|
221
|
+
whatever the interval. There the interval sets only the button's icon and the
|
|
222
|
+
handler's `interval`. To jump by the interval on Android, override the control
|
|
223
|
+
and call `seekBy(±interval)`.
|
|
224
|
+
- **Web** seeks by the offset the browser sends, or 10s when it sends none.
|
|
203
225
|
|
|
204
226
|
## Listening to presses
|
|
205
227
|
|
|
@@ -225,14 +247,50 @@ intercepted it (and even when that override refused to act). Use it to _observe_
|
|
|
225
247
|
use `handleRemote*` to _change behavior_.
|
|
226
248
|
:::
|
|
227
249
|
|
|
250
|
+
## Resuming after the app is killed
|
|
251
|
+
|
|
252
|
+
The library saves the last session natively, with nothing to configure: the
|
|
253
|
+
active track (with the browse path it was tapped from), its position, and the
|
|
254
|
+
repeat mode, shuffle and rate.
|
|
255
|
+
|
|
256
|
+
It saves on every pause, track change and setting change, and periodically
|
|
257
|
+
while playing, so a kill loses at most a few seconds of position. A live stream
|
|
258
|
+
keeps no position, so it resumes at the live edge; a track that had ended
|
|
259
|
+
resumes from the start.
|
|
260
|
+
|
|
261
|
+
That session plays again when a listener asks for playback while your app isn't
|
|
262
|
+
running:
|
|
263
|
+
|
|
264
|
+
- **Android**: a Bluetooth or headset play button, a car head unit, or the play
|
|
265
|
+
button on the system media controls, which keep your app's last session after
|
|
266
|
+
it is killed.
|
|
267
|
+
- **iOS**: Siri — "play «App»" or a bare "play" / "resume" (see
|
|
268
|
+
[Search → Voice playback](/guide/search#voice-playback-siri-google-assistant)).
|
|
269
|
+
Siri is the only path that resumes a saved session on iOS.
|
|
270
|
+
|
|
271
|
+
Resuming restores the settings, then rebuilds the queue by expanding the saved
|
|
272
|
+
track's path through your browse configuration, as if the listener had tapped it
|
|
273
|
+
again, and plays from the saved position.
|
|
274
|
+
|
|
275
|
+
If the path doesn't expand, the saved track plays alone. A saved track marked
|
|
276
|
+
[`disabled`](/guide/track) is never resumed.
|
|
277
|
+
|
|
278
|
+
Resuming waits for your JS: call `setupPlayer()` and `configureBrowser()` at the
|
|
279
|
+
top level of `index.js`. Resuming gives up within seconds if they haven't run
|
|
280
|
+
(on iOS, see
|
|
281
|
+
[CarPlay → AppDelegate intent handler](/guide/carplay#_4-appdelegate-intent-handler)).
|
|
282
|
+
On Android 12+, battery restrictions can block the background start; see
|
|
283
|
+
[Battery](/guide/battery).
|
|
284
|
+
|
|
228
285
|
## Voice commands ("play X")
|
|
229
286
|
|
|
230
287
|
A voice command like "play jazz on Android Auto" or a Siri "play …" is **not**
|
|
231
|
-
delivered as a remote-control event.
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
288
|
+
delivered as a remote-control event.
|
|
289
|
+
|
|
290
|
+
It's handled by the library's [search source](/guide/search) and play funnel:
|
|
291
|
+
you provide `configureBrowser({ search })`, and the library resolves the query
|
|
292
|
+
and starts playback for you (Android routes the system `MEDIA_PLAY_FROM_SEARCH`
|
|
293
|
+
intent through it). See [Search](/guide/search) for wiring voice intents.
|
|
236
294
|
|
|
237
295
|
## Payloads at a glance
|
|
238
296
|
|
package/website/guide/search.md
CHANGED
|
@@ -38,27 +38,31 @@ configureBrowser({
|
|
|
38
38
|
})
|
|
39
39
|
```
|
|
40
40
|
|
|
41
|
-
**An HTTP endpoint** — a `TransformableRequestConfig`. The library issues the request natively and appends the query parameters for you.
|
|
41
|
+
**An HTTP endpoint** — a `TransformableRequestConfig`. The library issues the request natively and appends the query parameters for you.
|
|
42
|
+
|
|
43
|
+
The endpoint must return a **bare `Track[]`**, a JSON array of results, not the page object a browse endpoint returns. iOS and Android decode only the array. On Android a page object gives no results, and on iOS the search rejects. The web accepts either shape. See [`SearchSource`](/api/types/browser/#searchsource).
|
|
42
44
|
|
|
43
45
|
```ts
|
|
44
46
|
configureBrowser({
|
|
45
47
|
search: {
|
|
46
48
|
baseUrl: 'https://api.example.com/search',
|
|
47
|
-
// "play jazz" → GET .../search
|
|
49
|
+
// "play jazz" → GET .../search with q=jazz, genre=jazz and limit=20
|
|
48
50
|
// (q always; genre because the intent carried one; no mode here
|
|
49
|
-
// because "play jazz" carries none; limit added by
|
|
50
|
-
|
|
51
|
+
// because "play jazz" carries none; limit added by transformSync)
|
|
52
|
+
transformSync(request) {
|
|
51
53
|
return { ...request, query: { ...request.query, limit: '20' } }
|
|
52
54
|
}
|
|
53
55
|
}
|
|
54
56
|
})
|
|
55
57
|
```
|
|
56
58
|
|
|
57
|
-
With the HTTP form the library
|
|
59
|
+
With the HTTP form the library adds to `request.query`: `q` (always, even when empty), `mode`, `reference` (only when it is `'my'`, see below), and the filter fields, each only when the intent carried it. The callback's `query` is sent as `q`.
|
|
58
60
|
|
|
59
61
|
## Searching from your own UI
|
|
60
62
|
|
|
61
|
-
The same source powers your in-app search box. [`search(query)`](/api/features/browser/#search) runs it and resolves to a `Track[]` — it only _returns_ results, it never queues or plays anything.
|
|
63
|
+
The same source powers your in-app search box. [`search(query)`](/api/features/browser/#search) runs it and resolves to a `Track[]` — it only _returns_ results, it never queues or plays anything.
|
|
64
|
+
|
|
65
|
+
[`hasSearch()`](/api/features/browser/#hassearch) tells you (synchronously) whether a search source is configured at all, so you can hide the search UI when it isn't. Check it before calling [`search()`](/api/features/browser/#search): with no source configured, Android and web resolve `[]` but iOS rejects. With a source configured, `[]` means it found nothing:
|
|
62
66
|
|
|
63
67
|
```tsx
|
|
64
68
|
import { search, hasSearch, navigate } from 'react-native-audio-browser'
|
|
@@ -80,11 +84,12 @@ function SearchScreen() {
|
|
|
80
84
|
}
|
|
81
85
|
```
|
|
82
86
|
|
|
83
|
-
|
|
87
|
+
Four things to know about the in-app call:
|
|
84
88
|
|
|
85
|
-
- **Your resolver sees a plain query.** An in-app `search('jazz')` arrives as `{ query: 'jazz', reference: 'unknown' }` — no `mode`, no filter fields.
|
|
86
|
-
- **You get the flat list, untouched.** The [browsable-first-result drill-in](#voice-playback-siri-google-assistant) is voice-only — in-app results are handed to you as returned
|
|
89
|
+
- **Your resolver sees a plain query.** An in-app `search('jazz')` arrives as `{ query: 'jazz', reference: 'unknown' }` — no `mode`, no filter fields. Only the voice assistants extract those. (On the HTTP form, only `q` is appended.) A resolver written against _the fields that are present_ handles both callers.
|
|
90
|
+
- **You get the flat list, untouched.** The [browsable-first-result drill-in](#voice-playback-siri-google-assistant) is voice-only — in-app results are handed to you as returned, and the user picks. A result with neither a `path` nor a `src` can't be rendered, so don't return one.
|
|
87
91
|
- **Route taps through `navigate(track)`** rather than `setQueue` + `play` — that gives a tapped result the library's load path ([`handleTrackLoad`](#mixed-audio-video), [Gate](/guide/gate) checks, favorite hearts) just like a tap on a browse row.
|
|
92
|
+
- **A failed search rejects; catch it** to tell a failure from no results. On web a failed HTTP search's error carries a `code`: `'http-error'` or `'network-error'`; a callback's rejection reaches you unchanged. On Android an HTTP source never rejects: it resolves `[]` on any failure (status, network, decoding), so there a failure looks like no results. See [`search`](/api/features/browser/#search).
|
|
88
93
|
|
|
89
94
|
## SearchParams
|
|
90
95
|
|
|
@@ -137,17 +142,21 @@ Those are **filters**, not result shapes — read them from `params.genre` / `pa
|
|
|
137
142
|
|
|
138
143
|
The two voice platforms feed the **same** `SearchParams`; they just differ in how many fields they fill:
|
|
139
144
|
|
|
140
|
-
- **iOS (SiriKit)** supplies the richer set
|
|
141
|
-
- **Android (`onPlayFromSearch`)** supplies the subset it can express: `query`, the music
|
|
145
|
+
- **iOS (SiriKit)** supplies the richer set: every `mode` except `any`, and the `reference` axis.
|
|
146
|
+
- **Android (`onPlayFromSearch`)** supplies the subset it can express: `query`, the modes `any` (for "play music" with no query), `song` and `playlist`, the genre, artist, album, title and playlist filters, and always `reference: 'unknown'`.
|
|
142
147
|
|
|
143
148
|
Write your resolver against the _fields that are present_ (`if (params.genre) …`), not against the platform. A field that's empty on one platform simply means "the assistant didn't provide it."
|
|
144
149
|
|
|
145
150
|
## Voice playback (Siri & Google Assistant)
|
|
146
151
|
|
|
147
|
-
A spoken command — "play jazz on «App»" — funnels to the **same `search` source** on both platforms, then the result is queued and played. Any active **[Gate](/guide/gate)** sees the search first, so voice can't slip past a paywall or region block unless your gate lets it through.
|
|
152
|
+
A spoken command — "play jazz on «App»" — funnels to the **same `search` source** on both platforms, then the result is queued and played. Any active **[Gate](/guide/gate)** sees the search first, so voice can't slip past a paywall or region block unless your gate lets it through.
|
|
148
153
|
|
|
149
154
|
::: tip A browsable first result is drilled into
|
|
150
|
-
|
|
155
|
+
The library inspects the **first** voice result. If it is browsable-only — a `path` with no `src` — the library resolves that page and queues _its_ playable children. So "play jazz" plays the first station _inside_ the jazz page, not the page itself.
|
|
156
|
+
|
|
157
|
+
Disabled results are skipped, so a disabled first result never counts. If the first result is already playable (has a `src`), or the drill-in finds nothing playable, the playable results (those with a `src` that are not `disabled`) are queued in order.
|
|
158
|
+
|
|
159
|
+
This applies on both platforms, and only to voice playback — an in-app search UI renders your results and lets the user pick.
|
|
151
160
|
:::
|
|
152
161
|
|
|
153
162
|
For ordinary queries ("play jazz", "play «station name»") the two behave identically — same resolver, same queue, same playback. The entry point and a few conveniences differ:
|
|
@@ -162,7 +171,7 @@ For ordinary queries ("play jazz", "play «station name»") the two behave ident
|
|
|
162
171
|
|
|
163
172
|
The gaps are all iOS-only conveniences — collection-by-voice and resume-by-name. Everything in the shared column is fully cross-platform.
|
|
164
173
|
|
|
165
|
-
## Playing the user's own collection
|
|
174
|
+
## Playing the user's own collection {#playing-the-users-own-collection}
|
|
166
175
|
|
|
167
176
|
When the user says **"play my favorites"**, the intent carries `reference: 'my'`. Resolve it however your collection lives:
|
|
168
177
|
|
|
@@ -178,14 +187,14 @@ configureBrowser({
|
|
|
178
187
|
})
|
|
179
188
|
```
|
|
180
189
|
|
|
181
|
-
**Server collection** — when you use the HTTP form, `reference=my` is appended to `request.query`, so branch in `
|
|
190
|
+
**Server collection** — when you use the HTTP form, `reference=my` is appended to `request.query`, so branch in `transformSync` to route the request — for example, to a favorites endpoint, injecting locally-stored identifiers:
|
|
182
191
|
|
|
183
192
|
```ts
|
|
184
193
|
configureBrowser({
|
|
185
194
|
search: {
|
|
186
195
|
baseUrl: 'https://api.example.com/search',
|
|
187
|
-
|
|
188
|
-
// `
|
|
196
|
+
transformSync(request) {
|
|
197
|
+
// `transformSync` runs for every search — pass normal queries straight
|
|
189
198
|
// through to /search; only "play my favorites" is rewritten below.
|
|
190
199
|
if (request.query?.reference !== 'my') return request
|
|
191
200
|
return {
|
|
@@ -207,11 +216,13 @@ configureBrowser({
|
|
|
207
216
|
|
|
208
217
|
## Voice phrase → params
|
|
209
218
|
|
|
210
|
-
These mappings are **illustrative, not guaranteed.** The assistant (Siri / Google Assistant) decides how to parse a spoken phrase, and the same words can arrive structured differently — or as a bare `query` — depending on the platform, locale, and the assistant's own interpretation.
|
|
219
|
+
These mappings are **illustrative, not guaranteed.** The assistant (Siri / Google Assistant) decides how to parse a spoken phrase, and the same words can arrive structured differently — or as a bare `query` — depending on the platform, locale, and the assistant's own interpretation.
|
|
220
|
+
|
|
221
|
+
Treat the table as _plausible_ shapes to handle, and always write your resolver against the fields actually present (see [Cross-platform differences](#cross-platform-differences)) rather than assuming a phrase produces a specific shape.
|
|
211
222
|
|
|
212
223
|
| Phrase | Resulting `SearchParams` |
|
|
213
224
|
| --------------------- | ------------------------------------------------------------- |
|
|
214
|
-
| "play something" | `{ query: '
|
|
225
|
+
| "play something" | `{ mode: 'any', query: '' }` |
|
|
215
226
|
| "play music" | `{ mode: 'any', query: '' }` _(iOS may send `mode: 'music'`)_ |
|
|
216
227
|
| "play jazz" | `{ genre: 'jazz', query: 'jazz' }` |
|
|
217
228
|
| "play The Stalk 88.5" | `{ mode: 'station', query: 'The Stalk 88.5' }` |
|
|
@@ -223,7 +234,9 @@ These mappings are **illustrative, not guaranteed.** The assistant (Siri / Googl
|
|
|
223
234
|
|
|
224
235
|
This is an **audio** library — its player streams audio and has no video surface, and CarPlay / Android Auto forbid video playback while driving. So video is fundamentally an **in-app** concern: a search can _signal_ a video request (via the video `mode` values), but the library will not render video.
|
|
225
236
|
|
|
226
|
-
To play video from your in-app search, intercept the load with [`handleTrackLoad`](/api/types/browser/#handletrackload). It runs whenever a track is loaded through [`navigate(track)`](/api/features/browser/#navigate) (or the library's own browse UI) — so route your in-app search-result taps through `navigate(track)` rather than calling `setQueue` / `play` yourself, or this hook never fires.
|
|
237
|
+
To play video from your in-app search, intercept the load with [`handleTrackLoad`](/api/types/browser/#handletrackload). It runs whenever a track is loaded through [`navigate(track)`](/api/features/browser/#navigate) (or the library's own browse UI) — so route your in-app search-result taps through `navigate(track)` rather than calling `setQueue` / `play` yourself, or this hook never fires.
|
|
238
|
+
|
|
239
|
+
When set, it is called **instead of** the library auto-playing the track — for **every** such load, not just video — so your handler must either route the track elsewhere or hand it back to the library to play:
|
|
227
240
|
|
|
228
241
|
```ts
|
|
229
242
|
import {
|
|
@@ -250,6 +263,8 @@ configureBrowser({
|
|
|
250
263
|
})
|
|
251
264
|
```
|
|
252
265
|
|
|
253
|
-
|
|
266
|
+
The `mode` you saw at **search** time (`music-video` / `movie` / …) is not carried onto the `Track`, and `handleTrackLoad` runs at **load** time with no `mode`.
|
|
267
|
+
|
|
268
|
+
The tracks your `search` source returns for a video request are _yours_, though — so tag them with a recognizable `src` (as above) when you build them, and read that tag in `isVideo` here.
|
|
254
269
|
|
|
255
|
-
|
|
270
|
+
On external surfaces (CarPlay / Android Auto), a video request falls back to audio or is declined — there is no video playback path there.
|