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
@@ -13,7 +13,9 @@ CarPlay integration for audio apps works through two systems:
13
13
 
14
14
  On CarPlay's audio interface the search button always triggers Siri — audio apps don't use `CPSearchTemplate` (that's a navigation-app API).
15
15
 
16
- The two systems are independent, but **both** require the [React Native host setup](#react-native-host-uiscene-headless) (UIScene lifecycle + headless RN boot) — that's the one prerequisite every CarPlay app needs, even browse-only. Siri then adds its own entitlement, Info.plist keys, and intent handler on top. The **Loading States** and **Album Line Navigation** sections are optional browse polish — skip them to get a minimal integration working.
16
+ The two systems are independent, but **both** require the [React Native host setup](#react-native-host-uiscene-headless) (UIScene lifecycle + headless RN boot). Every CarPlay app needs it, even browse-only. Siri then adds its own entitlement, Info.plist keys, and intent handler on top.
17
+
18
+ The **Now Playing Buttons**, **Playing Indicator**, **Loading States** and **Album Line Navigation** sections are optional polish. Skip them to get a minimal integration working.
17
19
 
18
20
  ::: info Before you start
19
21
  This page assumes you've installed the library and have the player running: add `react-native-audio-browser`, run `pod install` in `ios/`, and call `setupPlayer()` + `configureBrowser()` at startup. See [Getting Started](/guide/getting-started) and [Basic Usage](/guide/basic-usage) first.
@@ -68,16 +70,27 @@ Your scene manifest needs **two** scene configurations: the CarPlay template sce
68
70
  </dict>
69
71
  ```
70
72
 
71
- The two `UISceneDelegateClassName` strings name the delegates for each scene: the library's `RNABCarPlaySceneDelegate` (ships with the library — you never implement it; it links in once the `AudioBrowser` pod is installed) and your own `PhoneSceneDelegate`. These manifest strings are only a fallback — once you add `configurationForConnecting` (next section), your code picks each scene's delegate. So `PhoneSceneDelegate` not resolving yet, and the CarPlay value being a bare class name, are both expected until you finish the host setup next.
73
+ The two `UISceneDelegateClassName` strings name the delegate for each scene:
74
+
75
+ - `RNABCarPlaySceneDelegate` ships with the library. You never implement it; it links in once the `AudioBrowser` pod is installed.
76
+ - `PhoneSceneDelegate` is your own, written in the host setup below.
77
+
78
+ These manifest strings are only a fallback: once you add `configurationForConnecting` (next section), your code picks each scene's delegate. Until you finish the host setup, `PhoneSceneDelegate` does not resolve yet, and that is expected.
72
79
 
73
80
  ## React Native host (UIScene + headless)
74
81
 
75
- This section is **required for any CarPlay integration** — browse-only or Siri. CarPlay connects through scenes and can launch your app in the background with no phone window, so React Native has to be startable both on the foreground path (your phone scene) and headless (a hidden window). Set this up once; both the browse templates and Siri depend on it.
82
+ This section is **required for any CarPlay integration**, browse-only or Siri. Set it up once; both the browse templates and Siri depend on it.
83
+
84
+ CarPlay connects through scenes and can launch your app in the background with no phone window. So React Native has to start both on the foreground path (your phone scene) and headless (in a hidden window).
76
85
 
77
86
  ::: warning Two prerequisites
78
- **UIScene lifecycle** — CarPlay requires a `UIWindowSceneDelegate` for the phone window. The default `npx react-native init` app isn't scene-based; if yours still sets up its window directly in `AppDelegate`, migrate to scenes first (the sections below build all the pieces).
87
+ **UIScene lifecycle** — CarPlay requires a `UIWindowSceneDelegate` for the phone window. If your app still sets up its window directly in `AppDelegate`, migrate to scenes first (the sections below build all the pieces).
88
+
89
+ **New Architecture host, Swift** — these snippets assume a Swift `AppDelegate` built on `RCTReactNativeFactory` and `RCTDefaultReactNativeFactoryDelegate`, which React Native ships from **0.78**.
90
+
91
+ On React Native versions before 0.78 (see [Getting Started](/guide/getting-started#installation) for the minimum), the template's `AppDelegate` subclasses `RCTAppDelegate` instead, so adapt the same pieces (scene routing, the headless helper, the started flag) to that host.
79
92
 
80
- **New Architecture host, Swift** — these snippets assume `RCTReactNativeFactory` (present on every React Native version the library supports) and a Swift `AppDelegate`. If yours is still Objective-C (`.mm`), migrating it to Swift first is simpler than translating this wiring by hand — scaffold a throwaway app (`npx @react-native-community/cli init Tmp`) and copy its `AppDelegate.swift` as a reference. ObjC works too (the bridging header is then unnecessary, see [Siri step 3](#_3-bridging-header-swift-appdelegate-only)) but isn't shown here.
93
+ If yours is still Objective-C (`.mm`), migrating it to Swift first is simpler than translating this wiring by hand. Scaffold a throwaway app (`npx @react-native-community/cli init Tmp`) and use its `AppDelegate.swift` as a reference. ObjC works too (the bridging header is then unnecessary, see [Siri step 3](#_3-bridging-header-swift-appdelegate-only)) but isn't shown here.
81
94
  :::
82
95
 
83
96
  ### The factory
@@ -132,11 +145,11 @@ class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
132
145
 
133
146
  Two things call this helper, which is why it's required even for **browse-only** apps:
134
147
 
135
- - The library's `RNABCarPlaySceneDelegate` calls `startReactNativeHeadless` on your `AppDelegate` (via an optional protocol) when CarPlay connects with no phone scene running — so a browse-only CarPlay launch boots RN automatically.
148
+ - The library's `RNABCarPlaySceneDelegate` calls `startReactNativeHeadless` on your `AppDelegate` every time CarPlay connects. So a browse-only CarPlay launch boots RN automatically. When the phone scene already started RN, the helper's guard makes the call a no-op.
136
149
  - Your Siri intent handler calls it (step 4) for a background intent launch.
137
150
 
138
- ::: warning Name it exactly `startReactNativeHeadless`
139
- The library finds this method **by selector** — it must be named exactly `startReactNativeHeadless` (no args) on your `AppDelegate`, or the library's CarPlay delegate won't be able to boot RN and browse screens will hang empty.
151
+ ::: warning Declare it `@objc func startReactNativeHeadless()`
152
+ The library finds this method **by Objective-C selector**. It must be named exactly `startReactNativeHeadless`, take no arguments, and be marked `@objc`: Swift does not expose a plain method to the Objective-C runtime. Otherwise the library's CarPlay delegate can't boot RN and browse screens hang empty.
140
153
  :::
141
154
 
142
155
  ```swift
@@ -147,7 +160,7 @@ private var headlessWindow: UIWindow?
147
160
  /// Boots React Native into a hidden window when no UI scene exists yet.
148
161
  /// Called by the library's CarPlay delegate (browse) and your Siri handler.
149
162
  /// Safe to call repeatedly — it starts RN at most once.
150
- func startReactNativeHeadless() {
163
+ @objc func startReactNativeHeadless() {
151
164
  guard !reactNativeStarted else { return }
152
165
  reactNativeStarted = true
153
166
 
@@ -167,9 +180,9 @@ func startReactNativeHeadless() {
167
180
  )
168
181
  }
169
182
 
170
- /// Called by the phone scene after it starts RN on the foreground path, so the
171
- /// headless helper never double-starts it. Both paths gate on the same
172
- /// `reactNativeStarted` flag, so RN starts exactly once.
183
+ /// Called by the phone scene when it starts RN on the foreground path, so the
184
+ /// headless helper doesn't start it again. Only the headless helper checks
185
+ /// `reactNativeStarted`: the phone scene always starts RN in its own window.
173
186
  func markReactNativeStarted() {
174
187
  reactNativeStarted = true
175
188
  }
@@ -208,7 +221,13 @@ class PhoneSceneDelegate: UIResponder, UIWindowSceneDelegate {
208
221
  }
209
222
  ```
210
223
 
211
- See the example app's [`AppDelegate.swift`](https://github.com/radio-garden/react-native-audio-browser/blob/main/apps/example-native/ios/AudioBrowserExample/AppDelegate.swift) and [`PhoneSceneDelegate.swift`](https://github.com/radio-garden/react-native-audio-browser/blob/main/apps/example-native/ios/AudioBrowserExample/PhoneSceneDelegate.swift) for the complete, copy-pasteable versions.
224
+ ::: info After a headless launch
225
+ The phone scene starts RN even when CarPlay or Siri already started it headless. The factory reuses its React host, so JS keeps running in the same runtime.
226
+
227
+ But your root component mounts a second time, in the phone window, while the headless one stays mounted in the hidden window. Keep app-wide side effects (player setup, `configureBrowser`) idempotent, or put them outside the root component.
228
+ :::
229
+
230
+ See the example app's [`AppDelegate.swift`](https://github.com/radio-garden/react-native-audio-browser/blob/next/apps/example-native/ios/AudioBrowserExample/AppDelegate.swift) and [`PhoneSceneDelegate.swift`](https://github.com/radio-garden/react-native-audio-browser/blob/next/apps/example-native/ios/AudioBrowserExample/PhoneSceneDelegate.swift) for the complete, copy-pasteable versions.
212
231
 
213
232
  ### Routing scene connections
214
233
 
@@ -243,7 +262,9 @@ One coupling that **is** load-bearing: the `name:` you pass to `UISceneConfigura
243
262
 
244
263
  ### The assembled `AppDelegate`
245
264
 
246
- The fragments above all live on one `AppDelegate`. Here is the whole class in one piece — the authoritative copy-paste. It **replaces** the `@main class AppDelegate` your RN template generated in `ios/<app>/AppDelegate.swift` (you keep one `@main`; don't add a second). The Siri `handlerFor` method at the end is needed only if you add [Siri Voice Search](#siri-voice-search):
265
+ The fragments above all live on one `AppDelegate`. Here is the whole class in one piece, to copy.
266
+
267
+ It **replaces** the `@main class AppDelegate` your RN template generated in `ios/<app>/AppDelegate.swift` (you keep one `@main`; don't add a second). The Siri `handlerFor` method at the end is needed only if you add [Siri Voice Search](#siri-voice-search):
247
268
 
248
269
  ```swift
249
270
  import UIKit
@@ -294,7 +315,8 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
294
315
  }
295
316
 
296
317
  // Boots RN into a hidden window when there's no UI scene (background launch).
297
- func startReactNativeHeadless() {
318
+ // `@objc` so the library's CarPlay delegate can find it by selector.
319
+ @objc func startReactNativeHeadless() {
298
320
  guard !reactNativeStarted else { return }
299
321
  reactNativeStarted = true
300
322
  headlessWindow = UIWindow(frame: CGRect(x: 0, y: 0, width: 1, height: 1))
@@ -339,24 +361,29 @@ class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
339
361
  This is the complete `AppDelegate.swift` (the `@main class AppDelegate` plus its `ReactNativeDelegate` in the same file). `PhoneSceneDelegate` lives in its **own** `PhoneSceneDelegate.swift` (shown above). Those two files are the complete native side.
340
362
 
341
363
  ::: warning Don't blindly overwrite an AppDelegate you've customized
342
- This block is the minimal shape. If your existing `AppDelegate` / `ReactNativeDelegate` already has extra overrides — bundle customization, linking setup, push/deep-link handlers, `customize(rootView:)`, extra modules — **keep them**. Merge the CarPlay additions (the factory split, `configurationForConnecting`, the headless helper, `markReactNativeStarted`, and the Siri `handlerFor`) into your file rather than replacing it wholesale.
364
+ This block is the minimal shape. If your existing `AppDelegate` / `ReactNativeDelegate` already has extra overrides (bundle customization, linking setup, push/deep-link handlers, `customize(rootView:)`, extra modules), **keep them**.
365
+
366
+ Merge the CarPlay additions into your file rather than replacing it wholesale: the factory split, `configurationForConnecting`, the headless helper, `markReactNativeStarted`, and the Siri `handlerFor`.
343
367
  :::
344
368
 
345
369
  ### Where to call `configureBrowser`
346
370
 
347
- A headless launch boots RN into a hidden window with **no components mounted**, so a `configureBrowser` call inside a component's `useEffect` will never run on a CarPlay/Siri cold launch. Call it (and `setupPlayer`) as a **top-level side-effect in `index.js`** — alongside `AppRegistry.registerComponent` — so it executes when the JS bundle loads, mounted UI or not.
371
+ Call `configureBrowser` (and `setupPlayer`) as a **top-level side-effect in `index.js`**, next to `AppRegistry.registerComponent`. It then runs when the JS bundle loads, mounted UI or not.
348
372
 
349
- First, because `configureBrowser` **replaces** the whole config, build one object with everything — tabs, routes, and (for Siri) search — together:
373
+ The headless helper mounts your root component in the hidden window, and the phone scene mounts it again later. So a call in a component's `useEffect` runs once per window, and only after the first render. That's late for Siri, whose handler waits only briefly for setup (see [step 4](#_4-appdelegate-intent-handler)). A top-level call in `index.js` runs once, as soon as the bundle loads.
374
+
375
+ `configureBrowser` **replaces** the whole config each time; it doesn't merge. So build one object with everything together: tabs, routes, and (for Siri) search. The snippets further down show one key at a time for brevity.
350
376
 
351
377
  ```ts
352
378
  const browserConfig = {
353
- // Tabs along the top of the CarPlay browser (max 4 — capped for
354
- // Android Auto + CarPlay compatibility; extra tabs dropped with a warning).
379
+ // Tabs along the top of the CarPlay browser (see the tab limit in
380
+ // /guide/browser#tabs-and-the-initial-path).
355
381
  tabs: [{ title: 'Home', path: '/' }],
356
382
 
357
383
  // routes: path → BrowserSource (static page, callback, or HTTP).
358
384
  routes: {
359
385
  '/': async () => ({
386
+ path: '/',
360
387
  title: 'Home',
361
388
  children: [{ title: 'Crunchy Greens FM', src: 'https://...' }]
362
389
  })
@@ -397,7 +424,7 @@ Siri voice search builds on the [React Native host setup](#react-native-host-uis
397
424
  - **Steps 1–4** — Siri entitlement, Info.plist keys, bridging header, intent handler
398
425
 
399
426
  ::: warning Step 0 (required) — a configured `search` source
400
- Siri voice search resolves spoken queries through the **same [`search`](/guide/search) source as your in-app search**. If you haven't set one, the mic will open, hear "play jazz", and return **nothing** — steps 1–4 will look wired up but produce silence. Configure it once:
427
+ Siri voice search resolves spoken queries through the **same [`search`](/guide/search) source as your in-app search**. Without one, "play jazz" returns **nothing**, even with steps 1–4 wired up. Add `search` to the one config you pass to [`configureBrowser`](#where-to-call-configurebrowser) at startup:
401
428
 
402
429
  ```ts
403
430
  configureBrowser({
@@ -405,22 +432,25 @@ configureBrowser({
405
432
  search: {
406
433
  // GET https://api.example.com/search?q=jazz — the library appends
407
434
  // `q` plus structured voice params (`mode`, `genre`, `artist`,
408
- // `album`, `reference`) and expects a page object back:
409
- // { title?, children: Track[] }, where each playable child Track
410
- // needs at least `title` + `src`.
435
+ // `album`, `reference`) and expects a bare Track[] back (a JSON
436
+ // array, not a page object), where each playable Track needs at
437
+ // least `title` + `src`.
411
438
  baseUrl: 'https://api.example.com/search'
412
439
  }
413
440
  })
414
441
  ```
415
442
 
416
- `configureBrowser` **replaces** the entire configuration each time it's called — it doesn't merge. So this isn't a second call: fold `search` into the single `configureBrowser({ tabs, routes, search, … })` you make at startup (see [Where to call `configureBrowser`](#where-to-call-configurebrowser)). The snippets on this page show one key at a time for brevity.
443
+ The browse templates work without `search`; Siri does not. See [Search](/guide/search#configuring-search) for:
417
444
 
418
- Naming note: in the **callback** form the spoken text arrives as `query` (`search: async ({ query }) => …`); on the **HTTP** form the library sends it as the wire param **`q`** (`?q=jazz`). Same value, two names depending on which form you use.
445
+ - the full `SearchParams` (genre / artist / album / `mode` / `reference`)
446
+ - the callback form, which returns [`Track`](/api/types/browser-nodes/#track)`[]` itself and receives the spoken text as `query` rather than `q`
447
+ - `transform`, for rewriting requests
419
448
 
420
- See [Search](/guide/search) for the full `SearchParams` (genre / artist / album / `mode` / `reference`), the callback form (return [`Track`](/api/types/browser-nodes/#track)`[]` yourself), and `transform` for rewriting requests. This is required for Siri; the browse templates work without it.
421
449
  :::
422
450
 
423
- CarPlay's tab bar already has a **search button that launches Siri automatically** — you get that for free once the steps below are wired up. Separately, the library can also show an **"Ask Siri to Play Audio" cell inside a list** as an extra entry point. This `carPlaySiriListButton` is optional polish — it's not what enables Siri search. To add it, set [`carPlaySiriListButton`](/api/types/browser/#carplaysirilistbuttonposition) on the resolved content returned by your route source:
451
+ CarPlay's tab bar already has a **search button that launches Siri**, which works once the steps below are wired up.
452
+
453
+ The library can also show an **"Ask Siri to Play Audio" cell inside a list** as an extra entry point. This is optional polish, not what enables Siri search. To add it, set [`carPlaySiriListButton`](/api/types/browser/#carplaysirilistbuttonposition) on the resolved content your route source returns:
424
454
 
425
455
  ```ts
426
456
  configureBrowser({
@@ -429,6 +459,7 @@ configureBrowser({
429
459
  // Basic Usage and the BrowserSource type: /api/types/browser/#browsersource
430
460
  routes: {
431
461
  '/': async () => ({
462
+ path: '/',
432
463
  title: 'Home',
433
464
  carPlaySiriListButton: 'top',
434
465
  children: [{ title: 'Crunchy Greens FM', src: 'https://...' }]
@@ -439,16 +470,16 @@ configureBrowser({
439
470
 
440
471
  (Tabs themselves come from your separate [`tabs`](/api/types/browser/#tabs) config, not from this route — the `'/'` route here is just where the button is attached. See [Basic Usage](/guide/basic-usage) for how `tabs` and `routes` fit together.)
441
472
 
442
- The `carPlaySiriListButton` property accepts `'top'` or `'bottom'` to control where the system assistant cell appears. It only affects CarPlay — it has no effect on the phone UI.
443
-
444
- ::: tip
445
- The button just launches Siri — it does **nothing** until the entitlement, Info.plist keys, and intent handler in the steps below are in place. Wire those up first, or tapping it will appear to do nothing.
446
- :::
473
+ The `carPlaySiriListButton` property accepts `'top'` or `'bottom'` to control where the system assistant cell appears. It only affects CarPlay, not the phone UI.
447
474
 
448
475
  To complete the setup, your app needs the Siri entitlement, a couple of Info.plist keys, a bridging header, and a one-line handler in your AppDelegate. Media intents are handled in-app: Siri delivers the `INPlayMediaIntent` straight to your `AppDelegate`.
449
476
 
450
477
  ::: info iOS version
451
- The library's minimum is **iOS 16**. The other version numbers on this page are finer-grained capability notes within that floor: the in-app handler API (`application(_:handlerFor:)`) exists from iOS 14 so you never need to gate on it, and the automatic CarPlay loading spinner is iOS 18.4+.
478
+ The version numbers on this page are capability notes within the library's [iOS floor](/guide/getting-started#installation):
479
+
480
+ - The in-app handler API (`application(_:handlerFor:)`) exists from iOS 14, so you never need to gate on it.
481
+ - The automatic CarPlay loading spinner needs iOS 18.4+.
482
+
452
483
  :::
453
484
 
454
485
  ### 1. Siri entitlement
@@ -499,7 +530,7 @@ Add Siri usage description and supported media categories to your app's Info.pli
499
530
  - **`INUpdateMediaAffinityIntent`** — "like" / "dislike" the current track.
500
531
  - **`INAddMediaIntent`** — add the current track to favorites.
501
532
 
502
- Register only the ones you want; `INPlayMediaIntent` alone is enough for voice search. The [`INSupportedMediaCategories`](https://developer.apple.com/documentation/sirikit/inmediacategory) values tell Siri which spoken requests to route to your app — if they don't cover your content, Siri may hand the request to a **different app**, so list every category you actually support.
533
+ Register only the ones you want; `INPlayMediaIntent` alone is enough for voice search. The [`INSupportedMediaCategories`](https://developer.apple.com/documentation/bundleresources/information-property-list/insupportedmediacategories) values tell Siri which spoken requests to route to your app — if they don't cover your content, Siri may hand the request to a **different app**, so list every category you actually support.
503
534
 
504
535
  ### 3. Bridging Header (Swift AppDelegate only)
505
536
 
@@ -535,13 +566,21 @@ func application(
535
566
  }
536
567
  ```
537
568
 
538
- `RNABAudioBrowser.handler(for:)` is the library's **only** intent entry point. It returns an opaque handler object for intents it supports (`INPlayMediaIntent`, `INUpdateMediaAffinityIntent`, `INAddMediaIntent`) and `nil` for anything else — there is no separate registration or setup call. The library resolves the spoken query through your configured [`search`](/guide/search) source (the same one your in-app search uses — it is **not** a browse route), queues the results, and starts playback automatically.
569
+ `RNABAudioBrowser.handler(for:)` is the library's **only** intent entry point, with no separate registration or setup call. It returns an opaque handler object for the intents it supports (`INPlayMediaIntent`, `INUpdateMediaAffinityIntent`, `INAddMediaIntent`) and `nil` for anything else.
570
+
571
+ The library resolves the spoken query through your configured [`search`](/guide/search) source (the same one your in-app search uses — it is **not** a browse route), queues the results, and starts playback automatically.
572
+
573
+ ::: tip The handler waits only briefly for setup
574
+ On a cold launch, the handler waits up to about **8 seconds** for your JS to run `setupPlayer()` and `configureBrowser()`, then fails the intent. So call both at the top level of `index.js`, before any slow async work (see [Where to call `configureBrowser`](#where-to-call-configurebrowser)).
539
575
 
540
- ::: tip Cold-launch ordering is handled for you
541
- You don't need to race `configureBrowser` against the intent. The handler **waits for your configured `search` source (and any [Gate](/guide/gate) — a paywall/region check that can intercept playback — if you use one) to be ready** before resolving — so even on a cold launch with RN not yet booted, the query resolves only after your JS has run `configureBrowser`. Just call it as a top-level side-effect (see [Where to call `configureBrowser`](#where-to-call-configurebrowser)).
576
+ That limit covers only the wait for setup. Your Gate's resolver and your `search` source run after it with no time limit of their own, so keep them quick: Siri gives up on a slow request.
577
+
578
+ If you use a [Gate](/guide/gate), a paywall or region check, it can refuse the search. It blocks search and browsing from the car, not playback, so "resume" still plays.
542
579
  :::
543
580
 
544
- > **Why a handler object, not `application(_:handle:completionHandler:)`?** The latter is not a real `UIApplicationDelegate` method, so iOS never calls it. With no in-app handler registered, the system falls back to a `UISIntentForwardingAction`, which crashes in `-[INHandleIntentForwardingActionResponse isSuccess]`. Returning a handler from `application(_:handlerFor:)` keeps iOS on the in-app path. **No separate Intents Extension is required** — everything runs in-app.
581
+ > **Why a handler object, not `application(_:handle:completionHandler:)`?** The latter is not a real `UIApplicationDelegate` method, so iOS never calls it. With no in-app handler registered, the system falls back to a `UISIntentForwardingAction`, which crashes in `-[INHandleIntentForwardingActionResponse isSuccess]`.
582
+ >
583
+ > Returning a handler from `application(_:handlerFor:)` keeps iOS on the in-app path. **No separate Intents Extension is required**; everything runs in-app.
545
584
 
546
585
  ### How It Works
547
586
 
@@ -552,11 +591,44 @@ You don't need to race `configureBrowser` against the intent. The handler **wait
552
591
  5. The library resolves the request and starts playback — **resuming** the last session when the user just said your app's name, otherwise **searching** your content (genre/artist/album/etc. are forwarded as structured search params)
553
592
  6. CarPlay's Now Playing screen updates automatically
554
593
 
555
- ## Loading States
594
+ ## Now Playing Buttons
556
595
 
557
- ::: tip Optional browse polish
558
- This and Album Line Navigation below are optional refinements to the browse templates — skip them for a minimal integration.
559
- :::
596
+ The Now Playing screen always has CarPlay's transport controls. More buttons, one of each kind in the table below, go in the row beneath them: list them in `ios.carPlayNowPlayingButtons`, left to right in the order you want them:
597
+
598
+ ```ts
599
+ await setupPlayer({
600
+ capabilities: { favorite: true },
601
+ ios: {
602
+ carPlayNowPlayingButtons: ['shuffle', 'repeat', 'favorite', 'playback-rate']
603
+ }
604
+ })
605
+ ```
606
+
607
+ You can also change them later with `updateOptions({ ios: { carPlayNowPlayingButtons: [...] } })`. The default is `[]`, which means no extra buttons.
608
+
609
+ | Button | What a tap does |
610
+ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
611
+ | `'shuffle'` | Turns shuffle on or off. |
612
+ | `'repeat'` | Cycles the repeat mode: off → track → queue → off. |
613
+ | `'favorite'` | Toggles the playing track's favorite state; the heart is filled while it is a favorite. See [Favorites](/guide/favorites). |
614
+ | `'playback-rate'` | Steps to the next rate in `ios.playbackRates`, wrapping from the last back to the first. With `playbackRates: []` the tap does nothing. |
615
+
616
+ - **Each button is drawn once.** A button listed twice keeps its first position.
617
+ - **More than five entries log a warning.** Five is CarPlay's limit for the row; the count includes repeats.
618
+ - **A [gate](/guide/gate) hides them.** While a gate is active the row is empty. The transport controls stay.
619
+
620
+ The **Up Next** button is separate. It opens the queue and shows only when the queue has more than one track. Set `ios.carPlayUpNextButton: false` to never show it.
621
+
622
+ ## Playing Indicator
623
+
624
+ CarPlay marks the playing item in browse lists with a now-playing indicator. `ios.carPlayPlayingIndicatorLocation` chooses where it draws:
625
+
626
+ - `'leading'` (default): in the artwork slot, in place of the row's artwork while it plays, as Apple Music does.
627
+ - `'trailing'`: at the end of the row, so the artwork stays visible.
628
+
629
+ If you change it with `updateOptions`, rows already on screen update too.
630
+
631
+ ## Loading States
560
632
 
561
633
  Browse screens show a loading state while their content resolves — pushed destinations, tabs loading lazily, and the startup screen while tabs are queried. On iOS 18.4+ the system loading spinner is shown automatically. Older iOS versions have no spinner API; those screens stay blank unless you supply a [`carPlayLoadingTitle`](/api/types/browser/#carplayloadingtitle):
562
634
 
@@ -571,7 +643,12 @@ The title renders as the list's centered empty state and disappears as soon as c
571
643
 
572
644
  ## Album Line Navigation
573
645
 
574
- The album line on the Now Playing screen can navigate into the browse tree. Two things are needed for it to become tappable: the track must have an **`album`** string (CarPlay builds the tappable line from it — see the warning below), and an **`albumPath`** pointing at a browse path (a `path` in your [`routes`](/guide/basic-usage), so the destination must exist there). Set `albumPath` to make the album line tappable while that track is active — tapping pushes that path:
646
+ The album line on the Now Playing screen can navigate into the browse tree. It becomes tappable when the active track has both:
647
+
648
+ - an **`album`** string, which CarPlay builds the tappable line from (see the warning below)
649
+ - an **`albumPath`**: a `path` in your [`routes`](/guide/basic-usage), so the destination must exist there
650
+
651
+ Tapping the line pushes that path:
575
652
 
576
653
  ```ts
577
654
  {
@@ -598,12 +675,16 @@ configureBrowser({
598
675
  Return a browse path to enable the album line for that track, or `undefined` to leave it untappable.
599
676
 
600
677
  ::: warning Album metadata required
601
- CarPlay renders the tappable album/artist button as a **separate line built from the track's `album`** (visible as the third metadata line, with a chevron). Tracks without an `album` have no string for CarPlay to turn into a button — the artist line alone is never tappable. Set `album` on any track that should offer album-line navigation. See [Now Playing](/guide/now-playing) for the full field-by-surface rendering matrix.
678
+ CarPlay renders the tappable album/artist button as a **separate line built from the track's `album`**: the third metadata line, with a chevron. A track without an `album` gives CarPlay no string to turn into a button, and the artist line alone is never tappable.
679
+
680
+ Set `album` on any track that should offer album-line navigation. See [Now Playing](/guide/now-playing) for the full field-by-surface rendering matrix.
602
681
  :::
603
682
 
604
683
  ## Template Depth
605
684
 
606
- CarPlay limits an audio app's template stack to **five templates, the tab bar included** (CarPlay App Programming Guide, p. 15), so the stack is full four pushes in. Now Playing and Up Next each take a slot like any list. A browse tree with a fixed shape (tabs → show → episodes) never gets there; one that can be drilled without end — a place, a place near it, a place near that — does.
685
+ CarPlay limits an audio app's template stack to **five templates, the tab bar included** (see Apple's [CarPlay App Programming Guide](https://developer.apple.com/carplay/)), so the stack is full four pushes in. Now Playing and Up Next each take a slot like any list.
686
+
687
+ A browse tree with a fixed shape (tabs → show → episodes) never gets there; one that can be drilled without end — a place, a place near it, a place near that — does.
607
688
 
608
689
  At the limit, the library replaces the **top** page with the new one, so a push always lands:
609
690
 
@@ -633,7 +714,9 @@ An `error` line in that category means the pop or the push failed; it names the
633
714
 
634
715
  ## Testing
635
716
 
636
- Test your app in the `CarPlay Simulator.app`, which is part of the [Additional Tools for Xcode](https://developer.apple.com/download/all/?q=additional%20tools%20for%20xcode). Siri voice search works there, so you can exercise the full intent flow without a car. CarPlay support on the iOS Simulator can be a little flaky — if something looks broken, retry or fall back to a physical device for final verification.
717
+ Test your app in the `CarPlay Simulator.app`, which is part of the [Additional Tools for Xcode](https://developer.apple.com/download/all/?q=additional%20tools%20for%20xcode). Siri voice search works there, so you can exercise the full intent flow without a car.
718
+
719
+ CarPlay support on the iOS Simulator can be a little flaky. If something looks broken, retry, or check on a physical device.
637
720
 
638
721
  ### Troubleshooting
639
722
 
@@ -641,10 +724,10 @@ Test your app in the `CarPlay Simulator.app`, which is part of the [Additional T
641
724
  | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
642
725
  | Siri mic opens but returns nothing | No [`search` source](#siri-voice-search) configured (Step 0). |
643
726
  | The "Ask Siri" cell does nothing | Siri entitlement / Info.plist keys / intent handler not wired (steps 1–4). |
644
- | CarPlay browse screens hang empty | `startReactNativeHeadless` missing or misnamed — the library calls it by exact selector. |
727
+ | CarPlay browse screens hang empty | `startReactNativeHeadless` missing, misnamed or missing `@objc`: the library calls it by selector. |
645
728
  | Build error: _module 'AudioBrowser' not found_ | `pod install` hasn't linked the `AudioBrowser` pod. |
646
729
  | Crash: _no UISceneConfiguration named …_ | The `name:` in `configurationForConnecting` doesn't match `UISceneConfigurationName` in the manifest. |
647
730
 
648
731
  ## Reference
649
732
 
650
- See the [example app](https://github.com/radio-garden/react-native-audio-browser/tree/main/apps/example-native/ios/AudioBrowserExample) for a complete working implementation.
733
+ See the [example app](https://github.com/radio-garden/react-native-audio-browser/tree/next/apps/example-native/ios/AudioBrowserExample) for a complete working implementation.
@@ -11,8 +11,8 @@ Everything about how the player behaves is set through three functions:
11
11
  - [`updateOptions(options)`](/api/features/player/#updateoptions) — change a
12
12
  subset of options later, at runtime.
13
13
  - [`getOptions()`](/api/features/player/#getoptions) /
14
- [`useOptions()`](/api/features/player/#useoptions) — read the current,
15
- resolved options.
14
+ [`useOptions()`](/api/features/player/#useoptions) — read the current
15
+ options.
16
16
 
17
17
  This page maps the whole options surface and links to the feature guide that
18
18
  covers each area in depth.
@@ -35,10 +35,21 @@ await setupPlayer({
35
35
  })
36
36
  ```
37
37
 
38
- Calling `setupPlayer` again **reconfigures in place**: the fields you pass are
39
- merged over the previous ones, and the audio engine is only rebuilt when a
40
- construction-bound field (buffers, wake mode, …) actually changed. This is also
41
- how you change a [setup-only option](#setup-only-vs-updatable) after launch.
38
+ Calling `setupPlayer` again is how you change a
39
+ [setup-only option](#setup-only-vs-updatable) after launch. The runtime options
40
+ (capabilities, intervals, the updatable `android` / `ios` fields) carry over on
41
+ both platforms. The setup-only fields behave differently on each:
42
+
43
+ - **Android** reconfigures in place. The fields you pass are merged over the
44
+ previous ones, and the audio engine is only rebuilt when a construction-bound
45
+ field (buffers, wake mode, …) changed. Two fields are exceptions. Left out,
46
+ `remoteOutputs` turns the remote outputs off again, and `nowPlaying` turns
47
+ the default mapping back on. A `nowPlaying` formatter stays until another
48
+ function replaces it: passing `true` or leaving it out does not drop it.
49
+ - **iOS** replaces the player, built from that call's options alone. The queue
50
+ is cleared, and a setup-only field you leave out (`ios.category`,
51
+ `ios.buffer`, `retry`, …) goes back to its default, so pass the full `ios` and
52
+ `retry` set each time.
42
53
 
43
54
  ## `updateOptions`
44
55
 
@@ -53,27 +64,28 @@ updateOptions({ progressUpdateEventInterval: null }) // disable progress events
53
64
  updateOptions({ ios: { carPlayNowPlayingButtons: ['repeat'] } })
54
65
  ```
55
66
 
56
- `null` is meaningful on exactly two fields, where it turns the feature off:
67
+ `null` means something on two fields:
57
68
  `progressUpdateEventInterval: null` disables progress events, and
58
- `android.remoteButtonLayout: null` empties the layout (deriving it from
59
- capabilities). Elsewhere, just omit a field to leave it unchanged.
69
+ `android.remoteButtonLayout: null` goes back to the layout derived from
70
+ capabilities. Elsewhere, omit a field to leave it unchanged.
60
71
 
61
72
  ## Setup-only vs updatable
62
73
 
63
74
  `updateOptions` can change only a subset. The rest are set in `setupPlayer`
64
- (call it again to change them later).
65
-
66
- | Option | `setupPlayer` | `updateOptions` |
67
- | ---------------------------------------------------------------------------------------- | :-----------: | :-------------: |
68
- | `capabilities` | ✓ | ✓ |
69
- | `forwardJumpInterval` / `backwardJumpInterval` | ✓ | ✓ |
70
- | `progressUpdateEventInterval` | ✓ | ✓ |
71
- | `android.appKilledPlaybackBehavior` / `skipSilence` / `remoteButtonLayout` | ✓ | ✓ |
72
- | `ios.playbackRates` / `carPlayUpNextButton` / `carPlayNowPlayingButtons` | ✓ | ✓ |
73
- | `nowPlaying` (metadata formatter) | ✓ | — |
74
- | `playWhenReady`, `repeatMode` (initial values) | ✓ | — |
75
- | `retry`, `keepSessionAliveOnError`, `remoteOutputs` | ✓ | — |
76
- | `android` / `ios` audio engine & session (`audioContentType`, `wakeMode`, `category`, …) | ✓ | — |
75
+ (call it again to change them later; on iOS that call also clears the queue and
76
+ resets any setup-only field you omit, see [`setupPlayer`](#setupplayer)).
77
+
78
+ | Option | `setupPlayer` | `updateOptions` |
79
+ | ------------------------------------------------------------------------------------------------------------ | :-----------: | :-------------: |
80
+ | `capabilities` | ✓ | ✓ |
81
+ | `forwardJumpInterval` / `backwardJumpInterval` | ✓ | ✓ |
82
+ | `progressUpdateEventInterval` | ✓ | ✓ |
83
+ | `android.appKilledPlaybackBehavior` / `skipSilence` / `remoteButtonLayout` | ✓ | ✓ |
84
+ | `ios.playbackRates` / `carPlayUpNextButton` / `carPlayNowPlayingButtons` / `carPlayPlayingIndicatorLocation` | ✓ | ✓ |
85
+ | `nowPlaying` (metadata formatter) | ✓ | — |
86
+ | `playWhenReady`, `repeatMode` (initial values) | ✓ | — |
87
+ | `retry`, `keepSessionAliveOnError`, `remoteOutputs` | ✓ | — |
88
+ | `android` / `ios` audio engine & session (`audioContentType`, `wakeMode`, `category`, …) | ✓ | — |
77
89
 
78
90
  `remoteOutputs` (Android) turns on the outputs of the system Output Switcher
79
91
  beyond the phone's own: `{}` lists media route providers' speakers, and
@@ -81,6 +93,12 @@ beyond the phone's own: `{}` lists media route providers' speakers, and
81
93
  a `setupPlayer` call, they are off; see
82
94
  [Remote outputs](/guide/audio-output#remote-outputs-android).
83
95
 
96
+ `retry` retries load errors automatically, and is off by default; see
97
+ [Automatic retry](/guide/errors#automatic-retry). `keepSessionAliveOnError`
98
+ (Android, default `true`) keeps the media session and its transport controls
99
+ through a terminal playback error, so Android Auto keeps next and previous on a
100
+ dead stream.
101
+
84
102
  `playWhenReady` and `repeatMode` set the _initial_ state; change them at runtime
85
103
  with [`setPlayWhenReady`](/guide/playback#play-when-ready) /
86
104
  [`setRepeatMode`](/guide/queue#repeat-and-shuffle), not `updateOptions`.
@@ -111,11 +129,11 @@ updateOptions({
111
129
 
112
130
  ## Controls & progress
113
131
 
114
- | Option | Default | What |
115
- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
116
- | `forwardJumpInterval` | `15` | Seconds for the jump-forward control. |
117
- | `backwardJumpInterval` | `15` | Seconds for the jump-backward control. |
118
- | `progressUpdateEventInterval` | `null` | Seconds between progress events; `null` disables them — see [Playback → Progress](/guide/playback#progress). |
132
+ | Option | Default | What |
133
+ | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
134
+ | `forwardJumpInterval` | `15` | Seconds for the jump-forward control. With no handler, Android seeks by Media3's fixed increment instead; see [Remote Controls](/guide/remote-controls#overriding-a-control). |
135
+ | `backwardJumpInterval` | `15` | Seconds for the jump-backward control. With no handler, Android seeks by Media3's fixed increment instead; see [Remote Controls](/guide/remote-controls#overriding-a-control). |
136
+ | `progressUpdateEventInterval` | `null` | Seconds between progress events; `null` disables them — see [Playback → Progress](/guide/playback#progress). |
119
137
 
120
138
  ## Now Playing
121
139
 
@@ -130,30 +148,48 @@ It's **setup-only** (a function can't cross `updateOptions`). See
130
148
 
131
149
  ## Android options (`android`)
132
150
 
133
- | Option | Default | What |
134
- | --------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
135
- | `appKilledPlaybackBehavior` | `'continue-playback'` | What happens when the app is swiped away (`continue-playback` / `pause-playback` / `stop-playback-and-remove-notification`). |
136
- | `skipSilence` | `false` | Skip silent segments during playback. |
137
- | `remoteButtonLayout` | `null` | Explicit button placement (`back` / `forward` / `overflow`); `null` derives it from capabilities — see [Button layout](/guide/remote-controls#button-layout-android). |
138
- | `audioContentType` | `'music'` | Audio attributes content type (setup-only). |
139
- | `wakeMode` | `'none'` | CPU/network wake lock during playback (setup-only). |
151
+ | Option | Default | What |
152
+ | --------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
153
+ | `appKilledPlaybackBehavior` | `'stop-playback-and-remove-notification'` | What happens when the app is swiped away (`continue-playback` / `pause-playback` / `stop-playback-and-remove-notification`). |
154
+ | `skipSilence` | `false` | Skip silent segments during playback. |
155
+ | `remoteButtonLayout` | `null` | Explicit button placement (`back` / `forward` / `overflow`); `null` derives it from capabilities — see [Button layout](/guide/remote-controls#button-layout-android). |
156
+ | `audioContentType` | `'music'` | Audio attributes content type (setup-only). |
157
+ | `wakeMode` | `'none'` | CPU/network wake lock during playback (setup-only). |
158
+ | `handleAudioBecomingNoisy` | `true` | Pause when the audio becomes noisy, such as when headphones are unplugged (setup-only). |
159
+ | `maxBuffer` | `50000` | Milliseconds of media the player loads ahead (setup-only). |
160
+ | `minBuffer` | `50000` | Accepted but has no effect; the player always loads up to `maxBuffer` (setup-only). |
161
+ | `playBuffer` | `1000` | Milliseconds that must be buffered to start or resume after a user action such as a seek (setup-only). |
162
+ | `rebufferBuffer` | `null` | Milliseconds that must be buffered to resume after a rebuffer; `null` adapts it to how fast the buffer drained (setup-only). |
163
+ | `backBuffer` | `0` | Milliseconds kept behind the playhead (setup-only). |
164
+ | `maxCacheSize` | `0` | Cache size in MB (setup-only). |
165
+ | `audioOffload` | `false` | Decode on dedicated hardware to save power (setup-only). |
140
166
 
141
167
  ## iOS options (`ios`)
142
168
 
143
- | Option | Default | What |
144
- | -------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
145
- | `playbackRates` | `[0.5, 1.0, 1.5, 2.0]` | Rates offered by the rate control. |
146
- | `carPlayUpNextButton` | `true` | Show the "Up Next" button on CarPlay (auto-hidden when the queue has one track). |
147
- | `carPlayNowPlayingButtons` | `[]` | Buttons on the CarPlay now-playing screen (max **5**, left-to-right) — see [CarPlay](/guide/carplay). |
148
- | `category` | _(none)_ | iOS audio session category (setup-only). |
169
+ | Option | Default | What |
170
+ | --------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
171
+ | `playbackRates` | `[0.5, 1.0, 1.5, 2.0]` | Rates offered by the rate control. |
172
+ | `carPlayUpNextButton` | `true` | Show the "Up Next" button on CarPlay (auto-hidden when the queue has one track). |
173
+ | `carPlayNowPlayingButtons` | `[]` | Buttons on the CarPlay now-playing screen, left to right, at most one of each kind: see [CarPlay](/guide/carplay#now-playing-buttons). |
174
+ | `carPlayPlayingIndicatorLocation` | `'leading'` | Where the now-playing indicator draws on CarPlay list rows: `'leading'` in the artwork slot, `'trailing'` at the end of the row — see [CarPlay](/guide/carplay#playing-indicator). |
175
+ | `category` | `'playback'` | iOS audio session category (setup-only). |
176
+ | `categoryMode` | `'default'` | Audio session mode (setup-only). |
177
+ | `categoryOptions` | `[]` | Audio session category options (setup-only). |
178
+ | `categoryPolicy` | `'default'` | Audio session route-sharing policy (setup-only). |
179
+ | `buffer` | `0` | Preferred forward buffer in milliseconds; `0` lets AVPlayer choose (setup-only). |
149
180
 
150
181
  ## Reading the current options
151
182
 
152
- [`getOptions()`](/api/features/player/#getoptions) returns the resolved
183
+ [`getOptions()`](/api/features/player/#getoptions) returns the current
153
184
  [`Options`](/api/features/player/#options) (capabilities, intervals,
154
185
  `progressUpdateEventInterval`, and the `android` / `ios` blocks for the current
155
- platform). [`useOptions()`](/api/features/player/#useoptions) is the reactive
156
- hook; [`onOptionsChanged`](/api/features/player/#onoptionschanged) is the
186
+ platform). `capabilities` holds only the capabilities you set, plus
187
+ `jumpForward` / `jumpBackward: false` on Android and iOS. A missing entry means
188
+ its default from the [Capabilities](#capabilities) table, so test
189
+ `capabilities.play !== false` rather than `capabilities.play === true`.
190
+
191
+ [`useOptions()`](/api/features/player/#useoptions) is the reactive hook;
192
+ [`onOptionsChanged`](/api/features/player/#onoptionschanged) is the
157
193
  subscription.
158
194
 
159
195
  ```tsx
@@ -171,9 +207,9 @@ own getters/hooks, e.g. [`useRepeatMode`](/guide/queue#repeat-and-shuffle)).
171
207
 
172
208
  ## API summary
173
209
 
174
- | API | Purpose |
175
- | ------------------------------- | ------------------------------------------------------------------------------------------------------ |
176
- | `setupPlayer(options?)` | Initialize (and reconfigure) the player; `async`, once at startup. |
177
- | `updateOptions(options)` | Change runtime options later (merged over current); `null` disables on the two fields that support it. |
178
- | `getOptions()` / `useOptions()` | Read the resolved runtime options. |
179
- | `onOptionsChanged` | Subscribe to options changes outside React. |
210
+ | API | Purpose |
211
+ | ------------------------------- | ------------------------------------------------------------------ |
212
+ | `setupPlayer(options?)` | Initialize (and reconfigure) the player; `async`, once at startup. |
213
+ | `updateOptions(options)` | Change runtime options later, merged over the current ones. |
214
+ | `getOptions()` / `useOptions()` | Read the current runtime options. |
215
+ | `onOptionsChanged` | Subscribe to options changes outside React. |