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,10 +1,10 @@
1
1
  ---
2
- description: 'Track the device''s validated internet connectivity with useOnline, getOnline, and onOnlineChanged, and what "online" means on each platform.'
2
+ description: 'Track the device''s internet connectivity with useOnline, getOnline, and onOnlineChanged, and what "online" means on each platform.'
3
3
  ---
4
4
 
5
5
  # Network
6
6
 
7
- The library tracks the device's internet connectivity with a native monitor and
7
+ The library tracks the device's internet connectivity with a platform monitor and
8
8
  exposes it three ways:
9
9
 
10
10
  - [`useOnline()`](/api/features/network/#useonline) — a reactive hook for your UI.
@@ -12,15 +12,26 @@ exposes it three ways:
12
12
  - [`onOnlineChanged`](/api/features/network/#ononlinechanged) — subscribe to
13
13
  changes outside React.
14
14
 
15
- All three report the same boolean: `true` when the device has a working internet
16
- connection. **"Online" means _validated_ internet, not just "connected to a
17
- network".** Android is strict here — it requires the OS to confirm the network
18
- actually reaches the internet, so Wi-Fi with no real connectivity reads as
19
- `false`. iOS derives the signal from the system path monitor (`NWPathMonitor`),
20
- which is slightly more permissive about such captive networks.
15
+ All three report the same boolean, but each platform decides it differently:
21
16
 
22
- The UI snippet imports `Text` from `react-native`; everything else is from
23
- `react-native-audio-browser`.
17
+ - **Android** asks the OS whether the default network is _validated_: it must
18
+ actually reach the internet, so Wi-Fi with no internet behind it reads
19
+ `false`.
20
+ - **iOS** reads the system path monitor (`NWPathMonitor`), which reports
21
+ whether a usable network path exists. It does not check that the internet is
22
+ reachable, so a captive or dead Wi-Fi can read `true`.
23
+ - **Web** reads `navigator.onLine` and the window's `online` and `offline`
24
+ events, which only say whether a network interface is up.
25
+
26
+ ::: warning Android: only after setupPlayer()
27
+ On Android the connectivity monitor belongs to the player, so it runs only once
28
+ `setupPlayer()` has connected the player service.
29
+
30
+ Before that, and while the service restarts, `getOnline()` and `useOnline()`
31
+ read `true` even when the device is offline, and `onOnlineChanged` doesn't
32
+ fire. Once the service connects, `onOnlineChanged` fires with the current
33
+ state. iOS and web report the real state from the start.
34
+ :::
24
35
 
25
36
  ## In your UI
26
37
 
@@ -63,13 +74,18 @@ these up for playback:
63
74
  - When the connection drops mid-stream, the now-playing formatter receives
64
75
  `stalled: 'offline'` (vs `'buffering'` when online) — see
65
76
  [Now Playing → the formatter](/guide/now-playing#the-formatter-derived-continuous).
66
- - When the connection returns while the stream sits **stalled** (state
67
- `'buffering'` with play intent), the player re-establishes it automatically —
68
- you don't need to listen for reconnect and re-`play()`. If the drop instead
69
- surfaced as a playback **error**, recovery belongs to
70
- [automatic retry](/guide/errors#automatic-retry) (`setupPlayer({ retry })`,
71
- off by default); once retry gives up — or without it — the player stays in
72
- `'error'` until the listener (or your code) calls `retry()` / `play()`.
77
+ - On iOS, when the connection returns while the stream sits **stalled** (state
78
+ `'buffering'` with play intent), the player re-establishes it automatically:
79
+ you don't need to listen for reconnect and re-`play()`.
80
+
81
+ On Android, most drops surface as a playback **error** instead, and the
82
+ reconnect when connectivity returns only runs with
83
+ [automatic retry](/guide/errors#automatic-retry)
84
+ (`setupPlayer({ retry })`, off by default) enabled. See
85
+ [Live streams → Dropouts](/guide/live-streams#dropouts-stalls-and-retry).
86
+
87
+ Once retry gives up, or without it, the player stays in `'error'` until the
88
+ listener (or your code) calls `retry()` or `play()`.
73
89
 
74
90
  Reach for `useOnline` / `onOnlineChanged` for **your own** UI and data — an
75
91
  offline banner, disabling a control, refetching a list on reconnect.
@@ -79,8 +95,8 @@ offline banner, disabling a control, refetching a list on reconnect.
79
95
  | API | Purpose |
80
96
  | ----------------- | --------------------------------------------------------------------- |
81
97
  | `useOnline()` | Reactive `boolean`; re-renders on connectivity change. |
82
- | `getOnline()` | One-off snapshot `boolean`. |
98
+ | `getOnline()` | One-off snapshot `boolean` (`true` on Android before setup). |
83
99
  | `onOnlineChanged` | Subscribe outside React; `addListener(cb)` returns an unsubscribe fn. |
84
100
 
85
- `true` = validated internet connection; `false` = offline (including a network
86
- with no real internet on Android).
101
+ `true` = online by the platform's definition above; `false` = offline
102
+ (including a network with no internet behind it on Android).
@@ -4,7 +4,9 @@ description: 'What the system surfaces show: which metadata field lands where, t
4
4
 
5
5
  # Now Playing
6
6
 
7
- The now-playing surface is everything that displays the current track on the _system's_ surfaces: the iOS lock screen and Control Center, the Android notification, CarPlay and Android Auto's Now Playing screens, and Bluetooth head units. The library publishes one metadata dictionary and the _operating system_ renders it — each surface picks different fields, composes them differently, and ignores the rest. The same published metadata is also readable inside your own app — see [Reading now-playing in your own UI](#reading-now-playing-in-your-own-ui).
7
+ The now-playing surface is everything that displays the current track on the _system's_ surfaces: the iOS lock screen and Control Center, the Android notification, CarPlay and Android Auto's Now Playing screens, and Bluetooth head units.
8
+
9
+ The library publishes one metadata dictionary and the _operating system_ renders it. Each surface picks different fields, composes them differently, and ignores the rest. Your own app can read the same metadata: see [Reading now-playing in your own UI](#reading-now-playing-in-your-own-ui).
8
10
 
9
11
  This guide covers: **which fields land where** (the static matrix), **the four layers that decide what those fields contain at any moment** (the dynamic model), and **reading the result back** in your own UI.
10
12
 
@@ -22,32 +24,40 @@ Apple and Google document very little of this; the table below reflects observed
22
24
 
23
25
  The time scrubber (elapsed, duration, playback rate) is not driven by track fields at all — every surface derives it from the player itself. `Track.duration` is informational metadata for your app (echoed back through now-playing events); it does not affect the scrubber.
24
26
 
25
- `artwork` is the URL you _set_ on a track. (`Track.artworkSource` is a separate, output-only `ImageSource` the library populates for you to render in your own `<Image>` — it isn't published to surfaces.) Note that artwork isn't one of the overridable text fields: the formatter, override, and flash layers below carry only `title` / `artist` / `album`. Now-playing artwork comes from the track's `artwork`, optionally resolved through the [`nowPlayingArtwork`](#now-playing-artwork) config.
27
+ `artwork` is the URL you _set_ on a track. On iOS and Android, surfaces show the resolved image, not the raw URL. On web, the Media Session gets the raw URL. The layers below cannot change it: see [Now-playing artwork](#now-playing-artwork).
26
28
 
27
29
  ## The four metadata layers
28
30
 
29
- What actually renders is decided by a fixed priority order. Each layer only overrides the fields it sets — anything it leaves `undefined` falls through to the layer below:
31
+ What actually renders is decided by a fixed priority order. Each layer only overrides the fields it sets. A field it leaves `undefined` falls through to the layer below, except under a flash (see [the flash](#the-flash-transient-top-priority)):
30
32
 
31
- | Priority | Layer | API | Lifetime |
32
- | ------------ | ---------------- | -------------------------------------- | ------------------------------------ |
33
- | 1 (highest) | **Flash** | `flashNowPlaying(update, durationMs)` | `durationMs`, on a native timer |
34
- | 2 | **Formatter** | `setupPlayer({ nowPlaying })` | as long as it's configured |
35
- | 3 | **Override** | `updateNowPlaying(update)` | until cleared or the track changes |
36
- | 4 (baseline) | **Track fields** | `Track.title` / `artist` / `album` / … | the track's time as the active track |
33
+ | Priority | Layer | API | Lifetime |
34
+ | ------------ | ---------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
35
+ | 1 (highest) | **Flash** | `flashNowPlaying(update, durationMs)` | `durationMs`, on a native timer (web: see [the flash](#the-flash-transient-top-priority)) |
36
+ | 2 | **Formatter** | `setupPlayer({ nowPlaying })` | as long as it's configured |
37
+ | 3 | **Override** | `updateNowPlaying(update)` | until cleared or the track changes |
38
+ | 4 (baseline) | **Track fields** | `Track.title` / `artist` / `album` / … | the track's time as the active track |
37
39
 
38
- ### Track fields — the baseline
40
+ ### Track fields: the baseline
39
41
 
40
42
  With nothing else configured, the active track's own fields are published as-is. For on-demand content this is usually all you need.
41
43
 
42
- ### The formatter — derived, continuous
44
+ ### The formatter: derived, continuous
45
+
46
+ The [`nowPlaying`](/api/features/player/#formatnowplayingcallback) formatter hands you the now-playing text lines outright. The library calls it again whenever the lines could change:
47
+
48
+ - on a track change
49
+ - on every timed-metadata update
50
+ - on every playback transition: play / pause, a stall starting or recovering, an error
51
+ - on connectivity changes
43
52
 
44
- The [`nowPlaying`](/api/features/player/#formatnowplayingcallback) formatter hands you the now-playing text lines outright, re-invoked whenever they could change: on track change, on every timed-metadata update, on every playback transition (play / pause, a stall starting or recovering, an error), and on connectivity changes. It's the right layer for anything _derived from playback state_ — the live song from ICY/ID3 metadata, a "Reconnecting…" line during a stall, an error message:
53
+ It's the right layer for anything _derived from playback state_: the live song from ICY/ID3 metadata, a "Reconnecting…" line during a stall, an error message:
45
54
 
46
55
  ```ts
47
56
  setupPlayer({
48
57
  nowPlaying: ({ timedMetadata, playWhenReady, stalled, error }) => {
49
- // `yourErrorLine` is your own kind→copy mapping — branch on `error.kind`,
50
- // never `error.message`, which is developer English and never localized.
58
+ // `yourErrorLine` is your own kind→copy mapping. Branch on
59
+ // `error.kind`, never `error.message`, which is developer English
60
+ // and never localized.
51
61
  // This line is read by listeners, on the lock screen and in the car.
52
62
  // See [Playback errors](/guide/errors#playback-errors).
53
63
  if (error) return { artist: yourErrorLine(error.kind) }
@@ -66,27 +76,33 @@ setupPlayer({
66
76
 
67
77
  The callback receives a single [`FormatNowPlayingParams`](/api/features/player/#formatnowplayingparams) object:
68
78
 
69
- | Field | Type | Meaning |
70
- | --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
71
- | `track` | `Track` | The currently playing track. |
72
- | `timedMetadata` | `TimedMetadata?` | The ICY / ID3 "now playing song", if any. |
73
- | `playWhenReady` | `boolean` | Play/pause intent — stays `true` through buffers, so the song line won't flicker. |
74
- | `stalled` | `StallReason?` | Truthy only during a mid-stream stall: `'buffering'` (rebuffering while online) or `'offline'` (no connectivity). Use `if (stalled)`, compare `=== 'offline'` for the reason. |
75
- | `error` | `PlaybackError?` | The current playback error, if playback failed. Switch on `error.kind` to pick your own localized line — see [Playback errors](/guide/errors#playback-errors). While [automatic retry](/guide/errors#automatic-retry) is still working, this carries the advisory error (`error.retrying === true`) — the formatter re-runs when it arrives, changes, and clears, so you can show provisional copy ("… — retrying") that hardens into the final line when the player gives up. |
79
+ | Field | Type | Meaning |
80
+ | --------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
81
+ | `track` | `Track` | The currently playing track. |
82
+ | `timedMetadata` | `TimedMetadata?` | The ICY / ID3 "now playing song", if any. On iOS, also a file's own tags when the file has no chapters. |
83
+ | `playWhenReady` | `boolean` | Play/pause intent — stays `true` through buffers, so the song line won't flicker. |
84
+ | `stalled` | `StallReason?` | Truthy only during a mid-stream stall: `'buffering'` (rebuffering while online) or `'offline'` (no connectivity). Use `if (stalled)`, compare `=== 'offline'` for the reason. |
85
+ | `error` | `PlaybackError?` | The current playback error, if playback failed. Switch on `error.kind` to pick your own localized line: see [Playback errors](/guide/errors#playback-errors). |
76
86
 
77
- It returns a [`NowPlayingUpdate`](/api/features/metadata/#nowplayingupdate) (`{ title?, artist?, album? }`) or `undefined`. The callback is synchronous and should stay cheap — it's a pure formatting function, no I/O. Each returned field falls back **independently** to the track's value when omitted; returning `undefined` (or `{}`) uses the track default entirely. Identical results across a rapid burst of transitions are de-duplicated natively, so they won't flicker the surface.
87
+ While [automatic retry](/guide/errors#automatic-retry) is still working, `error` carries the advisory error (`error.retrying === true`). The formatter runs again when that error arrives, changes and clears. So you can show provisional copy ("Retrying…") that becomes the final line when the player gives up.
88
+
89
+ It returns a [`NowPlayingUpdate`](/api/features/metadata/#nowplayingupdate) (`{ title?, artist?, album? }`) or `undefined`. The callback is synchronous and should stay cheap: a pure formatting function, no I/O.
90
+
91
+ Each returned field falls back **independently** to the track's value when omitted. Returning `undefined` (or `{}`) uses the track default entirely. Identical results across a rapid burst of transitions are de-duplicated natively, so they won't flicker the surface.
78
92
 
79
93
  Timed metadata is never auto-applied: the library surfaces ICY (Shoutcast/Icecast) and in-band ID3 (HLS) frames to your code, and the formatter is where you decide what reaches the now-playing line. (To consume those frames outside the formatter, subscribe to [`onTimedMetadata`](/api/features/metadata/#ontimedmetadata).)
80
94
 
81
- ### The override — imperative, sticky
95
+ ### The override: imperative, sticky
82
96
 
83
97
  [`updateNowPlaying({ artist: '…' })`](/api/features/nowPlaying/#updatenowplaying) pins fields until you pass `null` or the track changes. It's the layer to reach for when you _don't_ configure a formatter.
84
98
 
85
- **If a formatter is configured, it outranks the override** — the formatter's result is applied on top, falling back per-field to `override ?? track`. Mixing the two is rarely what you want: with a formatter in place, feed it state instead of calling `updateNowPlaying` around it. (The override predates the formatter; the formatter is the newer, preferred layer for anything derived from playback state.)
99
+ **If a formatter is configured, it outranks the override.** The formatter's result is applied on top, falling back per-field to `override ?? track`. With a formatter in place, feed it state instead of calling `updateNowPlaying` around it. Prefer the formatter for anything derived from playback state.
100
+
101
+ ### The flash: transient, top priority
86
102
 
87
- ### The flash — transient, top priority
103
+ [`flashNowPlaying(update, durationMs)`](/api/features/nowPlaying/#flashnowplaying) is the toast of the now-playing world: it briefly replaces the fields it sets, then reverts to whatever the lower layers say.
88
104
 
89
- [`flashNowPlaying(update, durationMs)`](/api/features/nowPlaying/#flashnowplaying) is the toast of the now-playing world: it briefly replaces the fields it sets, then reverts to whatever the lower layers say. External surfaces have no notification primitive, so a transient metadata swap is the only way to give feedback there — the canonical use is answering a refused remote command:
105
+ External surfaces have no notification primitive, so a transient metadata swap is the only way to give feedback there. The canonical use is answering a refused remote command:
90
106
 
91
107
  ```ts
92
108
  // A radio product with an hourly skip allowance:
@@ -101,12 +117,20 @@ handleRemoteNext(() => {
101
117
 
102
118
  Three properties make it a dedicated layer rather than sugar over `updateNowPlaying`:
103
119
 
104
- - **It outranks the formatter.** While a flash is active the formatter pass is skipped entirely, so a live station's next metadata tick can't overwrite the message mid-window.
120
+ - **It outranks the formatter.** While a flash is active the formatter pass is skipped, so a live station's next metadata tick can't overwrite the message mid-window. Fields the flash leaves unset come from the override or the track, not from the formatter. Set every line you want to keep.
105
121
  - **The revert runs on a native timer.** A JS `setTimeout` pauses with a backgrounded host on Android — and remote commands from the lock screen arrive exactly when the host is backgrounded. The native timer fires regardless.
106
122
  - **A track change clears it early.** A flash is feedback about a moment; it never carries over to a new track.
107
123
 
108
124
  Repeated calls restart the window. [`clearNowPlayingFlash()`](/api/features/nowPlaying/#clearnowplayingflash) cancels one imperatively — for example when the condition the flash complained about resolves mid-window.
109
125
 
126
+ ::: warning Web and `nowPlaying: false`
127
+ The three properties above hold on iOS and Android. On web, a flash is an `updateNowPlaying` override with a JS timer. It replaces any override you set, and the revert (or `clearNowPlayingFlash()`) clears the override instead of restoring it.
128
+
129
+ A track change doesn't cancel the timer, so a pending revert also clears an override you set for the next track.
130
+
131
+ With `nowPlaying: false`, Android ignores the flash, while iOS still shows it.
132
+ :::
133
+
110
134
  ## Reading now-playing in your own UI
111
135
 
112
136
  The metadata you publish is also what your own app should render — a mini-player, a full-screen "now playing" view — so the in-app UI matches the lock screen exactly, formatter and all. Use the [`useNowPlaying`](/api/features/nowPlaying/#usenowplaying) hook:
@@ -126,15 +150,19 @@ function MiniPlayer() {
126
150
  }
127
151
  ```
128
152
 
129
- `useNowPlaying` returns the resolved [`NowPlayingMetadata`](/api/features/metadata/#nowplayingmetadata) — the same dictionary the system surfaces see, _after_ the four layers are applied — or `undefined` when nothing is playing. It carries `title` / `artist` / `album` / `artwork` (and `elapsedTime`). For the live scrubber position, pair it with [`useProgress`](/guide/playback#progress).
153
+ `useNowPlaying` returns the resolved [`NowPlayingMetadata`](/api/features/metadata/#nowplayingmetadata): the same dictionary the system surfaces see, _after_ the four layers are applied. The exception is `nowPlaying: false` on iOS and Android: the hook still reports an `updateNowPlaying` override the surface ignores (on Android, a flash too). It returns `undefined` when there is no active track. It carries `title` / `artist` / `album` / `artwork`.
130
154
 
131
- Outside React, [`getNowPlaying()`](/api/features/nowPlaying/#getnowplaying) reads a snapshot and [`onNowPlayingChanged`](/api/features/nowPlaying/#onnowplayingchanged) subscribes to changes (it fires when the override changes or the track changes).
155
+ It also carries `elapsedTime`, but only on iOS, and it is not a live position. For the scrubber position, use [`useProgress`](/guide/playback#progress).
132
156
 
133
- To render artwork, don't use this `artwork` field directly — it's a raw URL string. Use the active track's ready-to-use `artworkSource` instead (`<Image source={track.artworkSource} />`) — see [Track](/guide/track).
157
+ Outside React, [`getNowPlaying()`](/api/features/nowPlaying/#getnowplaying) reads a snapshot. [`onNowPlayingChanged`](/api/features/nowPlaying/#onnowplayingchanged) fires whenever the published lines change: a new track, a formatter result, an override, or a flash starting or ending.
158
+
159
+ To render artwork, don't use this `artwork` field: it is a plain URL string, and on Android and web it is the track's `artwork` before your artwork config resolves it. Use the active track's `artworkSource` (`<Image source={track.artworkSource} />`). See [Track](/guide/track).
134
160
 
135
161
  ## Gotchas worth knowing
136
162
 
137
- **CarPlay's tappable line renders from `album`.** When a track has an `albumPath` (or `resolveAlbumPath` returns a path), the _album line_ becomes tappable — rendered as a third metadata line with a chevron, navigating the browse stack. A track without an `album` has no such line, so there is nothing to render or tap even though a destination exists. See the [CarPlay guide](/guide/carplay#album-line-navigation).
163
+ **CarPlay's tappable line renders from `album`.** When a track has an `albumPath` (or `resolveAlbumPath` returns a path), the _album line_ becomes tappable. It renders as a third metadata line with a chevron and navigates the browse stack.
164
+
165
+ A track without an `album` has no such line, so there is nothing to tap even though a destination exists. See the [CarPlay guide](/guide/carplay#album-line-navigation).
138
166
 
139
167
  **The iOS lock screen never shows `album`.** Its secondary line comes from `artist` alone. If you move information from `artist` to `album` (for example to feed the CarPlay button line), it disappears from the lock screen.
140
168
 
@@ -142,15 +170,15 @@ To render artwork, don't use this `artwork` field directly — it's a raw URL st
142
170
 
143
171
  **One metadata dictionary feeds every surface.** There is no per-surface metadata: whatever you publish appears (or doesn't) everywhere simultaneously, per the table above. You cannot hide a field from one surface without hiding it from all of them.
144
172
 
145
- **A formatter quietly disables `updateNowPlaying` for the fields it returns.** See [the override](#the-override--imperative-sticky) — the formatter's result wins per-field. If a line you set imperatively keeps reverting, a formatter is overwriting it; either move that logic into the formatter or use `flashNowPlaying` if it was meant to be transient.
173
+ **A formatter quietly disables `updateNowPlaying` for the fields it returns.** See [the override](#the-override-imperative-sticky): the formatter's result wins per-field. If a line you set imperatively keeps reverting, a formatter is overwriting it; either move that logic into the formatter or use `flashNowPlaying` if it was meant to be transient.
146
174
 
147
175
  **Browse lists are separate.** `subtitle` drives browse-list rows (CarPlay list detail text, Android Auto list subtitle) and is never shown on now-playing surfaces; `artist` drives now-playing and is never shown in browse lists. Neither falls back to the other.
148
176
 
149
177
  ## Now-playing artwork
150
178
 
151
- Artwork is the one surface field the text layers (formatter / override / flash) can't touch — they carry only `title` / `artist` / `album`. The now-playing image comes from the active track's `artwork`.
179
+ Artwork is the one surface field the text layers (formatter / override / flash) can't touch: they carry only `title` / `artist` / `album`. On iOS and Android, surfaces show the active track's resolved artwork, `artworkSource`. That is the track's `artwork` after your [artwork configuration](/guide/browser#media-and-artwork) transforms it. On web, the Media Session gets the track's raw `artwork` URL (the `dark` one of a pair), which neither artwork config touches.
152
180
 
153
- By default that's the same image as the track's browse-list thumbnail. To resolve it differently — a larger, lock-screen-quality image without bloating list thumbnails — set the `nowPlayingArtwork` config kind, which builds the now-playing image from its own request (e.g. `{ path: '/artwork/{id}' }`):
181
+ By default that's the same image as the track's browse-list thumbnail. To resolve it differently, set the `nowPlayingArtwork` config kind. It builds the now-playing image from its own request (e.g. `{ path: '/artwork/{id}' }`), for example a larger, lock-screen-quality image that does not bloat list thumbnails:
154
182
 
155
183
  ```ts
156
184
  configureBrowser({
@@ -163,13 +191,13 @@ See [`BrowserConfiguration.nowPlayingArtwork`](/api/types/browser/#browserconfig
163
191
 
164
192
  ## API summary
165
193
 
166
- | API | Purpose |
167
- | ----------------------------------------- | ------------------------------------------------------------ |
168
- | `setupPlayer({ nowPlaying })` | Configure the formatter — derived lines from playback state. |
169
- | `updateNowPlaying(update \| null)` | Imperatively override fields; `null` clears. |
170
- | `flashNowPlaying(update, durationMs)` | Transient, top-priority swap (refused-command feedback). |
171
- | `clearNowPlayingFlash()` | Cancel an active flash early. |
172
- | `useNowPlaying()` / `getNowPlaying()` | Read the resolved metadata in your own UI. |
173
- | `onNowPlayingChanged` | Subscribe to metadata changes outside React. |
174
- | `onTimedMetadata` | Subscribe to ICY / ID3 stream metadata directly. |
175
- | `configureBrowser({ nowPlayingArtwork })` | Resolve now-playing artwork from its own request. |
194
+ | API | Purpose |
195
+ | ----------------------------------------- | ----------------------------------------------------------- |
196
+ | `setupPlayer({ nowPlaying })` | Configure the formatter: derived lines from playback state. |
197
+ | `updateNowPlaying(update \| null)` | Imperatively override fields; `null` clears. |
198
+ | `flashNowPlaying(update, durationMs)` | Transient, top-priority swap (refused-command feedback). |
199
+ | `clearNowPlayingFlash()` | Cancel an active flash early. |
200
+ | `useNowPlaying()` / `getNowPlaying()` | Read the resolved metadata in your own UI. |
201
+ | `onNowPlayingChanged` | Subscribe to metadata changes outside React. |
202
+ | `onTimedMetadata` | Subscribe to ICY / ID3 stream metadata directly. |
203
+ | `configureBrowser({ nowPlayingArtwork })` | Resolve now-playing artwork from its own request. |
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: 'Control the active track — play, pause, stop, seek, playback state, progress, rate, and volume — the toolkit for building your own player UI.'
2
+ description: 'Control the active track — play, pause, stop, seek, playback state, progress, rate, and volume — and how playback handles the background, interruptions, and audio focus.'
3
3
  ---
4
4
 
5
5
  # Playback
@@ -7,14 +7,25 @@ description: 'Control the active track — play, pause, stop, seek, playback sta
7
7
  This guide covers **controlling the active track** — transport (play / pause /
8
8
  stop), seeking, playback state, progress, rate, and volume. It's the toolkit for
9
9
  building your own player UI.
10
+ [A later section](#background-audio-interruptions-and-audio-focus) covers what
11
+ the library handles for you: background audio, interruptions, and audio focus.
10
12
 
11
13
  Playback acts on whatever the **active track** is. _Which_ track that is — and
12
- moving between tracks with next/previous — belongs to the [queue](/guide/basic-usage#the-queue);
14
+ moving between tracks with next/previous — belongs to the
15
+ [queue](/guide/queue#moving-between-tracks);
13
16
  this page is about playing the one that's already active. The system surfaces
14
17
  (lock screen, notification, car) are covered in [Now Playing](/guide/now-playing).
15
18
 
16
- > All functions here are synchronous and safe to call before a track is loaded —
17
- > they're no-ops or update intent rather than throwing.
19
+ > All functions here are synchronous. Called with no track loaded, they don't
20
+ > throw: `pause`, `stop` and the seek calls do nothing, and `setPlayWhenReady`,
21
+ > `setRate` and `setVolume` keep their value for the next track. `play()` and
22
+ > `togglePlayback()` raise the play intent as `setPlayWhenReady(true)` does, so
23
+ > the next track loaded starts playing (on web, Chrome keeps that intent and
24
+ > Firefox drops it). On iOS and Android, play, pause, stop, seek, rate and
25
+ > volume calls made before `setupPlayer` has resolved are dropped; on web they
26
+ > throw `SetupNotCalledError`. On every platform `setPlayWhenReady` is kept and
27
+ > applied at setup. Two have argument rules: `setRate` and
28
+ > `trackPlaybackTime`, both covered below.
18
29
 
19
30
  The UI snippets below import `useState` from `react`, `Text` / `Button` /
20
31
  `Switch` from `react-native`, and `Slider` from
@@ -29,12 +40,15 @@ import { play, pause, togglePlayback, stop } from 'react-native-audio-browser'
29
40
  play() // play or resume the active track
30
41
  pause() // pause, keeping position
31
42
  togglePlayback() // flip between play and pause
32
- stop() // stop and reset position to the start
43
+ stop() // stop; the track stays loaded
33
44
  ```
34
45
 
35
- `stop` keeps the track loaded — `play()` afterwards starts it again from the
36
- beginning. (For live streams there's no position to reset, so it just stops.)
37
- That's different from `reset`, which stops playback **and clears the queue**:
46
+ `stop` keeps the track loaded, and what `play()` does afterwards depends on the
47
+ platform. On iOS, `stop` rewinds a non-live track to the start, so `play()`
48
+ plays it from the beginning. On Android and web the position is kept, so
49
+ `play()` resumes where it stopped.
50
+
51
+ `stop` is not the same as `reset`, which stops playback **and clears the queue**:
38
52
 
39
53
  ```ts
40
54
  import { reset } from 'react-native-audio-browser'
@@ -42,11 +56,11 @@ import { reset } from 'react-native-audio-browser'
42
56
  reset() // tear down: stop + empty the queue
43
57
  ```
44
58
 
45
- | | Position | Track stays loaded | Queue |
46
- | --------- | -------------- | ------------------ | ------- |
47
- | `pause()` | kept | yes | kept |
48
- | `stop()` | reset to start | yes | kept |
49
- | `reset()` | — | no | cleared |
59
+ | | Position | Track stays loaded | Queue |
60
+ | --------- | ---------------------------------------------- | ------------------ | ------- |
61
+ | `pause()` | kept | yes | kept |
62
+ | `stop()` | reset to start on iOS; kept on Android and web | yes | kept |
63
+ | `reset()` | — | no | cleared |
50
64
 
51
65
  ## Seeking
52
66
 
@@ -70,7 +84,7 @@ seekToLiveEdge()
70
84
  ```
71
85
 
72
86
  Moving between tracks (next / previous / skip) is part of the
73
- [queue](/guide/basic-usage#the-queue), not seeking.
87
+ [queue](/guide/queue#moving-between-tracks), not seeking.
74
88
 
75
89
  ## Playback state
76
90
 
@@ -101,8 +115,13 @@ function PlayerStatus() {
101
115
  }
102
116
  ```
103
117
 
104
- `retry()` only does something while the state is `'error'`; it re-attempts the
105
- current item. See [Errors](/guide/errors) for the error shape and handling.
118
+ `retry()` is meant for the `'error'` state, where it re-attempts the current
119
+ item. It isn't gated on that state.
120
+
121
+ On iOS it reloads the current item in any state, even while playing. On Android
122
+ and web it reloads whenever the player is stopped or failed, without raising the
123
+ play intent, so after `stop()` it loads the track but doesn't play it. See [Errors](/guide/errors#manual-retry) for the
124
+ error shape and handling.
106
125
 
107
126
  ### Just playing or buffering?
108
127
 
@@ -128,13 +147,18 @@ function PlayPauseButton() {
128
147
  ### Play-when-ready
129
148
 
130
149
  `playWhenReady` is the **intent** to play, separate from whether audio is
131
- actually coming out yet (it may still be loading or buffering). Setting it is
132
- equivalent to calling `play()` / `pause()`:
150
+ actually coming out yet (it may still be loading or buffering). Setting it does
151
+ what `play()` / `pause()` do, with two exceptions. Before `setupPlayer`
152
+ resolves, `setPlayWhenReady` is kept and applied at setup, while `play()` is
153
+ dropped on iOS and Android and throws on web.
154
+
155
+ On Android, `setPlayWhenReady(true)` doesn't restart a stopped or failed player;
156
+ `play()` or `retry()` does:
133
157
 
134
158
  ```tsx
135
159
  import { setPlayWhenReady, usePlayWhenReady } from 'react-native-audio-browser'
136
160
 
137
- setPlayWhenReady(true) // same as play()
161
+ setPlayWhenReady(true) // raise the intent to play
138
162
 
139
163
  function PlayToggle() {
140
164
  const wantsToPlay = usePlayWhenReady()
@@ -147,9 +171,13 @@ function PlayToggle() {
147
171
  }
148
172
  ```
149
173
 
150
- Use `usePlayWhenReady` when your control should reflect the user's _intent_
151
- immediately (the toggle flips the instant they tap, even while buffering); use
152
- `usePlayingState` when it should reflect whether sound is actually playing.
174
+ `usePlayWhenReady` is the raw intent: it stays `true` after an error.
175
+ `usePlayingState().playing` is that intent only while a
176
+ track can play, so it goes `false` in the `'error'`, `'ended'`, `'none'` and
177
+ `'stopped'` states.
178
+
179
+ Both flip the instant the user taps. Neither says whether
180
+ sound is coming out yet; `buffering` does.
153
181
 
154
182
  ## Progress
155
183
 
@@ -212,7 +240,9 @@ getRate() // → current rate
212
240
  ```
213
241
 
214
242
  Rate is a speed multiplier, not a transport control: it's independent of
215
- play/pause, and setting it while paused doesn't start playback. Pass a value
243
+ play/pause, and setting it while paused doesn't start playback.
244
+
245
+ Pass a value
216
246
  greater than zero — the platforms disagree on what a non-positive rate does
217
247
  (iOS ignores it, Android throws, web stalls the audio element), so treat it as
218
248
  unsupported rather than as a way to pause.
@@ -277,7 +307,8 @@ function SystemVolumeLabel() {
277
307
 
278
308
  `setSystemVolume` is a **no-op on iOS** — Apple provides no public API to set
279
309
  the system volume (use the player volume there instead). Reading it and
280
- `useSystemVolume` work on both platforms.
310
+ `useSystemVolume` work on iOS and Android. On web, `setSystemVolume` does
311
+ nothing, and `getSystemVolume` and `useSystemVolume` always return `1`.
281
312
 
282
313
  ## Measuring listening time
283
314
 
@@ -300,29 +331,75 @@ const cancel = trackPlaybackTime(({ total, sinceLast, track }) => {
300
331
  cancel()
301
332
  ```
302
333
 
303
- `period` must be `>= 1` (it throws otherwise). The clock is cumulative across
304
- the whole session and
305
- counts _all_ play time, not per-track — `total` keeps climbing through track
306
- changes. To measure per track, cancel and re-subscribe whenever the
307
- [active track changes](/guide/now-playing). It's a coarse, ~1-second-resolution
308
- signal, not a precise timer.
334
+ `period` must be `>= 1` (it throws otherwise). On Android, subscribe after
335
+ `setupPlayer` has resolved. A subscription made earlier never fires, even once
336
+ the player is up, and neither does one that was active while the playback
337
+ service restarted. To get ticks again, cancel every subscription and subscribe
338
+ once more.
339
+
340
+ `total` counts from when you subscribed, across every track that plays: it
341
+ keeps climbing through track changes. To measure per track, cancel and
342
+ re-subscribe whenever the [active track changes](/guide/queue#the-active-track). It's a coarse,
343
+ ~1-second-resolution signal, not a precise timer.
344
+
345
+ `track` is the active track as of the latest track change since the first
346
+ `trackPlaybackTime` subscription. If the first subscription starts while a track
347
+ is already playing, it is `undefined` until the next track change.
348
+
349
+ ## Background audio, interruptions and audio focus
350
+
351
+ Playback carries on with your app in the background and the screen locked:
352
+
353
+ - **iOS** needs the `audio` background mode in your app's `Info.plist` (see
354
+ [Getting Started](/guide/getting-started#installation)). The audio session
355
+ category defaults to `'playback'`; `ios.category`, `categoryMode`,
356
+ `categoryOptions` and `categoryPolicy` change it at setup
357
+ ([iOS options](/guide/configuration#ios-options-ios)).
358
+ - **Android** plays from the library's foreground media service, which its
359
+ merged manifest declares. What happens when the app is swiped away is set by
360
+ `android.appKilledPlaybackBehavior`
361
+ ([Android options](/guide/configuration#android-options-android)).
362
+
363
+ On iOS, the library activates the audio session when playback starts (on
364
+ `play()`, not at setup), so launching your app doesn't stop other apps' audio. It releases the
365
+ session about 3 seconds after playback stops, so their audio can come back.
366
+
367
+ **Interruptions** (a phone call, an alarm, another app starting audio) are
368
+ handled natively, with nothing to wire up:
369
+
370
+ - On **iOS**, an interruption pauses playback. When it ends, playback resumes
371
+ if iOS says it should and the player was playing when it began; otherwise it
372
+ stays paused.
373
+ - On **Android**, the player holds audio focus. It pauses while another app
374
+ holds focus briefly and resumes when focus returns. It pauses when another
375
+ app takes focus for good. It lowers its volume under a short sound such as a
376
+ notification, or pauses instead with `android.audioContentType: 'speech'`.
377
+
378
+ When the output disappears (headphones unplugged, a Bluetooth speaker switched
379
+ off), playback pauses; see
380
+ [Audio Output](/guide/audio-output#you-may-not-need-this-for-unplug-handling).
381
+ On Android, `android.handleAudioBecomingNoisy: false` turns that off.
309
382
 
310
383
  ## API summary
311
384
 
312
385
  | API | Purpose |
313
386
  | ----------------------------------------------- | ----------------------------------------------------------------------- |
314
387
  | `play()` / `pause()` / `togglePlayback()` | Start, pause, or flip playback. |
315
- | `stop()` | Stop and reset position; track stays loaded. |
388
+ | `stop()` | Stop; track stays loaded (position resets to the start on iOS only). |
316
389
  | `reset()` | Stop **and** clear the queue. |
317
390
  | `seekTo(seconds)` / `seekBy(offset)` | Seek to an absolute / relative position. |
318
391
  | `seekToLiveEdge()` | Jump to the live edge (no-op if not live). |
319
392
  | `usePlayback()` / `getPlayback()` | Full `{ state, error }`; subscribe via `onPlaybackChanged`. |
320
- | `retry()` | Re-attempt the current item while in the `'error'` state. |
321
- | `usePlayingState()` | `{ playing, buffering }` booleans for a play/pause button. |
393
+ | `retry()` | Re-attempt the current item; meant for the `'error'` state. |
394
+ | `usePlayingState()` / `getPlayingState()` | `{ playing, buffering }` booleans for a play/pause button. |
395
+ | `onPlayingState` | Subscribe to `{ playing, buffering }` changes. |
322
396
  | `setPlayWhenReady(bool)` / `usePlayWhenReady()` | Play/pause _intent_, independent of buffering. |
397
+ | `getPlayWhenReady()` / `onPlayWhenReadyChanged` | Read or subscribe to the play/pause intent. |
323
398
  | `usePolledProgress(intervalMs?)` | `{ position, duration, buffered }` via polling (ms) — works by default. |
324
- | `useProgress()` / `getProgress()` | Progress via events (enable `progressUpdateEventInterval` first). |
399
+ | `useProgress()` / `onProgressUpdated` | Progress via events (enable `progressUpdateEventInterval` first). |
400
+ | `getProgress()` | One-off progress snapshot; always works. |
325
401
  | `getRate()` / `setRate(rate)` | Playback speed multiplier (`1` = normal). |
326
402
  | `getVolume()` / `setVolume(0..1)` | This player's volume. |
327
- | `getSystemVolume()` / `useSystemVolume()` | Device media volume (`setSystemVolume` is iOS no-op). |
403
+ | `getSystemVolume()` / `useSystemVolume()` | Device media volume (`setSystemVolume` does nothing on iOS or web). |
404
+ | `onSystemVolumeChanged` | Subscribe to device media volume changes. |
328
405
  | `trackPlaybackTime(cb, period)` | Heartbeat every `period` seconds of real playback. |