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
package/src/types/browser.ts
CHANGED
|
@@ -2,7 +2,8 @@ import type { NavigationError } from '../features/errors'
|
|
|
2
2
|
import type { ResolvedTrack, Track } from './browser-nodes.ts'
|
|
3
3
|
|
|
4
4
|
/**
|
|
5
|
-
* Event fired when a track is about to
|
|
5
|
+
* Event fired when a playable track is about to load: a browse-row tap or a
|
|
6
|
+
* `navigate(track)` call.
|
|
6
7
|
*/
|
|
7
8
|
export interface TrackLoadEvent {
|
|
8
9
|
/** The track that will be loaded */
|
|
@@ -22,6 +23,7 @@ export interface TrackLoadEvent {
|
|
|
22
23
|
*/
|
|
23
24
|
export type HandleTrackLoadCallback = (event: TrackLoadEvent) => Promise<void>
|
|
24
25
|
|
|
26
|
+
/** What a browse callback receives: the path, and the params its route matched. */
|
|
25
27
|
export type BrowserSourceCallbackParam = {
|
|
26
28
|
path: string
|
|
27
29
|
routeParams?: Record<string, string>
|
|
@@ -29,7 +31,9 @@ export type BrowserSourceCallbackParam = {
|
|
|
29
31
|
|
|
30
32
|
/**
|
|
31
33
|
* Return BrowseError from a browse callback to display an error to the user.
|
|
32
|
-
*
|
|
34
|
+
* CarPlay and Android Auto show the error in place of the list: as the CarPlay
|
|
35
|
+
* list's message, and as an error row in Android Auto. The title comes from
|
|
36
|
+
* `formatNavigationError` (default "Error"), and your string is the message.
|
|
33
37
|
*
|
|
34
38
|
* On the app side, the error is surfaced as a `NavigationError` with
|
|
35
39
|
* `code: 'callback-error'`. Use `useNavigationError()` to get the error details,
|
|
@@ -37,11 +41,13 @@ export type BrowserSourceCallbackParam = {
|
|
|
37
41
|
*
|
|
38
42
|
* @example
|
|
39
43
|
* ```ts
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
44
|
+
* routes: {
|
|
45
|
+
* '/premium': async ({ path }) => {
|
|
46
|
+
* if (!user.subscribed) {
|
|
47
|
+
* return { error: 'Please subscribe to access this content' }
|
|
48
|
+
* }
|
|
49
|
+
* return fetchContent(path)
|
|
43
50
|
* }
|
|
44
|
-
* return fetchContent(path)
|
|
45
51
|
* }
|
|
46
52
|
* ```
|
|
47
53
|
*/
|
|
@@ -55,6 +61,7 @@ export type BrowseError = {
|
|
|
55
61
|
*/
|
|
56
62
|
export type BrowseResult = ResolvedTrack | BrowseError
|
|
57
63
|
|
|
64
|
+
/** Browse callback: returns the page for a path, or a {@link BrowseError}. */
|
|
58
65
|
export type BrowserSourceCallback = (
|
|
59
66
|
param: BrowserSourceCallbackParam
|
|
60
67
|
) => BrowseResult | Promise<BrowseResult>
|
|
@@ -159,22 +166,30 @@ export interface SearchParams {
|
|
|
159
166
|
reference: MediaReference
|
|
160
167
|
}
|
|
161
168
|
|
|
169
|
+
/** Search callback: returns the result tracks for a search. */
|
|
162
170
|
export type SearchSourceCallback = (params: SearchParams) => Promise<Track[]>
|
|
171
|
+
|
|
163
172
|
// Sync and async transforms are SEPARATE fields (`transform` / `transformSync`),
|
|
164
173
|
// never a `T | Promise<T>` union. A union lowers to a Nitro `variant<Struct,
|
|
165
174
|
// Promise<Struct>>`, and an all-optional struct's `canConvert` also accepts a
|
|
166
175
|
// Promise — so the async case is silently misread as an empty config. Two
|
|
167
176
|
// single-typed fields keep both paths unambiguous, and the sync field allocates
|
|
168
177
|
// no Promise. When both are set they run as a pipeline: async first, then sync.
|
|
178
|
+
/**
|
|
179
|
+
* Async `transform`: receives the merged request and the route's params, and
|
|
180
|
+
* returns the request to send.
|
|
181
|
+
*/
|
|
169
182
|
export type RequestConfigTransformer = (
|
|
170
183
|
request: RequestConfig,
|
|
171
184
|
routeParams?: Record<string, string>
|
|
172
185
|
) => Promise<RequestConfig>
|
|
186
|
+
/** Sync `transformSync`: the {@link RequestConfigTransformer} without a Promise. */
|
|
173
187
|
export type RequestConfigTransformerSync = (
|
|
174
188
|
request: RequestConfig,
|
|
175
189
|
routeParams?: Record<string, string>
|
|
176
190
|
) => RequestConfig
|
|
177
191
|
|
|
192
|
+
/** HTTP method of a request. */
|
|
178
193
|
export type HttpMethod =
|
|
179
194
|
| 'GET'
|
|
180
195
|
| 'POST'
|
|
@@ -184,26 +199,50 @@ export type HttpMethod =
|
|
|
184
199
|
| 'HEAD'
|
|
185
200
|
| 'OPTIONS'
|
|
186
201
|
|
|
202
|
+
/**
|
|
203
|
+
* One HTTP request's fields. When configs layer, `headers` and `query` merge
|
|
204
|
+
* by key, and every other set field overrides the one below it, unless the
|
|
205
|
+
* layer has a transform, which replaces the config outright.
|
|
206
|
+
*/
|
|
187
207
|
export interface RequestConfig {
|
|
208
|
+
/** HTTP method. Defaults to `'GET'`. */
|
|
188
209
|
method?: HttpMethod
|
|
189
210
|
/**
|
|
190
211
|
* The request path.
|
|
191
212
|
* - For browser requests, this is the track's `path`
|
|
192
213
|
* - For media requests, this is the track's `src` value
|
|
193
214
|
* - For artwork requests, this is the track's `artwork` URL
|
|
215
|
+
*
|
|
216
|
+
* A static value is ignored on `request`, `browse`, `media` and route
|
|
217
|
+
* layers; change it in a `transform`.
|
|
194
218
|
*/
|
|
195
219
|
path?: string
|
|
220
|
+
/** URL that a relative `path` is appended to. */
|
|
196
221
|
baseUrl?: string
|
|
222
|
+
/** Request headers, merged by key with the layers below. */
|
|
197
223
|
headers?: Record<string, string>
|
|
224
|
+
/** Query parameters, merged by key with the layers below. */
|
|
198
225
|
query?: Record<string, string>
|
|
226
|
+
/**
|
|
227
|
+
* Request body, sent for POST, PUT and PATCH (and DELETE when set) on iOS
|
|
228
|
+
* and Android; not sent on web.
|
|
229
|
+
*/
|
|
199
230
|
body?: string
|
|
231
|
+
/**
|
|
232
|
+
* Content type of the body on iOS and Android. Defaults to
|
|
233
|
+
* `'application/json'`; not sent on web.
|
|
234
|
+
*/
|
|
200
235
|
contentType?: string
|
|
236
|
+
/**
|
|
237
|
+
* Sent as `User-Agent` on iOS and Android (a `User-Agent` in `headers` wins
|
|
238
|
+
* on iOS); ignored on web.
|
|
239
|
+
*/
|
|
201
240
|
userAgent?: string
|
|
202
241
|
}
|
|
203
242
|
|
|
204
243
|
/**
|
|
205
244
|
* Context for image loading requests.
|
|
206
|
-
* Provides pixel dimensions
|
|
245
|
+
* Provides pixel dimensions from Android Auto/CarPlay.
|
|
207
246
|
*
|
|
208
247
|
* @example
|
|
209
248
|
* ```typescript
|
|
@@ -273,10 +312,11 @@ export interface MediaTransformParams {
|
|
|
273
312
|
* }
|
|
274
313
|
* ```
|
|
275
314
|
*/
|
|
276
|
-
|
|
315
|
+
/** Async artwork `transform`: receives `{ request, context }`. */
|
|
277
316
|
export type MediaRequestConfigTransformer = (
|
|
278
317
|
params: MediaTransformParams
|
|
279
318
|
) => Promise<RequestConfig>
|
|
319
|
+
/** Sync artwork `transformSync`: the {@link MediaRequestConfigTransformer} without a Promise. */
|
|
280
320
|
export type MediaRequestConfigTransformerSync = (
|
|
281
321
|
params: MediaTransformParams
|
|
282
322
|
) => RequestConfig
|
|
@@ -349,66 +389,6 @@ export type RequestConfigResolver = () =>
|
|
|
349
389
|
| TransformableRequestConfig
|
|
350
390
|
| Promise<TransformableRequestConfig>
|
|
351
391
|
|
|
352
|
-
/**
|
|
353
|
-
* Configuration for artwork image requests
|
|
354
|
-
*
|
|
355
|
-
* ### Configuration Hierarchy
|
|
356
|
-
*
|
|
357
|
-
* When a request is made, configs are merged in this order (later overrides earlier):
|
|
358
|
-
* 1. `request` (base config) - shared settings like user agent, common headers
|
|
359
|
-
* 2. `artwork` config - resource-specific settings
|
|
360
|
-
* 3. `resolve(track)` result - per-track overrides (if provided)
|
|
361
|
-
* 4. `imageQueryParams` - automatic size query param injection (if configured)
|
|
362
|
-
* 5. `transform(request, context)` result - final modifications (if provided)
|
|
363
|
-
*
|
|
364
|
-
* ### Usage Patterns
|
|
365
|
-
*
|
|
366
|
-
* **Simple CDN configuration:**
|
|
367
|
-
* ```typescript
|
|
368
|
-
* media: {
|
|
369
|
-
* baseUrl: 'https://audio.cdn.example.com',
|
|
370
|
-
* headers: { 'X-API-Key': 'your-api-key' }
|
|
371
|
-
* }
|
|
372
|
-
* ```
|
|
373
|
-
*
|
|
374
|
-
* **Per-track URL resolution:**
|
|
375
|
-
* ```typescript
|
|
376
|
-
* media: {
|
|
377
|
-
* resolve: async (track) => ({
|
|
378
|
-
* baseUrl: 'https://audio.cdn.example.com',
|
|
379
|
-
* path: `/streams/${track.src}`,
|
|
380
|
-
* query: { token: await getSignedToken(track.src) }
|
|
381
|
-
* })
|
|
382
|
-
* }
|
|
383
|
-
* ```
|
|
384
|
-
*
|
|
385
|
-
* **Size-aware transformation (for artwork):**
|
|
386
|
-
* ```typescript
|
|
387
|
-
* artwork: {
|
|
388
|
-
* baseUrl: 'https://images.cdn.example.com',
|
|
389
|
-
* transform: async ({ request, context }) => ({
|
|
390
|
-
* ...request,
|
|
391
|
-
* query: {
|
|
392
|
-
* ...request.query,
|
|
393
|
-
* w: context?.width ? String(context.width) : '600',
|
|
394
|
-
* sig: await signUrl(request.path)
|
|
395
|
-
* }
|
|
396
|
-
* })
|
|
397
|
-
* }
|
|
398
|
-
* ```
|
|
399
|
-
*
|
|
400
|
-
* **Simple size params (declarative alternative):**
|
|
401
|
-
* ```typescript
|
|
402
|
-
* artwork: {
|
|
403
|
-
* baseUrl: 'https://images.cdn.example.com',
|
|
404
|
-
* imageQueryParams: { width: 'w', height: 'h' }
|
|
405
|
-
* }
|
|
406
|
-
* ```
|
|
407
|
-
*
|
|
408
|
-
* @see BrowserConfiguration.media - Audio stream configuration
|
|
409
|
-
* @see BrowserConfiguration.artwork - Image/artwork configuration
|
|
410
|
-
*/
|
|
411
|
-
|
|
412
392
|
/**
|
|
413
393
|
* Query parameter names for automatic context injection from CarPlay/Android Auto.
|
|
414
394
|
* Maps ImageContext fields to query parameter names for your CDN.
|
|
@@ -421,11 +401,9 @@ export interface ImageQueryParams {
|
|
|
421
401
|
}
|
|
422
402
|
|
|
423
403
|
/**
|
|
424
|
-
* Configuration for
|
|
404
|
+
* Configuration for audio stream requests: `media` in BrowserConfiguration.
|
|
425
405
|
* Extends TransformableRequestConfig with per-track resolution capabilities.
|
|
426
|
-
*
|
|
427
|
-
* Used for both `media` (audio streaming) and `artwork` (image loading) configuration
|
|
428
|
-
* in BrowserConfiguration.
|
|
406
|
+
* For `artwork`, see {@link ArtworkRequestConfig}.
|
|
429
407
|
*
|
|
430
408
|
* ### Configuration Hierarchy
|
|
431
409
|
*
|
|
@@ -438,10 +416,8 @@ export interface ImageQueryParams {
|
|
|
438
416
|
* per-track resolver is the most specific layer and wins over the
|
|
439
417
|
* transform, on every platform
|
|
440
418
|
*
|
|
441
|
-
*
|
|
442
|
-
*
|
|
443
|
-
* means a `media.transform` cannot sign what `resolve` produced — do that work
|
|
444
|
-
* inside `resolve`, or move the signing to `transform` and drop `resolve`.
|
|
419
|
+
* So a `media.transform` cannot sign what `resolve` produced: sign inside
|
|
420
|
+
* `resolve`, or sign in `transform` and drop `resolve`.
|
|
445
421
|
*
|
|
446
422
|
* ### Usage Patterns
|
|
447
423
|
*
|
|
@@ -466,10 +442,10 @@ export interface ImageQueryParams {
|
|
|
466
442
|
*
|
|
467
443
|
* **Dynamic request signing:**
|
|
468
444
|
* ```typescript
|
|
469
|
-
*
|
|
470
|
-
* baseUrl: 'https://images.cdn.example.com',
|
|
445
|
+
* media: {
|
|
471
446
|
* transform: async (request) => ({
|
|
472
447
|
* ...request,
|
|
448
|
+
* baseUrl: 'https://audio.cdn.example.com',
|
|
473
449
|
* query: { ...request.query, sig: await signUrl(request.path) }
|
|
474
450
|
* })
|
|
475
451
|
* }
|
|
@@ -480,18 +456,18 @@ export interface ImageQueryParams {
|
|
|
480
456
|
*/
|
|
481
457
|
export interface MediaRequestConfig extends TransformableRequestConfig {
|
|
482
458
|
/**
|
|
483
|
-
*
|
|
459
|
+
* Async per-track request resolution.
|
|
484
460
|
*
|
|
485
461
|
* Called for each track to generate the final request configuration.
|
|
486
462
|
* Receives the full Track object, allowing URL generation based on
|
|
487
463
|
* track metadata (id, artist, album, src, etc.).
|
|
488
464
|
*
|
|
489
465
|
* Runs **last** for media — after `transform`, and winning over it on every
|
|
490
|
-
* field including `path
|
|
491
|
-
*
|
|
466
|
+
* field including `path`; artwork runs them the other way round (see
|
|
467
|
+
* {@link MediaRequestConfig}). When `resolveSync` is also set, both run and
|
|
468
|
+
* the `resolveSync` result merges over this one.
|
|
492
469
|
*
|
|
493
470
|
* @param track - The track being requested
|
|
494
|
-
* @returns Request configuration for this specific track (sync or async)
|
|
495
471
|
*
|
|
496
472
|
* @example
|
|
497
473
|
* ```typescript
|
|
@@ -501,21 +477,62 @@ export interface MediaRequestConfig extends TransformableRequestConfig {
|
|
|
501
477
|
* })
|
|
502
478
|
* ```
|
|
503
479
|
*/
|
|
504
|
-
/** Async per-track resolution. When both are set, runs (merged) BEFORE `resolveSync`. */
|
|
505
480
|
resolve?: (track: Track) => Promise<RequestConfig>
|
|
506
481
|
/** Sync per-track resolution (no Promise allocation). When both are set, runs (merged) AFTER `resolve`. */
|
|
507
482
|
resolveSync?: (track: Track) => RequestConfig
|
|
508
483
|
}
|
|
509
484
|
|
|
485
|
+
/**
|
|
486
|
+
* Configuration for artwork image requests: `artwork` and `nowPlayingArtwork`
|
|
487
|
+
* in BrowserConfiguration.
|
|
488
|
+
*
|
|
489
|
+
* ### Configuration Hierarchy
|
|
490
|
+
*
|
|
491
|
+
* Configs merge in this order (later overrides earlier):
|
|
492
|
+
* 1. `request` (base config) - shared settings like user agent, common headers
|
|
493
|
+
* 2. `artwork` (or `nowPlayingArtwork`) config - resource-specific settings
|
|
494
|
+
* 3. `resolve(track)` result - per-track overrides (if provided)
|
|
495
|
+
* 4. `imageQueryParams` - automatic size query params (if configured)
|
|
496
|
+
* 5. `transform({ request, context })` result - final changes (if provided)
|
|
497
|
+
*
|
|
498
|
+
* ### Usage Patterns
|
|
499
|
+
*
|
|
500
|
+
* **Size-aware transformation:**
|
|
501
|
+
* ```typescript
|
|
502
|
+
* artwork: {
|
|
503
|
+
* baseUrl: 'https://images.cdn.example.com',
|
|
504
|
+
* transform: async ({ request, context }) => ({
|
|
505
|
+
* ...request,
|
|
506
|
+
* query: {
|
|
507
|
+
* ...request.query,
|
|
508
|
+
* w: context?.width ? String(context.width) : '600',
|
|
509
|
+
* sig: await signUrl(request.path)
|
|
510
|
+
* }
|
|
511
|
+
* })
|
|
512
|
+
* }
|
|
513
|
+
* ```
|
|
514
|
+
*
|
|
515
|
+
* **Simple size params (declarative alternative):**
|
|
516
|
+
* ```typescript
|
|
517
|
+
* artwork: {
|
|
518
|
+
* baseUrl: 'https://images.cdn.example.com',
|
|
519
|
+
* imageQueryParams: { width: 'w', height: 'h' }
|
|
520
|
+
* }
|
|
521
|
+
* ```
|
|
522
|
+
*
|
|
523
|
+
* @see BrowserConfiguration.artwork - Image/artwork configuration
|
|
524
|
+
* @see BrowserConfiguration.nowPlayingArtwork - Now-playing artwork
|
|
525
|
+
*/
|
|
510
526
|
export interface ArtworkRequestConfig extends RequestConfig {
|
|
511
527
|
/**
|
|
512
|
-
*
|
|
528
|
+
* Async per-track request resolution.
|
|
513
529
|
*
|
|
514
530
|
* Called for each track to generate the request configuration based on
|
|
515
531
|
* track metadata (id, artist, album, src, etc.).
|
|
516
532
|
*
|
|
517
533
|
* The returned config is merged with base configs, then passed to
|
|
518
|
-
* `transform` if provided.
|
|
534
|
+
* `transform` if provided. When `resolveSync` is also set, both run and the
|
|
535
|
+
* `resolveSync` result merges over this one.
|
|
519
536
|
*
|
|
520
537
|
* @param track - The track being requested
|
|
521
538
|
* @returns Request configuration for this specific track
|
|
@@ -530,24 +547,24 @@ export interface ArtworkRequestConfig extends RequestConfig {
|
|
|
530
547
|
* }
|
|
531
548
|
* ```
|
|
532
549
|
*/
|
|
533
|
-
/** Async per-track resolution. When both are set, runs (merged) BEFORE `resolveSync`. */
|
|
534
550
|
resolve?: (track: Track) => Promise<RequestConfig>
|
|
535
551
|
/** Sync per-track resolution (no Promise allocation). When both are set, runs (merged) AFTER `resolve`. */
|
|
536
552
|
resolveSync?: (track: Track) => RequestConfig
|
|
537
553
|
|
|
538
554
|
/**
|
|
539
|
-
*
|
|
555
|
+
* Async final transform for artwork requests.
|
|
540
556
|
*
|
|
541
557
|
* Called after `resolve` (if provided) with the merged request config.
|
|
542
558
|
* Receives optional ImageContext with size hints from Android Auto/CarPlay.
|
|
559
|
+
* When `transformSync` is also set, it runs after this one on its result.
|
|
543
560
|
*
|
|
544
561
|
* Use this for:
|
|
545
562
|
* - Adding size query params dynamically
|
|
546
563
|
* - URL signing
|
|
547
564
|
* - Adding authentication tokens
|
|
548
565
|
*
|
|
549
|
-
* @param
|
|
550
|
-
*
|
|
566
|
+
* @param params - `{ request, context }`: the merged request configuration
|
|
567
|
+
* and the optional image context with size hints
|
|
551
568
|
* @returns Modified request configuration
|
|
552
569
|
*
|
|
553
570
|
* @example
|
|
@@ -564,7 +581,6 @@ export interface ArtworkRequestConfig extends RequestConfig {
|
|
|
564
581
|
* }
|
|
565
582
|
* ```
|
|
566
583
|
*/
|
|
567
|
-
/** Async final transform. When both are set, runs BEFORE `transformSync`. */
|
|
568
584
|
transform?: MediaRequestConfigTransformer
|
|
569
585
|
/** Sync final transform (no Promise allocation). When both are set, runs AFTER `transform`. */
|
|
570
586
|
transformSync?: MediaRequestConfigTransformerSync
|
|
@@ -572,8 +588,9 @@ export interface ArtworkRequestConfig extends RequestConfig {
|
|
|
572
588
|
/**
|
|
573
589
|
* Query parameter names for automatic context injection from CarPlay/Android Auto.
|
|
574
590
|
*
|
|
575
|
-
* When configured, the image
|
|
576
|
-
*
|
|
591
|
+
* When configured, the image width and height from CarPlay/Android Auto are
|
|
592
|
+
* added as query parameters to artwork URLs, in whole pixels, when the
|
|
593
|
+
* display size is known.
|
|
577
594
|
*
|
|
578
595
|
* This is a simpler alternative to using `transform` for context-aware URLs.
|
|
579
596
|
*
|
|
@@ -605,25 +622,29 @@ export interface ArtworkRequestConfig extends RequestConfig {
|
|
|
605
622
|
* sub-container (`path`). A callback / static `ResolvedTrack` returns the same
|
|
606
623
|
* page object directly.
|
|
607
624
|
*
|
|
608
|
-
*
|
|
609
|
-
*
|
|
625
|
+
* A {@link TabsSource} HTTP endpoint returns this same page shape, with the
|
|
626
|
+
* tabs as its `children`. A {@link SearchSource} HTTP endpoint differs: it
|
|
627
|
+
* returns a bare `Track[]`.
|
|
610
628
|
*/
|
|
611
629
|
export type BrowserSource =
|
|
612
630
|
| ResolvedTrack
|
|
613
631
|
| BrowserSourceCallback
|
|
614
632
|
| TransformableRequestConfig
|
|
615
633
|
|
|
634
|
+
/**
|
|
635
|
+
* A callback or an HTTP request config. A route's `browse` takes the wider
|
|
636
|
+
* {@link BrowserSource}, which also accepts a static {@link ResolvedTrack}.
|
|
637
|
+
*/
|
|
616
638
|
export type RouteSource = BrowserSourceCallback | TransformableRequestConfig
|
|
617
639
|
|
|
618
640
|
/**
|
|
619
|
-
* Route configuration with per-route
|
|
641
|
+
* Route configuration with per-route browse and artwork overrides.
|
|
620
642
|
*
|
|
621
643
|
* @example
|
|
622
644
|
* ```typescript
|
|
623
645
|
* routes: {
|
|
624
646
|
* '/premium': {
|
|
625
647
|
* browse: async () => fetchPremiumContent(),
|
|
626
|
-
* media: { baseUrl: 'https://premium-audio.cdn.com' },
|
|
627
648
|
* artwork: { baseUrl: 'https://premium-images.cdn.com' }
|
|
628
649
|
* }
|
|
629
650
|
* }
|
|
@@ -632,18 +653,25 @@ export type RouteSource = BrowserSourceCallback | TransformableRequestConfig
|
|
|
632
653
|
export type RouteConfig = {
|
|
633
654
|
/** Override browse config for this route. */
|
|
634
655
|
browse?: BrowserSource
|
|
635
|
-
/**
|
|
656
|
+
/**
|
|
657
|
+
* Not applied on any platform: media always resolves from the top-level
|
|
658
|
+
* `media` config.
|
|
659
|
+
*/
|
|
636
660
|
media?: MediaRequestConfig
|
|
637
661
|
/** Override artwork config for this route. */
|
|
638
662
|
artwork?: ArtworkRequestConfig
|
|
639
663
|
}
|
|
640
664
|
|
|
665
|
+
/** Tabs callback: returns the tab tracks. */
|
|
641
666
|
export type TabsSourceCallback = () => Track[] | Promise<Track[]>
|
|
667
|
+
|
|
642
668
|
/**
|
|
643
669
|
* Tab source configuration for navigation tabs.
|
|
644
670
|
*
|
|
645
|
-
* When using API configuration (TransformableRequestConfig), the
|
|
646
|
-
*
|
|
671
|
+
* When using API configuration (TransformableRequestConfig), the web requests
|
|
672
|
+
* path '/', but iOS and Android request an internal placeholder path instead.
|
|
673
|
+
* A static `path` is ignored, so set the path in a `transform` for the same
|
|
674
|
+
* request on every platform. The endpoint must return a page object
|
|
647
675
|
* `{ title?, children: Track[] }` whose `children` are the tabs — the same
|
|
648
676
|
* shape a browse endpoint returns. Callback/static sources provide `Track[]`
|
|
649
677
|
* directly.
|
|
@@ -657,15 +685,19 @@ export type TabsSource =
|
|
|
657
685
|
* Search source configuration for handling search requests.
|
|
658
686
|
*
|
|
659
687
|
* **Response shape (HTTP / `TransformableRequestConfig`):** the endpoint must
|
|
660
|
-
* return a
|
|
661
|
-
*
|
|
662
|
-
*
|
|
663
|
-
*
|
|
688
|
+
* return a bare `Track[]` of result rows, not the page object a browse
|
|
689
|
+
* endpoint returns. (The web implementation also accepts a page object
|
|
690
|
+
* `{ children: Track[] }`; iOS and Android do not.) Callback sources return
|
|
691
|
+
* `Track[]` directly.
|
|
664
692
|
*
|
|
665
693
|
* @see BrowserConfiguration.search
|
|
666
694
|
*/
|
|
667
695
|
export type SearchSource = SearchSourceCallback | TransformableRequestConfig
|
|
668
696
|
|
|
697
|
+
/**
|
|
698
|
+
* The browser's configuration: requests, routes, tabs, search and the car
|
|
699
|
+
* surfaces. Pass it to `configureBrowser`.
|
|
700
|
+
*/
|
|
669
701
|
export type BrowserConfiguration = {
|
|
670
702
|
/**
|
|
671
703
|
* Initial navigation path. Setting this triggers initial navigation to the
|
|
@@ -766,9 +798,9 @@ export type BrowserConfiguration = {
|
|
|
766
798
|
* the result flows through the shared `request` layer (so a relative path gets `baseUrl`
|
|
767
799
|
* prepended). For logic that can't be expressed as a template, use `resolve(track)`.
|
|
768
800
|
*
|
|
769
|
-
* The `{id}` templating
|
|
770
|
-
*
|
|
771
|
-
* implementation.
|
|
801
|
+
* The same `{id}` templating applies to every artwork config (`artwork`,
|
|
802
|
+
* a route's `artwork`, `nowPlayingArtwork`) on iOS and Android. Neither
|
|
803
|
+
* `{id}` nor `nowPlayingArtwork` is implemented by the web implementation.
|
|
772
804
|
*
|
|
773
805
|
* @example
|
|
774
806
|
* // 302-redirect endpoint keyed by the track id:
|
|
@@ -811,8 +843,8 @@ export type BrowserConfiguration = {
|
|
|
811
843
|
* expects different names, rename them in `transform` — it receives the params
|
|
812
844
|
* already on `request.query`, e.g. `query: { search: request.query?.q }`.
|
|
813
845
|
*
|
|
814
|
-
* Response shape: the endpoint must return a
|
|
815
|
-
*
|
|
846
|
+
* Response shape: the endpoint must return a bare `Track[]` — see
|
|
847
|
+
* {@link SearchSource}.
|
|
816
848
|
*
|
|
817
849
|
* @example
|
|
818
850
|
* ```typescript
|
|
@@ -822,11 +854,15 @@ export type BrowserConfiguration = {
|
|
|
822
854
|
* if (params.reference === 'my') return await getFavorites();
|
|
823
855
|
* // Filters are read directly from their props (not derived from `mode`)
|
|
824
856
|
* if (params.album && params.artist) {
|
|
825
|
-
* return await db.query(
|
|
826
|
-
*
|
|
857
|
+
* return await db.query(
|
|
858
|
+
* 'SELECT * FROM tracks WHERE album = ? AND artist = ?',
|
|
859
|
+
* [params.album, params.artist]
|
|
860
|
+
* );
|
|
827
861
|
* }
|
|
828
862
|
* if (params.artist) {
|
|
829
|
-
* return await db.query('SELECT * FROM tracks WHERE artist = ?', [
|
|
863
|
+
* return await db.query('SELECT * FROM tracks WHERE artist = ?', [
|
|
864
|
+
* params.artist,
|
|
865
|
+
* ]);
|
|
830
866
|
* }
|
|
831
867
|
* // `mode` is the container vertical — narrow by it when present
|
|
832
868
|
* if (params.mode === 'podcast') return await searchPodcasts(params.query);
|
|
@@ -837,8 +873,8 @@ export type BrowserConfiguration = {
|
|
|
837
873
|
* // API configuration - parameters automatically added to query string
|
|
838
874
|
* search: {
|
|
839
875
|
* baseUrl: 'https://api.example.com/search',
|
|
840
|
-
* // GET /search?q=greens&
|
|
841
|
-
*
|
|
876
|
+
* // GET /search?q=greens&album=greens&artist=the+radishes&limit=20
|
|
877
|
+
* transformSync(request) {
|
|
842
878
|
* return {
|
|
843
879
|
* ...request,
|
|
844
880
|
* query: { ...request.query, limit: '20' }
|
|
@@ -854,7 +890,11 @@ export type BrowserConfiguration = {
|
|
|
854
890
|
* The first tab's path is automatically loaded when the browser starts.
|
|
855
891
|
*
|
|
856
892
|
* Optional - if not provided, no tab navigation will be available.
|
|
857
|
-
*
|
|
893
|
+
* Car surfaces show only the first tabs: Android Auto shows 4, CarPlay
|
|
894
|
+
* shows up to `CPTabBarTemplate.maximumTabCount`. `getTabs` and `useTabs`
|
|
895
|
+
* still return every tab, and `configureBrowser` warns in development when
|
|
896
|
+
* a static array has more than Android Auto shows. See
|
|
897
|
+
* [Tabs and the initial path](/guide/browser#tabs-and-the-initial-path).
|
|
858
898
|
*
|
|
859
899
|
* Can provide static array of Track objects with paths as tabs, API configuration, or custom callback.
|
|
860
900
|
*/
|
|
@@ -889,13 +929,14 @@ export type BrowserConfiguration = {
|
|
|
889
929
|
* which receives `routeParams` as its second argument.
|
|
890
930
|
*
|
|
891
931
|
* Values can be a `BrowserSource` (callback, request config, or static page
|
|
892
|
-
* object) or a `RouteConfig` with per-route `
|
|
932
|
+
* object) or a `RouteConfig` with per-route `browse`/`artwork` overrides.
|
|
893
933
|
*
|
|
894
934
|
* @example
|
|
895
935
|
* ```typescript
|
|
896
936
|
* routes: {
|
|
897
937
|
* '/favorites': async () => getFavoritesPage(),
|
|
898
|
-
* '/albums/{id}': async ({ routeParams }) =>
|
|
938
|
+
* '/albums/{id}': async ({ routeParams }) =>
|
|
939
|
+
* fetchAlbumPage(routeParams?.id),
|
|
899
940
|
* '/premium': {
|
|
900
941
|
* browse: { baseUrl: 'https://premium-api.example.com' },
|
|
901
942
|
* artwork: { baseUrl: 'https://premium-images.example.com' }
|
|
@@ -919,7 +960,9 @@ export type BrowserConfiguration = {
|
|
|
919
960
|
|
|
920
961
|
/**
|
|
921
962
|
* Custom handler for track load events.
|
|
922
|
-
* When set,
|
|
963
|
+
* When set, loading a playable track (a browse-row tap or a
|
|
964
|
+
* `navigate(track)` call) invokes this handler instead of auto-loading and
|
|
965
|
+
* playing the track.
|
|
923
966
|
* Pass undefined to restore default behavior.
|
|
924
967
|
*
|
|
925
968
|
* @param event - The track load event containing the track, queue, and startIndex
|
|
@@ -941,28 +984,16 @@ export type BrowserConfiguration = {
|
|
|
941
984
|
androidControllerOfflineError?: boolean
|
|
942
985
|
|
|
943
986
|
/**
|
|
944
|
-
* Titles the "view more" row
|
|
945
|
-
* `Section.path
|
|
946
|
-
* Android Auto, today the only one.
|
|
987
|
+
* Titles the "view more" row Android Auto appends to a `Section` that
|
|
988
|
+
* carries a `Section.path`, one string for every section.
|
|
947
989
|
*
|
|
948
|
-
*
|
|
949
|
-
* default, the same arrangement `formatNavigationError` has. Set this to
|
|
950
|
-
* localize it: it is re-resolved once per content generation, so
|
|
990
|
+
* It is re-resolved once per content generation, so
|
|
951
991
|
* `invalidateAllContent()` after an in-app language switch picks up the new
|
|
952
|
-
* copy without reconfiguring the browser.
|
|
953
|
-
* than a plain string — an app whose locale is its own, not the system's,
|
|
954
|
-
* cannot express that with a value frozen at configure time.
|
|
955
|
-
*
|
|
956
|
-
* One string for every section by design — the row is a fallback for a
|
|
957
|
-
* surface that cannot draw a link in its header, so per-section wording would
|
|
958
|
-
* be ceremony most consumers never see rendered.
|
|
992
|
+
* copy without reconfiguring the browser.
|
|
959
993
|
*
|
|
960
|
-
* For wording that varies by section
|
|
961
|
-
*
|
|
962
|
-
*
|
|
963
|
-
* leave `Section.path` unset so this row doesn't also appear. Since the
|
|
964
|
-
* row is Android-only, that branch is an ordinary platform check on the
|
|
965
|
-
* content you emit; CarPlay never sees the extra row.
|
|
994
|
+
* For wording that varies by section, leave `Section.path` unset and append
|
|
995
|
+
* your own browsable {@link Track} to `children`; that Track shows on every
|
|
996
|
+
* surface. See [Android Auto](https://audiobrowser.dev/guide/android-auto).
|
|
966
997
|
*
|
|
967
998
|
* @default 'View more'
|
|
968
999
|
*
|
|
@@ -994,13 +1025,13 @@ export type BrowserConfiguration = {
|
|
|
994
1025
|
carPlayLoadingTitle?: string
|
|
995
1026
|
|
|
996
1027
|
/**
|
|
997
|
-
* Called when the
|
|
998
|
-
*
|
|
999
|
-
*
|
|
1000
|
-
*
|
|
1028
|
+
* Called when the active track changes and it has no {@link Track.albumPath}.
|
|
1029
|
+
* Return a browse path to make the album line on the CarPlay Now Playing
|
|
1030
|
+
* screen tappable: a tap navigates the CarPlay browse stack there. Return
|
|
1031
|
+
* `undefined` to leave the album line untappable for this track.
|
|
1001
1032
|
*
|
|
1002
|
-
* The
|
|
1003
|
-
*
|
|
1033
|
+
* The library calls it ahead of any tap, so the album line is tappable only
|
|
1034
|
+
* when there is somewhere to go.
|
|
1004
1035
|
*
|
|
1005
1036
|
* @example
|
|
1006
1037
|
* ```typescript
|
|
@@ -1014,7 +1045,8 @@ export type BrowserConfiguration = {
|
|
|
1014
1045
|
|
|
1015
1046
|
/**
|
|
1016
1047
|
* Callback to customize error messages for navigation errors.
|
|
1017
|
-
* Used by CarPlay and
|
|
1048
|
+
* Used by CarPlay and Android Auto, and available via
|
|
1049
|
+
* `useFormattedNavigationError()` for app UI.
|
|
1018
1050
|
*
|
|
1019
1051
|
* If not provided or returns undefined, default English messages are used.
|
|
1020
1052
|
*
|
|
@@ -1079,8 +1111,13 @@ export type FormattedNavigationError = {
|
|
|
1079
1111
|
* Default values:
|
|
1080
1112
|
* - `'content-not-found'`: "Content Not Found" (English)
|
|
1081
1113
|
* - `'network-error'`: "Network Error" (English)
|
|
1082
|
-
* - `'http-error'`:
|
|
1114
|
+
* - `'http-error'`: the status text, system-localized on iOS (e.g. "Not
|
|
1115
|
+
* Found", "Service Unavailable"); on Android an English name for common
|
|
1116
|
+
* codes. "Server Error" when there is no status code, for codes Android
|
|
1117
|
+
* does not name, and always on web
|
|
1083
1118
|
* - `'callback-error'`: "Error" (English)
|
|
1119
|
+
* - `'empty-content'`: "Nothing here" (English)
|
|
1120
|
+
* - `'timeout'`: "Couldn't load" (English)
|
|
1084
1121
|
* - `'unknown-error'`: "Error" (English)
|
|
1085
1122
|
*/
|
|
1086
1123
|
title: string
|
|
@@ -1141,8 +1178,8 @@ export type FormatNavigationErrorCallback = (
|
|
|
1141
1178
|
) => FormattedNavigationError | undefined
|
|
1142
1179
|
|
|
1143
1180
|
/**
|
|
1144
|
-
* Maps the
|
|
1145
|
-
*
|
|
1181
|
+
* Maps the active track to a browse path for the CarPlay album line, or
|
|
1182
|
+
* `undefined` to leave the line untappable. See {@link BrowserConfiguration.resolveAlbumPath | resolveAlbumPath}.
|
|
1146
1183
|
*/
|
|
1147
1184
|
export type ResolveAlbumPathCallback = (track: Track) => string | undefined
|
|
1148
1185
|
|