react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.55
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
|
@@ -1,23 +1,24 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: '
|
|
2
|
+
description: 'Pause playback after a fixed time or at the end of the current track, counted down natively so it fires with the app backgrounded or the screen off.'
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Sleep Timer
|
|
6
6
|
|
|
7
|
-
A **sleep timer**
|
|
7
|
+
A **sleep timer** pauses playback on its own after a set time — the classic
|
|
8
8
|
"fall asleep to the radio" feature. The library runs the timer natively, so it
|
|
9
9
|
keeps counting down and fires even when your app is backgrounded or the screen
|
|
10
10
|
is off. There are two kinds:
|
|
11
11
|
|
|
12
12
|
- **Time-based** — pause after a fixed number of seconds (e.g. "in 30 minutes").
|
|
13
|
-
- **End of track** — pause when the current track finishes playing
|
|
13
|
+
- **End of track** — pause when the current track finishes playing (see
|
|
14
|
+
[Behavior and edge cases](#behavior-and-edge-cases) for skips and repeat).
|
|
14
15
|
|
|
15
16
|
Only one timer is active at a time; setting a new one replaces the old.
|
|
16
17
|
|
|
17
18
|
## Setting a timer
|
|
18
19
|
|
|
19
|
-
Call `setSleepTimer` with a duration in **seconds**. This example
|
|
20
|
-
after 30 minutes:
|
|
20
|
+
Call `setSleepTimer` with a duration in **seconds**. This example pauses
|
|
21
|
+
playback after 30 minutes:
|
|
21
22
|
|
|
22
23
|
```ts
|
|
23
24
|
import { setSleepTimer } from 'react-native-audio-browser'
|
|
@@ -29,7 +30,7 @@ Most UIs offer a few presets rather than a free-form duration — multiply the
|
|
|
29
30
|
minutes you show by 60:
|
|
30
31
|
|
|
31
32
|
```ts
|
|
32
|
-
const PRESETS_MINUTES = [15, 30, 45, 60]
|
|
33
|
+
const PRESETS_MINUTES = [15, 30, 45, 60] as const
|
|
33
34
|
|
|
34
35
|
setSleepTimer(PRESETS_MINUTES[1] * 60) // 30 minutes
|
|
35
36
|
```
|
|
@@ -52,7 +53,7 @@ Pass a `fadeDuration` (in seconds) to ramp the volume down to silence as the
|
|
|
52
53
|
timer runs out — a gentler finish than an abrupt pause:
|
|
53
54
|
|
|
54
55
|
```ts
|
|
55
|
-
//
|
|
56
|
+
// Pause in 30 minutes, fading the last 20 seconds to silence.
|
|
56
57
|
setSleepTimer(30 * 60, { fadeDuration: 20 })
|
|
57
58
|
```
|
|
58
59
|
|
|
@@ -63,10 +64,15 @@ starts at normal loudness.
|
|
|
63
64
|
|
|
64
65
|
During the fade the timer takes priority: seeking or skipping plays into the
|
|
65
66
|
remaining ramp rather than cancelling it. Only pausing, or clearing/replacing
|
|
66
|
-
the timer, stops the fade.
|
|
67
|
-
|
|
67
|
+
the timer, stops the fade.
|
|
68
|
+
|
|
69
|
+
The countdown keeps ticking throughout, so you can show a "fading out" hint
|
|
70
|
+
once `secondsLeft` drops to `fadeDuration` (see the
|
|
68
71
|
[complete example](#a-complete-screen)).
|
|
69
72
|
|
|
73
|
+
While casting on Android, the timer pauses the receiver at the deadline without
|
|
74
|
+
fading: see [Google Cast](/guide/audio-output#google-cast-android).
|
|
75
|
+
|
|
70
76
|
## Clearing a timer
|
|
71
77
|
|
|
72
78
|
`clearSleepTimer` cancels the active timer. It returns `true` if a timer was
|
|
@@ -96,7 +102,7 @@ function SleepTimerLabel() {
|
|
|
96
102
|
|
|
97
103
|
if (!timer) return <Text>No sleep timer</Text>
|
|
98
104
|
if ('sleepWhenPlayedToEnd' in timer) {
|
|
99
|
-
return <Text>
|
|
105
|
+
return <Text>Pausing at end of track</Text>
|
|
100
106
|
}
|
|
101
107
|
|
|
102
108
|
const minutes = Math.floor(timer.secondsLeft / 60)
|
|
@@ -111,9 +117,11 @@ function SleepTimerLabel() {
|
|
|
111
117
|
|
|
112
118
|
The countdown only ticks while the app is in the foreground — `secondsLeft`
|
|
113
119
|
doesn't advance in the background (the native timer still fires on time
|
|
114
|
-
regardless).
|
|
115
|
-
|
|
116
|
-
|
|
120
|
+
regardless).
|
|
121
|
+
|
|
122
|
+
The only reason to care is to avoid pointless per-second re-renders while
|
|
123
|
+
backgrounded: derive the `inactive` flag from React Native's `AppState` and
|
|
124
|
+
pass it in. You can also tune the refresh rate with `updateInterval`
|
|
117
125
|
(milliseconds, default `1000`):
|
|
118
126
|
|
|
119
127
|
```tsx
|
|
@@ -201,7 +209,7 @@ function Status(props: {
|
|
|
201
209
|
const { timer, fadeSeconds } = props
|
|
202
210
|
if (!timer) return <Text>No sleep timer</Text>
|
|
203
211
|
if ('sleepWhenPlayedToEnd' in timer) {
|
|
204
|
-
return <Text>
|
|
212
|
+
return <Text>Pausing at end of track</Text>
|
|
205
213
|
}
|
|
206
214
|
if (timer.secondsLeft <= fadeSeconds) return <Text>Fading out…</Text>
|
|
207
215
|
|
|
@@ -254,6 +262,19 @@ unsubscribe()
|
|
|
254
262
|
matters.
|
|
255
263
|
- **Nothing throws.** Every function here is synchronous; the setters return
|
|
256
264
|
`void` and `clearSleepTimer` returns a boolean. No `try/catch` needed.
|
|
265
|
+
- **Set it after setup.** On iOS and Android, a setter called before
|
|
266
|
+
`setupPlayer` has resolved is ignored without an error, and `getSleepTimer`
|
|
267
|
+
stays `null`.
|
|
268
|
+
- **End of track when the track changes early, on iOS.** Any change of current
|
|
269
|
+
track before it ends (a skip, a new queue) cancels an end-of-track timer, and
|
|
270
|
+
`onSleepTimerChanged` fires with `null`.
|
|
271
|
+
- **End of track when the track changes early, on Android and web.** The timer
|
|
272
|
+
stays set through a skip or a new queue, and it pauses at the end of the next
|
|
273
|
+
track that plays to its end.
|
|
274
|
+
- **End of track with repeat-track on Android.** While the repeat mode is
|
|
275
|
+
`track`, an end-of-track timer never fires on Android, because the track loops
|
|
276
|
+
without ending. On iOS and web it pauses at the end of the current
|
|
277
|
+
play-through.
|
|
257
278
|
|
|
258
279
|
## API summary
|
|
259
280
|
|
package/website/guide/track.md
CHANGED
|
@@ -31,9 +31,9 @@ const episode: Track = {
|
|
|
31
31
|
|
|
32
32
|
This guide is the field-by-field reference. For _where_ tracks come from (routes, callbacks, HTTP) see the [Browser](/guide/browser) guide.
|
|
33
33
|
|
|
34
|
-
## Browsable
|
|
34
|
+
## Browsable or playable
|
|
35
35
|
|
|
36
|
-
Two fields decide what a Track _does_. A Track must set at least one of them
|
|
36
|
+
Two fields decide what a Track _does_. A Track must set at least one of them:
|
|
37
37
|
|
|
38
38
|
| Field | Makes the track | Effect |
|
|
39
39
|
| ------ | --------------- | ---------------------------------------------------- |
|
|
@@ -46,11 +46,10 @@ Two fields decide what a Track _does_. A Track must set at least one of them, an
|
|
|
46
46
|
|
|
47
47
|
// Playable: a station you stream
|
|
48
48
|
{ title: 'Smooth Floret FM', src: 'https://example.com/floret.mp3' }
|
|
49
|
-
|
|
50
|
-
// Both: a podcast episode you can open *and* play
|
|
51
|
-
{ title: 'Episode 42', path: '/episodes/42', src: 'https://…/42.mp3' }
|
|
52
49
|
```
|
|
53
50
|
|
|
51
|
+
Set exactly one. On a browse page a track that sets both plays: the library replaces its `path` with one that points back to the page it appears on.
|
|
52
|
+
|
|
54
53
|
`src` is usually an absolute audio URL, but it can be any string — a file path or your own identifier — that you turn into a real request in `media.resolve` (see [Browser → Media and artwork](/guide/browser#media-and-artwork)).
|
|
55
54
|
|
|
56
55
|
## Identity: `id`
|
|
@@ -72,7 +71,9 @@ The event also carries `index`, `lastTrack`, and `lastIndex`; `addListener` retu
|
|
|
72
71
|
`id` is also passed to the per-track `resolve` hooks, so you can set `src` to the same stable identifier and synthesise the real request/artwork from it at request time.
|
|
73
72
|
|
|
74
73
|
::: tip `id` is optional
|
|
75
|
-
A track's identity is its `id`, falling back to `src` — so if the same item's `src` string is identical wherever it appears, you can skip `id` entirely.
|
|
74
|
+
A track's identity is its `id`, falling back to `src` — so if the same item's `src` string is identical wherever it appears, you can skip `id` entirely.
|
|
75
|
+
|
|
76
|
+
Set ids consistently across your content or not at all: identity is compared whole, and a row carrying an `id` never matches a track without one. To compare tracks the same way in your own code, use [`getTrackIdentity`](/api/utils/getTrackIdentity/).
|
|
76
77
|
:::
|
|
77
78
|
|
|
78
79
|
## Display fields
|
|
@@ -104,7 +105,7 @@ Set `artwork` to an image URL. It's transformed through your [artwork configurat
|
|
|
104
105
|
|
|
105
106
|
Don't set `artworkSource` yourself — the library populates it.
|
|
106
107
|
|
|
107
|
-
**SF Symbols (iOS).** Prefix `artwork` with `sf:` to use a system symbol, with optional colors
|
|
108
|
+
**SF Symbols (iOS).** Prefix `artwork` with `sf:` to use a system symbol, with optional colors: `bg` (background) and `fg` (symbol). On the lock screen and in `artworkSource`, an omitted `bg` is transparent and an omitted `fg` is black:
|
|
108
109
|
|
|
109
110
|
```ts
|
|
110
111
|
{
|
|
@@ -114,15 +115,19 @@ Don't set `artworkSource` yourself — the library populates it.
|
|
|
114
115
|
}
|
|
115
116
|
```
|
|
116
117
|
|
|
117
|
-
On CarPlay, an SF Symbol with no
|
|
118
|
+
On CarPlay, an SF Symbol with no `fg` adapts to light/dark mode automatically: black on light grey or white on dark grey, and a `bg` alone is ignored.
|
|
119
|
+
|
|
120
|
+
**Tinting (`style: { artworkRendering: 'stencil' }`).** For monochrome icons, declare this so CarPlay tints them per appearance — black in light mode, white in dark. Use it for icons, not full-color album art. iOS CarPlay only; for Android Auto see [Tinting and platform icons](/guide/artwork#tinting-and-platform-icons).
|
|
118
121
|
|
|
119
|
-
|
|
122
|
+
On Android Auto, when a list or grid `display` applies and `artwork` is an `android.resource://` URI, the library asks for the category style, which adds margins around small icons.
|
|
120
123
|
|
|
121
124
|
**Light and dark images.** When the appearances need genuinely different artwork rather than the same shape recolored, set `artwork` to an [`ArtworkVariants`](/api/types/browser-nodes/#artworkvariants) pair — `{ light, dark }`. CarPlay adapts between them in place; everywhere that needs a single image uses `dark`. See [Artwork → Light and dark](/guide/artwork#light-and-dark-artwork).
|
|
122
125
|
|
|
123
126
|
## Per-track request override
|
|
124
127
|
|
|
125
|
-
[`request`](/api/types/browser-nodes/#trackrequest) is a **narrow** per-track
|
|
128
|
+
[`request`](/api/types/browser-nodes/#trackrequest) is a **narrow** per-track field for _how_ this track's audio request should be made.
|
|
129
|
+
|
|
130
|
+
[`TrackRequest`](/api/types/browser-nodes/#trackrequest) says which platforms merge it into the media request. Where they don't, return per-track headers or query from [`media.resolve`](/api/types/browser/#mediarequestconfig) (or `resolveSync`), which receives the track.
|
|
126
131
|
|
|
127
132
|
```ts
|
|
128
133
|
{
|
|
@@ -132,28 +137,31 @@ On CarPlay, an SF Symbol with no explicit colors adapts to light/dark mode autom
|
|
|
132
137
|
}
|
|
133
138
|
```
|
|
134
139
|
|
|
135
|
-
It carries only `userAgent`, `headers`, and `query` —
|
|
140
|
+
It carries only `userAgent`, `headers`, and `query` — **not** `baseUrl` / `path` / `method` / `body`, so a track (often server-sourced) can't repoint its own host or verb. Like every field, it round-trips verbatim through the queue.
|
|
136
141
|
|
|
137
142
|
## Presentation on native surfaces
|
|
138
143
|
|
|
139
144
|
Optional fields that change how a Track renders on CarPlay / Android Auto. Each surface applies the ones it supports; an unsupported field is a no-op, never an error.
|
|
140
145
|
|
|
141
|
-
| Field | Effect
|
|
142
|
-
| ------------------------------------------ |
|
|
143
|
-
| `style: { display: 'list' \| 'grid' }` | on a browsable track: the layout of the page it opens
|
|
144
|
-
| `style: { artworkRendering: 'stencil' }` | tint monochrome artwork to the surface appearance
|
|
145
|
-
| `style: { imageShape: 'circular' }` | crop `'image'` and `'condensed'` tile artwork circular (people)
|
|
146
|
-
| `style: { accessorySymbol: '…' }` | SF Symbol accessory; `'none'` restores the derived accessory
|
|
147
|
-
| `style: { cardTint: '…', cardImage: '…' }` | card color and image mode, when the section renders `gridTile: 'card'`
|
|
148
|
-
| `disabled` | unavailable:
|
|
149
|
-
| `favorited` | filled/empty heart (needs the `favorite` capability)
|
|
150
|
-
| `live` | a "live" indicator
|
|
151
|
-
| `albumPath` | make the now-playing album line tappable
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
146
|
+
| Field | Effect | Platform |
|
|
147
|
+
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
|
|
148
|
+
| `style: { display: 'list' \| 'grid' }` | on a browsable track: the layout of the page it opens | Android Auto / AAOS |
|
|
149
|
+
| `style: { artworkRendering: 'stencil' }` | tint monochrome artwork to the surface appearance | CarPlay |
|
|
150
|
+
| `style: { imageShape: 'circular' }` | crop `'image'` and `'condensed'` tile artwork circular (people) | CarPlay (iOS 26+) |
|
|
151
|
+
| `style: { accessorySymbol: '…' }` | SF Symbol accessory; `'none'` restores the derived accessory | CarPlay |
|
|
152
|
+
| `style: { cardTint: '…', cardImage: '…' }` | card color and image mode, when the section renders `gridTile: 'card'` | CarPlay (iOS 26+) |
|
|
153
|
+
| `disabled` | 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 |
|
|
154
|
+
| `favorited` | filled/empty heart (Android: needs the `favorite` capability; CarPlay: needs `'favorite'` in `ios.carPlayNowPlayingButtons`) | Android Auto, notification, CarPlay now-playing |
|
|
155
|
+
| `live` | a "live" indicator | iOS now-playing |
|
|
156
|
+
| `albumPath` | make the now-playing album line tappable | CarPlay |
|
|
157
|
+
|
|
158
|
+
Constraints worth knowing:
|
|
159
|
+
|
|
160
|
+
- **`display` goes on the browsable track as it appears in its parent's list** — Android Auto reads it there, before the page resolves, to decide how to lay out the page once you navigate in.
|
|
161
|
+
|
|
162
|
+
It is only sent when you declare it — the library never infers it from the page's content. The drilled-into page's own sections override it per section via their `style`.
|
|
163
|
+
|
|
164
|
+
- **`live` is more than an indicator.** On iOS it decides how a dropped or stalled stream recovers and stops a resume from seeking a stale position; on every platform, [`seekToLiveEdge()`](/api/features/playback/#seektoliveedge) does nothing unless the active track is declared live. Declare it on every live track — see [Live streams](/guide/live-streams).
|
|
157
165
|
- **`albumPath` requires `album`** (CarPlay renders the tappable line from album metadata), and pairs with `resolveAlbumPath` in the [Browser config](/guide/browser).
|
|
158
166
|
|
|
159
167
|
```ts
|
|
@@ -167,13 +175,19 @@ A couple of constraints worth knowing:
|
|
|
167
175
|
}
|
|
168
176
|
```
|
|
169
177
|
|
|
170
|
-
## Sections
|
|
178
|
+
## Sections: grouping and tile layouts
|
|
171
179
|
|
|
172
180
|
A Track appears in two roles. As a **row** in its parent's list it's a handle: its own `style.display` only advertises the layout of the page it opens (see [above](#presentation-on-native-surfaces)). Once resolved, that same Track **is the page** — a [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack) — and that is when it carries `sections`.
|
|
173
181
|
|
|
174
|
-
Headers and layout belong to the container role: declare them on the page's [`Section`](/api/types/browser-nodes/#section)s (`{ title?,
|
|
182
|
+
Headers and layout belong to the container role: declare them on the page's [`Section`](/api/types/browser-nodes/#section)s (`{ title?, style?, path?, children }`), never on the rows.
|
|
183
|
+
|
|
184
|
+
A section groups tracks under a header, and its `style` block's `display` picks their layout: `'list'` rows (the default) or `'grid'` artwork tiles — wrapping unless `gridWrap: false` keeps them to a single line.
|
|
185
|
+
|
|
186
|
+
The section's `path` is the navigation target for its header / "view all" surface; without one the header is a plain label, not a link — the section is self-contained.
|
|
187
|
+
|
|
188
|
+
A tile with `src` **plays immediately on tap** (same selection path as a playable list row — a station app can make tiles play their station directly); otherwise its `path` is navigated.
|
|
175
189
|
|
|
176
|
-
|
|
190
|
+
Tiles are ordinary Tracks, so playable ones carry the now-playing fields any track would (`id`, `artist`, `album`, `albumPath`, `live`, `request`). Tapping a playable child queues **its section** on every surface (see [Playback behavior](/guide/browser#playback-behavior)):
|
|
177
191
|
|
|
178
192
|
```ts
|
|
179
193
|
{
|
|
@@ -185,7 +199,11 @@ A tile with `src` **plays immediately on tap** (same selection path as a playabl
|
|
|
185
199
|
style: { display: 'grid', gridWrap: false },
|
|
186
200
|
path: '/browse/featured', // header tap → the full list
|
|
187
201
|
children: [
|
|
188
|
-
{
|
|
202
|
+
{
|
|
203
|
+
title: 'Jazz',
|
|
204
|
+
path: '/browse/jazz',
|
|
205
|
+
artwork: 'https://…/jazz.jpg'
|
|
206
|
+
},
|
|
189
207
|
{
|
|
190
208
|
title: 'Beacon FM',
|
|
191
209
|
src: 'https://audio.example.com/beacon.mp3', // tap plays it
|
|
@@ -200,11 +218,13 @@ A tile with `src` **plays immediately on tap** (same selection path as a playabl
|
|
|
200
218
|
}
|
|
201
219
|
```
|
|
202
220
|
|
|
203
|
-
Each surface renders a declaration as its nearest supported form
|
|
221
|
+
Each surface renders a declaration as its nearest supported form; see [Browser → Presentation](/guide/browser#presentation).
|
|
222
|
+
|
|
223
|
+
## ResolvedTrack: a resolved page
|
|
204
224
|
|
|
205
|
-
|
|
225
|
+
A [**`ResolvedTrack`**](/api/types/browser-nodes/#resolvedtrack) is the same Track plus its resolved content — the page the browser is currently showing. Its `path` is always present, and `sections` is the [`Section`](/api/types/browser-nodes/#section)`[]` to render (optional — a leaf page has none).
|
|
206
226
|
|
|
207
|
-
A
|
|
227
|
+
A page authored with a plain `children` list resolves to a single untitled section: `children` is authoring sugar, never populated on resolved output — read `sections`.
|
|
208
228
|
|
|
209
229
|
Navigation is **fire-and-forget**: `navigate(path)` returns `void`. Read the resolved page from `useContent()` (or `getContent()` / `onContentChanged`):
|
|
210
230
|
|
|
@@ -222,6 +242,10 @@ function JazzPage() {
|
|
|
222
242
|
|
|
223
243
|
A `ResolvedTrack` may also set [`carPlaySiriListButton`](/api/types/browser/#carplaysirilistbuttonposition)`: 'top' | 'bottom'` to show the "Ask Siri to Play" cell on that page (needs Siri wiring — see [CarPlay](/guide/carplay)).
|
|
224
244
|
|
|
245
|
+
## Stream title encoding: `icyCharset`
|
|
246
|
+
|
|
247
|
+
Some Shoutcast / Icecast stations send their ICY stream titles in a legacy code page rather than UTF-8. Set `icyCharset` to its IANA label (`'windows-1251'`, …) and the player re-decodes those titles on iOS and Android. See [Metadata](/guide/metadata).
|
|
248
|
+
|
|
225
249
|
## Using tracks in your code
|
|
226
250
|
|
|
227
251
|
Tracks flow through the queue and playback API. A minimal playable track needs just `title` + `src`:
|
|
@@ -236,7 +260,7 @@ setQueue([
|
|
|
236
260
|
play()
|
|
237
261
|
```
|
|
238
262
|
|
|
239
|
-
`load(track)`
|
|
263
|
+
`load(track)` replaces the active track (or starts the queue if it is empty), `add(tracks)` appends to the queue, and `getActiveTrack()` / `useActiveTrack()` read what's playing now (with its `artworkSource` populated for your UI). See [Basic Usage](/guide/basic-usage) for the full queue and playback API.
|
|
240
264
|
|
|
241
265
|
## Where to go next
|
|
242
266
|
|