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.
Files changed (271) hide show
  1. package/README.md +32 -19
  2. package/lib/commonjs/CLAUDE.md +7 -2
  3. package/lib/commonjs/features/battery.js +16 -12
  4. package/lib/commonjs/features/battery.js.map +1 -1
  5. package/lib/commonjs/features/browser-config.js +1 -1
  6. package/lib/commonjs/features/browser.js +74 -24
  7. package/lib/commonjs/features/browser.js.map +1 -1
  8. package/lib/commonjs/features/carConnection.js +3 -4
  9. package/lib/commonjs/features/carConnection.js.map +1 -1
  10. package/lib/commonjs/features/equalizer.js +9 -5
  11. package/lib/commonjs/features/equalizer.js.map +1 -1
  12. package/lib/commonjs/features/errors.js +35 -21
  13. package/lib/commonjs/features/errors.js.map +1 -1
  14. package/lib/commonjs/features/favorites.js +15 -13
  15. package/lib/commonjs/features/favorites.js.map +1 -1
  16. package/lib/commonjs/features/gate.js +12 -6
  17. package/lib/commonjs/features/gate.js.map +1 -1
  18. package/lib/commonjs/features/metadata.js +16 -14
  19. package/lib/commonjs/features/metadata.js.map +1 -1
  20. package/lib/commonjs/features/network.js +5 -1
  21. package/lib/commonjs/features/network.js.map +1 -1
  22. package/lib/commonjs/features/nowPlaying.js +28 -14
  23. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  24. package/lib/commonjs/features/output.js +8 -4
  25. package/lib/commonjs/features/output.js.map +1 -1
  26. package/lib/commonjs/features/playback/controls.js +10 -5
  27. package/lib/commonjs/features/playback/controls.js.map +1 -1
  28. package/lib/commonjs/features/playback/playWhenReady.js +6 -5
  29. package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
  30. package/lib/commonjs/features/playback/playing.js +5 -3
  31. package/lib/commonjs/features/playback/playing.js.map +1 -1
  32. package/lib/commonjs/features/playback/progress.js +11 -5
  33. package/lib/commonjs/features/playback/progress.js.map +1 -1
  34. package/lib/commonjs/features/playback/state.js +3 -3
  35. package/lib/commonjs/features/playback/state.js.map +1 -1
  36. package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
  37. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  38. package/lib/commonjs/features/playback/volume.js +6 -5
  39. package/lib/commonjs/features/playback/volume.js.map +1 -1
  40. package/lib/commonjs/features/player/options.js +20 -10
  41. package/lib/commonjs/features/player/options.js.map +1 -1
  42. package/lib/commonjs/features/player/setup.js +34 -38
  43. package/lib/commonjs/features/player/setup.js.map +1 -1
  44. package/lib/commonjs/features/queue/activeTrack.js +0 -1
  45. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  46. package/lib/commonjs/features/queue/queue.js +48 -20
  47. package/lib/commonjs/features/queue/queue.js.map +1 -1
  48. package/lib/commonjs/features/queue/repeatMode.js +2 -1
  49. package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
  50. package/lib/commonjs/features/queue/shuffle.js +0 -1
  51. package/lib/commonjs/features/queue/shuffle.js.map +1 -1
  52. package/lib/commonjs/features/remoteControls.js +59 -35
  53. package/lib/commonjs/features/remoteControls.js.map +1 -1
  54. package/lib/commonjs/features/sleepTimer.js +15 -6
  55. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  56. package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
  57. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  58. package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
  59. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  60. package/lib/commonjs/utils/getTrackIdentity.js +6 -4
  61. package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
  62. package/lib/commonjs/utils/useDebug.js +16 -3
  63. package/lib/commonjs/utils/useDebug.js.map +1 -1
  64. package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
  65. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  66. package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
  67. package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
  68. package/lib/commonjs/web/browser/sections.js +1 -1
  69. package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
  70. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  71. package/lib/module/CLAUDE.md +7 -2
  72. package/lib/module/features/battery.js +16 -12
  73. package/lib/module/features/battery.js.map +1 -1
  74. package/lib/module/features/browser-config.js +1 -1
  75. package/lib/module/features/browser.js +74 -24
  76. package/lib/module/features/browser.js.map +1 -1
  77. package/lib/module/features/carConnection.js +3 -4
  78. package/lib/module/features/carConnection.js.map +1 -1
  79. package/lib/module/features/equalizer.js +9 -5
  80. package/lib/module/features/equalizer.js.map +1 -1
  81. package/lib/module/features/errors.js +35 -21
  82. package/lib/module/features/errors.js.map +1 -1
  83. package/lib/module/features/favorites.js +15 -13
  84. package/lib/module/features/favorites.js.map +1 -1
  85. package/lib/module/features/gate.js +12 -6
  86. package/lib/module/features/gate.js.map +1 -1
  87. package/lib/module/features/metadata.js +16 -14
  88. package/lib/module/features/metadata.js.map +1 -1
  89. package/lib/module/features/network.js +5 -1
  90. package/lib/module/features/network.js.map +1 -1
  91. package/lib/module/features/nowPlaying.js +28 -14
  92. package/lib/module/features/nowPlaying.js.map +1 -1
  93. package/lib/module/features/output.js +8 -4
  94. package/lib/module/features/output.js.map +1 -1
  95. package/lib/module/features/playback/controls.js +10 -5
  96. package/lib/module/features/playback/controls.js.map +1 -1
  97. package/lib/module/features/playback/playWhenReady.js +6 -5
  98. package/lib/module/features/playback/playWhenReady.js.map +1 -1
  99. package/lib/module/features/playback/playing.js +5 -3
  100. package/lib/module/features/playback/playing.js.map +1 -1
  101. package/lib/module/features/playback/progress.js +11 -5
  102. package/lib/module/features/playback/progress.js.map +1 -1
  103. package/lib/module/features/playback/state.js +3 -3
  104. package/lib/module/features/playback/state.js.map +1 -1
  105. package/lib/module/features/playback/trackPlaybackTime.js +6 -1
  106. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  107. package/lib/module/features/playback/volume.js +6 -5
  108. package/lib/module/features/playback/volume.js.map +1 -1
  109. package/lib/module/features/player/options.js +20 -10
  110. package/lib/module/features/player/options.js.map +1 -1
  111. package/lib/module/features/player/setup.js +34 -38
  112. package/lib/module/features/player/setup.js.map +1 -1
  113. package/lib/module/features/queue/activeTrack.js +0 -1
  114. package/lib/module/features/queue/activeTrack.js.map +1 -1
  115. package/lib/module/features/queue/queue.js +48 -20
  116. package/lib/module/features/queue/queue.js.map +1 -1
  117. package/lib/module/features/queue/repeatMode.js +2 -1
  118. package/lib/module/features/queue/repeatMode.js.map +1 -1
  119. package/lib/module/features/queue/shuffle.js +0 -1
  120. package/lib/module/features/queue/shuffle.js.map +1 -1
  121. package/lib/module/features/remoteControls.js +59 -35
  122. package/lib/module/features/remoteControls.js.map +1 -1
  123. package/lib/module/features/sleepTimer.js +15 -6
  124. package/lib/module/features/sleepTimer.js.map +1 -1
  125. package/lib/module/utils/LazyNativeEmitter.js +6 -9
  126. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  127. package/lib/module/utils/NativeUpdatedValue.js +13 -12
  128. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  129. package/lib/module/utils/getTrackIdentity.js +6 -4
  130. package/lib/module/utils/getTrackIdentity.js.map +1 -1
  131. package/lib/module/utils/useDebug.js +16 -3
  132. package/lib/module/utils/useDebug.js.map +1 -1
  133. package/lib/module/web/NativeAudioBrowser.js +2 -4
  134. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  135. package/lib/module/web/browser/parseSearchResponse.js +3 -4
  136. package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
  137. package/lib/module/web/browser/sections.js +1 -1
  138. package/lib/module/web/util/BrowserPathHelper.js +1 -3
  139. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  140. package/lib/typescript/src/features/battery.d.ts +17 -12
  141. package/lib/typescript/src/features/battery.d.ts.map +1 -1
  142. package/lib/typescript/src/features/browser.d.ts +64 -24
  143. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  144. package/lib/typescript/src/features/carConnection.d.ts +3 -4
  145. package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
  146. package/lib/typescript/src/features/equalizer.d.ts +9 -5
  147. package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
  148. package/lib/typescript/src/features/errors.d.ts +37 -22
  149. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  150. package/lib/typescript/src/features/favorites.d.ts +15 -13
  151. package/lib/typescript/src/features/favorites.d.ts.map +1 -1
  152. package/lib/typescript/src/features/gate.d.ts +14 -8
  153. package/lib/typescript/src/features/gate.d.ts.map +1 -1
  154. package/lib/typescript/src/features/metadata.d.ts +37 -17
  155. package/lib/typescript/src/features/metadata.d.ts.map +1 -1
  156. package/lib/typescript/src/features/network.d.ts +5 -1
  157. package/lib/typescript/src/features/network.d.ts.map +1 -1
  158. package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
  159. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  160. package/lib/typescript/src/features/output.d.ts +8 -4
  161. package/lib/typescript/src/features/output.d.ts.map +1 -1
  162. package/lib/typescript/src/features/playback/controls.d.ts +10 -5
  163. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  164. package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
  165. package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
  166. package/lib/typescript/src/features/playback/playing.d.ts +16 -3
  167. package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
  168. package/lib/typescript/src/features/playback/progress.d.ts +11 -5
  169. package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
  170. package/lib/typescript/src/features/playback/state.d.ts +8 -3
  171. package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
  172. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
  173. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  174. package/lib/typescript/src/features/playback/volume.d.ts +6 -5
  175. package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
  176. package/lib/typescript/src/features/player/options.d.ts +52 -37
  177. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  178. package/lib/typescript/src/features/player/setup.d.ts +65 -60
  179. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  180. package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
  181. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  182. package/lib/typescript/src/features/queue/queue.d.ts +48 -20
  183. package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
  184. package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
  185. package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
  186. package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
  187. package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
  188. package/lib/typescript/src/features/remoteControls.d.ts +58 -25
  189. package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
  190. package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
  191. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  192. package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
  193. package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
  194. package/lib/typescript/src/types/browser.d.ts +181 -144
  195. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  196. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
  197. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  198. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
  199. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  200. package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
  201. package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
  202. package/lib/typescript/src/utils/useDebug.d.ts +16 -3
  203. package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
  204. package/package.json +1 -1
  205. package/src/CLAUDE.md +7 -2
  206. package/src/docs-floors.test.ts +71 -0
  207. package/src/features/battery.ts +17 -13
  208. package/src/features/browser-config.ts +1 -1
  209. package/src/features/browser.ts +65 -24
  210. package/src/features/carConnection.ts +3 -4
  211. package/src/features/equalizer.ts +9 -5
  212. package/src/features/errors.ts +37 -22
  213. package/src/features/favorites.ts +15 -13
  214. package/src/features/gate.ts +14 -8
  215. package/src/features/metadata.ts +37 -17
  216. package/src/features/network.ts +5 -1
  217. package/src/features/nowPlaying.ts +28 -14
  218. package/src/features/output.ts +8 -4
  219. package/src/features/playback/controls.ts +10 -5
  220. package/src/features/playback/playWhenReady.ts +6 -5
  221. package/src/features/playback/playing.ts +16 -3
  222. package/src/features/playback/progress.ts +11 -5
  223. package/src/features/playback/state.ts +8 -3
  224. package/src/features/playback/trackPlaybackTime.ts +9 -2
  225. package/src/features/playback/volume.ts +6 -5
  226. package/src/features/player/options.ts +54 -43
  227. package/src/features/player/setup.ts +67 -61
  228. package/src/features/queue/activeTrack.ts +0 -1
  229. package/src/features/queue/queue.ts +48 -20
  230. package/src/features/queue/repeatMode.ts +1 -1
  231. package/src/features/queue/shuffle.ts +0 -1
  232. package/src/features/remoteControls.ts +59 -35
  233. package/src/features/sleepTimer.ts +15 -7
  234. package/src/types/browser-nodes.ts +54 -57
  235. package/src/types/browser.ts +183 -146
  236. package/src/utils/LazyNativeEmitter.ts +6 -9
  237. package/src/utils/NativeUpdatedValue.ts +13 -12
  238. package/src/utils/getTrackIdentity.ts +6 -4
  239. package/src/utils/useDebug.ts +16 -3
  240. package/src/web/NativeAudioBrowser.ts +2 -4
  241. package/src/web/browser/parseSearchResponse.ts +3 -4
  242. package/src/web/browser/sections.ts +1 -1
  243. package/src/web/util/BrowserPathHelper.ts +1 -3
  244. package/website/guide/android-auto.md +25 -13
  245. package/website/guide/android-certificates.md +199 -120
  246. package/website/guide/artwork.md +93 -48
  247. package/website/guide/audio-output.md +86 -68
  248. package/website/guide/automotive.md +15 -10
  249. package/website/guide/basic-usage.md +5 -2
  250. package/website/guide/battery.md +50 -23
  251. package/website/guide/browser.md +155 -68
  252. package/website/guide/carplay.md +132 -49
  253. package/website/guide/configuration.md +85 -49
  254. package/website/guide/equalizer.md +36 -32
  255. package/website/guide/errors.md +106 -64
  256. package/website/guide/favorites.md +41 -31
  257. package/website/guide/gate.md +24 -10
  258. package/website/guide/getting-started.md +55 -2
  259. package/website/guide/hooks.md +53 -47
  260. package/website/guide/live-streams.md +80 -49
  261. package/website/guide/metadata.md +87 -53
  262. package/website/guide/migrating-from-track-player.md +94 -49
  263. package/website/guide/native-callback-fetch.md +46 -36
  264. package/website/guide/network.md +36 -20
  265. package/website/guide/now-playing.md +72 -44
  266. package/website/guide/playback.md +112 -35
  267. package/website/guide/queue.md +77 -43
  268. package/website/guide/remote-controls.md +87 -29
  269. package/website/guide/search.md +37 -22
  270. package/website/guide/sleep-timer.md +35 -14
  271. package/website/guide/track.md +59 -35
