react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.56
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -19
- package/lib/commonjs/CLAUDE.md +7 -2
- package/lib/commonjs/features/battery.js +16 -12
- package/lib/commonjs/features/battery.js.map +1 -1
- package/lib/commonjs/features/browser-config.js +1 -1
- package/lib/commonjs/features/browser.js +74 -24
- package/lib/commonjs/features/browser.js.map +1 -1
- package/lib/commonjs/features/carConnection.js +3 -4
- package/lib/commonjs/features/carConnection.js.map +1 -1
- package/lib/commonjs/features/equalizer.js +9 -5
- package/lib/commonjs/features/equalizer.js.map +1 -1
- package/lib/commonjs/features/errors.js +35 -21
- package/lib/commonjs/features/errors.js.map +1 -1
- package/lib/commonjs/features/favorites.js +15 -13
- package/lib/commonjs/features/favorites.js.map +1 -1
- package/lib/commonjs/features/gate.js +12 -6
- package/lib/commonjs/features/gate.js.map +1 -1
- package/lib/commonjs/features/metadata.js +16 -14
- package/lib/commonjs/features/metadata.js.map +1 -1
- package/lib/commonjs/features/network.js +5 -1
- package/lib/commonjs/features/network.js.map +1 -1
- package/lib/commonjs/features/nowPlaying.js +28 -14
- package/lib/commonjs/features/nowPlaying.js.map +1 -1
- package/lib/commonjs/features/output.js +8 -4
- package/lib/commonjs/features/output.js.map +1 -1
- package/lib/commonjs/features/playback/controls.js +10 -5
- package/lib/commonjs/features/playback/controls.js.map +1 -1
- package/lib/commonjs/features/playback/playWhenReady.js +6 -5
- package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
- package/lib/commonjs/features/playback/playing.js +5 -3
- package/lib/commonjs/features/playback/playing.js.map +1 -1
- package/lib/commonjs/features/playback/progress.js +11 -5
- package/lib/commonjs/features/playback/progress.js.map +1 -1
- package/lib/commonjs/features/playback/state.js +3 -3
- package/lib/commonjs/features/playback/state.js.map +1 -1
- package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
- package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
- package/lib/commonjs/features/playback/volume.js +6 -5
- package/lib/commonjs/features/playback/volume.js.map +1 -1
- package/lib/commonjs/features/player/options.js +20 -10
- package/lib/commonjs/features/player/options.js.map +1 -1
- package/lib/commonjs/features/player/setup.js +34 -38
- package/lib/commonjs/features/player/setup.js.map +1 -1
- package/lib/commonjs/features/queue/activeTrack.js +0 -1
- package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
- package/lib/commonjs/features/queue/queue.js +48 -20
- package/lib/commonjs/features/queue/queue.js.map +1 -1
- package/lib/commonjs/features/queue/repeatMode.js +2 -1
- package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
- package/lib/commonjs/features/queue/shuffle.js +0 -1
- package/lib/commonjs/features/queue/shuffle.js.map +1 -1
- package/lib/commonjs/features/remoteControls.js +59 -35
- package/lib/commonjs/features/remoteControls.js.map +1 -1
- package/lib/commonjs/features/sleepTimer.js +15 -6
- package/lib/commonjs/features/sleepTimer.js.map +1 -1
- package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
- package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
- package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
- package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
- package/lib/commonjs/utils/getTrackIdentity.js +6 -4
- package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
- package/lib/commonjs/utils/useDebug.js +16 -3
- package/lib/commonjs/utils/useDebug.js.map +1 -1
- package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
- package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
- package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
- package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
- package/lib/commonjs/web/browser/sections.js +1 -1
- package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
- package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
- package/lib/module/CLAUDE.md +7 -2
- package/lib/module/features/battery.js +16 -12
- package/lib/module/features/battery.js.map +1 -1
- package/lib/module/features/browser-config.js +1 -1
- package/lib/module/features/browser.js +74 -24
- package/lib/module/features/browser.js.map +1 -1
- package/lib/module/features/carConnection.js +3 -4
- package/lib/module/features/carConnection.js.map +1 -1
- package/lib/module/features/equalizer.js +9 -5
- package/lib/module/features/equalizer.js.map +1 -1
- package/lib/module/features/errors.js +35 -21
- package/lib/module/features/errors.js.map +1 -1
- package/lib/module/features/favorites.js +15 -13
- package/lib/module/features/favorites.js.map +1 -1
- package/lib/module/features/gate.js +12 -6
- package/lib/module/features/gate.js.map +1 -1
- package/lib/module/features/metadata.js +16 -14
- package/lib/module/features/metadata.js.map +1 -1
- package/lib/module/features/network.js +5 -1
- package/lib/module/features/network.js.map +1 -1
- package/lib/module/features/nowPlaying.js +28 -14
- package/lib/module/features/nowPlaying.js.map +1 -1
- package/lib/module/features/output.js +8 -4
- package/lib/module/features/output.js.map +1 -1
- package/lib/module/features/playback/controls.js +10 -5
- package/lib/module/features/playback/controls.js.map +1 -1
- package/lib/module/features/playback/playWhenReady.js +6 -5
- package/lib/module/features/playback/playWhenReady.js.map +1 -1
- package/lib/module/features/playback/playing.js +5 -3
- package/lib/module/features/playback/playing.js.map +1 -1
- package/lib/module/features/playback/progress.js +11 -5
- package/lib/module/features/playback/progress.js.map +1 -1
- package/lib/module/features/playback/state.js +3 -3
- package/lib/module/features/playback/state.js.map +1 -1
- package/lib/module/features/playback/trackPlaybackTime.js +6 -1
- package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
- package/lib/module/features/playback/volume.js +6 -5
- package/lib/module/features/playback/volume.js.map +1 -1
- package/lib/module/features/player/options.js +20 -10
- package/lib/module/features/player/options.js.map +1 -1
- package/lib/module/features/player/setup.js +34 -38
- package/lib/module/features/player/setup.js.map +1 -1
- package/lib/module/features/queue/activeTrack.js +0 -1
- package/lib/module/features/queue/activeTrack.js.map +1 -1
- package/lib/module/features/queue/queue.js +48 -20
- package/lib/module/features/queue/queue.js.map +1 -1
- package/lib/module/features/queue/repeatMode.js +2 -1
- package/lib/module/features/queue/repeatMode.js.map +1 -1
- package/lib/module/features/queue/shuffle.js +0 -1
- package/lib/module/features/queue/shuffle.js.map +1 -1
- package/lib/module/features/remoteControls.js +59 -35
- package/lib/module/features/remoteControls.js.map +1 -1
- package/lib/module/features/sleepTimer.js +15 -6
- package/lib/module/features/sleepTimer.js.map +1 -1
- package/lib/module/utils/LazyNativeEmitter.js +6 -9
- package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
- package/lib/module/utils/NativeUpdatedValue.js +13 -12
- package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
- package/lib/module/utils/getTrackIdentity.js +6 -4
- package/lib/module/utils/getTrackIdentity.js.map +1 -1
- package/lib/module/utils/useDebug.js +16 -3
- package/lib/module/utils/useDebug.js.map +1 -1
- package/lib/module/web/NativeAudioBrowser.js +2 -4
- package/lib/module/web/NativeAudioBrowser.js.map +1 -1
- package/lib/module/web/browser/parseSearchResponse.js +3 -4
- package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
- package/lib/module/web/browser/sections.js +1 -1
- package/lib/module/web/util/BrowserPathHelper.js +1 -3
- package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
- package/lib/typescript/src/features/battery.d.ts +17 -12
- package/lib/typescript/src/features/battery.d.ts.map +1 -1
- package/lib/typescript/src/features/browser.d.ts +64 -24
- package/lib/typescript/src/features/browser.d.ts.map +1 -1
- package/lib/typescript/src/features/carConnection.d.ts +3 -4
- package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
- package/lib/typescript/src/features/equalizer.d.ts +9 -5
- package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
- package/lib/typescript/src/features/errors.d.ts +37 -22
- package/lib/typescript/src/features/errors.d.ts.map +1 -1
- package/lib/typescript/src/features/favorites.d.ts +15 -13
- package/lib/typescript/src/features/favorites.d.ts.map +1 -1
- package/lib/typescript/src/features/gate.d.ts +14 -8
- package/lib/typescript/src/features/gate.d.ts.map +1 -1
- package/lib/typescript/src/features/metadata.d.ts +37 -17
- package/lib/typescript/src/features/metadata.d.ts.map +1 -1
- package/lib/typescript/src/features/network.d.ts +5 -1
- package/lib/typescript/src/features/network.d.ts.map +1 -1
- package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
- package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
- package/lib/typescript/src/features/output.d.ts +8 -4
- package/lib/typescript/src/features/output.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/controls.d.ts +10 -5
- package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
- package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/playing.d.ts +16 -3
- package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/progress.d.ts +11 -5
- package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/state.d.ts +8 -3
- package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
- package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/volume.d.ts +6 -5
- package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
- package/lib/typescript/src/features/player/options.d.ts +52 -37
- package/lib/typescript/src/features/player/options.d.ts.map +1 -1
- package/lib/typescript/src/features/player/setup.d.ts +65 -60
- package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
- package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/queue.d.ts +48 -20
- package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
- package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
- package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
- package/lib/typescript/src/features/remoteControls.d.ts +58 -25
- package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
- package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
- package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
- package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
- package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
- package/lib/typescript/src/types/browser.d.ts +181 -144
- package/lib/typescript/src/types/browser.d.ts.map +1 -1
- package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
- package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
- package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
- package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
- package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
- package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
- package/lib/typescript/src/utils/useDebug.d.ts +16 -3
- package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/CLAUDE.md +7 -2
- package/src/docs-floors.test.ts +71 -0
- package/src/features/battery.ts +17 -13
- package/src/features/browser-config.ts +1 -1
- package/src/features/browser.ts +65 -24
- package/src/features/carConnection.ts +3 -4
- package/src/features/equalizer.ts +9 -5
- package/src/features/errors.ts +37 -22
- package/src/features/favorites.ts +15 -13
- package/src/features/gate.ts +14 -8
- package/src/features/metadata.ts +37 -17
- package/src/features/network.ts +5 -1
- package/src/features/nowPlaying.ts +28 -14
- package/src/features/output.ts +8 -4
- package/src/features/playback/controls.ts +10 -5
- package/src/features/playback/playWhenReady.ts +6 -5
- package/src/features/playback/playing.ts +16 -3
- package/src/features/playback/progress.ts +11 -5
- package/src/features/playback/state.ts +8 -3
- package/src/features/playback/trackPlaybackTime.ts +9 -2
- package/src/features/playback/volume.ts +6 -5
- package/src/features/player/options.ts +54 -43
- package/src/features/player/setup.ts +67 -61
- package/src/features/queue/activeTrack.ts +0 -1
- package/src/features/queue/queue.ts +48 -20
- package/src/features/queue/repeatMode.ts +1 -1
- package/src/features/queue/shuffle.ts +0 -1
- package/src/features/remoteControls.ts +59 -35
- package/src/features/sleepTimer.ts +15 -7
- package/src/types/browser-nodes.ts +54 -57
- package/src/types/browser.ts +183 -146
- package/src/utils/LazyNativeEmitter.ts +6 -9
- package/src/utils/NativeUpdatedValue.ts +13 -12
- package/src/utils/getTrackIdentity.ts +6 -4
- package/src/utils/useDebug.ts +16 -3
- package/src/web/NativeAudioBrowser.ts +2 -4
- package/src/web/browser/parseSearchResponse.ts +3 -4
- package/src/web/browser/sections.ts +1 -1
- package/src/web/util/BrowserPathHelper.ts +1 -3
- package/website/guide/android-auto.md +25 -13
- package/website/guide/android-certificates.md +199 -120
- package/website/guide/artwork.md +93 -48
- package/website/guide/audio-output.md +86 -68
- package/website/guide/automotive.md +15 -10
- package/website/guide/basic-usage.md +5 -2
- package/website/guide/battery.md +50 -23
- package/website/guide/browser.md +155 -68
- package/website/guide/carplay.md +132 -49
- package/website/guide/configuration.md +85 -49
- package/website/guide/equalizer.md +36 -32
- package/website/guide/errors.md +106 -64
- package/website/guide/favorites.md +41 -31
- package/website/guide/gate.md +24 -10
- package/website/guide/getting-started.md +55 -2
- package/website/guide/hooks.md +53 -47
- package/website/guide/live-streams.md +80 -49
- package/website/guide/metadata.md +87 -53
- package/website/guide/migrating-from-track-player.md +94 -49
- package/website/guide/native-callback-fetch.md +46 -36
- package/website/guide/network.md +36 -20
- package/website/guide/now-playing.md +72 -44
- package/website/guide/playback.md +112 -35
- package/website/guide/queue.md +77 -43
- package/website/guide/remote-controls.md +87 -29
- package/website/guide/search.md +37 -22
- package/website/guide/sleep-timer.md +35 -14
- package/website/guide/track.md +59 -35
package/website/guide/artwork.md
CHANGED
|
@@ -4,9 +4,11 @@ description: 'Set Track.artwork once and render it everywhere: the fetch and tra
|
|
|
4
4
|
|
|
5
5
|
# Artwork
|
|
6
6
|
|
|
7
|
-
**Artwork** is the image shown for a track — the thumbnail in a browse list, the cover on the lock screen, the icon on a CarPlay row.
|
|
7
|
+
**Artwork** is the image shown for a track — the thumbnail in a browse list, the cover on the lock screen, the icon on a CarPlay row.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
You set one field, `artwork`, on a [`Track`](/guide/track); the library resolves and transforms it per surface and per requested size, and hands the ready-to-render result back on `artworkSource`.
|
|
10
|
+
|
|
11
|
+
This guide covers the mental model (the two configs and the output field), **which artwork renders where**, and the **transform pipeline** that turns your URL into a sized request. It then covers the platform-specific bits: SF Symbols on iOS, tinting, light/dark artwork, Android vector icons, and SVG.
|
|
10
12
|
|
|
11
13
|
## Mental model
|
|
12
14
|
|
|
@@ -35,21 +37,22 @@ function Cover() {
|
|
|
35
37
|
|
|
36
38
|
The library publishes art to several surfaces; each gets its image from a field/config and (where the surface knows its display size) a size hint:
|
|
37
39
|
|
|
38
|
-
| Surface
|
|
39
|
-
|
|
|
40
|
-
| **
|
|
41
|
-
| **
|
|
42
|
-
| **
|
|
43
|
-
| **
|
|
44
|
-
| **
|
|
45
|
-
| **
|
|
40
|
+
| Surface | Image from | Size hint | Tinting |
|
|
41
|
+
| --------------------------------------------- | --------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
|
|
42
|
+
| **CarPlay browse rows / tabs** | `artwork` (global config; no per-route) | yes | `style: { artworkRendering: 'stencil' }`, or a `{ light, dark }` pair |
|
|
43
|
+
| **Android Auto browse rows** | `artwork` (per-route override allowed) | no | — (see [Tinting](#tinting-and-platform-icons)) |
|
|
44
|
+
| **In-app `<Image>`** | `artworkSource` (output) | no | your UI |
|
|
45
|
+
| **iOS lock screen / Control Center** | `nowPlayingArtwork` → falls back to `artwork` | yes | — |
|
|
46
|
+
| **CarPlay Now Playing** | `nowPlayingArtwork` → `artwork` | yes | — |
|
|
47
|
+
| **Android notification / Android Auto** | `nowPlayingArtwork` → `artwork` | yes | — (see [Tinting](#tinting-and-platform-icons)) |
|
|
48
|
+
| **CarPlay tile sections** (`display: 'grid'`) | `artwork` (each tile is a Track) | yes | CarPlay: `style: { artworkRendering: 'stencil' }`, or a `{ light, dark }` pair |
|
|
46
49
|
|
|
47
|
-
**Size hint** = the surface tells the library the pixels it needs, delivered as an [`ImageContext`](/api/types/browser/#imagecontext) to your `transform` / `imageQueryParams`. Browse-time resolution has none.
|
|
50
|
+
**Size hint** = the surface tells the library the pixels it needs, delivered as an [`ImageContext`](/api/types/browser/#imagecontext) to your `transform` / `imageQueryParams`. Browse-time resolution, which produces `artworkSource` and the Android Auto browse URLs, has none.
|
|
48
51
|
|
|
49
|
-
|
|
52
|
+
Three things to take from the table:
|
|
50
53
|
|
|
51
54
|
- **One image by default.** With only `artwork` set, the same source feeds browse rows _and_ every now-playing surface. Set `nowPlayingArtwork` only when the now-playing image should differ (a larger, lock-screen-quality cover without bloating list thumbnails).
|
|
52
|
-
- **Size hints exist only where the surface knows its size.** Browse-time resolution has no size, so `imageQueryParams` and `context` (below) do nothing there; they kick in
|
|
55
|
+
- **Size hints exist only where the surface knows its size.** Browse-time resolution (`artworkSource`, Android Auto browse rows) has no size, so `imageQueryParams` and `context` (below) do nothing there; they kick in when CarPlay loads a row, tab or tile, and on now-playing surfaces.
|
|
53
56
|
- **Tinting is for browse icons only.** `artworkRendering: 'stencil'` is applied when CarPlay renders browse content — list rows, tabs, and tiles — not to now-playing cover art.
|
|
54
57
|
|
|
55
58
|
## The transform pipeline
|
|
@@ -62,7 +65,7 @@ Two things to take from the table:
|
|
|
62
65
|
4. **`imageQueryParams`** — appends the surface's requested size (when it reports one).
|
|
63
66
|
5. **`transform({ request, context })` / `transformSync`** — final tweak, with the requested size in `context`.
|
|
64
67
|
|
|
65
|
-
To build a per-track URL, use `resolve` (the track is the argument).
|
|
68
|
+
To build a per-track URL, use `resolve` (the track is the argument). On iOS and Android, an `{id}` token in an artwork config's `path`, `query` or `headers` is replaced with the track's `id`. This applies to `artwork`, a route's `artwork` and `nowPlayingArtwork` alike. The web implementation sends static values verbatim.
|
|
66
69
|
|
|
67
70
|
A typical CDN setup never needs more than `baseUrl` plus `imageQueryParams`:
|
|
68
71
|
|
|
@@ -79,15 +82,17 @@ configureBrowser({
|
|
|
79
82
|
})
|
|
80
83
|
```
|
|
81
84
|
|
|
82
|
-
With [`imageQueryParams`](/api/types/browser/#imagequeryparams) the requested size from CarPlay / Android Auto is appended automatically — `?w=200&h=200` — so each surface gets right-sized art. Omit `height` to send width only. This only fires on surfaces that report a size; browse rows (no size hint) get the URL without these params.
|
|
85
|
+
With [`imageQueryParams`](/api/types/browser/#imagequeryparams) the requested size from CarPlay / Android Auto is appended automatically — `?w=200&h=200` — so each surface gets right-sized art. Omit `height` to send width only. This only fires on surfaces that report a size; `artworkSource` and Android Auto browse rows (no size hint) get the URL without these params.
|
|
83
86
|
|
|
84
87
|
For anything `imageQueryParams` can't express — per-track paths, signed URLs — use `resolve` and `transform` (or their sync variants):
|
|
85
88
|
|
|
86
89
|
```ts
|
|
87
90
|
import { configureBrowser } from 'react-native-audio-browser'
|
|
88
|
-
|
|
91
|
+
// add: yarn add crypto-js
|
|
92
|
+
import HmacSHA256 from 'crypto-js/hmac-sha256'
|
|
89
93
|
|
|
90
|
-
|
|
94
|
+
// your CDN signing key
|
|
95
|
+
const CDN_KEY = process.env.CDN_KEY ?? ''
|
|
91
96
|
|
|
92
97
|
// sign the path locally with your key — a pure, sync function
|
|
93
98
|
const signUrl = (path: string) => HmacSHA256(path, CDN_KEY).toString()
|
|
@@ -104,7 +109,7 @@ configureBrowser({
|
|
|
104
109
|
query: {
|
|
105
110
|
...request.query,
|
|
106
111
|
w: context?.width ? String(context.width) : '600',
|
|
107
|
-
//
|
|
112
|
+
// path is optional in the type; resolveSync above always sets it
|
|
108
113
|
sig: signUrl(request.path ?? '')
|
|
109
114
|
}
|
|
110
115
|
})
|
|
@@ -112,17 +117,23 @@ configureBrowser({
|
|
|
112
117
|
})
|
|
113
118
|
```
|
|
114
119
|
|
|
115
|
-
A `transform` (or `transformSync`) **replaces** the request — it doesn't merge — so spread `...request` (and `...request.query`) or you'll drop the `baseUrl` and other layers. The [`context`](/api/types/browser/#imagecontext) is an `ImageContext` with `width` / `height` in **pixels**, present only when the surface knows its display size (so guard with `context?.width`).
|
|
120
|
+
A `transform` (or `transformSync`) **replaces** the request — it doesn't merge — so spread `...request` (and `...request.query`) or you'll drop the `baseUrl` and other layers. The [`context`](/api/types/browser/#imagecontext) is an `ImageContext` with `width` / `height` in **pixels**, present only when the surface knows its display size (so guard with `context?.width`).
|
|
121
|
+
|
|
122
|
+
`request.path` starts as the track's `artwork` URL, which a `resolve` or a static `path` can replace; it's undefined only for a track with no artwork and nothing supplying a path, so guard it before signing (as above).
|
|
123
|
+
|
|
124
|
+
`resolveSync` / `transformSync` are no-Promise variants of `resolve` / `transform`. Reach for them when the per-track config or final tweak needs no `await` — a synced query param, a locally-computed path — to skip a Promise allocation per image (the example above is fully sync for that reason).
|
|
116
125
|
|
|
117
|
-
|
|
126
|
+
If you set _both_ the sync and async form of the **same** stage (e.g. `transform` _and_ `transformSync`), the async one runs first and the sync one tweaks its result; `resolve` and `transform` are independent stages that both always run.
|
|
118
127
|
|
|
119
128
|
::: tip Per-route artwork
|
|
120
|
-
A route can override the global `artwork` with its own config — `routes: { '/premium': { artwork: { baseUrl: '…' } } }` — so different content can load images from different hosts. See the [Browser](/guide/browser) guide.
|
|
129
|
+
A route can override the global `artwork` with its own config — `routes: { '/premium': { artwork: { baseUrl: '…' } } }` — so different content can load images from different hosts. On iOS and Android it applies to `artworkSource` and Android Auto browse rows; CarPlay rows, tabs and tiles use the global config, and so does the web implementation. See the [Browser](/guide/browser) guide.
|
|
121
130
|
:::
|
|
122
131
|
|
|
123
132
|
## SF Symbols (iOS)
|
|
124
133
|
|
|
125
|
-
Prefix `artwork` with `sf:` to render an Apple [SF Symbol](https://developer.apple.com/sf-symbols/) instead of fetching an image — ideal for tab and category icons.
|
|
134
|
+
Prefix `artwork` with `sf:` to render an Apple [SF Symbol](https://developer.apple.com/sf-symbols/) instead of fetching an image — ideal for tab and category icons.
|
|
135
|
+
|
|
136
|
+
Optional `bg` (background) and `fg` (symbol color) query params set the colors. On the lock screen and in `artworkSource`, `bg` defaults to transparent and `fg` to black. There the library renders the symbol to a PNG on device and caches it. CarPlay differs (below):
|
|
126
137
|
|
|
127
138
|
```ts
|
|
128
139
|
{
|
|
@@ -132,14 +143,25 @@ Prefix `artwork` with `sf:` to render an Apple [SF Symbol](https://developer.app
|
|
|
132
143
|
}
|
|
133
144
|
```
|
|
134
145
|
|
|
135
|
-
On CarPlay
|
|
146
|
+
On CarPlay rows and tiles the library draws the symbol on a grey tile.
|
|
147
|
+
|
|
148
|
+
With **no `fg`**, it draws black on light grey and white on dark grey, and CarPlay swaps them with the appearance; a `bg` alone is ignored. With an `fg`, the symbol is drawn in that color on `bg`, or on a grey tile when `bg` is omitted.
|
|
149
|
+
|
|
150
|
+
A tab icon is the exception: the symbol goes to CarPlay as is, `bg` and `fg` are ignored, and CarPlay tints it. This is iOS-only; on Android an `sf:` value is not a valid image.
|
|
136
151
|
|
|
137
152
|
## Tinting and platform icons
|
|
138
153
|
|
|
139
154
|
For monochrome **icons** (not full-color album art), let the system tint them to stay legible on either appearance:
|
|
140
155
|
|
|
141
|
-
- **iOS CarPlay** — declare [`style: { artworkRendering: 'stencil' }`](/api/types/browser-nodes/#trackstyle) on the track. Inside a page it's an inherited style property (a section- or page-wide value covers every item); tabs render without a section context, so a tab icon needs the declaration on the tab track itself.
|
|
142
|
-
|
|
156
|
+
- **iOS CarPlay** — declare [`style: { artworkRendering: 'stencil' }`](/api/types/browser-nodes/#trackstyle) on the track. Inside a page it's an inherited style property (a section- or page-wide value covers every item); tabs render without a section context, so a tab icon needs the declaration on the tab track itself.
|
|
157
|
+
|
|
158
|
+
CarPlay tints the glyph per appearance: black in light mode, white in dark.
|
|
159
|
+
|
|
160
|
+
- **Android Auto** is dark-only, so there's no per-appearance tinting — ship an appropriately colored (e.g. white) icon.
|
|
161
|
+
|
|
162
|
+
When a layout is declared (`display` on the section, page, or parent item), an `android.resource://…/drawable/…` artwork URI switches Android Auto to the **category** variant of that layout (which adds icon margins and lets Android Auto render it as an icon).
|
|
163
|
+
|
|
164
|
+
The library only sets the category style; the visual treatment is Android Auto's — see [Browse display](/guide/android-auto#browse-display).
|
|
143
165
|
|
|
144
166
|
```ts
|
|
145
167
|
{
|
|
@@ -150,7 +172,9 @@ For monochrome **icons** (not full-color album art), let the system tint them to
|
|
|
150
172
|
}
|
|
151
173
|
```
|
|
152
174
|
|
|
153
|
-
**SVG** is
|
|
175
|
+
**SVG** is detected by a `.svg` URL suffix: serve SVGs with a path ending in `.svg` and they decode as vectors rather than raster images.
|
|
176
|
+
|
|
177
|
+
On iOS that covers CarPlay browse rows, tabs and tiles, but not the lock screen or Control Center. On Android it covers Android Auto browse and the notification / now-playing image. Your own `<Image>` showing `artworkSource` needs its own SVG support.
|
|
154
178
|
|
|
155
179
|
## Light and dark artwork
|
|
156
180
|
|
|
@@ -169,14 +193,16 @@ Tinting recolors _one_ image. When the two appearances need genuinely **differen
|
|
|
169
193
|
|
|
170
194
|
Both fields are required — a pair with one side missing has no sensible fallback at render time.
|
|
171
195
|
|
|
172
|
-
On CarPlay browse rows and tabs the library fetches both and registers them as a single adaptive image, so switching appearance mid-drive swaps the image **in place** — no re-fetch, and no re-query of the browse tree.
|
|
196
|
+
On CarPlay browse rows and tabs the library fetches both and registers them as a single adaptive image, so switching appearance mid-drive swaps the image **in place** — no re-fetch, and no re-query of the browse tree.
|
|
197
|
+
|
|
198
|
+
Each URL runs through the [transform pipeline](#the-transform-pipeline) independently, so `baseUrl`, headers, `imageQueryParams` and `resolve` / `transform` apply to both.
|
|
173
199
|
|
|
174
200
|
Everywhere a single image is required, a pair resolves to its `dark` URL:
|
|
175
201
|
|
|
176
202
|
| Surface | Uses |
|
|
177
203
|
| ---------------------------------------- | ----------------------------- |
|
|
178
204
|
| **CarPlay browse rows / tabs** | both, adapting per appearance |
|
|
179
|
-
| **Android Auto** | `dark`
|
|
205
|
+
| **Android Auto** | `dark` |
|
|
180
206
|
| **Now-playing** (all platforms) | `dark` |
|
|
181
207
|
| **`artworkSource`** (your own `<Image>`) | `dark` |
|
|
182
208
|
|
|
@@ -190,7 +216,9 @@ Browse artwork is served to Android Auto through an internal content provider th
|
|
|
190
216
|
|
|
191
217
|
## Now-playing artwork
|
|
192
218
|
|
|
193
|
-
By default the now-playing image (lock screen, Control Center, CarPlay / Android Auto Now Playing) is the active track's `artwork` — the same image as its browse-row thumbnail.
|
|
219
|
+
By default the now-playing image (lock screen, Control Center, CarPlay / Android Auto Now Playing) is the active track's `artwork` — the same image as its browse-row thumbnail.
|
|
220
|
+
|
|
221
|
+
To resolve it differently, set `nowPlayingArtwork`, which builds the now-playing image from its **own** request. Like any artwork config, it can use an `{id}` template filled from the active track's `id`:
|
|
194
222
|
|
|
195
223
|
```ts
|
|
196
224
|
import { configureBrowser } from 'react-native-audio-browser'
|
|
@@ -206,14 +234,20 @@ configureBrowser({
|
|
|
206
234
|
})
|
|
207
235
|
```
|
|
208
236
|
|
|
209
|
-
Now-playing surfaces request a **much larger** image than list thumbnails — on iOS, up to the screen width in pixels
|
|
237
|
+
Now-playing surfaces request a **much larger** image than list thumbnails — on iOS, up to the screen width in pixels — so with `imageQueryParams` set you fetch a fittingly large variant rather than upscaling a tiny thumbnail.
|
|
210
238
|
|
|
211
|
-
|
|
239
|
+
If you _don't_ set `nowPlayingArtwork` at all, now-playing surfaces fall back to the `artwork` config (and to `track.artwork`).
|
|
212
240
|
|
|
213
|
-
`nowPlayingArtwork` is an `ArtworkRequestConfig` like `artwork`, so it takes the same `resolve` / `transform` / `imageQueryParams`. It is **native-only
|
|
241
|
+
`nowPlayingArtwork` is an `ArtworkRequestConfig` like `artwork`, so it takes the same `resolve` / `transform` / `imageQueryParams`. It is **native-only**. On web, now-playing artwork is the track's own `artwork` URL as set (the `dark` URL of a pair), with neither `artwork` nor `nowPlayingArtwork` applied.
|
|
242
|
+
|
|
243
|
+
Artwork is also the one now-playing field the text layers can't touch — the formatter / override / flash carry only `title` / `artist` / `album`. See [Now Playing](/guide/now-playing#now-playing-artwork) for the metadata side.
|
|
214
244
|
|
|
215
245
|
::: warning Now-playing artwork follows the active track
|
|
216
|
-
Now-playing artwork is resolved **once per active track**, keyed on its `id` — so it won't re-resolve while the same track keeps playing.
|
|
246
|
+
Now-playing artwork is resolved **once per active track**, keyed on its `id` — so it won't re-resolve while the same track keeps playing.
|
|
247
|
+
|
|
248
|
+
There is no imperative way to swap _only_ the image mid-stream: `updateNowPlaying()` overrides `title` / `artist` / `album`, not artwork.
|
|
249
|
+
|
|
250
|
+
Changing it means making a _new_ active track (a different `id` plus the new `artwork`) the current one, which reloads playback — so it's not a fit for, say, updating live-radio cover art on each song. An in-place update API is tracked in [issue #76](https://github.com/radio-garden/react-native-audio-browser/issues/76).
|
|
217
251
|
:::
|
|
218
252
|
|
|
219
253
|
## Tile sections
|
|
@@ -228,28 +262,39 @@ A page's [`Section`](/api/types/browser-nodes/#section) can render its tracks as
|
|
|
228
262
|
{
|
|
229
263
|
title: 'Featured',
|
|
230
264
|
style: { display: 'grid', gridWrap: false },
|
|
231
|
-
|
|
265
|
+
// header / "view all" target
|
|
266
|
+
path: '/browse/featured',
|
|
232
267
|
children: [
|
|
233
|
-
{
|
|
234
|
-
|
|
268
|
+
{
|
|
269
|
+
title: 'Jazz',
|
|
270
|
+
path: '/browse/jazz',
|
|
271
|
+
artwork: 'https://…/jazz.jpg'
|
|
272
|
+
},
|
|
273
|
+
{
|
|
274
|
+
title: 'Rock',
|
|
275
|
+
path: '/browse/rock',
|
|
276
|
+
artwork: 'https://…/rock.jpg'
|
|
277
|
+
}
|
|
235
278
|
]
|
|
236
279
|
}
|
|
237
280
|
]
|
|
238
281
|
}
|
|
239
282
|
```
|
|
240
283
|
|
|
241
|
-
Each tile is an ordinary Track, so its `artwork` runs through the same pipeline as any other. Tile styles presume artwork: a track without any renders as a placeholder tile plus its title — the artwork `resolve` hook is the place to supply fallback art.
|
|
284
|
+
Each tile is an ordinary Track, so its `artwork` runs through the same pipeline as any other. Tile styles presume artwork: a track without any renders as a placeholder tile plus its title — the artwork `resolve` hook is the place to supply fallback art.
|
|
285
|
+
|
|
286
|
+
See [Browser → Presentation](/guide/browser#presentation) for the full per-surface rundown.
|
|
242
287
|
|
|
243
288
|
## API summary
|
|
244
289
|
|
|
245
|
-
| Symbol | Purpose
|
|
246
|
-
| --------------------------------------------------------------------- |
|
|
247
|
-
| [`Track.artwork`](/api/types/browser-nodes/#track) | The image you set — `https` URL, `sf:` symbol (iOS), or
|
|
248
|
-
| [`Track.artworkSource`](/api/types/browser-nodes/#track) | Output-only resolved `ImageSource` for your own `<Image>`.
|
|
249
|
-
| [`TrackStyle.artworkRendering`](/api/types/browser-nodes/#trackstyle) | `'stencil'` tints a monochrome icon per CarPlay light/dark (iOS only).
|
|
250
|
-
| [`ArtworkVariants`](/api/types/browser-nodes/#artworkvariants) | A `{ light, dark }` pair set on `artwork` when the appearances need different images.
|
|
251
|
-
| [`artwork`](/api/types/browser/#artworkrequestconfig) | Config for browse-row image requests (and the default everywhere).
|
|
252
|
-
| `nowPlayingArtwork` | Separate config for now-playing art;
|
|
253
|
-
| [`imageQueryParams`](/api/types/browser/#imagequeryparams) | Map the surface's requested size to your CDN's query params.
|
|
254
|
-
| [`ImageContext`](/api/types/browser/#imagecontext) | Requested `width`/`height` in pixels, passed to `transform`.
|
|
255
|
-
| [`Section.style`](/api/types/browser-nodes/#sectionstyle) | `display: 'grid'` (± `gridWrap: false`) renders a section's tracks as artwork tiles.
|
|
290
|
+
| Symbol | Purpose |
|
|
291
|
+
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
292
|
+
| [`Track.artwork`](/api/types/browser-nodes/#track) | The image you set — `https` URL, `sf:` symbol (iOS), platform URI, or a `{ light, dark }` pair. |
|
|
293
|
+
| [`Track.artworkSource`](/api/types/browser-nodes/#track) | Output-only resolved `ImageSource` for your own `<Image>`. |
|
|
294
|
+
| [`TrackStyle.artworkRendering`](/api/types/browser-nodes/#trackstyle) | `'stencil'` tints a monochrome icon per CarPlay light/dark (iOS only). |
|
|
295
|
+
| [`ArtworkVariants`](/api/types/browser-nodes/#artworkvariants) | A `{ light, dark }` pair set on `artwork` when the appearances need different images. |
|
|
296
|
+
| [`artwork`](/api/types/browser/#artworkrequestconfig) | Config for browse-row image requests (and the default everywhere). |
|
|
297
|
+
| `nowPlayingArtwork` | Separate config for now-playing art; native-only. |
|
|
298
|
+
| [`imageQueryParams`](/api/types/browser/#imagequeryparams) | Map the surface's requested size to your CDN's query params. |
|
|
299
|
+
| [`ImageContext`](/api/types/browser/#imagecontext) | Requested `width`/`height` in pixels, passed to `transform`. |
|
|
300
|
+
| [`Section.style`](/api/types/browser-nodes/#sectionstyle) | `display: 'grid'` (± `gridWrap: false`) renders a section's tracks as artwork tiles. |
|
|
@@ -9,15 +9,16 @@ react when it changes, and open the system output switcher so the listener can
|
|
|
9
9
|
move playback to another device. Both layers are **cross-platform**:
|
|
10
10
|
|
|
11
11
|
- **Reading the current output** — `getOutput()` / `useOutput()` /
|
|
12
|
-
`onOutputChanged`. iOS reports the active route while a session is active
|
|
13
|
-
Android reports the
|
|
14
|
-
|
|
12
|
+
`onOutputChanged`. iOS reports the active route while a session is active.
|
|
13
|
+
Android reports the device media is routed to; below Android 13 it can miss a
|
|
14
|
+
reroute made while a device stays connected.
|
|
15
15
|
- **Opening the switcher** — `openOutputPicker()` / `supportsOutputSwitcher()`:
|
|
16
16
|
the system route picker on iOS, the system Output Switcher on Android 11+.
|
|
17
17
|
|
|
18
18
|
::: tip Gate the switcher button on `supportsOutputSwitcher()`
|
|
19
19
|
Surface your output button only when `supportsOutputSwitcher()` is `true` — it's
|
|
20
20
|
`true` on iOS and Android 11+ (API 30), `false` on older Android and web.
|
|
21
|
+
|
|
21
22
|
Reading the current output works more broadly, but `getOutput()` can still be
|
|
22
23
|
`undefined` (before playback, or when unknown) — so guard for it.
|
|
23
24
|
:::
|
|
@@ -50,24 +51,46 @@ An [`Output`](/api/features/output/#output) is:
|
|
|
50
51
|
| `type` | `OutputType` | The output kind (see below). |
|
|
51
52
|
| `external` | `boolean` | `false` only for the built-in speaker/receiver; `true` for everything external. |
|
|
52
53
|
|
|
53
|
-
`type` is one of `'speaker'`, `'receiver'` (the
|
|
54
|
-
`'bluetooth'`, `'airplay'`, `'car'`, `'hdmi'`, `'usb'`, `'cast'`
|
|
55
|
-
(see below), `'remote'` (a remote speaker or TV, see below), or
|
|
56
|
-
|
|
57
|
-
`'bluetooth'`.
|
|
58
|
-
|
|
59
|
-
::: warning Android
|
|
60
|
-
On Android the
|
|
61
|
-
|
|
62
|
-
|
|
54
|
+
`type` is one of `'speaker'`, `'receiver'` (the built-in earpiece),
|
|
55
|
+
`'headphones'`, `'bluetooth'`, `'airplay'`, `'car'`, `'hdmi'`, `'usb'`, `'cast'`
|
|
56
|
+
and `'sonos'` (see below), `'remote'` (a remote speaker or TV, see below), or
|
|
57
|
+
`'other'`. Both platforms map their native ports/routes into this shared set —
|
|
58
|
+
e.g. iOS's separate Bluetooth ports all collapse to `'bluetooth'`.
|
|
59
|
+
|
|
60
|
+
::: warning Android below 13 can miss a reroute
|
|
61
|
+
On Android 13+ (API 33), the output is the device media is routed to. Below
|
|
62
|
+
that, the library picks from the connected devices: Bluetooth, then wired
|
|
63
|
+
headphones, then the speaker. It misses a reroute made while a device stays
|
|
64
|
+
connected.
|
|
63
65
|
:::
|
|
64
66
|
|
|
67
|
+
`'airplay'` and `'car'` come from iOS only. On Android, a car's Bluetooth
|
|
68
|
+
reports `'bluetooth'`.
|
|
69
|
+
|
|
70
|
+
Outside React, read a snapshot with `getOutput()` or subscribe with
|
|
71
|
+
[`onOutputChanged`](/api/features/output/#onoutputchanged):
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { getOutput, onOutputChanged } from 'react-native-audio-browser'
|
|
75
|
+
|
|
76
|
+
getOutput() // Output | undefined
|
|
77
|
+
|
|
78
|
+
const unsubscribe = onOutputChanged.addListener((output) => {
|
|
79
|
+
console.log('now playing on', output.name)
|
|
80
|
+
})
|
|
81
|
+
|
|
82
|
+
// later:
|
|
83
|
+
unsubscribe()
|
|
84
|
+
```
|
|
85
|
+
|
|
65
86
|
### Remote outputs (Android)
|
|
66
87
|
|
|
67
88
|
With `remoteOutputs: {}` in [`setupPlayer`](/guide/configuration), the system
|
|
68
89
|
Output Switcher (Android 11+) also lists the speakers and TVs of media route
|
|
69
90
|
providers, and the one the listener selects becomes the output, with
|
|
70
|
-
`type: 'remote'`.
|
|
91
|
+
`type: 'remote'`.
|
|
92
|
+
|
|
93
|
+
While one is selected, the switcher offers **Stop casting**
|
|
71
94
|
rather than the phone's own outputs; stopping reports the local device again.
|
|
72
95
|
|
|
73
96
|
The switcher moves the session only for an app that declares AndroidX's
|
|
@@ -85,13 +108,9 @@ logs a warning saying the receiver is missing.
|
|
|
85
108
|
Each `setupPlayer` sets the remote outputs: a call that leaves `remoteOutputs`
|
|
86
109
|
out turns them off, and playback on one comes back to the phone.
|
|
87
110
|
|
|
88
|
-
::: tip Migrating from `remoteOutputs: true`
|
|
89
|
-
`remoteOutputs` was a boolean; it is now an object, with a flag for each output
|
|
90
|
-
the library plays on. `remoteOutputs: true` becomes `remoteOutputs: {}`.
|
|
91
|
-
:::
|
|
92
|
-
|
|
93
111
|
A provider offers its routes by declaring the library's control category,
|
|
94
|
-
`com.audiobrowser.RemoteOutputs.CATEGORY
|
|
112
|
+
`"com.audiobrowser.CATEGORY_REMOTE_OUTPUT"` (`RemoteOutputs.CATEGORY` in
|
|
113
|
+
Kotlin), in its control filters. Only the
|
|
95
114
|
selection is reported: the library keeps playing locally, and rendering the
|
|
96
115
|
audio on the speaker is the provider's job.
|
|
97
116
|
|
|
@@ -99,10 +118,10 @@ audio on the speaker is the provider's job.
|
|
|
99
118
|
|
|
100
119
|
With `remoteOutputs: { cast: true }`, selecting a Cast device in the switcher
|
|
101
120
|
moves playback there, through Google's Default Media Receiver, or the receiver
|
|
102
|
-
`castReceiverApplicationId` names. The output
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
same track.
|
|
121
|
+
`castReceiverApplicationId` names. The output reports `type: 'cast'`.
|
|
122
|
+
|
|
123
|
+
The queue, the position and the play intent move across both ways: **Stop
|
|
124
|
+
casting** brings playback back to the phone, at the same track.
|
|
106
125
|
|
|
107
126
|
```ts
|
|
108
127
|
await setupPlayer({ remoteOutputs: { cast: true } })
|
|
@@ -134,8 +153,9 @@ phone and the library logs a warning.
|
|
|
134
153
|
|
|
135
154
|
The receiver fetches the stream itself:
|
|
136
155
|
|
|
137
|
-
- It gets the URL
|
|
138
|
-
|
|
156
|
+
- It gets the URL the `media` request config resolves the track's `src` to
|
|
157
|
+
(your Transform and Resolve included), without its headers. A stream that
|
|
158
|
+
needs request headers won't play on it.
|
|
139
159
|
- A track without a file extension is sent as `audio/mpeg`; the receiver works
|
|
140
160
|
out the real codec. A track with `live: true` loads as a live stream.
|
|
141
161
|
- The receiver shows the track's title, artist and artwork. It doesn't read
|
|
@@ -174,7 +194,8 @@ the library talks to the speakers itself.
|
|
|
174
194
|
|
|
175
195
|
```xml
|
|
176
196
|
<!-- android/app/src/main/AndroidManifest.xml -->
|
|
177
|
-
<uses-permission
|
|
197
|
+
<uses-permission
|
|
198
|
+
android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
|
|
178
199
|
```
|
|
179
200
|
|
|
180
201
|
Without the permission, the library logs a warning and looks for rooms without
|
|
@@ -182,30 +203,35 @@ the lock, so a room can be missed while the phone saves power on Wi-Fi.
|
|
|
182
203
|
|
|
183
204
|
Local network access: the library finds and controls the rooms itself, over
|
|
184
205
|
the local network. An app that targets SDK 36 or lower has that access through
|
|
185
|
-
`INTERNET`, and needs nothing more.
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
See Android's
|
|
206
|
+
`INTERNET`, and needs nothing more.
|
|
207
|
+
|
|
208
|
+
From target SDK 37 (Android 17), Android blocks the local network until the
|
|
209
|
+
app is granted the runtime permission `ACCESS_LOCAL_NETWORK`. The library
|
|
210
|
+
doesn't request it, so request it in your app: without it, rooms don't appear
|
|
211
|
+
and can't be controlled. For what Android exempts, see its
|
|
192
212
|
[local network permission](https://developer.android.com/privacy-and-security/local-network-permission).
|
|
193
213
|
|
|
194
214
|
::: warning Sonos support is a bonus, not a promise
|
|
195
|
-
The library controls the speakers over UPnP, on port 1400 of each speaker.
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
215
|
+
The library controls the speakers over UPnP, on port 1400 of each speaker.
|
|
216
|
+
|
|
217
|
+
Sonos calls UPnP unsupported and unmaintained, and lets the listener switch it
|
|
218
|
+
off in the Sonos app. When it is off, or Sonos removes it, the rooms don't
|
|
219
|
+
appear in the switcher.
|
|
220
|
+
|
|
221
|
+
The library doesn't use Sonos's cloud or local Control APIs, which need
|
|
222
|
+
Sonos's approval.
|
|
200
223
|
:::
|
|
201
224
|
|
|
202
225
|
What plays:
|
|
203
226
|
|
|
204
|
-
- The speaker fetches the stream itself, from the URL
|
|
205
|
-
resolves
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
227
|
+
- The speaker fetches the stream itself, from the URL the `media` request
|
|
228
|
+
config resolves the track's `src` to (your Transform and Resolve
|
|
229
|
+
included), without its headers.
|
|
230
|
+
- A live stream goes as a radio stream: the speaker follows redirects and works
|
|
231
|
+
out the codec, so MP3, AAC and HLS streams play, over `https` and plain
|
|
232
|
+
`http`.
|
|
233
|
+
- A track goes as a file, in a format the speaker plays, so the speaker
|
|
234
|
+
knows its duration and can seek in it.
|
|
209
235
|
- The speaker is sent the track's title, artist and artwork to show.
|
|
210
236
|
- The speaker reads song titles from the stream (ICY titles, and the ID3 titles
|
|
211
237
|
of HLS streams). The library polls them and reports them through
|
|
@@ -226,8 +252,8 @@ Grouping:
|
|
|
226
252
|
- The library doesn't group or ungroup rooms; the listener does that in the
|
|
227
253
|
Sonos app.
|
|
228
254
|
|
|
229
|
-
While on Sonos, local-only behaviour steps aside as it does for Cast
|
|
230
|
-
volume is the speaker's, the equalizer waits for the phone
|
|
255
|
+
While on Sonos, local-only behaviour steps aside as it does for Cast. The
|
|
256
|
+
volume is the speaker's, and the equalizer waits for the phone. A speaker error
|
|
231
257
|
reaches the app as a playback error, as does a speaker that stops answering.
|
|
232
258
|
|
|
233
259
|
Known limits:
|
|
@@ -235,8 +261,8 @@ Known limits:
|
|
|
235
261
|
- Rooms are found by SSDP multicast on the local network, so the phone and the
|
|
236
262
|
speakers must share it; guest and isolated Wi-Fi networks hide them.
|
|
237
263
|
- A track that needs request headers won't play.
|
|
238
|
-
- The state is polled
|
|
239
|
-
|
|
264
|
+
- The state is polled, so a change made in the Sonos app shows up here after a
|
|
265
|
+
moment.
|
|
240
266
|
- If another app or the Sonos app starts something else on the room, this app
|
|
241
267
|
reads as paused and leaves the room alone; playing again loads its own track.
|
|
242
268
|
- Android only. On iOS, a Sonos speaker with AirPlay 2 appears in the route
|
|
@@ -260,7 +286,7 @@ Cast and Sonos play the queue the same way:
|
|
|
260
286
|
- Moving from one room or Cast device to another goes straight there, without
|
|
261
287
|
the phone in between.
|
|
262
288
|
- A receiver that fails to play reaches the app as a playback error with code
|
|
263
|
-
`remote-error
|
|
289
|
+
`remote-error`. So does an item whose URL can't be resolved for it, and one
|
|
264
290
|
the receiver hasn't started within 30 seconds of being sent or played.
|
|
265
291
|
Playing again loads the item there anew.
|
|
266
292
|
|
|
@@ -268,22 +294,6 @@ The library's Sonos route provider service is exported, as the Output Switcher
|
|
|
268
294
|
needs to bind it: another app on the phone can bind it too, list the rooms,
|
|
269
295
|
select one and set its volume, as through any media route provider.
|
|
270
296
|
|
|
271
|
-
Outside React, read a snapshot with `getOutput()` or subscribe with
|
|
272
|
-
[`onOutputChanged`](/api/features/output/#onoutputchanged):
|
|
273
|
-
|
|
274
|
-
```ts
|
|
275
|
-
import { getOutput, onOutputChanged } from 'react-native-audio-browser'
|
|
276
|
-
|
|
277
|
-
getOutput() // Output | undefined
|
|
278
|
-
|
|
279
|
-
const unsubscribe = onOutputChanged.addListener((output) => {
|
|
280
|
-
console.log('now playing on', output.name)
|
|
281
|
-
})
|
|
282
|
-
|
|
283
|
-
// later:
|
|
284
|
-
unsubscribe()
|
|
285
|
-
```
|
|
286
|
-
|
|
287
297
|
## Opening the output picker
|
|
288
298
|
|
|
289
299
|
[`openOutputPicker()`](/api/features/output/#openoutputpicker) presents the
|
|
@@ -313,7 +323,9 @@ from showing a control that would do nothing.
|
|
|
313
323
|
On Android the switcher is the system one (the picker from the media
|
|
314
324
|
notification); selecting a Bluetooth speaker there routes audio at the OS level.
|
|
315
325
|
The library can't force playback to a _specific_ Bluetooth device itself — route
|
|
316
|
-
selection is the system's job, which is what this hands off to.
|
|
326
|
+
selection is the system's job, which is what this hands off to.
|
|
327
|
+
|
|
328
|
+
Sonos appears on
|
|
317
329
|
iOS as an AirPlay target, and on Android with `remoteOutputs: { sonos: true }`.
|
|
318
330
|
|
|
319
331
|
## You may not need this for unplug handling
|
|
@@ -321,10 +333,15 @@ iOS as an AirPlay target, and on Android with `remoteOutputs: { sonos: true }`.
|
|
|
321
333
|
When the current output **disappears** — headphones unplugged, a Bluetooth
|
|
322
334
|
speaker powered off — the player **pauses automatically** rather than blaring out
|
|
323
335
|
of the built-in speaker (the convention every media app follows). It's a
|
|
324
|
-
deliberate pause: the listener presses play again when ready.
|
|
336
|
+
deliberate pause: the listener presses play again when ready.
|
|
337
|
+
|
|
338
|
+
So you don't need
|
|
325
339
|
to watch `onOutputChanged` just to handle unplugging — reach for these APIs to
|
|
326
340
|
_display_ the output or to _offer_ a switcher.
|
|
327
341
|
|
|
342
|
+
On Android, `setupPlayer({ android: { handleAudioBecomingNoisy: false } })`
|
|
343
|
+
turns the pause off. On iOS it always happens.
|
|
344
|
+
|
|
328
345
|
## API summary
|
|
329
346
|
|
|
330
347
|
| API | Platforms | Purpose |
|
|
@@ -336,4 +353,5 @@ _display_ the output or to _offer_ a switcher.
|
|
|
336
353
|
| `onOutputChanged` | iOS, Android | Subscribe outside React; `addListener(cb)` returns an unsubscribe fn. |
|
|
337
354
|
|
|
338
355
|
The whole API is cross-platform; only the switcher needs Android 11+ (gate on
|
|
339
|
-
`supportsOutputSwitcher()`)
|
|
356
|
+
`supportsOutputSwitcher()`). Below Android 13, the output can miss a reroute
|
|
357
|
+
made while a device stays connected.
|
|
@@ -16,7 +16,12 @@ already built**:
|
|
|
16
16
|
whether the user started it in-app or in the car,
|
|
17
17
|
- your [`search` source](/guide/search) answers in-car voice commands
|
|
18
18
|
("play jazz"),
|
|
19
|
-
- [favorites](/guide/favorites)
|
|
19
|
+
- your [favorites](/guide/favorites) are one state shared by the app and the
|
|
20
|
+
car. With `capabilities.favorite` on, Android Auto shows the heart; CarPlay
|
|
21
|
+
shows it once you list it in `ios.carPlayNowPlayingButtons` (see
|
|
22
|
+
[Favoriting from system controls](/guide/favorites#favoriting-from-system-controls)).
|
|
23
|
+
Only Siri understands "play my favorites"; Android Auto searches the phrase
|
|
24
|
+
as plain text.
|
|
20
25
|
|
|
21
26
|
Build those once and they light up every car surface. The per-platform pages
|
|
22
27
|
handle the platform-specific **setup**: **[Android Auto](/guide/android-auto)**
|
|
@@ -24,15 +29,15 @@ handle the platform-specific **setup**: **[Android Auto](/guide/android-auto)**
|
|
|
24
29
|
|
|
25
30
|
## Shared vs platform-specific
|
|
26
31
|
|
|
27
|
-
| Concern
|
|
28
|
-
|
|
|
29
|
-
| Browse tree / menus
|
|
30
|
-
| Now-playing metadata & artwork
|
|
31
|
-
| Player, queue, playback
|
|
32
|
-
| Voice search ("play …")
|
|
33
|
-
| Favorites
|
|
34
|
-
| App setup, entitlements, manifest
|
|
35
|
-
| Now-playing buttons
|
|
32
|
+
| Concern | Where it's handled |
|
|
33
|
+
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
34
|
+
| Browse tree / menus | Shared — [Browser](/guide/browser) |
|
|
35
|
+
| Now-playing metadata & artwork | Shared — [Now Playing](/guide/now-playing) |
|
|
36
|
+
| Player, queue, playback | Shared — [Playback](/guide/playback) |
|
|
37
|
+
| Voice search ("play …") | Shared — your [`search`](/guide/search) source |
|
|
38
|
+
| Favorites state | Shared — [Favorites](/guide/favorites) |
|
|
39
|
+
| App setup, entitlements, manifest | Per-platform — [Android Auto](/guide/android-auto) / [CarPlay](/guide/carplay) |
|
|
40
|
+
| Now-playing buttons, the heart among them | Per-platform — [Button layout](/guide/remote-controls#button-layout-android) (Android) / [`ios.carPlayNowPlayingButtons`](/guide/carplay#now-playing-buttons) (iOS) |
|
|
36
41
|
|
|
37
42
|
The takeaway: spend your effort on the shared content model; reach for a platform
|
|
38
43
|
page only for that platform's setup and buttons.
|