react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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,12 +1,12 @@
1
1
  ---
2
- description: 'Install react-native-audio-browser and its react-native-nitro-modules peer dependency, then complete the iOS and Android native setup.'
2
+ description: 'Install react-native-audio-browser and its react-native-nitro-modules peer dependency, complete the iOS and Android native setup, and add shaka-player if you target the browser.'
3
3
  ---
4
4
 
5
5
  # Getting Started
6
6
 
7
7
  ## Installation
8
8
 
9
- The library requires **React Native 0.76 or newer** (with the New Architecture enabled) and React 18.2+. `react-native-nitro-modules` is a required peer dependency — install it alongside:
9
+ The library requires **React Native 0.76 or newer** (with the New Architecture enabled) and React 18.2+, and runs on iOS 16+ and Android API 24+. `react-native-nitro-modules` 0.35 or later is a required peer dependency — install it alongside:
10
10
 
11
11
  ::: code-group
12
12
 
@@ -28,6 +28,45 @@ bun add react-native-audio-browser react-native-nitro-modules
28
28
 
29
29
  :::
30
30
 
31
+ On iOS, install the pods:
32
+
33
+ ```bash
34
+ cd ios && pod install
35
+ ```
36
+
37
+ For playback to continue in the background on iOS, add the `audio` background mode to your app's `Info.plist`:
38
+
39
+ ```xml
40
+ <key>UIBackgroundModes</key>
41
+ <array>
42
+ <string>audio</string>
43
+ </array>
44
+ ```
45
+
46
+ Android links automatically.
47
+
48
+ For web (`react-native-web`), also install [`shaka-player`](https://github.com/shaka-project/shaka-player) 4 (4.7.9 or later). It is an optional peer dependency that the web player loads during `setupPlayer()`. Native builds don't need it.
49
+
50
+ ::: code-group
51
+
52
+ ```bash [npm]
53
+ npm install shaka-player
54
+ ```
55
+
56
+ ```bash [yarn]
57
+ yarn add shaka-player
58
+ ```
59
+
60
+ ```bash [pnpm]
61
+ pnpm add shaka-player
62
+ ```
63
+
64
+ ```bash [bun]
65
+ bun add shaka-player
66
+ ```
67
+
68
+ :::
69
+
31
70
  ## Basic Setup
32
71
 
33
72
  ```ts
@@ -39,6 +78,20 @@ await setupPlayer()
39
78
 
40
79
  > The library exposes both named exports (`import { setupPlayer }`) and a default namespace (`import AudioBrowser from '…'; AudioBrowser.setupPlayer()`). The guides use the named form throughout.
41
80
 
81
+ ## Web
82
+
83
+ The same API runs in the browser. On web the library plays through an HTML `<audio>` element driven by [Shaka Player](https://github.com/shaka-project/shaka-player), the optional peer dependency from [Installation](#installation).
84
+
85
+ Your bundler must resolve `.web.ts` / `.web.js` files ahead of plain ones, as react-native-web setups do, and map `react-native` to `react-native-web`. On the server (no `window`) `setupPlayer()` creates no player, so call it in the browser.
86
+
87
+ Playback, the queue, browse, search and the sleep timer work as on native. Now Playing metadata goes to the browser's Media Session API, so the system's media controls, media keys and Bluetooth buttons show the track and drive the player through the same [remote controls](/guide/remote-controls) handlers.
88
+
89
+ What web lacks:
90
+
91
+ - No CarPlay or Android Auto: the [Gate](/guide/gate) does nothing and `isCarConnected()` is always `false`.
92
+ - The [equalizer](/guide/equalizer), [battery](/guide/battery) and [audio output](/guide/audio-output) APIs return their empty values (`undefined`, `false`, `'unrestricted'`) and their setters do nothing. `getSystemVolume()` is always `1` and `setSystemVolume()` does nothing.
93
+ - No automatic retry (manual `retry()` works) and no timed metadata, neither ICY nor HLS ID3; see [Live Streams](/guide/live-streams#dropouts-stalls-and-retry).
94
+
42
95
  ## Next Steps
43
96
 
44
97
  - [Basic Usage](/guide/basic-usage) - Learn how to play audio and build navigation trees
@@ -4,7 +4,9 @@ description: 'The React hooks that keep your UI in sync with playback, the queue
4
4
 
5
5
  # Hooks
6
6
 
7
- The library exposes its state as **React hooks** — call one in a component and it returns the current value and re-renders whenever that value changes. They keep your in-app UI in sync with playback, the queue, the browse tree, and the device, including changes driven from _outside_ your app (the lock screen, CarPlay, Android Auto, Bluetooth).
7
+ The library exposes its state as **React hooks** — call one in a component and it returns the current value and re-renders whenever that value changes.
8
+
9
+ They keep your in-app UI in sync with playback, the queue, the browse tree, and the device, including changes driven from _outside_ your app (the lock screen, CarPlay, Android Auto, Bluetooth).
8
10
 
9
11
  ```tsx
10
12
  import { useActiveTrack, usePlayingState } from 'react-native-audio-browser'
@@ -36,11 +38,14 @@ Most events are named `on<Thing>Changed`, but several aren't — `onProgressUpda
36
38
  import { getPlayback, onPlaybackChanged } from 'react-native-audio-browser'
37
39
 
38
40
  const now = getPlayback() // read once
39
- const stop = onPlaybackChanged.addListener((p) => console.log(p.state)) // subscribe
41
+ // subscribe
42
+ const stop = onPlaybackChanged.addListener((p) => console.log(p.state))
40
43
  // stop() to unsubscribe
41
44
  ```
42
45
 
43
- Every hook, getter, and event is a named export from `react-native-audio-browser`. Hooks read a cached value synchronously on first render (no flash of empty state) and then subscribe for you. Mutating state is separate — `setX()` / action functions (`play`, `setQueue`, `setShuffle`, `setRepeatMode`, `setPlayWhenReady`, …) — covered in [Basic Usage](/guide/basic-usage).
46
+ Every hook, getter, and event is a named export from `react-native-audio-browser`. Hooks read a cached value synchronously on first render (no flash of empty state) and then subscribe for you, except `usePolledProgress`, which starts at zero and fills in on its first poll.
47
+
48
+ Mutating state is separate — `setX()` / action functions (`play`, `setQueue`, `setShuffle`, `setRepeatMode`, `setPlayWhenReady`, …) — covered in [Basic Usage](/guide/basic-usage).
44
49
 
45
50
  ## Playback
46
51
 
@@ -63,7 +68,7 @@ function Transport() {
63
68
 
64
69
  - [**`usePlayback()`**](/api/features/playback/#useplayback) → `{ state, error? }`. `state` is one of `none`, `ready`, `loading`, `buffering`, `playing`, `paused`, `stopped`, `ended`, `error`.
65
70
  - [**`usePlayingState()`**](/api/features/playback/#useplayingstate) → `{ playing, buffering }`. A lighter hook when you only need the booleans.
66
- - [**`useProgress()`**](/api/features/playback/#useprogress) → [`Progress`](/api/features/playback/#progress) (`{ position, duration, buffered }`) in seconds. Event-driven, but **off by default**: `progressUpdateEventInterval` is `null` until you set it (in seconds) via `updateOptions({ progressUpdateEventInterval: 0.5 })` — otherwise the value never ticks.
71
+ - [**`useProgress()`**](/api/features/playback/#useprogress) → [`Progress`](/api/features/playback/#progress) (`{ position, duration, buffered }`) in seconds. Event-driven, but **off by default**: `progressUpdateEventInterval` is `null` until you set it (in seconds) in `setupPlayer` or `updateOptions`, e.g. `progressUpdateEventInterval: 0.5` — otherwise the value never ticks.
67
72
  - [**`usePolledProgress(updateInterval = 1000)`**](/api/features/playback/#usepolledprogress) → same [`Progress`](/api/features/playback/#progress), but polled on its own timer (milliseconds) instead of event-driven, so it works without `progressUpdateEventInterval`. Good for a smooth scrubber; it pauses while the app is backgrounded.
68
73
  - [**`usePlayWhenReady()`**](/api/features/playback/#useplaywhenready) → `boolean`: whether the player will start as soon as content is ready.
69
74
  - [**`useSystemVolume()`**](/api/features/playback/#usesystemvolume) → `number` 0–1, the device volume (read-only on iOS).
@@ -76,6 +81,7 @@ function Transport() {
76
81
 
77
82
  ```tsx
78
83
  import {
84
+ getTrackIdentity,
79
85
  useActiveTrack,
80
86
  useQueue,
81
87
  useRepeatMode,
@@ -87,20 +93,22 @@ function QueueScreen() {
87
93
  const queue = useQueue() // Track[]
88
94
  const repeat = useRepeatMode() // 'off' | 'track' | 'queue'
89
95
  const shuffle = useShuffle() // boolean
90
- return <List data={queue} highlight={active?.id} />
96
+ return <List data={queue} highlight={active && getTrackIdentity(active)} />
91
97
  }
92
98
  ```
93
99
 
94
- [`useActiveTrack`](/api/features/queue/#useactivetrack) updates even when the track changes from an external control (car next/previous), so matching on the track's identity keeps your UI correct. Note `Track.id` is **optional** (and may be undefined for a browse item the user picked in the car without you queuing it) — fall back to `src` / `path` if you rely on `id`. See [Track](/guide/track) for the Track shape.
100
+ [`useActiveTrack`](/api/features/queue/#useactivetrack) updates even when the track changes from an external control (car next/previous), so matching on the track's identity keeps your UI correct. Compare tracks by identity: `id` when set, else `src`. [`getTrackIdentity(track)`](/api/utils/getTrackIdentity/) gives you the same comparison the library uses (see [Track](/guide/track#identity-id)).
95
101
 
96
102
  ## Now playing
97
103
 
98
- [**`useNowPlaying()`**](/api/features/nowPlaying/#usenowplaying) → [`NowPlayingMetadata`](/api/features/metadata/#nowplayingmetadata)` | undefined` — the metadata shown on the lock screen and car surfaces. It reflects any override you set via `updateNowPlaying()` (e.g. the current song on a live stream), falling back to the active track otherwise. See [Now Playing](/guide/now-playing).
104
+ [**`useNowPlaying()`**](/api/features/nowPlaying/#usenowplaying) → [`NowPlayingMetadata`](/api/features/metadata/#nowplayingmetadata)` | undefined` — the metadata shown on the lock screen and car surfaces.
105
+
106
+ On iOS and Android it returns what those surfaces show, in priority order: a `flashNowPlaying()` flash first, then your `nowPlaying` formatter, then any override you set via `updateNowPlaying()` (e.g. the current song on a live stream), then the active track's own fields. On web there is no formatter, and a flash replaces your override (see [the flash](/guide/now-playing#the-flash-transient-top-priority)). See [the four metadata layers](/guide/now-playing#the-four-metadata-layers).
99
107
 
100
108
  ```tsx
101
109
  const meta = useNowPlaying()
102
110
  // { title?, artist?, album?, artwork?, genre?, duration?,
103
- // description?, mediaId?, elapsedTime? }
111
+ // description?, mediaId?, elapsedTime? (iOS only, not live) }
104
112
  ```
105
113
 
106
114
  ## Browsing
@@ -156,17 +164,17 @@ const output = useOutput() // { type, name, external } | undefined
156
164
  // e.g. output?.type === 'bluetooth', output?.external === true
157
165
  ```
158
166
 
159
- `useOutput` updates as routes change (AirPods connect, a Bluetooth speaker is selected, etc.); it's `undefined` when unknown, and Android reports coarser `type`s. See [Audio Output](/guide/audio-output).
167
+ `useOutput` updates as routes change (AirPods connect, a Bluetooth speaker is selected, etc.); it's `undefined` when unknown. On Android below 13 (API 33) it can miss a reroute made while a device stays connected; see [The current output](/guide/audio-output#the-current-output).
160
168
 
161
169
  ## Errors
162
170
 
163
- - [**`usePlaybackError()`**](/api/features/errors/#useplaybackerror) → [`PlaybackError`](/api/features/errors/#playbackerror)` | undefined` — playback failures, with a normalized `kind` (`offline`, `unreachable`, `not-found`, `rejected`, `unplayable`, `stalled`, …) to branch on, plus a platform-specific `code` and optional `statusCode` for telemetry. Never show its `message` — see [Errors](/guide/errors#playback-errors).
171
+ - [**`usePlaybackError()`**](/api/features/errors/#useplaybackerror) → [`PlaybackError`](/api/features/errors/#playbackerror)` | undefined` — playback failures, with a normalized `kind` (`offline`, `unreachable`, `not-found`, `rejected`, `unplayable`, `stalled`, …) to branch on, plus a platform-specific `code` and optional `statusCode` for telemetry. Never show its `message` — see [Errors](/guide/errors#playback-errors). Terminal errors only: an error the player is still retrying (`retrying: true`) arrives on `usePlayback().error` — see [Errors while retrying](/guide/errors#errors-while-retrying).
164
172
  - [**`useNavigationError()`**](/api/features/errors/#usenavigationerror) → [`NavigationError`](/api/features/errors/#navigationerror)` | undefined` — a browse/search failure, with a typed `code` (`network-error`, `http-error`, `timeout`, `empty-content`, …) and optional `statusCode`.
165
- - [**`useFormattedNavigationError()`**](/api/features/errors/#useformattednavigationerror) → `{ title, message } | undefined` — the same error run through your `formatNavigationError` config (the copy CarPlay and Android Auto show), ready to display.
173
+ - [**`useFormattedNavigationError()`**](/api/features/errors/#useformattednavigationerror) → [`FormattedNavigationError`](/api/features/errors/#formattednavigationerror)` | undefined` (`{ title, message? }`) — the same error run through your `formatNavigationError` config (the copy CarPlay and Android Auto show), ready to display.
166
174
 
167
175
  ```tsx
168
176
  const error = useFormattedNavigationError()
169
- return error ? <Banner title={error.title} body={error.message} /> : null
177
+ return error ? <Banner title={error.title} body={error.message ?? ''} /> : null
170
178
  ```
171
179
 
172
180
  ## Player options
@@ -192,7 +200,7 @@ const { pending, status, dismiss, openSettings } = useBatteryWarning()
192
200
 
193
201
  ## Debugging
194
202
 
195
- **`useDebug(options?)`** → `{ state, logs, clear }` — a live snapshot of all player state plus a change log (last 100 entries). It's a development aid; `options.enabled` defaults to `__DEV__`.
203
+ [**`useDebug(options?)`**](/api/utils/useDebug/#usedebug) → `{ state, logs, clear }` — a live snapshot of the core player state (playback, queue, options, browse path, errors) plus a bounded log of recent changes. It's a development aid; `options.enabled` defaults to `__DEV__`.
196
204
 
197
205
  ```tsx
198
206
  const { state, logs, clear } = useDebug({ metadata: true })
@@ -200,39 +208,37 @@ const { state, logs, clear } = useDebug({ metadata: true })
200
208
 
201
209
  ## All hooks at a glance
202
210
 
203
- The **Event** column is the emitter name for the getter/event form — handy because the names aren't fully uniform.
204
-
205
- The **Hook** name links to its full API entry; the **Returns** type links to its definition where it has one.
206
-
207
- | Hook | Returns | Event | Platform |
208
- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------ | ------------------- |
209
- | [`usePlayback`](/api/features/playback/#useplayback) | `{ state, error? }` | `onPlaybackChanged` | all |
210
- | [`usePlayingState`](/api/features/playback/#useplayingstate) | `{ playing, buffering }` | `onPlayingState` | all |
211
- | [`useProgress`](/api/features/playback/#useprogress) | `{ position, duration, buffered }` | `onProgressUpdated` | all |
212
- | [`usePolledProgress`](/api/features/playback/#usepolledprogress) | `{ position, duration, buffered }` | _(polled)_ | all |
213
- | [`usePlayWhenReady`](/api/features/playback/#useplaywhenready) | `boolean` | `onPlayWhenReadyChanged` | all |
214
- | [`useSystemVolume`](/api/features/playback/#usesystemvolume) | `number` | `onSystemVolumeChanged` | all (read-only iOS) |
215
- | [`useActiveTrack`](/api/features/queue/#useactivetrack) | [`Track`](/api/types/browser-nodes/#track)` \| undefined` | `onActiveTrackChanged` | all |
216
- | [`useQueue`](/api/features/queue/#usequeue) | [`Track`](/api/types/browser-nodes/#track)`[]` | `onQueueChanged` | all |
217
- | [`useRepeatMode`](/api/features/queue/#userepeatmode) | [`RepeatMode`](/api/features/queue/#repeatmode) | `onRepeatModeChanged` | all |
218
- | [`useShuffle`](/api/features/queue/#useshuffle) | `boolean` | `onShuffleChanged` | all |
219
- | [`useNowPlaying`](/api/features/nowPlaying/#usenowplaying) | `NowPlayingMetadata \| undefined` | `onNowPlayingChanged` | all |
220
- | [`useTabs`](/api/features/browser/#usetabs) | [`Track`](/api/types/browser-nodes/#track)`[] \| undefined` | `onTabsChanged` | all |
221
- | [`usePath`](/api/features/browser/#usepath) | `string \| undefined` | `onPathChanged` | all |
222
- | [`useContent`](/api/features/browser/#usecontent) | [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack)` \| undefined` | `onContentChanged` | all |
223
- | [`useSleepTimerActive`](/api/features/sleepTimer/#usesleeptimeractive) | `boolean` | `onSleepTimerChanged` | all |
224
- | [`useSleepTimer`](/api/features/sleepTimer/#usesleeptimer) | [`SleepTimerState`](/api/features/sleepTimer/#sleeptimerstate)` \| undefined` | `onSleepTimerChanged` | all |
225
- | [`useOnline`](/api/features/network/#useonline) | `boolean` | `onOnlineChanged` | all |
226
- | [`useCarConnected`](/api/features/carConnection/#usecarconnected) | `boolean` | `onCarConnectedChanged` | all (`false` web) |
227
- | [`useOutput`](/api/features/output/#useoutput) | [`Output`](/api/features/output/#output)` \| undefined` | `onOutputChanged` | iOS, Android |
228
- | [`usePlaybackError`](/api/features/errors/#useplaybackerror) | [`PlaybackError`](/api/features/errors/#playbackerror)` \| undefined` | `onPlaybackError` | all |
229
- | [`useNavigationError`](/api/features/errors/#usenavigationerror) | [`NavigationError`](/api/features/errors/#navigationerror)` \| undefined` | `onNavigationError` | all |
230
- | [`useFormattedNavigationError`](/api/features/errors/#useformattednavigationerror) | `{ title, message } \| undefined` | `onFormattedNavigationError` | all |
231
- | [`useOptions`](/api/features/player/#useoptions) | [`Options`](/api/features/player/#options) | `onOptionsChanged` | all |
232
- | [`useBatteryWarning`](/api/features/battery/#usebatterywarning) | `{ pending, status, dismiss, openSettings }` | _(composite)_ | Android |
233
- | [`useBatteryWarningPending`](/api/features/battery/#usebatterywarningpending) | `boolean` | `onBatteryWarningPendingChanged` | Android |
234
- | [`useBatteryOptimizationStatus`](/api/features/battery/#usebatteryoptimizationstatus) | [`BatteryOptimizationStatus`](/api/features/battery/#batteryoptimizationstatus) | `onBatteryOptimizationStatusChanged` | Android |
235
- | [`useEqualizerSettings`](/api/features/equalizer/#useequalizersettings) | [`EqualizerSettings`](/api/features/equalizer/#equalizersettings)` \| undefined` | `onEqualizerChanged` | Android |
236
- | `useDebug` | `{ state, logs, clear }` | _(composite)_ | all |
211
+ The **Event** column is the emitter for the getter/event form, the **Hook** name links to its full API entry, and the **Returns** type links to its definition where it has one.
212
+
213
+ | Hook | Returns | Event | Platform |
214
+ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------- |
215
+ | [`usePlayback`](/api/features/playback/#useplayback) | `{ state, error? }` | `onPlaybackChanged` | all |
216
+ | [`usePlayingState`](/api/features/playback/#useplayingstate) | `{ playing, buffering }` | `onPlayingState` | all |
217
+ | [`useProgress`](/api/features/playback/#useprogress) | `{ position, duration, buffered }` | `onProgressUpdated` | all |
218
+ | [`usePolledProgress`](/api/features/playback/#usepolledprogress) | `{ position, duration, buffered }` | _(polled)_ | all |
219
+ | [`usePlayWhenReady`](/api/features/playback/#useplaywhenready) | `boolean` | `onPlayWhenReadyChanged` | all |
220
+ | [`useSystemVolume`](/api/features/playback/#usesystemvolume) | `number` | `onSystemVolumeChanged` | all (read-only iOS) |
221
+ | [`useActiveTrack`](/api/features/queue/#useactivetrack) | [`Track`](/api/types/browser-nodes/#track)` \| undefined` | `onActiveTrackChanged` | all |
222
+ | [`useQueue`](/api/features/queue/#usequeue) | [`Track`](/api/types/browser-nodes/#track)`[]` | `onQueueChanged` | all |
223
+ | [`useRepeatMode`](/api/features/queue/#userepeatmode) | [`RepeatMode`](/api/features/queue/#repeatmode) | `onRepeatModeChanged` | all |
224
+ | [`useShuffle`](/api/features/queue/#useshuffle) | `boolean` | `onShuffleChanged` | all |
225
+ | [`useNowPlaying`](/api/features/nowPlaying/#usenowplaying) | `NowPlayingMetadata \| undefined` | `onNowPlayingChanged` | all |
226
+ | [`useTabs`](/api/features/browser/#usetabs) | [`Track`](/api/types/browser-nodes/#track)`[] \| undefined` | `onTabsChanged` | all |
227
+ | [`usePath`](/api/features/browser/#usepath) | `string \| undefined` | `onPathChanged` | all |
228
+ | [`useContent`](/api/features/browser/#usecontent) | [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack)` \| undefined` | `onContentChanged` | all |
229
+ | [`useSleepTimerActive`](/api/features/sleepTimer/#usesleeptimeractive) | `boolean` | `onSleepTimerChanged` | all |
230
+ | [`useSleepTimer`](/api/features/sleepTimer/#usesleeptimer) | [`SleepTimerState`](/api/features/sleepTimer/#sleeptimerstate)` \| undefined` | `onSleepTimerChanged` | all |
231
+ | [`useOnline`](/api/features/network/#useonline) | `boolean` | `onOnlineChanged` | all |
232
+ | [`useCarConnected`](/api/features/carConnection/#usecarconnected) | `boolean` | `onCarConnectedChanged` | all (`false` web) |
233
+ | [`useOutput`](/api/features/output/#useoutput) | [`Output`](/api/features/output/#output)` \| undefined` | `onOutputChanged` | iOS, Android |
234
+ | [`usePlaybackError`](/api/features/errors/#useplaybackerror) | [`PlaybackError`](/api/features/errors/#playbackerror)` \| undefined` | `onPlaybackError` | all |
235
+ | [`useNavigationError`](/api/features/errors/#usenavigationerror) | [`NavigationError`](/api/features/errors/#navigationerror)` \| undefined` | `onNavigationError` | all |
236
+ | [`useFormattedNavigationError`](/api/features/errors/#useformattednavigationerror) | [`FormattedNavigationError`](/api/features/errors/#formattednavigationerror)` \| undefined` | `onFormattedNavigationError` | all |
237
+ | [`useOptions`](/api/features/player/#useoptions) | [`Options`](/api/features/player/#options) | `onOptionsChanged` | all |
238
+ | [`useBatteryWarning`](/api/features/battery/#usebatterywarning) | `{ pending, status, dismiss, openSettings }` | _(composite)_ | Android |
239
+ | [`useBatteryWarningPending`](/api/features/battery/#usebatterywarningpending) | `boolean` | `onBatteryWarningPendingChanged` | Android |
240
+ | [`useBatteryOptimizationStatus`](/api/features/battery/#usebatteryoptimizationstatus) | [`BatteryOptimizationStatus`](/api/features/battery/#batteryoptimizationstatus) | `onBatteryOptimizationStatusChanged` | Android |
241
+ | [`useEqualizerSettings`](/api/features/equalizer/#useequalizersettings) | [`EqualizerSettings`](/api/features/equalizer/#equalizersettings)` \| undefined` | `onEqualizerChanged` | Android |
242
+ | [`useDebug`](/api/utils/useDebug/#usedebug) | `{ state, logs, clear }` | _(composite)_ | all |
237
243
 
238
244
  For the exact return types, see the [API reference](/api/).
@@ -6,30 +6,38 @@ description: 'The map for live audio: stream formats, missing durations, dropped
6
6
 
7
7
  Live audio is what most of this player's edge cases are about: streams that
8
8
  have no duration, drop in tunnels, expire their URLs, and carry their song
9
- titles in-band. The pieces live in their own guides — this page is the map,
9
+ titles in-band.
10
+
11
+ The pieces live in their own guides — this page is the map,
10
12
  with just enough of each to know which link you need.
11
13
 
12
14
  ## Stream formats
13
15
 
14
- Point [`src`](/api/types/browser-nodes/#track) at the stream URL — there is
16
+ Point [`src`](/api/types/browser-nodes/#src) at the stream URL — there is
15
17
  no format field; each platform's player detects the container:
16
18
 
17
- - **HLS** (`.m3u8`) — both platforms. In-band ID3 timed metadata is read —
18
- see [Metadata](/guide/metadata#timed-metadata-the-live-song).
19
- - **ICY / Icecast / Shoutcast** — plain HTTP radio, both platforms. The ICY
20
- `StreamTitle` arrives as timed metadata, filling only `title` — it reaches
21
- the lock screen once your
22
- [now-playing formatter](/guide/now-playing#the-formatter-derived-continuous)
23
- applies it, never automatically (see
24
- [Metadata](/guide/metadata#timed-metadata-the-live-song)).
25
- - **Progressive HTTP** — ordinary MP3/AAC/… files and endless streams, both
26
- platforms.
27
- - **DASH / SmoothStreaming** — Android only (bundled Media3 modules); iOS's
28
- AVPlayer doesn't support them.
29
-
30
- Mark the track itself with [`live: true`](/api/types/browser-nodes/#track):
31
- it shows the live indicator on iOS now-playing and arms
32
- [`seekToLiveEdge()`](#the-live-edge) — declare it on every live track.
19
+ - **HLS** (`.m3u8`) — iOS, Android and web. iOS and Android read in-band
20
+ ID3 timed metadata.
21
+ - **ICY / Icecast / Shoutcast** — plain HTTP radio, iOS, Android and web. On
22
+ iOS and Android the ICY `StreamTitle` arrives as timed metadata, filling
23
+ only `title`.
24
+ - **Progressive HTTP** — ordinary MP3/AAC/… files and endless streams, iOS,
25
+ Android and web.
26
+ - **DASH** — Android (bundled Media3 module) and web; iOS's AVPlayer doesn't
27
+ support it. **SmoothStreaming** is Android only.
28
+
29
+ Timed metadata of either kind reaches the lock screen only once your
30
+ [now-playing formatter](/guide/now-playing#the-formatter-derived-continuous)
31
+ applies it, never automatically (see
32
+ [Metadata](/guide/metadata#timed-metadata-the-live-song)).
33
+
34
+ Mark the track itself with [`live: true`](/api/types/browser-nodes/#live):
35
+ it arms [`seekToLiveEdge()`](#the-live-edge) on every platform, and gives
36
+ now-playing non-scrubbing controls on iOS and Android. On Android a cast
37
+ receiver also loads it as a live stream. On iOS it also shows the live
38
+ indicator, turns an end of stream or a stall into a reconnect at the live
39
+ edge, and skips saving a position. Declare it on every live track.
40
+
33
41
  To hear it, put the track in the queue (or serve it from a
34
42
  [browse tree](/guide/basic-usage)) after
35
43
  [`setupPlayer()`](/guide/basic-usage#set-up-the-player) has run:
@@ -53,36 +61,54 @@ A connection drop mid-stream surfaces one of two ways, with different owners:
53
61
 
54
62
  - **A stall** (how most iOS drops surface) — the player holds `'buffering'`
55
63
  with play intent, and re-establishes the stream by itself when
56
- connectivity returns. No wiring needed — see
57
- [Network → You may not need this](/guide/network#you-may-not-need-this).
64
+ connectivity returns (see
65
+ [Network → You may not need this](/guide/network#you-may-not-need-this)).
58
66
  While stalled offline, the [now-playing formatter](/guide/now-playing#the-formatter-derived-continuous)
59
67
  receives `stalled: 'offline'` (vs `'buffering'` when online) so the lock
60
68
  screen can say why.
61
69
  - **A playback error** (how most Android drops surface) — recovery belongs
62
70
  to [automatic retry](/guide/errors#automatic-retry)
63
- (`setupPlayer({ retry })`, off by default). Two duration budgets, chosen
64
- by whether this load has ever produced audio: **12 s** for a stream that
65
- never played (counting only online time — a station tapped in a tunnel
66
- still gets its chance when the network returns), **2 min** once playback
67
- proved the stream works. The 2 min budget is a wall clock that _includes_
68
- offline time, deliberately — see
69
- [the budgets](/guide/errors#two-duration-budgets). Budgets exhausted →
70
- state `'error'`, where [`retry()`](/guide/errors#manual-retry) and your
71
- error UI take over.
71
+ (`setupPlayer({ retry })`, off by default). Which of
72
+ [two duration budgets](/guide/errors#two-duration-budgets) applies depends
73
+ on whether this load has ever produced audio:
74
+ - **First connect**, for a stream that never played. Only online time
75
+ counts, so a station tapped in a tunnel still gets its chance when the
76
+ network returns.
77
+ - **Recovery**, once playback proved the stream works. This one is
78
+ wall-clock time and includes offline time, so playback never resumes by
79
+ surprise after a long outage.
80
+
81
+ Once the budget runs out, the state is `'error'`, and
82
+ [`retry()`](/guide/errors#manual-retry) and your error UI take over.
72
83
 
73
84
  Android's reconnect-on-restore only arms through the retry machinery, so
74
85
  the platform whose drops become errors is also the one that won't heal
75
- without it. **If surviving tunnels matters to you, enable `retry`.** (The
76
- web implementation has no automatic retry at all, and no ICY metadata —
77
- every web error is terminal.)
86
+ without it. **If surviving tunnels matters to you, enable `retry`.**
78
87
 
79
- ## Fresh URLs on every reconnect
88
+ The web implementation has no automatic retry at all, and no timed metadata,
89
+ neither ICY nor HLS ID3. Every web error is terminal.
90
+
91
+ ## Fresh URLs on reconnect
80
92
 
81
93
  If your stream URLs are signed or short-lived, build them in
82
94
  [`media.resolve`](/guide/browser#media-and-artwork) — the per-track layer of
83
- the stream request. Every recovery path re-runs it rather than replaying the
84
- cached URL: automatic retry, network restore, play-from-`'error'`. A URL
85
- that expired during the outage is re-signed instead of re-failing.
95
+ the stream request. When a reconnect re-runs it depends on the platform:
96
+
97
+ - **iOS** re-runs it on every reload: automatic retry, network restore,
98
+ play-from-`'error'` and a live-edge reconnect. A URL that expired during
99
+ the outage is re-signed instead of re-failing.
100
+ - **Android** reuses the URL it resolved, and re-runs `media.resolve` only
101
+ after an attempt to open that URL has failed. A URL that expired
102
+ mid-stream therefore costs one failed attempt.
103
+
104
+ With `retry` on, a status that retrying can't fix (a 401 or 403, say; see
105
+ [which failures qualify](/guide/errors#automatic-retry)) puts playback in
106
+ `'error'`, and the next [`retry()`](/guide/errors#manual-retry) or play
107
+ command re-resolves. With `retry` off, ExoPlayer's own few retries cover any
108
+ status, and the first of them re-resolves.
109
+
110
+ - **Web** re-runs it on every reload: play-from-`'error'` or after a stop,
111
+ `retry()` and a live-edge reconnect. Web has no automatic retry.
86
112
 
87
113
  ```ts
88
114
  import { configureBrowser } from 'react-native-audio-browser'
@@ -107,19 +133,24 @@ A relative `path` is joined to your configured `baseUrl` — see
107
133
 
108
134
  [`seekToLiveEdge()`](/api/features/playback/#seektoliveedge) jumps a live
109
135
  track back to the newest available audio — a no-op unless the current track
110
- declares `live: true`. On a stream with a seekable live window (HLS with a
111
- sliding window) it seeks to the window's edge; on a non-seekable one
112
- (typical ICY radio) it reconnects instead — a fresh connection _is_ the
113
- live edge, and an expired URL re-resolves through `media.resolve`. General
114
- seeking is in [Playback](/guide/playback).
136
+ declares `live: true`.
137
+
138
+ On a stream with a seekable live window (HLS with a sliding window) it seeks
139
+ to the window's edge; on a non-seekable one (typical ICY radio) it
140
+ reconnects instead — a fresh connection _is_ the live edge.
141
+
142
+ On iOS and web the reconnect re-runs `media.resolve`. On Android it reuses the
143
+ resolved URL, so an expired one re-resolves only after that first attempt
144
+ fails (see [Fresh URLs on reconnect](#fresh-urls-on-reconnect)).
145
+ General seeking is in [Playback](/guide/playback).
115
146
 
116
147
  ## API summary
117
148
 
118
- | API | Purpose |
119
- | ------------------------------------------------------------ | ----------------------------------------------------------------- |
120
- | [`Track.live`](/api/types/browser-nodes/#track) | Declare a live track: iOS live indicator, arms the live edge. |
121
- | [`seekToLiveEdge()`](/api/features/playback/#seektoliveedge) | Jump to the newest audio (no-op for non-live tracks). |
122
- | [`setupPlayer({ retry })`](/guide/errors#automatic-retry) | Automatic retry: 12 s first-connect / 2 min recovery budgets. |
123
- | [`retry()`](/guide/errors#manual-retry) | Restart from `'error'` with fresh budgets. |
124
- | [`media.resolve`](/guide/browser#media-and-artwork) | Build each (re)load's stream request — signed / short-lived URLs. |
125
- | [`useOnline()`](/guide/network) | Connectivity for your own UI; playback reacts on its own. |
149
+ | API | Purpose |
150
+ | ------------------------------------------------------------ | ------------------------------------------------------------- |
151
+ | [`Track.live`](/api/types/browser-nodes/#live) | Declare a live track: iOS live indicator, arms the live edge. |
152
+ | [`seekToLiveEdge()`](/api/features/playback/#seektoliveedge) | Jump to the newest audio (no-op for non-live tracks). |
153
+ | [`setupPlayer({ retry })`](/guide/errors#automatic-retry) | Automatic retry with first-connect and recovery budgets. |
154
+ | [`retry()`](/guide/errors#manual-retry) | Restart from `'error'` with fresh budgets. |
155
+ | [`media.resolve`](/guide/browser#media-and-artwork) | Build the stream request — signed / short-lived URLs. |
156
+ | [`useOnline()`](/guide/network) | Connectivity for your own UI; playback reacts on its own. |