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
|
@@ -8,11 +8,13 @@ This guide covers the core idea — the **browse tree** — and the minimal code
|
|
|
8
8
|
|
|
9
9
|
## The browse tree
|
|
10
10
|
|
|
11
|
-
The library models all content as one navigable tree of **Tracks**. A
|
|
11
|
+
The library models all content as one navigable tree of **Tracks**. A Track is **browsable** or **playable**, depending on which field you set:
|
|
12
12
|
|
|
13
13
|
- **Browsable** — has a `path`; navigating into it resolves its children.
|
|
14
14
|
- **Playable** — has a `src`; the player can stream it.
|
|
15
15
|
|
|
16
|
+
Set exactly one. [Track → Browsable or playable](/guide/track#browsable-or-playable) covers a Track that sets both.
|
|
17
|
+
|
|
16
18
|
Three fields at a glance — each answers a different question about a Track:
|
|
17
19
|
|
|
18
20
|
| Field | Answers | Meaning |
|
|
@@ -103,7 +105,7 @@ configureBrowser({
|
|
|
103
105
|
})
|
|
104
106
|
```
|
|
105
107
|
|
|
106
|
-
A route value is a [`BrowserSource`](/api/types/browser/#browsersource): the static page object shown above, an **async callback** that returns one (`'/path': async ({ routeParams }) => ({ title, children })`), or an HTTP request config that fetches it from your API — handy for trees too large to declare upfront.
|
|
108
|
+
A route value is a [`BrowserSource`](/api/types/browser/#browsersource): the static page object shown above, an **async callback** that returns one (`'/path': async ({ path, routeParams }) => ({ path, title, children })`), or an HTTP request config that fetches it from your API — handy for trees too large to declare upfront.
|
|
107
109
|
|
|
108
110
|
A page can also group its tracks into titled, styled **sections** (`sections: [{ title, style, children }, …]`) — a flat `children` list like the ones above is shorthand for a single untitled section. See [Browser → How a path resolves](/guide/browser#how-a-path-resolves).
|
|
109
111
|
|
|
@@ -129,6 +131,7 @@ The player works through a **queue** of Tracks. The Track at the current positio
|
|
|
129
131
|
Reactive hooks keep your in-app UI in sync with playback — they re-render automatically as it changes:
|
|
130
132
|
|
|
131
133
|
```tsx
|
|
134
|
+
import { Button } from 'react-native'
|
|
132
135
|
import {
|
|
133
136
|
togglePlayback,
|
|
134
137
|
usePlayingState,
|
package/website/guide/battery.md
CHANGED
|
@@ -7,26 +7,30 @@ description: 'Detect the Android 12+ battery restrictions that block the foregro
|
|
|
7
7
|
On Android 12+, if the OS has put your app under battery restrictions, it
|
|
8
8
|
**blocks the foreground service** the player needs to start audio in the
|
|
9
9
|
background. So when a Bluetooth device or car head unit tries to resume playback
|
|
10
|
-
while your app is killed, nothing happens.
|
|
11
|
-
|
|
10
|
+
while your app is killed, nothing happens.
|
|
11
|
+
|
|
12
|
+
This feature detects that block and lets you prompt the user to fix their
|
|
13
|
+
battery settings.
|
|
12
14
|
|
|
13
15
|
::: warning Android only
|
|
14
16
|
This is an **Android-only** concern (Android 12+ foreground-service limits).
|
|
15
17
|
On iOS every getter/hook here is inert: `getBatteryWarningPending()` is always
|
|
16
18
|
`false`, `getBatteryOptimizationStatus()` is always `'unrestricted'`, the events
|
|
17
19
|
never fire, and `dismissBatteryWarning()` / `openBatterySettings()` are no-ops.
|
|
18
|
-
So you can render the banner below unconditionally — it simply never shows on iOS.
|
|
19
|
-
:::
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
21
|
+
So you can render the banner below unconditionally: it never shows on iOS.
|
|
22
|
+
:::
|
|
23
23
|
|
|
24
24
|
## The warning banner
|
|
25
25
|
|
|
26
|
-
A warning becomes **pending** when a background resume is actually blocked.
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
26
|
+
A warning becomes **pending** when a background resume is actually blocked. The
|
|
27
|
+
block happens while your app is killed, so the library saves the warning and you
|
|
28
|
+
see it the next time the app opens. It stays pending across launches until it
|
|
29
|
+
clears.
|
|
30
|
+
|
|
31
|
+
Show a banner only while `pending` is true, offering to open settings or
|
|
32
|
+
dismiss. [`useBatteryWarning()`](/api/features/battery/#usebatterywarning)
|
|
33
|
+
bundles everything you need:
|
|
30
34
|
|
|
31
35
|
```tsx
|
|
32
36
|
import { View, Text, Button } from 'react-native'
|
|
@@ -47,17 +51,42 @@ function BatteryWarningBanner() {
|
|
|
47
51
|
```
|
|
48
52
|
|
|
49
53
|
- `openSettings` ([`openBatterySettings`](/api/features/battery/#openbatterysettings))
|
|
50
|
-
|
|
51
|
-
|
|
54
|
+
depends on the status. When it is `'optimized'`, it asks the system for the
|
|
55
|
+
dialog that lets the user exempt the app from battery optimization in one tap.
|
|
56
|
+
This works only if your app declares the permission below.
|
|
57
|
+
|
|
58
|
+
With any other status, `'restricted'` included, it opens the app's App info
|
|
59
|
+
page, and the user changes the battery setting from there. When the user
|
|
60
|
+
returns having set the app to unrestricted, the warning clears itself.
|
|
61
|
+
|
|
52
62
|
- `dismiss` ([`dismissBatteryWarning`](/api/features/battery/#dismissbatterywarning))
|
|
53
63
|
hides the warning without changing settings.
|
|
54
64
|
|
|
65
|
+
::: warning The one-tap dialog needs a permission
|
|
66
|
+
The library doesn't declare `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`. Without it,
|
|
67
|
+
Android drops the dialog request in the `'optimized'` state: nothing appears,
|
|
68
|
+
and the status stays `'optimized'`. The library doesn't detect this or fall
|
|
69
|
+
back to another settings page.
|
|
70
|
+
|
|
71
|
+
To get the dialog, declare the permission in your app:
|
|
72
|
+
|
|
73
|
+
```xml
|
|
74
|
+
<!-- android/app/src/main/AndroidManifest.xml -->
|
|
75
|
+
<uses-permission
|
|
76
|
+
android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Google Play restricts which apps may declare this permission. Check its policy
|
|
80
|
+
before you add it. If you can't declare it, send users in the `'optimized'`
|
|
81
|
+
state to the system battery settings some other way.
|
|
82
|
+
:::
|
|
83
|
+
|
|
55
84
|
## When the warning clears
|
|
56
85
|
|
|
57
86
|
`pending` goes back to `false` when any of these happens — you don't clear it
|
|
58
87
|
manually:
|
|
59
88
|
|
|
60
|
-
-
|
|
89
|
+
- your app calls `dismiss` (for example, when the user taps Dismiss), or
|
|
61
90
|
- the battery status becomes `'unrestricted'` (e.g. they fixed it in settings).
|
|
62
91
|
|
|
63
92
|
## Battery optimization status
|
|
@@ -103,13 +132,11 @@ two actions.
|
|
|
103
132
|
|
|
104
133
|
## API summary
|
|
105
134
|
|
|
106
|
-
| API | Purpose
|
|
107
|
-
| ----------------------------------------------------------------------- |
|
|
108
|
-
| `useBatteryWarning()` | Everything for a banner: `{ pending, status, dismiss, openSettings }`.
|
|
109
|
-
| `getBatteryWarningPending()` / `useBatteryWarningPending()` | Is a warning pending? (Android; `false` on iOS)
|
|
110
|
-
| `getBatteryOptimizationStatus()` / `useBatteryOptimizationStatus()` | Current status (Android; `'unrestricted'` on iOS)
|
|
111
|
-
| `onBatteryWarningPendingChanged` / `onBatteryOptimizationStatusChanged` | Subscribe outside React.
|
|
112
|
-
| `openBatterySettings()` |
|
|
113
|
-
| `dismissBatteryWarning()` | Dismiss the warning without changing settings (Android).
|
|
114
|
-
|
|
115
|
-
All are **Android-only** — inert (`false` / `'unrestricted'` / no-op) on iOS.
|
|
135
|
+
| API | Purpose |
|
|
136
|
+
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
137
|
+
| `useBatteryWarning()` | Everything for a banner: `{ pending, status, dismiss, openSettings }`. |
|
|
138
|
+
| `getBatteryWarningPending()` / `useBatteryWarningPending()` | Is a warning pending? (Android; `false` on iOS) |
|
|
139
|
+
| `getBatteryOptimizationStatus()` / `useBatteryOptimizationStatus()` | Current status (Android; `'unrestricted'` on iOS) |
|
|
140
|
+
| `onBatteryWarningPendingChanged` / `onBatteryOptimizationStatusChanged` | Subscribe outside React. |
|
|
141
|
+
| `openBatterySettings()` | Prompt the user to lift the restriction (Android; see above for the permission the `'optimized'` dialog needs). |
|
|
142
|
+
| `dismissBatteryWarning()` | Dismiss the warning without changing settings (Android). |
|
package/website/guide/browser.md
CHANGED
|
@@ -4,13 +4,15 @@ description: 'The reference for configureBrowser: every source shape (static, ca
|
|
|
4
4
|
|
|
5
5
|
# Browser
|
|
6
6
|
|
|
7
|
-
The **Browser** is the subsystem that turns one declarative description of your content into a navigable tree — the same tree that powers your in-app browse UI, CarPlay, and Android Auto.
|
|
7
|
+
The **Browser** is the subsystem that turns one declarative description of your content into a navigable tree — the same tree that powers your in-app browse UI, CarPlay, and Android Auto.
|
|
8
|
+
|
|
9
|
+
You describe it once with **`configureBrowser`**; the library resolves paths, fetches children, transforms requests, and renders the native surfaces for you.
|
|
8
10
|
|
|
9
11
|
[Basic Usage](/guide/basic-usage) introduces the browse tree. This guide is the reference for _configuring_ it: every source shape, every routing pattern, and every option on [`BrowserConfiguration`](/api/types/browser/#browserconfiguration).
|
|
10
12
|
|
|
11
13
|
## A complete example
|
|
12
14
|
|
|
13
|
-
Here is a full, runnable configuration — call `setupPlayer` once, then `configureBrowser` once. It has two tabs,
|
|
15
|
+
Here is a full, runnable configuration — call `setupPlayer` once, then `configureBrowser` once. It has two tabs, two **static** routes, and one **callback** route. Paste it, swap in your own content, and you have a working browse tree on phone, CarPlay, and Android Auto.
|
|
14
16
|
|
|
15
17
|
```ts
|
|
16
18
|
import { setupPlayer, configureBrowser } from 'react-native-audio-browser'
|
|
@@ -38,6 +40,13 @@ configureBrowser({
|
|
|
38
40
|
'/browse/jazz': async () => {
|
|
39
41
|
const stations = await fetchJazzStations() // your code
|
|
40
42
|
return { path: '/browse/jazz', title: 'Jazz', children: stations }
|
|
43
|
+
},
|
|
44
|
+
'/favorites': {
|
|
45
|
+
path: '/favorites',
|
|
46
|
+
title: 'Favorites',
|
|
47
|
+
children: [
|
|
48
|
+
{ title: 'Smooth Floret FM', src: 'https://example.com/floret.mp3' }
|
|
49
|
+
]
|
|
41
50
|
}
|
|
42
51
|
}
|
|
43
52
|
})
|
|
@@ -70,13 +79,22 @@ A **page** is a [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack): it r
|
|
|
70
79
|
path: '/home',
|
|
71
80
|
title: 'Home',
|
|
72
81
|
sections: [
|
|
73
|
-
{
|
|
82
|
+
{
|
|
83
|
+
title: 'Popular',
|
|
84
|
+
style: { display: 'grid', gridWrap: false },
|
|
85
|
+
path: '/popular',
|
|
86
|
+
children: [...]
|
|
87
|
+
},
|
|
74
88
|
{ title: 'All stations', children: [...] }
|
|
75
89
|
]
|
|
76
90
|
}
|
|
77
91
|
```
|
|
78
92
|
|
|
79
|
-
A Section is `{ title?, style?, path?, children }
|
|
93
|
+
A Section is `{ title?, style?, path?, children }`. `title` renders as a header above its tracks. `style` is a declaration block whose `display` picks the children's layout: `'list'` rows (the default) or `'grid'` artwork tiles, with `gridWrap: false` keeping the grid to a single line.
|
|
94
|
+
|
|
95
|
+
`path` is the navigation target for the section's "view all" affordance.
|
|
96
|
+
|
|
97
|
+
See [Presentation](#presentation) for how each surface renders the declarations.
|
|
80
98
|
|
|
81
99
|
A flat page doesn't have to spell that out: authoring a plain `children: Track[]` — as most examples in this guide do — is sugar for one untitled section. Resolved output always carries `sections`; `children` is never populated on a resolved page.
|
|
82
100
|
|
|
@@ -84,7 +102,7 @@ So configuring the Browser is really three decisions, covered in turn below: **w
|
|
|
84
102
|
|
|
85
103
|
## Source shapes
|
|
86
104
|
|
|
87
|
-
Wherever the Browser needs content — a route, the `tabs`, `search` — you supply a **source
|
|
105
|
+
Wherever the Browser needs content — a route, the `tabs`, `search` — you supply a **source**. A route's source is one of three shapes: static data, a callback, or an HTTP endpoint.
|
|
88
106
|
|
|
89
107
|
### 1. Static data
|
|
90
108
|
|
|
@@ -115,7 +133,7 @@ A function `({ path, routeParams }) => ResolvedTrack` (sync or async). Resolve c
|
|
|
115
133
|
configureBrowser({
|
|
116
134
|
routes: {
|
|
117
135
|
'/albums/{id}': async ({ routeParams }) => {
|
|
118
|
-
const album = await fetchAlbum(routeParams
|
|
136
|
+
const album = await fetchAlbum(routeParams?.id) // your code
|
|
119
137
|
return {
|
|
120
138
|
path: `/albums/${album.id}`,
|
|
121
139
|
title: album.name,
|
|
@@ -146,8 +164,8 @@ configureBrowser({
|
|
|
146
164
|
On an HTTP route, the _navigated_ path is used as the request path — a static `path` field is ignored for this. To remap (e.g. send `/favorites` to `/favorites/v2`), use a [transform](#transforms-per-request), which also receives `routeParams`.
|
|
147
165
|
:::
|
|
148
166
|
|
|
149
|
-
::: tip
|
|
150
|
-
`tabs`
|
|
167
|
+
::: tip Tabs and search
|
|
168
|
+
`tabs` accepts the same three shapes, but its static form and its callback give a `Track[]`, not a page. `search` accepts a callback or an HTTP endpoint, with no static form. Its callback receives the search params and returns a `Track[]`:
|
|
151
169
|
|
|
152
170
|
```ts
|
|
153
171
|
configureBrowser({
|
|
@@ -172,12 +190,14 @@ configureBrowser({
|
|
|
172
190
|
})
|
|
173
191
|
```
|
|
174
192
|
|
|
175
|
-
::: warning
|
|
176
|
-
|
|
193
|
+
::: warning Car surfaces show only the first few tabs
|
|
194
|
+
Android Auto shows the first **4** tabs. CarPlay shows as many as `CPTabBarTemplate.maximumTabCount` allows. Only those surfaces hide the extra tabs: `getTabs` and `useTabs` return every tab. A debug build warns when a static `tabs` array has more tabs than Android Auto shows.
|
|
177
195
|
:::
|
|
178
196
|
|
|
179
197
|
::: tip A tab's path stays a tab
|
|
180
|
-
Link freely to a tab's own path — a "view all" section header on one tab pointing at another tab's route, say. On CarPlay (iOS 17+) that **switches to the tab** instead of pushing a second copy of it onto the current tab's stack
|
|
198
|
+
Link freely to a tab's own path — a "view all" section header on one tab pointing at another tab's route, say. On CarPlay (iOS 17+) that **switches to the tab** instead of pushing a second copy of it onto the current tab's stack.
|
|
199
|
+
|
|
200
|
+
The user lands where the tab bar already shows that content, with no Back button to a page they never came from. Elsewhere — earlier iOS, Android Auto, your app UI — it navigates as usual.
|
|
181
201
|
:::
|
|
182
202
|
|
|
183
203
|
Like any source, `tabs` can also be a **callback** — useful when the tabs themselves depend on runtime state, such as a debug build or the current user:
|
|
@@ -198,7 +218,8 @@ configureBrowser({
|
|
|
198
218
|
|
|
199
219
|
```ts
|
|
200
220
|
configureBrowser({
|
|
201
|
-
|
|
221
|
+
// where browse opens; defaults to the first tab's path (or '/')
|
|
222
|
+
path: '/home',
|
|
202
223
|
tabs: [
|
|
203
224
|
/* … */
|
|
204
225
|
]
|
|
@@ -218,7 +239,9 @@ Patterns match on **exact segment count** first — `/artists` does _not_ match
|
|
|
218
239
|
| `/favorites` | exactly `/favorites` | — |
|
|
219
240
|
| `/albums/{id}` | `/albums/floret`, `/albums/42` | `routeParams.id` |
|
|
220
241
|
| `/artists/*` | any single segment at that position (`/artists/anything`) | — |
|
|
221
|
-
| `/files/**` | `/files/...` at any depth below
|
|
242
|
+
| `/files/**` | `/files` itself, and `/files/...` at any depth below | `routeParams.tail` |
|
|
243
|
+
|
|
244
|
+
On `/files` itself, `routeParams.tail` is `undefined`.
|
|
222
245
|
|
|
223
246
|
When several patterns match, **most specific wins**: constant > `{param}` > `*` > `**`. So `/albums/new` and `/albums/{id}` can coexist — `/albums/new` takes the literal route.
|
|
224
247
|
|
|
@@ -228,15 +251,17 @@ configureBrowser({
|
|
|
228
251
|
// literal — checked first
|
|
229
252
|
'/albums/new': newReleasesPage,
|
|
230
253
|
// {id} otherwise
|
|
231
|
-
'/albums/{id}': ({ routeParams }) => fetchAlbum(routeParams
|
|
254
|
+
'/albums/{id}': ({ routeParams }) => fetchAlbum(routeParams?.id),
|
|
232
255
|
// deep file paths
|
|
233
|
-
'/files/**': ({ routeParams }) => listFiles(routeParams
|
|
256
|
+
'/files/**': ({ routeParams }) => listFiles(routeParams?.tail)
|
|
234
257
|
}
|
|
235
258
|
})
|
|
236
259
|
```
|
|
237
260
|
|
|
238
261
|
::: warning The bare `'*'` key is the _default_, not a wildcard segment
|
|
239
|
-
A single-segment wildcard only works as a `*` **segment inside a longer pattern** (e.g. `/artists/*`).
|
|
262
|
+
A single-segment wildcard only works as a `*` **segment inside a longer pattern** (e.g. `/artists/*`).
|
|
263
|
+
|
|
264
|
+
The bare top-level key `'*'` is different: it's the **custom default** — the source used for any path no other route matches (and only needed if you want to override the built-in HTTP default).
|
|
240
265
|
|
|
241
266
|
```ts
|
|
242
267
|
routes: {
|
|
@@ -256,20 +281,19 @@ A callback (or transform) receives the captured params in `routeParams`:
|
|
|
256
281
|
```ts
|
|
257
282
|
'/stations/{country}/{city}': async ({ routeParams }) => {
|
|
258
283
|
// /stations/nl/amsterdam → { country: 'nl', city: 'amsterdam' }
|
|
259
|
-
return fetchStations(routeParams
|
|
284
|
+
return fetchStations(routeParams?.country, routeParams?.city)
|
|
260
285
|
}
|
|
261
286
|
```
|
|
262
287
|
|
|
263
288
|
### Per-route overrides
|
|
264
289
|
|
|
265
|
-
A route value can be a bare source (the common case) **or** a [`RouteConfig`](/api/types/browser/#routeconfig) object that overrides request behavior for just that subtree — its `browse` source, plus its own `
|
|
290
|
+
A route value can be a bare source (the common case) **or** a [`RouteConfig`](/api/types/browser/#routeconfig) object that overrides request behavior for just that subtree — its `browse` source, plus its own `artwork` config. The web ignores a route's `artwork` and uses the top-level `artwork` config.
|
|
266
291
|
|
|
267
292
|
```ts
|
|
268
293
|
configureBrowser({
|
|
269
294
|
routes: {
|
|
270
295
|
'/premium/**': {
|
|
271
|
-
browse: { baseUrl: 'https://api.example.com
|
|
272
|
-
media: { baseUrl: 'https://premium-audio.cdn.example.com' },
|
|
296
|
+
browse: { baseUrl: 'https://premium-api.example.com' },
|
|
273
297
|
artwork: { baseUrl: 'https://premium-images.cdn.example.com' }
|
|
274
298
|
}
|
|
275
299
|
}
|
|
@@ -294,26 +318,29 @@ configureBrowser({
|
|
|
294
318
|
request: { baseUrl: 'https://api.example.com', headers: { 'x-app': 'demo' } },
|
|
295
319
|
browse: { query: { client: 'audio-browser', hl: 'en' } },
|
|
296
320
|
routes: {
|
|
297
|
-
//
|
|
298
|
-
|
|
321
|
+
// adds genre=jazz on top of the request and browse layers;
|
|
322
|
+
// the navigated path is the request path
|
|
323
|
+
'/browse/jazz': { query: { genre: 'jazz' } }
|
|
299
324
|
}
|
|
300
325
|
})
|
|
301
326
|
```
|
|
302
327
|
|
|
328
|
+
A path that needs nothing extra needs no route at all: an unmatched path is fetched through `request` and `browse`. An empty route object (`{}`) is not a request config: it is read as a static page with no `path` or `title`. On iOS and Android `configureBrowser` throws on it, on web it renders a blank page, and a debug build warns about it.
|
|
329
|
+
|
|
303
330
|
### RequestConfig fields
|
|
304
331
|
|
|
305
|
-
Every request layer is a [`RequestConfig`](/api/types/browser/#requestconfig) — set only the fields you need
|
|
332
|
+
Every request layer is a [`RequestConfig`](/api/types/browser/#requestconfig) — set only the fields you need. Headers and query params merge key by key; other fields override:
|
|
306
333
|
|
|
307
|
-
| Field | Purpose
|
|
308
|
-
| ---------------------- |
|
|
309
|
-
| `baseUrl` / `path` | Where to send the request (note: `path` doesn't override the navigated browse path)
|
|
310
|
-
| `method` | `GET` (default), `POST`, …
|
|
311
|
-
| `headers` | HTTP headers
|
|
312
|
-
| `query` | Query parameters (merged
|
|
313
|
-
| `body` / `contentType` | Request body,
|
|
314
|
-
| `userAgent` | `User-Agent` override
|
|
334
|
+
| Field | Purpose |
|
|
335
|
+
| ---------------------- | ------------------------------------------------------------------------------------ |
|
|
336
|
+
| `baseUrl` / `path` | Where to send the request (note: `path` doesn't override the navigated browse path) |
|
|
337
|
+
| `method` | `GET` (default), `POST`, … |
|
|
338
|
+
| `headers` | HTTP headers (merged key by key) |
|
|
339
|
+
| `query` | Query parameters (merged key by key) |
|
|
340
|
+
| `body` / `contentType` | Request body, sent for `POST`, `PUT` and `PATCH` (and `DELETE` when set); not on web |
|
|
341
|
+
| `userAgent` | `User-Agent` override (a `User-Agent` in `headers` wins on iOS); ignored on web |
|
|
315
342
|
|
|
316
|
-
### Transforms
|
|
343
|
+
### Transforms: per request
|
|
317
344
|
|
|
318
345
|
When a layer needs to change _per request_ (read the captured `routeParams`, switch a `GET` to a `POST`, remap the path), add a `transform` (async) or `transformSync`. It receives the merged request and returns the final one:
|
|
319
346
|
|
|
@@ -339,9 +366,11 @@ configureBrowser({
|
|
|
339
366
|
})
|
|
340
367
|
```
|
|
341
368
|
|
|
342
|
-
### Resolvers
|
|
369
|
+
### Resolvers: values that change rarely
|
|
370
|
+
|
|
371
|
+
When the _whole_ config depends on runtime state — a domain that varies by environment, a locale, an auth host — make the layer a **resolver**: a thunk returning the config.
|
|
343
372
|
|
|
344
|
-
|
|
373
|
+
It runs **once per content generation** and is cached until you call [`invalidateAllContent`](#updating-the-configuration), so it's the cheap place to read values that change rarely:
|
|
345
374
|
|
|
346
375
|
```ts
|
|
347
376
|
configureBrowser({
|
|
@@ -381,12 +410,15 @@ configureBrowser({
|
|
|
381
410
|
|
|
382
411
|
With `imageQueryParams`, CarPlay and Android Auto's requested size is injected automatically (`?w=200&h=200`) so each surface gets right-sized art. For full control, an `artwork.transform` receives that size as an [`ImageContext`](/api/types/browser/#imagecontext).
|
|
383
412
|
|
|
384
|
-
**Now-playing art** can differ from browse-row art — set `nowPlayingArtwork` for the lock screen / car now-playing surface only.
|
|
413
|
+
**Now-playing art** can differ from browse-row art — set `nowPlayingArtwork` for the lock screen / car now-playing surface only. Like `artwork`, it can use an `{id}` template filled from the active track's `id`:
|
|
385
414
|
|
|
386
415
|
```ts
|
|
416
|
+
// {id} templating (in any artwork config) is native-only:
|
|
417
|
+
// the web implementation does not apply it
|
|
387
418
|
configureBrowser({
|
|
388
|
-
|
|
389
|
-
|
|
419
|
+
// {id} → the active track's id
|
|
420
|
+
nowPlayingArtwork: { path: '/artwork/{id}' }
|
|
421
|
+
})
|
|
390
422
|
```
|
|
391
423
|
|
|
392
424
|
See [Now Playing](/guide/now-playing) for the metadata side of the now-playing surface.
|
|
@@ -395,11 +427,19 @@ See [Now Playing](/guide/now-playing) for the metadata side of the now-playing s
|
|
|
395
427
|
|
|
396
428
|
Two options control what happens when a playable Track is tapped.
|
|
397
429
|
|
|
398
|
-
**`singleTrack`** — by default, tapping a track queues **its section** and starts there, so next/previous walk the list the user tapped in.
|
|
430
|
+
**`singleTrack`** — by default, tapping a track queues **its section** and starts there, so next/previous walk the list the user tapped in.
|
|
431
|
+
|
|
432
|
+
The scope is the page's declared structure: the tapped [Section](#how-a-path-resolves)'s `children`, identical on every surface (a page authored with plain `children` is one untitled section). Rendering may truncate what a section _shows_ — a CarPlay single-line grid fits only so many tiles — but never what _plays_.
|
|
399
433
|
|
|
400
|
-
|
|
434
|
+
A page aggregating several sections never leaks next/previous across them. Set `singleTrack: true` to play only the tapped track. If the track has meanwhile disappeared from its section (a stale resume, say), the library plays it as a single track rather than guessing a queue from the changed list.
|
|
401
435
|
|
|
402
|
-
|
|
436
|
+
Section scoping knows _where_ the tap happened, not just on what. Each playable row's path carries the track's identity (`id`, falling back to `src`) and the row's position on the page.
|
|
437
|
+
|
|
438
|
+
So the same track can safely appear in several places on one page: a tap queues the section it happened in, and when a playlist holds the same track twice, next/previous continue from the tapped copy.
|
|
439
|
+
|
|
440
|
+
The position is only a tie-breaker. If the page has changed by the time the queue is expanded (a stale resume, say), the first row matching the identity wins instead — a stale position can pick a different copy of the tapped track, never a different track.
|
|
441
|
+
|
|
442
|
+
Tapping a row that's already in the current queue from the same page skips in place rather than requeueing the section.
|
|
403
443
|
|
|
404
444
|
**`handleTrackLoad`** — intercept loading entirely. When set, tapping a track calls _your_ handler **instead of** the library auto-playing, and native waits for your promise to resolve before continuing. The two branches differ:
|
|
405
445
|
|
|
@@ -420,7 +460,9 @@ configureBrowser({
|
|
|
420
460
|
})
|
|
421
461
|
```
|
|
422
462
|
|
|
423
|
-
In the video branch, returning without calling the player tells the library
|
|
463
|
+
In the video branch, returning without calling the player tells the library the tap is handled and audio stays as it is. In the audio branch, call [`setQueue` and `play`](/guide/basic-usage) yourself. Both return `void`, so there is nothing to await on them.
|
|
464
|
+
|
|
465
|
+
Native **awaits the promise your handler returns**. Anything you `await` inside, such as an auth check or a fetch, delays the tap being treated as handled. Keep slow work out of the handler, or start it without awaiting it.
|
|
424
466
|
|
|
425
467
|
## Reading and driving browse state
|
|
426
468
|
|
|
@@ -473,7 +515,9 @@ The tree isn't static — content changes, languages switch, environments move.
|
|
|
473
515
|
| Everything is stale (locale, domain, auth changed) | `invalidateAllContent()` |
|
|
474
516
|
| The config _shape_ itself changed | `configureBrowser(newConfig)` |
|
|
475
517
|
|
|
476
|
-
`notifyContentChanged(path)` refreshes a single path in place — external controllers re-fetch just that page. `invalidateAllContent()` clears every cache and re-resolves all visible surfaces (and re-runs your [resolvers](#resolvers-values-that-change-rarely)) — this is what you call after a language or domain switch.
|
|
518
|
+
`notifyContentChanged(path)` refreshes a single path in place — external controllers re-fetch just that page. `invalidateAllContent()` clears every cache and re-resolves all visible surfaces (and re-runs your [resolvers](#resolvers-values-that-change-rarely)) — this is what you call after a language or domain switch.
|
|
519
|
+
|
|
520
|
+
`configureBrowser` replaces everything wholesale and re-runs initial navigation: the in-app browser opens `path` (or the first tab) again. On web it opens the first tab only when `tabs` is an array, and `/` otherwise. CarPlay and Android Auto keep their place; if the tabs changed, CarPlay rebuilds its tab bar once the user is back at the root.
|
|
477
521
|
|
|
478
522
|
```ts
|
|
479
523
|
// language changed → resolvers read the new locale on the next resolve
|
|
@@ -506,37 +550,56 @@ configureBrowser({
|
|
|
506
550
|
})
|
|
507
551
|
```
|
|
508
552
|
|
|
509
|
-
|
|
553
|
+
For the `code` values, see [Navigation errors](/guide/errors#navigation-errors). Your formatter drives both the car dialogs and the [`useFormattedNavigationError`](/api/features/errors/#useformattednavigationerror) hook in your app.
|
|
510
554
|
|
|
511
555
|
## Presentation
|
|
512
556
|
|
|
513
557
|
Presentation lives in `style` blocks, separate from content, plus a few Track fields and config options. Each surface applies the style properties it supports and ignores the rest — an unsupported property is a no-op, never an error.
|
|
514
558
|
|
|
515
|
-
| Field | On | Effect
|
|
516
|
-
| ------------------------------------------------ | ------------------------ |
|
|
517
|
-
| `title` | a section | header above its tracks
|
|
518
|
-
| `style: { display: 'grid' }` | a section | wrapping artwork-tile grid
|
|
519
|
-
| `style: { display: 'grid', gridWrap: false }` | a section | a single line of artwork tiles
|
|
520
|
-
| `path` | a section | "view all" target
|
|
521
|
-
| `style` (same block) | a page | declaration for the whole page — a section overrides it for its own children
|
|
522
|
-
| `style: { display: 'grid' }` | a browsable track | the layout of the page it opens — Android Auto reads it from the parent item
|
|
523
|
-
| `style: { artworkRendering: 'stencil' }` | a track / section / page | tint monochrome artwork to the surface appearance
|
|
524
|
-
| `style: { imageShape: 'circular' }` | a track / section / page | crop `'image'` and `'condensed'` tile artwork circular (people)
|
|
525
|
-
| `style: { accessorySymbol: 'lock.fill' }` | a track / section / page | SF Symbol accessory on rows and on `'image'` / `'condensed'` tiles
|
|
526
|
-
| `style: { gridTile: 'card' }` | a section / page | the grid's tile kind: `'plain'` (default), `'image'`, `'card'`, or `'condensed'`
|
|
527
|
-
| `style: { cardTint: '#1e3a8a' }` (+ `cardImage`) | a track / section / page | card color and image mode (`'background'` fills the card full-height)
|
|
528
|
-
| `disabled: true` | a track | unavailable:
|
|
529
|
-
| `artwork: 'sf:heart.fill'` | any item | SF Symbol icon (supports `?bg=…&fg=…`)
|
|
530
|
-
| `live: true` | a track | live indicator
|
|
531
|
-
| `carPlaySiriListButton: 'top' \| 'bottom'` | a page | place the Siri cell on the page
|
|
532
|
-
| `albumPath`
|
|
559
|
+
| Field | On | Effect | Platform |
|
|
560
|
+
| ------------------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
|
|
561
|
+
| `title` | a section | header above its tracks | all |
|
|
562
|
+
| `style: { display: 'grid' }` | a section | wrapping artwork-tile grid | all\* |
|
|
563
|
+
| `style: { display: 'grid', gridWrap: false }` | a section | a single line of artwork tiles | all\* |
|
|
564
|
+
| `path` | a section | "view all" target: a tappable row on a CarPlay grid (none on a list); an appended `viewMoreTitle` row on Android Auto | all |
|
|
565
|
+
| `style` (same block) | a page | declaration for the whole page — a section overrides it for its own children | all |
|
|
566
|
+
| `style: { display: 'grid' }` | a browsable track | the layout of the page it opens — Android Auto reads it from the parent item | Android Auto / AAOS |
|
|
567
|
+
| `style: { artworkRendering: 'stencil' }` | a track / section / page | tint monochrome artwork to the surface appearance | CarPlay |
|
|
568
|
+
| `style: { imageShape: 'circular' }` | a track / section / page | crop `'image'` and `'condensed'` tile artwork circular (people) | CarPlay (iOS 26+) |
|
|
569
|
+
| `style: { accessorySymbol: 'lock.fill' }` | a track / section / page | SF Symbol accessory on rows and on `'image'` / `'condensed'` tiles | CarPlay |
|
|
570
|
+
| `style: { gridTile: 'card' }` | a section / page | the grid's tile kind: `'plain'` (default), `'image'`, `'card'`, or `'condensed'` | CarPlay (iOS 26+) |
|
|
571
|
+
| `style: { cardTint: '#1e3a8a' }` (+ `cardImage`) | a track / section / page | card color and image mode (`'background'` fills the card full-height) | CarPlay (iOS 26+) |
|
|
572
|
+
| `disabled: true` | a track | unavailable: taps, voice selection, queue expansion and resume refuse it, but a `setQueue` list is not filtered and plays it when reached; grayed where drawable, hidden elsewhere | all |
|
|
573
|
+
| `artwork: 'sf:heart.fill'` | any item | SF Symbol icon (supports `?bg=…&fg=…`) | iOS |
|
|
574
|
+
| `live: true` | a track | live indicator | iOS |
|
|
575
|
+
| `carPlaySiriListButton: 'top' \| 'bottom'` | a page | place the Siri cell on the page | iOS |
|
|
576
|
+
| `albumPath` or `resolveAlbumPath` | track or config | make the now-playing album line tappable | CarPlay |
|
|
533
577
|
|
|
534
578
|
::: info Caveats from the table
|
|
535
|
-
|
|
579
|
+
|
|
580
|
+
- **The album line needs `album`.** CarPlay draws the tappable line from the album metadata, so a track with no `album` has no line to tap.
|
|
581
|
+
- **\*Layouts render each platform's nearest supported form.** On CarPlay, a single-line grid (`gridWrap: false`) shows the tiles that fit on one line (about seven on a wide screen, or two condensed cells). A wrapping grid takes as many lines as it needs on iOS 26+, and is a list before that.
|
|
582
|
+
- **Android Auto's grid always wraps**, so it shows more, never less. No car surface scrolls horizontally. An app UI typically renders `gridWrap: false` as a horizontal scroller.
|
|
583
|
+
- **Truncation is visual only.** Tapping a tile queues the whole section (see [Playback behavior](#playback-behavior)).
|
|
584
|
+
- **Item properties are inherited.** `artworkRendering`, `imageShape` and `accessorySymbol` resolve as `track ?? section ?? page`, per property, so an item can override a section-wide value. `accessorySymbol: 'none'` removes an inherited symbol from one item.
|
|
585
|
+
- **The platform places the accessory.** It is trailing on list rows and condensed tiles, and leads the title on image tiles.
|
|
586
|
+
- **On an iOS 26 grid, `gridTile` decides what each tile draws.** `'plain'` has a subtitle but no shape and no accessory. `'image'` has a shape and an accessory but no subtitle. `'condensed'` has all three beside a small image. `'card'` has a subtitle, a tint and an image mode.
|
|
587
|
+
- **`display` is never inherited.** It describes the children of whatever it is set on. On a browsable track it declares the layout of the page the track opens: Android Auto needs it there, or that page renders as a list.
|
|
588
|
+
- **`gridWrap` is inert unless `display` is `'grid'`.**
|
|
589
|
+
- **AAOS honors only the parent item's `display`.** AOSP-based Automotive units render a page that mixes grid and list sections in one layout. See [Android Auto → Browse display](/guide/android-auto#browse-display).
|
|
590
|
+
|
|
536
591
|
:::
|
|
537
592
|
|
|
538
593
|
::: tip Inert declarations are logged in debug builds
|
|
539
|
-
|
|
594
|
+
Some combinations can never render. They are inert, not errors, so nothing breaks:
|
|
595
|
+
|
|
596
|
+
- `gridWrap` or `gridTile` outside a grid
|
|
597
|
+
- `cardTint` with no card treatment in scope
|
|
598
|
+
- `imageShape` anywhere but an image or condensed grid
|
|
599
|
+
- `accessorySymbol` on a plain or card grid
|
|
600
|
+
- `display` on a track that renders playable
|
|
601
|
+
|
|
602
|
+
In a **debug build**, each one is logged once per page resolution (`Timber` on Android, `os.log` on iOS) naming the section, the effective style, and the fix:
|
|
540
603
|
|
|
541
604
|
```
|
|
542
605
|
Inert style declaration on page '/home': `style.gridWrap` on section 'Featured'
|
|
@@ -551,14 +614,28 @@ A property a _surface_ can't draw is never reported — that's the aspirational
|
|
|
551
614
|
```ts
|
|
552
615
|
// A grid page. Android Auto also needs display: 'grid' on the item
|
|
553
616
|
// that opens this page — see the Android Auto guide:
|
|
554
|
-
{
|
|
617
|
+
{
|
|
618
|
+
path: '/genres',
|
|
619
|
+
title: 'Genres',
|
|
620
|
+
style: { display: 'grid' },
|
|
621
|
+
children: [...]
|
|
622
|
+
}
|
|
555
623
|
{
|
|
556
624
|
path: '/home',
|
|
557
625
|
title: 'Home',
|
|
558
626
|
sections: [
|
|
559
|
-
{
|
|
627
|
+
{
|
|
628
|
+
title: 'Popular',
|
|
629
|
+
style: { display: 'grid', gridWrap: false },
|
|
630
|
+
path: '/popular',
|
|
631
|
+
children: [...]
|
|
632
|
+
},
|
|
560
633
|
// Round tiles for people: the image tile is the one with a shape.
|
|
561
|
-
{
|
|
634
|
+
{
|
|
635
|
+
title: 'Artists',
|
|
636
|
+
style: { display: 'grid', gridTile: 'image', imageShape: 'circular' },
|
|
637
|
+
children: [...]
|
|
638
|
+
},
|
|
562
639
|
{ title: 'All stations', children: [...] }
|
|
563
640
|
]
|
|
564
641
|
}
|
|
@@ -570,10 +647,20 @@ A property a _surface_ can't draw is never reported — that's the aspirational
|
|
|
570
647
|
```
|
|
571
648
|
|
|
572
649
|
::: tip See every style rendered
|
|
573
|
-
The example app's **Style Lab** tab draws each `style` declaration on CarPlay: one page per `gridTile` value, plus pages for section headers and for inheritance from page to section to track.
|
|
650
|
+
The example app's **Style Lab** tab draws each `style` declaration on CarPlay: one page per `gridTile` value, plus pages for section headers and for inheritance from page to section to track.
|
|
651
|
+
|
|
652
|
+
Every shelf is titled with the block it renders, so what you see on screen names what to copy.
|
|
653
|
+
|
|
654
|
+
The pages are plain route data in [`style-lab.ts`](https://github.com/radio-garden/react-native-audio-browser/blob/next/apps/example-native/src/utils/style-lab.ts), with a comment on each example saying what it shows.
|
|
574
655
|
:::
|
|
575
656
|
|
|
576
|
-
|
|
657
|
+
Three config-level platform options round it out:
|
|
658
|
+
|
|
659
|
+
- `carPlayLoadingTitle`: a localized "Loading…" on older CarPlay.
|
|
660
|
+
- `androidControllerOfflineError`: shows an offline error in Android Auto and other external controllers when the network is lost. It defaults to `true`.
|
|
661
|
+
- [`viewMoreTitle`](/api/types/browser/#viewmoretitle): titles the "view more" row Android Auto appends to a section with a `path`. It is read again on `invalidateAllContent()`.
|
|
662
|
+
|
|
663
|
+
The CarPlay now-playing album line is tappable when the active track has an `albumPath`. For tracks without one, a `resolveAlbumPath` callback maps the track to a browse path. In both cases the track needs an `album`. See [CarPlay](/guide/carplay) and [Android Auto](/guide/android-auto) for the platform setup these build on.
|
|
577
664
|
|
|
578
665
|
## Where to go next
|
|
579
666
|
|