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
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: 'Shape playback tone with the Android system equalizer: named presets, custom band levels, and handling its absence on iOS.'
2
+ description: 'Shape playback tone with the Android system equalizer: named presets, custom band levels, and handling its absence on iOS and web.'
3
3
  ---
4
4
 
5
5
  # Equalizer
@@ -9,9 +9,10 @@ either by applying a named **preset** (e.g. "Rock", "Jazz") or by setting
9
9
  **custom band levels** yourself. It wraps the system equalizer effect.
10
10
 
11
11
  ::: warning Android only
12
- The equalizer is **Android-only**. Every getter returns `undefined` and every
13
- setter is a no-op on iOS — Apple exposes no equivalent system equalizer. Always
14
- treat the settings as possibly-absent (see [Availability](#availability)).
12
+ The equalizer is **Android-only**. On iOS and web every getter returns
13
+ `undefined` and every setter is a no-op; neither platform has an equivalent
14
+ system equalizer. Always treat the settings as possibly-absent (see
15
+ [Availability](#availability)).
15
16
  :::
16
17
 
17
18
  The UI snippets below import `View` / `Text` / `Button` from `react-native` and
@@ -22,10 +23,14 @@ for brevity. Everything else comes from `react-native-audio-browser`.
22
23
 
23
24
  [`getEqualizerSettings()`](/api/features/equalizer/#getequalizersettings)
24
25
  returns [`EqualizerSettings | undefined`](/api/features/equalizer/#equalizersettings).
25
- It's `undefined` whenever the equalizer isn't available — on iOS, and **on
26
- Android until the player has an audio session**, which only exists once playback
27
- has started. A settings screen opened before anything has played may see
28
- `undefined`; use the reactive hook so it fills in when playback begins.
26
+ It's `undefined` whenever the equalizer isn't available: on iOS and web, and
27
+ **on Android before `setupPlayer`** and for a short moment after it, until the
28
+ player's audio session arrives. Use the reactive hook so a settings screen fills
29
+ in when it does.
30
+
31
+ On Android, a setter called after `setupPlayer` but before the equalizer exists
32
+ is kept and applied when it appears; the result arrives through
33
+ `onEqualizerChanged`. A setter called before `setupPlayer` is dropped.
29
34
 
30
35
  ## Reading the settings
31
36
 
@@ -129,12 +134,11 @@ flat[0] = 600
129
134
  setEqualizerLevels(flat)
130
135
  ```
131
136
 
132
- Setting custom levels clears `activePreset` (it becomes `undefined`) — you're no
133
- longer on a named preset. To go back, apply a preset again.
137
+ Setting custom levels clears `activePreset` (it becomes `undefined`), even if
138
+ they equal a preset's levels. To return to a preset, apply it again.
134
139
 
135
- Whichever you choose, the settings persist across track and audio-session
136
- changes: a preset wins over custom levels, and the enabled state always carries
137
- over.
140
+ Whichever you applied last, preset or custom levels, carries over to the next
141
+ audio session, along with the enabled state.
138
142
 
139
143
  ## A complete equalizer screen
140
144
 
@@ -183,29 +187,29 @@ function EqualizerScreen() {
183
187
  />
184
188
  ))}
185
189
 
186
- {eq.bandLevels.map((level, index) => (
187
- <View key={eq.centerBandFrequencies[index]}>
188
- <Text>
189
- {formatHz(eq.centerBandFrequencies[index])}:{' '}
190
- {(level / 100).toFixed(1)} dB
191
- </Text>
192
- <Slider
193
- minimumValue={eq.lowerBandLevelLimit}
194
- maximumValue={eq.upperBandLevelLimit}
195
- value={level}
196
- // Commit on release; onValueChange fires continuously.
197
- onSlidingComplete={(millibels) => setBand(index, millibels)}
198
- />
199
- </View>
200
- ))}
190
+ {eq.centerBandFrequencies.map((mHz, index) => {
191
+ const level = eq.bandLevels[index] ?? 0
192
+ return (
193
+ <View key={mHz}>
194
+ <Text>
195
+ {formatHz(mHz)}: {(level / 100).toFixed(1)} dB
196
+ </Text>
197
+ <Slider
198
+ minimumValue={eq.lowerBandLevelLimit}
199
+ maximumValue={eq.upperBandLevelLimit}
200
+ value={level}
201
+ // Commit on release; onValueChange fires continuously.
202
+ onSlidingComplete={(millibels) => setBand(index, millibels)}
203
+ />
204
+ </View>
205
+ )
206
+ })}
201
207
  </View>
202
208
  )
203
209
  }
204
210
  ```
205
211
 
206
- Note: `@react-native-community/slider`'s `value` is the _initial_ value only —
207
- the slider keeps its own state after mounting. That's fine here, but if you want
208
- the thumbs to jump when a preset is applied, give each `Slider` a
212
+ If the thumbs don't follow a newly applied preset, give each `Slider` a
209
213
  `key={eq.activePreset}` so it remounts with the new levels.
210
214
 
211
215
  ## A note on units
@@ -228,4 +232,4 @@ The system equalizer works in "milli" units, so convert for display:
228
232
  | `setEqualizerPreset(name)` | Apply a preset from `settings.presets`. |
229
233
  | `setEqualizerLevels(millibels[])` | Set all bands; length must equal `bandCount`. |
230
234
 
231
- All are **Android-only** — no-ops / `undefined` on iOS.
235
+ All are **Android-only**: no-ops or `undefined` on iOS and web.
@@ -47,16 +47,16 @@ string is especially jarring.
47
47
 
48
48
  `kind` is one of:
49
49
 
50
- | `kind` | Meaning | Retrying help? |
51
- | ---------------- | --------------------------------------------------------------------------------------------------------------- | ---------------- |
52
- | `'offline'` | The device had no connection at the moment of failure. The stream may be fine. | Once back online |
53
- | `'unreachable'` | The host could not be reached: DNS failure, refused connection, timeout, or a connection dropped while loading. | Maybe |
54
- | `'not-found'` | The server said this stream is gone (HTTP 404 / 410). | No |
55
- | `'rejected'` | The server refused the request (HTTP 401 / 403) — geo-blocking, an expired token. | No |
56
- | `'server-error'` | The server responded 5xx. Usually transient. | Maybe |
57
- | `'unplayable'` | Fetched, but not playable: unknown container, unsupported codec, decoder failure. | No |
58
- | `'stalled'` | Playback had started, then stopped, and the player exhausted its recovery budget. | Maybe |
59
- | `'unknown'` | Could not be classified. Inspect `code`. | Maybe |
50
+ | `kind` | Meaning | Retrying help? |
51
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
52
+ | `'offline'` | The device had no connection at the moment of failure. The stream may be fine. | Once back online |
53
+ | `'unreachable'` | The host could not be reached: DNS failure, refused connection, timeout, or a connection dropped while loading. | Maybe |
54
+ | `'not-found'` | The server said this stream is gone (HTTP 404 / 410). | No |
55
+ | `'rejected'` | The server refused the request: any HTTP 4xx other than 404 / 410 (auth, geo-blocking, rate limiting), or a DRM, licence or region refusal (Android and web). | No (except 408 / 429) |
56
+ | `'server-error'` | The server responded 5xx. Usually transient. | Maybe |
57
+ | `'unplayable'` | Fetched, but not playable: unknown container, unsupported codec, decoder failure. | No |
58
+ | `'stalled'` | Playback had started, then stopped, and the player exhausted its recovery budget. | Maybe |
59
+ | `'unknown'` | Could not be classified. Inspect `code`. | Maybe |
60
60
 
61
61
  Codes that name no cause stay `'unknown'` rather than being guessed into a
62
62
  friendlier bucket — a wrong classification misleads the listener _and_ poisons
@@ -80,7 +80,8 @@ function errorLine(kind: PlaybackErrorKind): string {
80
80
  case 'unreachable':
81
81
  case 'server-error':
82
82
  return t('…your "could not reach it" copy')
83
- // Both permanent — retrying will not help.
83
+ // Both refusals: a manual retry rarely helps (with automatic
84
+ // retry on, a 408 / 429 was already retried).
84
85
  case 'not-found':
85
86
  case 'rejected':
86
87
  return t('…your "not available" copy')
@@ -115,24 +116,31 @@ so you can show it on the lock screen / car too.
115
116
 
116
117
  ### Manual retry
117
118
 
118
- [`retry()`](/api/features/errors/#retry) re-attempts the current item — it only
119
- does something while the state is `'error'`. It's the action behind a "Try again"
120
- button, and what you call after [automatic retry](#automatic-retry) has given up.
121
- It begins a fresh load with fresh retry budgets, exactly as if the listener had
122
- re-selected the track (a plain play command from `'error'` does the same).
119
+ [`retry()`](/api/features/playback/#retry) re-attempts the current item. It's
120
+ the action behind a "Try again" button, and what you call after
121
+ [automatic retry](#automatic-retry) has given up.
122
+
123
+ From `'error'` it begins a fresh load with fresh retry budgets, exactly as if
124
+ the listener had re-selected the track. A plain play command from `'error'`
125
+ does the same.
126
+
127
+ Call it from `'error'` only, because the platforms differ outside that state.
128
+ On Android and web it does nothing unless the player is in `'error'` or
129
+ stopped, where it reloads the item. On iOS it reloads the current item from
130
+ any state, even while it plays.
123
131
 
124
132
  ## Automatic retry
125
133
 
126
- Configure [`setupPlayer({ retry })`](/guide/configuration) to recover from
127
- transient **load** failures (network blips, timeouts, a live stream dropping
128
- mid-play) with exponential backoff. It's **off by default**, and it's native
129
- only — the web implementation has no automatic retry, so every web error is
130
- terminal:
134
+ Configure [`setupPlayer({ retry })`](/api/features/player/#retryconfig) to
135
+ recover from transient **load** failures (network blips, timeouts, a live
136
+ stream dropping mid-play) with exponential backoff. It's **off by default**,
137
+ and it's native only — the web implementation has no automatic retry, so every
138
+ web error is terminal:
131
139
 
132
140
  ```ts
133
141
  import { setupPlayer } from 'react-native-audio-browser'
134
142
 
135
- // Retry with the default duration budgets (12s / 2 min, see below):
143
+ // Retry with the default duration budgets (see below):
136
144
  await setupPlayer({ retry: true })
137
145
 
138
146
  // Or bound it yourself:
@@ -145,20 +153,26 @@ await setupPlayer({
145
153
  })
146
154
  ```
147
155
 
148
- Which failures qualify is nearly the same on iOS and Android: HTTP 408 and
149
- 429, plus server errors — every 5xx on iOS, the common four (500, 502, 503, 504) on Android; transport failures (DNS, timeouts, a dropped connection);
150
- and anything the platform couldn't classify, which is assumed transient
156
+ Which failures qualify is nearly the same on iOS and Android. HTTP 408 and
157
+ 429 qualify, and so do server errors: every 5xx on iOS, the common four (500,
158
+ 502, 503, 504) on Android.
159
+
160
+ Transport failures qualify too (DNS, timeouts, a dropped connection), and so
161
+ does anything the platform couldn't classify, which is assumed transient
151
162
  rather than fatal.
163
+
152
164
  Permanent failures are never retried — 403 / 404, and media that can't be
153
165
  parsed or decoded.
154
166
 
155
167
  ### Two duration budgets
156
168
 
157
- Retry state is tracked per **load** — one track's playback session, created
158
- when a track becomes current (selection, queue advance, skip) _or restarted
159
- from a terminal error_ (`retry()`, or any play command while in `'error'`),
160
- and surviving every automatic retry of that track. A new load starts fresh
161
- budgets; retries within it don't.
169
+ Retry state is tracked per **load**: one track's playback session. A load is
170
+ created when a track becomes current (selection, queue advance, skip) _or is
171
+ restarted from a terminal error_ (`retry()`, or any play command while in
172
+ `'error'`), and it survives every automatic retry of that track.
173
+
174
+ A new load starts fresh budgets. Within a load, the recovery budget refills
175
+ after a stretch of uninterrupted playback (see below).
162
176
 
163
177
  How long the player keeps trying depends on one piece of evidence: **has this
164
178
  load ever produced audio?**
@@ -170,25 +184,38 @@ load ever produced audio?**
170
184
 
171
185
  While the device is **offline**, the first-connect budget does not apply: the
172
186
  player parks and retries the moment connectivity returns, so a stream started
173
- in a tunnel still plays when the network comes back. Any offline observation
174
- resets the first-connect clock entirely — after restoration the load gets
175
- another full first-connect window, because the clock only ever measures a
176
- contiguous online stretch. `maxRetryDurationMs` is different: it is a
177
- wall-clock ceiling that **includes** offline time, deliberately — it exists so
178
- playback can't surprise the listener by resuming after a long time offline.
179
-
180
- `maxRetries` additionally caps the retry attempts of a load, counted across
181
- both budgets and across offline/online transitions. (One Android caveat: for
182
- segmented formats like HLS, ExoPlayer counts attempts per internal loadable —
183
- playlist and segments separately — so an attempt cap is less predictable there;
184
- prefer the duration budgets as the bound you rely on.)
185
-
186
- Backoff delays grow `1s → 1.5s → 2.3s → 3.4s → 5s` (capped). Once a budget is
187
+ in a tunnel still plays when the network comes back.
188
+
189
+ Any offline observation resets the first-connect clock entirely — after
190
+ restoration the load gets another full first-connect window, because the
191
+ clock only ever measures a contiguous online stretch.
192
+
193
+ `maxRetryDurationMs` is different: it is a wall-clock ceiling that
194
+ **includes** offline time. It exists so playback can't surprise the listener
195
+ by resuming after a long time offline.
196
+
197
+ `maxRetries` additionally caps the retry attempts, counted across both budgets
198
+ and across offline/online transitions.
199
+
200
+ One Android caveat: for segmented formats like HLS, ExoPlayer counts attempts
201
+ per internal loadable — playlist and segments separately — so an attempt cap
202
+ is less predictable there. Prefer the duration budgets as the bound you rely
203
+ on.
204
+
205
+ After 20 seconds of uninterrupted audible playback, the stream counts as
206
+ recovered and the recovery budget refills (on iOS, the attempt count too), so
207
+ each later dropout of a long-lived stream gets a full window.
208
+
209
+ The load stays the same, and so does its evidence that it has played: the
210
+ first-connect budget does not come back.
211
+
212
+ Backoff delays grow exponentially from 1 s, capped at 5 s. Once a budget is
187
213
  exhausted the state lands on `'error'`, where your `PlaybackErrorView` and
188
- [`retry()`](#manual-retry) take over. Restarting from `'error'` — via
189
- `retry()` or any play command — begins a **new load** of the same track:
190
- fresh budgets, starting with the first-connect one. The tap behaves exactly
191
- like re-selecting the track.
214
+ [`retry()`](#manual-retry) take over.
215
+
216
+ Restarting from `'error'` — via `retry()` or any play command — begins a
217
+ **new load** of the same track: fresh budgets, starting with the
218
+ first-connect one. The tap behaves exactly like re-selecting the track.
192
219
 
193
220
  ### Errors while retrying
194
221
 
@@ -197,8 +224,11 @@ classified and surfaced immediately through
197
224
  [`onPlaybackChanged`](/api/features/playback/#onplaybackchanged) /
198
225
  [`usePlayback()`](/guide/playback#playback-state), attached to the current
199
226
  non-terminal state (`'loading'` / `'buffering'`, or `'paused'`) with
200
- `retrying: true`. Show it as advisory — the cause over a spinner — because the
201
- next attempt may still succeed:
227
+ `retrying: true`.
228
+
229
+ Show it as advisory — the cause over a spinner — because the next attempt may
230
+ still succeed. A 408 or 429 arrives here as `kind: 'rejected'` with
231
+ `retrying: true`; it becomes final only once retry gives up:
202
232
 
203
233
  ```tsx
204
234
  const { state, error } = usePlayback()
@@ -213,16 +243,19 @@ if (error?.retrying) {
213
243
  `onPlaybackError` and `usePlaybackError()` stay **terminal-only**: they fire on
214
244
  _both_ edges of the `'error'` state — entering it (with the error) and leaving
215
245
  it (with `error: undefined`; the hook returns `undefined` again). Advisory
216
- errors never pass through them. The same advisory error also reaches the
217
- [Now Playing formatter](/guide/now-playing#the-formatter-derived-continuous),
218
- so the lock screen and the car can show it too.
246
+ errors never pass through them.
247
+
248
+ The same advisory error also reaches the
249
+ [Now Playing formatter](/guide/now-playing#the-formatter-derived-continuous), so
250
+ the lock screen and the car can show it too.
219
251
 
220
252
  Advisory emissions are deduplicated by **classification** (`kind`, plus the
221
- HTTP status when there is one) — never by the raw native `message`. The scope
222
- is the current advisory episode: consecutive identical failures within one
223
- retry sequence produce a single event rather than one per backoff tick, and the
224
- dedupe resets once the advisory clears (recovery, track change, or hardening
225
- into the terminal error).
253
+ HTTP status when there is one) — never by the raw native `message`.
254
+
255
+ The scope is the current advisory episode. Consecutive identical failures
256
+ within one retry sequence produce a single event rather than one per backoff
257
+ tick. The dedupe resets once the advisory clears: on recovery, a track change,
258
+ or hardening into the terminal error.
226
259
 
227
260
  ## Navigation errors
228
261
 
@@ -241,17 +274,25 @@ with `onNavigationError` / snapshot with `getNavigationError()`.
241
274
  | `'network-error'` | The request failed (connection error, timeout, no internet). |
242
275
  | `'http-error'` | Server returned non-2xx (or 2xx but parsing failed) — see `statusCode` / `statusCodeSuccess`. |
243
276
  | `'callback-error'` | Your browse callback returned an error (e.g. auth/subscription required). |
244
- | `'empty-content'` | The path resolved but the page has no tracks (empty Favorites, no search results). |
245
- | `'timeout'` | Resolution didn't finish in time. |
277
+ | `'empty-content'` | The page has no tracks (empty Favorites, no search results). CarPlay / Android Auto only. |
278
+ | `'timeout'` | Resolution didn't finish in time. CarPlay only. |
246
279
  | `'unknown-error'` | An unexpected error (e.g. invalid configuration). |
247
280
 
281
+ `'empty-content'` and `'timeout'` never reach `useNavigationError()` or
282
+ `onNavigationError`: the library raises them only for the in-car screens, where
283
+ they pass through [`formatNavigationError`](#showing-navigation-errors). Handle
284
+ them there.
285
+
248
286
  ### Showing navigation errors
249
287
 
250
288
  For display, prefer
251
289
  [`useFormattedNavigationError()`](/api/features/errors/#useformattednavigationerror)
252
290
  — it returns a ready-to-show [`FormattedNavigationError`](/api/features/errors/#formattednavigationerror)
253
- (`{ title, message? }`). The **same** formatted error drives the CarPlay and
254
- Android Auto error dialogs, so your in-app and in-car messages stay consistent:
291
+ (`{ title, message? }`). Outside React, read it with
292
+ `getFormattedNavigationError()` or subscribe with
293
+ [`onFormattedNavigationError`](/api/features/errors/#onformattednavigationerror).
294
+ The **same** formatted error drives the CarPlay and Android Auto error dialogs,
295
+ so your in-app and in-car messages stay consistent:
255
296
 
256
297
  ```tsx
257
298
  import { Text } from 'react-native'
@@ -302,9 +343,10 @@ message to render.
302
343
  | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
303
344
  | `usePlaybackError()` / `getPlaybackError()` | The current playback error (`{ kind, code, message, statusCode?, retrying? }`) — branch on `kind`. |
304
345
  | `onPlaybackError` | Subscribe to terminal playback errors outside React (fires on entering/leaving `'error'`; advisory retrying errors arrive via `onPlaybackChanged`). |
305
- | `retry()` | Re-attempt the current item (while state is `'error'`). |
306
- | `setupPlayer({ retry })` | Automatic retry with two duration budgets: first-connect (12s) and recovery (2 min). Off by default. |
346
+ | `retry()` | Re-attempt the current item; meant for the `'error'` state (on iOS it reloads from any state). |
347
+ | `setupPlayer({ retry })` | Automatic retry with two [duration budgets](#two-duration-budgets): first-connect and recovery. Off by default. |
307
348
  | `useNavigationError()` / `getNavigationError()` | The raw navigation error (`code`, `statusCode`, …). |
308
349
  | `onNavigationError` | Subscribe to navigation errors outside React. |
309
350
  | `useFormattedNavigationError()` / `getFormattedNavigationError()` | Display-ready `{ title, message? }`, shared with CarPlay / Android Auto. |
351
+ | `onFormattedNavigationError` | Subscribe to the formatted navigation error outside React. |
310
352
  | `configureBrowser({ formatNavigationError })` | Customize / localize the formatted messages. |
@@ -1,10 +1,12 @@
1
1
  ---
2
- description: 'Let listeners heart the active track from the now-playing screen, notification, CarPlay, and Android Auto, and surface a Favorites tab and voice command.'
2
+ description: 'Let listeners heart the active track from the Android notification, Android Auto, CarPlay, and Siri, and surface a Favorites tab and voice command.'
3
3
  ---
4
4
 
5
5
  # Favorites
6
6
 
7
- **Favorites** let a listener mark the active track with a heart — on the now-playing screen, the notification, CarPlay, and Android Auto — and let you surface a "Favorites" tab and a "play my favorites" voice command. The library tracks favorite _state_ (which track is favorited, and keeping the heart in sync everywhere); **your app owns the collection** (where favorites are stored and how they persist).
7
+ **Favorites** let a listener mark the active track with a heart: in the Android notification and system media controls, Android Auto, the CarPlay now-playing screen, and through Siri. They also let you surface a "Favorites" tab and a "play my favorites" voice command.
8
+
9
+ The library tracks favorite _state_ (which track is favorited, and keeping the heart in sync everywhere); **your app owns the collection** (where favorites are stored and how they persist).
8
10
 
9
11
  ## Enabling favorites
10
12
 
@@ -18,7 +20,7 @@ await setupPlayer({
18
20
  })
19
21
  ```
20
22
 
21
- The identifiers you pass to [`setFavorites`](#hydrating-favorite-state) are compared against each track's **identity**: its `id` when set, falling back to its `src`. Store the same stable identifier you put in `Track.id` — or, for tracks without ids, the full `src`:
23
+ The identifiers you pass to [`setFavorites`](#hydrating-favorite-state) are compared against each track's **identity**: its `id` when set, falling back to its `src` ([`getTrackIdentity`](/api/utils/getTrackIdentity/) computes it). Store the same stable identifier you put in `Track.id` — or, for tracks without ids, the full `src`:
22
24
 
23
25
  ```ts
24
26
  import { setFavorites } from 'react-native-audio-browser'
@@ -32,7 +34,9 @@ setFavorites(['https://stream.example.com/jazz.mp3']) // matches by src
32
34
 
33
35
  ## Hydrating favorite state
34
36
 
35
- The library keeps a native cache of which tracks are favorited, so it paints hearts across browse rows and the Now Playing heart without a round-trip to JS — and **without your content API having to know which tracks are favorites**. Declare your favorites once with `setFavorites`; the library stamps `favorited` on any track whose [identity](#enabling-favorites) matches, wherever that track appears. Your content endpoints stay favorites-agnostic — they return the same tracks for everyone, and favorite state lives entirely in your app/user storage.
37
+ The library keeps a native cache of which tracks are favorited. It paints hearts on Android Auto browse rows and the now-playing heart without a round-trip to JS, and **without your content API having to know which tracks are favorites**.
38
+
39
+ Declare your favorites once with `setFavorites`; the library stamps `favorited` on any track whose [identity](#enabling-favorites) matches, wherever that track appears. Your content endpoints stay favorites-agnostic — they return the same tracks for everyone, and favorite state lives entirely in your app/user storage.
36
40
 
37
41
  ```ts
38
42
  import { setFavorites } from 'react-native-audio-browser'
@@ -44,29 +48,29 @@ setFavorites(favorites)
44
48
 
45
49
  You only need `setFavorites` for the initial hydrate. After that, taps on the system heart and calls to [`setActiveTrackFavorited`](#favoriting-from-your-own-ui) update the cache for you.
46
50
 
47
- Your API can also return `favorited: true` on a track directly. A caller-set flag always wins over hydration for display — the library never overwrites it — but it does **not** fill the favorites cache: it only affects the response it arrived in, so other appearances of the same track stay unhearted. Treat `setFavorites` as the source of truth, and server-supplied `favorited` as a per-response display override.
51
+ Your API can also return `favorited: true` on a track directly. A caller-set flag always wins over hydration for display — the library never overwrites it — but it does **not** fill the favorites cache. It only affects the response it arrived in, so other appearances of the same track stay unhearted.
52
+
53
+ Treat `setFavorites` as the source of truth, and server-supplied `favorited` as a per-response display override.
48
54
 
49
55
  ## Favoriting from system controls
50
56
 
51
- With the capability enabled, a heart appears on the now-playing surfaces. Add it to the Android notification and the CarPlay now-playing screen explicitly:
57
+ Where the heart shows up depends on the platform:
58
+
59
+ - **Android:** once the capability is on, the heart sits in the overflow of the notification, Android Auto and the system media controls. You need no layout for it. A [`remoteButtonLayout`](/guide/remote-controls#button-layout-android) places it, and a layout that leaves out `'favorite'` drops it.
60
+ - **iOS:** the only heart is a button on the CarPlay now-playing screen, and you opt into it. Control Center and the lock screen show none.
52
61
 
53
62
  ```ts
54
63
  import { setupPlayer } from 'react-native-audio-browser'
55
64
 
56
65
  await setupPlayer({
57
66
  capabilities: { favorite: true },
58
- android: {
59
- remoteButtonLayout: {
60
- back: 'skip-to-previous',
61
- forward: 'skip-to-next',
62
- overflow: ['favorite']
63
- }
64
- },
65
67
  ios: { carPlayNowPlayingButtons: ['favorite'] }
66
68
  })
67
69
  ```
68
70
 
69
- When the listener taps a system heart, the library updates its cache and the UI, then emits `onFavoriteChanged` so **you can persist the change** to your storage or backend:
71
+ On iOS, Siri can also favorite or unfavorite the playing track ("add this to my favorites", "I like this") once Siri is wired up as in [CarPlay → Siri Voice Search](/guide/carplay#siri-voice-search), with `INAddMediaIntent` and `INUpdateMediaAffinityIntent` also listed in `INIntentsSupported`. Favorites need no `search` source.
72
+
73
+ Every favorite change, from any source, updates the library's cache and the hearts, then emits `onFavoriteChanged`: a system heart tap, a Siri request, and your own calls to [`setActiveTrackFavorited`](#favoriting-from-your-own-ui) alike. Persist the change to your storage or backend here, and only here:
70
74
 
71
75
  ```ts
72
76
  import { onFavoriteChanged } from 'react-native-audio-browser'
@@ -77,7 +81,7 @@ const unsubscribe = onFavoriteChanged.addListener(({ track, favorited }) => {
77
81
  })
78
82
  ```
79
83
 
80
- The native side has already updated the now-playing heart by the time this fires, so your handler just persists the change — then refreshes the rest (see [Keep it in sync](#keep-it-in-sync)).
84
+ The native side has already updated the now-playing heart by the time this fires, so your handler persists the change, then refreshes the `/favorites` content (see [Keep it in sync](#keep-it-in-sync)).
81
85
 
82
86
  ## Favoriting from your own UI
83
87
 
@@ -93,7 +97,7 @@ setActiveTrackFavorited(true)
93
97
  toggleActiveTrackFavorited()
94
98
  ```
95
99
 
96
- These are the programmatic counterpart to a system heart tap — persist the result yourself, the same way you would in `onFavoriteChanged`.
100
+ Both emit `onFavoriteChanged` like a system heart tap does, so the listener above persists the change. Don't persist it again in your button handler.
97
101
 
98
102
  ## Surfacing favorites
99
103
 
@@ -122,18 +126,24 @@ Resolve it however your collection lives — from local storage, or from your AP
122
126
 
123
127
  ### Keep it in sync
124
128
 
125
- The library caches each browse route, so the `/favorites` route keeps showing its old contents until you tell it to re-fetch. **Whenever the favorites collection changes** — a system heart tap, your own UI, or a sync from another device — do two things:
129
+ The library caches each path's content, so `/favorites` keeps showing its old content until you tell it to re-fetch. **Whenever the favorites collection changes**, re-fetch it.
130
+
131
+ When the change came from outside the player, such as a sync from another device or an edit on your server, also refresh the hearts:
126
132
 
127
133
  ```ts
128
134
  import { setFavorites, notifyContentChanged } from 'react-native-audio-browser'
129
135
 
130
- // refresh the hearts (favorited flag)
136
+ // only for changes from outside the player: refresh the hearts
131
137
  setFavorites(updatedIds)
132
- // re-fetch the /favorites content
138
+ // always: re-fetch the /favorites content
133
139
  notifyContentChanged('/favorites')
134
140
  ```
135
141
 
136
- These hit two different caches: `setFavorites` updates the `favorited` flag wherever a track appears, while [`notifyContentChanged(path)`](/api/) re-runs the route handler for that one path and refreshes any surface currently showing it. (Use `invalidateAllContent()` instead only when _everything_ should re-fetch — e.g. a locale switch or sign-out.) Driving both from a single place that observes your favorites list — rather than from each individual toggle — keeps every source of change covered.
142
+ These hit two different caches. `setFavorites` updates the `favorited` flag wherever a track appears. A heart tap, a Siri request or `setActiveTrackFavorited` already updates it, so for those the call is redundant, though harmless.
143
+
144
+ [`notifyContentChanged(path)`](/api/features/browser/#notifycontentchanged) re-runs the route handler for that one path and refreshes any surface currently showing it. Use [`invalidateAllContent()`](/api/features/browser/#invalidateallcontent) instead only when _everything_ should re-fetch, such as on a locale switch or sign-out.
145
+
146
+ You can drive both calls from one place that observes your favorites list, rather than from each source of change.
137
147
 
138
148
  ## Searching within favorites
139
149
 
@@ -141,14 +151,14 @@ Voice intents can target the favorites collection — both "play my favorites" a
141
151
 
142
152
  ## API summary
143
153
 
144
- | API | Purpose |
145
- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
146
- | `capabilities: { favorite: true }` | Enable favoriting and the system hearts. |
147
- | `setFavorites(ids)` | Hydrate the favorites cache; ids match each track's identity (`id`, falling back to `src`). |
148
- | `track.favorited` | Per-track display flag; a caller-set value wins over hydration but does not fill the cache. |
149
- | `setActiveTrackFavorited(bool)` / `toggleActiveTrackFavorited()` | Favorite the active track from your own UI. |
150
- | `onFavoriteChanged` | Subscribe to system heart taps to persist the change. |
151
- | `notifyContentChanged('/favorites')` | Re-fetch the `/favorites` content after the collection changes. |
152
- | `'favorite'` in `android.remoteButtonLayout` | Heart in the Android notification, Android Auto, and the system media controls. A layout replaces the defaults wholesale, so list the other buttons you still want. |
153
- | `ios.carPlayNowPlayingButtons: ['favorite']` | Heart on the CarPlay now-playing screen. |
154
- | `search` source with `reference: 'my'` | Resolve "play my favorites" / favorites search. |
154
+ | API | Purpose |
155
+ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
156
+ | `capabilities: { favorite: true }` | Enable favoriting and the system hearts. |
157
+ | `setFavorites(ids)` | Hydrate the favorites cache; ids match each track's identity (`id`, falling back to `src`). |
158
+ | `track.favorited` | Per-track display flag; a caller-set value wins over hydration but does not fill the cache. |
159
+ | `setActiveTrackFavorited(bool)` / `toggleActiveTrackFavorited()` | Favorite the active track from your own UI. |
160
+ | `onFavoriteChanged` | Fires on every favorite change (system heart, Siri, your own calls); persist the change here. |
161
+ | `notifyContentChanged('/favorites')` | Re-fetch the `/favorites` content after the collection changes. |
162
+ | `'favorite'` in `android.remoteButtonLayout` | Places the Android heart. Without a layout it sits in the overflow already. A layout replaces the defaults wholesale, so list the other buttons you still want. |
163
+ | `ios.carPlayNowPlayingButtons: ['favorite']` | The heart on the CarPlay now-playing screen, the only one on iOS. |
164
+ | `search` source with `reference: 'my'` | Resolve "play my favorites" / favorites search. |
@@ -4,19 +4,27 @@ description: 'Block premium, login-only, or region-locked content on CarPlay and
4
4
 
5
5
  # Gate
6
6
 
7
- When part of your catalog is premium, login-only, or region-locked, you need a way to block it on the car surfaces — without building a separate UI for them. That's what a **Gate** is: you hand the library a short message, and it shows that in place of the browse content on **CarPlay** and **Android Auto**, and can turn away voice searches.
7
+ A **Gate** replaces the browse content on **CarPlay**, **Android Auto** and **Android Automotive** with a short message that you hand the library. It can also turn away voice searches.
8
8
 
9
- One rule worth keeping in mind: **a Gate blocks _finding_, never _hearing_.** Whatever is already playing keeps going, "resume" and "play this" still work by voice, and the queue and now-playing are left alone.
9
+ Use it when part of your catalog is premium, login-only or region-locked, and you want to block it in the car without building a separate UI there.
10
+
11
+ One rule worth keeping in mind: **a Gate blocks _finding_, never _hearing_.** Whatever is already playing keeps going, a voice "resume" is never gated, and the queue is left alone.
12
+
13
+ A voice request to play something new is a search. The Gate refuses it unless your resolver lets search through (see [Gating some requests, not others](#gating-some-requests-not-others)).
10
14
 
11
15
  Two things it never touches:
12
16
 
13
17
  - **Your own in-app browse UI.** The Gate only covers content the _library_ serves; the screens you draw in your app are yours to gate with your own paywall.
14
18
  - **Playback.** It lives on the find/resolve path, so audio is never interrupted.
15
19
 
16
- It follows that the Gate is **iOS and Android only**. On web `setGate` and `clearGate` are no-ops and `onGate` never fires — there's no CarPlay or Android Auto surface to cover, and in-app browse UI was never the Gate's job on any platform. Calling them from shared code is safe and does nothing.
20
+ It follows that the Gate is **iOS and Android only**. On web `setGate` and `clearGate` are no-ops and `onGate` never fires: there's no car surface to cover.
21
+
22
+ In-app browse UI is not the Gate's job on any platform. Calling the Gate functions from shared code is safe, and on web does nothing.
17
23
 
18
24
  ::: warning Voice search isn't only a "car" thing
19
- A Siri request ("Hey Siri, play jazz on App") can come from the phone or lock screen, not just CarPlay — and it still goes through the Gate. That's why the common setup below **gates browsing but lets search through**: voice-play keeps working everywhere, while the car's browse tabs stay walled off.
25
+ A Siri or Google Assistant request ("Hey Siri, play jazz on App") can come from the phone or lock screen, not just the car. It still goes through the Gate.
26
+
27
+ That's why the common setup below **gates browsing but lets search through**: voice-play keeps working everywhere, while the car's browse tabs stay walled off.
20
28
  :::
21
29
 
22
30
  ## Setting a gate
@@ -29,19 +37,23 @@ setGate({ title: 'Premium', message: 'Subscribe to browse in the car.' })
29
37
  clearGate()
30
38
  ```
31
39
 
32
- [`setGate`](/api/features/gate/#setgate) raises the gate (or updates it in place); [`clearGate`](/api/features/gate/#cleargate) drops it and the real content returns. Set it before the car connects and it'll be there the moment it does. A gate is global and singular — calling `setGate` again replaces the current one.
40
+ [`setGate`](/api/features/gate/#setgate) raises the gate (or updates it in place); [`clearGate`](/api/features/gate/#cleargate) drops it and the real content returns (on CarPlay, on the first tab; see the warning below).
41
+
42
+ Set it before the car connects and it'll be there the moment it does. A gate is global and singular — calling `setGate` again replaces the current one.
33
43
 
34
44
  A Gate is **independent** of `setupPlayer` and `configureBrowser` — call `setGate` any time after import. The usual lifecycle is: set it once at startup, then `clearGate` (or re-`setGate`) whenever the user's entitlement changes (purchase, login, logout).
35
45
 
36
46
  A gate is just a title and an optional message. How it renders depends on the surface:
37
47
 
38
- - **CarPlay** — a full-page centered message.
39
- - **Android Auto** — one non-playable list tile: the **title** as its main line, the **message** as the subtitle (newlines collapse to spaces). It's a tile, not a full page like CarPlay, so keep both short.
48
+ - **CarPlay**: the tab bar stays, and each gated tab, or gated page you navigate to, shows a centered message page in place of its list (newlines in the message collapse to spaces). The Now Playing screen keeps its transport controls but hides the custom buttons from `ios.carPlayNowPlayingButtons`.
49
+ - **Android Auto and Android Automotive**: the tabs stay visible, and each gated tab's content becomes one non-playable list tile. The tile shows the **title** as its main line and the **message** as the subtitle (newlines collapse to spaces). Keep both short: it's a tile, not a full page.
40
50
 
41
51
  There's no action button: Android Auto can't show one, and a car surface can't run a purchase flow anyway (see [Reacting to gate hits](#reacting-to-gate-hits) for the deferred-upsell pattern).
42
52
 
43
- ::: warning Updating a live gate resets CarPlay navigation
44
- Calling `setGate` while a gate is already up replaces it in place — but on CarPlay it pops any drilled-in navigation back to the tab root. Harmless for a set-once gate; worth knowing if you update the message mid-session.
53
+ ::: warning Changing the gate resets CarPlay navigation
54
+ While CarPlay is connected, every `setGate`, and every `clearGate` that drops a gate that was up, pops any drilled-in pages back to the tab root. This includes a first `setGate` on logout and a `clearGate` after a purchase. A `clearGate` with no gate up does nothing.
55
+
56
+ A `clearGate` also rebuilds the tab bar, so CarPlay returns to the first tab; `setGate` keeps the selected tab. A gate set before the car connects does not affect navigation.
45
57
  :::
46
58
 
47
59
  ## Gating some requests, not others
@@ -104,7 +116,9 @@ setGate({ title: 'Premium', message: 'Subscribe to unlock.' }, (request) => {
104
116
  })
105
117
  ```
106
118
 
107
- You can also pass **only** a resolver, with no default message — return a gate object for full control, or `true` to fall back to the generic built-in chrome. That fallback is a title only (`"Unavailable"`, no body), so on CarPlay its message area is blank — pass a default gate or return a gate object if you want body copy.
119
+ You can also pass **only** a resolver, with no default message. Return a gate object for full control, or `true` to fall back to the generic built-in chrome.
120
+
121
+ That fallback is a generic built-in title with no body, so on CarPlay its message area is blank. Pass a default gate or return a gate object if you want body copy.
108
122
 
109
123
  ```ts
110
124
  setGate((request) => request.kind === 'browse')