@@ -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. 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`.
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
- This guide covers the mental model (the two configs and the output field), **which artwork renders where**, the **transform pipeline** that turns your URL into a sized request, and the platform-specific bits: SF Symbols on iOS, tinting, light/dark artwork, Android vector icons, and SVG.
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 | Image from | Size hint | Tinting |
39
- | ----------------------------------------------- | --------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
40
- | **Browse rows / tabs** (CarPlay / Android Auto) | `artwork` (per-route override allowed) | no | CarPlay: `style: { artworkRendering: 'stencil' }`, or a `{ light, dark }` pair |
41
- | **In-app `<Image>`** | `artworkSource` (output) | no | your UI |
42
- | **iOS lock screen / Control Center** | `nowPlayingArtwork` → falls back to `artwork` | yes | — |
43
- | **CarPlay Now Playing** | `nowPlayingArtwork` → `artwork` | yes | — |
44
- | **Android notification / Android Auto** | `nowPlayingArtwork` → `artwork` | yes | — (Android Auto is dark-only) |
45
- | **CarPlay tile sections** (`display: 'grid'`) | `artwork` (each tile is a Track) | yes | CarPlay: `style: { artworkRendering: 'stencil' }`, or a `{ light, dark }` pair |
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
- Two things to take from the table:
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 at load time on CarPlay / Android Auto / now-playing.
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). The `{id}` token is **not** a general feature — only `nowPlayingArtwork` templates it (see below); static values in `artwork` are sent verbatim.
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
- import HmacSHA256 from 'crypto-js/hmac-sha256' // add: yarn add crypto-js
91
+ // add: yarn add crypto-js
92
+ import HmacSHA256 from 'crypto-js/hmac-sha256'
89
93
 
90
- const CDN_KEY = process.env.CDN_KEY ?? '' // your CDN signing key
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
- // request.path is optional — guard it before signing
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`). `request.path` is also optional — it's only set if a `resolve` ran first — so guard it before signing (as above).
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
- `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). 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.
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. Optional `bg` (background, transparent if omitted) and `fg` (symbol color, black if omitted) query params set the colors:
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, an SF Symbol with **no explicit colors** is handed to CarPlay untinted, so CarPlay renders it in the appearance's own color (adapting to light/dark); give it a `bg`/`fg` and you get exactly those colors instead. The library renders the symbol to an image on device and caches it. This is iOS-only; on Android an `sf:` value is not a valid image.
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. CarPlay tints the glyph per appearance: black in light mode, white in dark.
142
- - **Android Auto** is dark-only, so there's no per-appearance tinting — ship an appropriately colored (e.g. white) icon. 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). The library only sets the category style; the visual treatment is Android Auto's — see [Browse display](/guide/android-auto#browse-display).
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 supported on both platforms and detected by a `.svg` URL suffix — serve SVGs with a path ending in `.svg` and they decode as vectors rather than raster images.
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. Each URL runs through the [transform pipeline](#the-transform-pipeline) independently, so `baseUrl`, headers, `imageQueryParams` and `resolve` / `transform` apply to both.
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` (dark-only platform) |
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. To resolve it differently, set `nowPlayingArtwork`, which builds the now-playing image from its **own** request and uniquely supports an `{id}` template filled from the active track's `id`:
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, capped at 1200px — so with `imageQueryParams` set you fetch a fittingly large variant rather than upscaling a tiny thumbnail.
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
- Two separate ideas here: the **`{id}` template** is replaced with the active track's `id`; and if you _don't_ set `nowPlayingArtwork` at all, now-playing surfaces fall back to the `artwork` config (and to `track.artwork`).
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**: the `{id}` template and the `nowPlayingArtwork` config are not applied by the web implementation, where now-playing artwork simply uses the `artwork` config like any other surface. 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.
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. There is no imperative way to swap _only_ the image mid-stream: `updateNowPlaying()` overrides `title` / `artist` / `album`, not artwork. 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).
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
- path: '/browse/featured', // header / "view all" target
265
+ // header / "view all" target
266
+ path: '/browse/featured',
232
267
  children: [
233
- { title: 'Jazz', path: '/browse/jazz', artwork: 'https://…/jazz.jpg' },
234
- { title: 'Rock', path: '/browse/rock', artwork: 'https://…/rock.jpg' }
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. On CarPlay a single-line grid (`gridWrap: false`) shows the tiles that fit on one line (seven on a wide screen, or two condensed cells; the rest are truncated) and a wrapping grid takes as many lines as it needs on iOS 26+ (rendering as a list before that); Android Auto's grid always wraps, so it renders both identically. See [Browser → Presentation](/guide/browser#presentation) for the full per-surface rundown.
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 platform URI. |
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; supports `{id}`; native-only. |
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 active output route from `AudioManager` (the `type` is
14
- coarse — e.g. wired headphones may report as `speaker`).
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 iOS earpiece), `'headphones'`,
54
- `'bluetooth'`, `'airplay'`, `'car'`, `'hdmi'`, `'usb'`, `'cast'` and `'sonos'`
55
- (see below), `'remote'` (a remote speaker or TV, see below), or `'other'`. Both platforms map their native ports/routes into
56
- this shared set — e.g. iOS's separate Bluetooth ports all collapse to
57
- `'bluetooth'`.
58
-
59
- ::: warning Android reports a coarser type
60
- On Android the type comes from the system route and is coarser: wired headphones
61
- often report as `'speaker'` (the built-in route), and really only `'bluetooth'`
62
- is reliably distinguished from it. The device **name** still comes through.
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'`. While one is selected, the switcher offers **Stop casting**
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`, in their control filters. Only the
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
- reports `type: 'cast'`, and the queue, the position and the play intent move
104
- across both ways: **Stop casting** brings playback back to the phone, at the
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 your media transform resolves, without its headers, so a
138
- stream that needs request headers won't play on it.
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 android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
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. From target SDK 37 (Android 17), Android
186
- blocks the local network until the app is granted the runtime permission
187
- `ACCESS_LOCAL_NETWORK`, which the library doesn't request yet. Without it, rooms
188
- don't appear and can't be controlled. Android exempts apps that use the Output
189
- Switcher for Cast, whose discovery the system runs; its docs don't yet say
190
- whether that covers rooms the library finds itself, so plan for the permission.
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. Sonos
196
- calls UPnP unsupported and no longer maintained, and lets the listener switch it
197
- off in the Sonos app (Account › Privacy & Security). When it is off, or Sonos
198
- removes it, the rooms don't appear in the switcher. The library doesn't use
199
- Sonos's cloud or local Control APIs, which need Sonos's approval.
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 your media transform
205
- resolves, without its headers. A live stream goes as a radio stream: the
206
- speaker follows redirects and works out the codec, so MP3, AAC and HLS
207
- streams play, over `https` and plain `http`. A track goes as a file, in a
208
- format the speaker plays, so the speaker knows its duration and can seek in it.
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: the
230
- volume is the speaker's, the equalizer waits for the phone, and a speaker error
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 every two seconds, so a change made in the Sonos app shows
239
- up here after a moment.
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`, as does an item whose URL can't be resolved for it, and one
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. Sonos appears on
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. So you don't need
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()`), and Android reports coarser output `type`s than iOS.
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) surface a heart and a "play my favorites" intent.
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 | Where it's handled |
28
- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
29
- | Browse tree / menus | Shared — [Browser](/guide/browser) |
30
- | Now-playing metadata & artwork | Shared — [Now Playing](/guide/now-playing) |
31
- | Player, queue, playback | Shared — [Playback](/guide/playback) |
32
- | Voice search ("play …") | Shared — your [`search`](/guide/search) source |
33
- | Favorites heart & "play my favorites" | Shared — [Favorites](/guide/favorites) |
34
- | App setup, entitlements, manifest | Per-platform — [Android Auto](/guide/android-auto) / [CarPlay](/guide/carplay) |
35
- | Now-playing buttons | Per-platform — [Button layout](/guide/remote-controls#button-layout-android) (Android) / [CarPlay](/guide/carplay) (iOS) |
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.