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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (271) hide show
  1. package/README.md +32 -19
  2. package/lib/commonjs/CLAUDE.md +7 -2
  3. package/lib/commonjs/features/battery.js +16 -12
  4. package/lib/commonjs/features/battery.js.map +1 -1
  5. package/lib/commonjs/features/browser-config.js +1 -1
  6. package/lib/commonjs/features/browser.js +74 -24
  7. package/lib/commonjs/features/browser.js.map +1 -1
  8. package/lib/commonjs/features/carConnection.js +3 -4
  9. package/lib/commonjs/features/carConnection.js.map +1 -1
  10. package/lib/commonjs/features/equalizer.js +9 -5
  11. package/lib/commonjs/features/equalizer.js.map +1 -1
  12. package/lib/commonjs/features/errors.js +35 -21
  13. package/lib/commonjs/features/errors.js.map +1 -1
  14. package/lib/commonjs/features/favorites.js +15 -13
  15. package/lib/commonjs/features/favorites.js.map +1 -1
  16. package/lib/commonjs/features/gate.js +12 -6
  17. package/lib/commonjs/features/gate.js.map +1 -1
  18. package/lib/commonjs/features/metadata.js +16 -14
  19. package/lib/commonjs/features/metadata.js.map +1 -1
  20. package/lib/commonjs/features/network.js +5 -1
  21. package/lib/commonjs/features/network.js.map +1 -1
  22. package/lib/commonjs/features/nowPlaying.js +28 -14
  23. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  24. package/lib/commonjs/features/output.js +8 -4
  25. package/lib/commonjs/features/output.js.map +1 -1
  26. package/lib/commonjs/features/playback/controls.js +10 -5
  27. package/lib/commonjs/features/playback/controls.js.map +1 -1
  28. package/lib/commonjs/features/playback/playWhenReady.js +6 -5
  29. package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
  30. package/lib/commonjs/features/playback/playing.js +5 -3
  31. package/lib/commonjs/features/playback/playing.js.map +1 -1
  32. package/lib/commonjs/features/playback/progress.js +11 -5
  33. package/lib/commonjs/features/playback/progress.js.map +1 -1
  34. package/lib/commonjs/features/playback/state.js +3 -3
  35. package/lib/commonjs/features/playback/state.js.map +1 -1
  36. package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
  37. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  38. package/lib/commonjs/features/playback/volume.js +6 -5
  39. package/lib/commonjs/features/playback/volume.js.map +1 -1
  40. package/lib/commonjs/features/player/options.js +20 -10
  41. package/lib/commonjs/features/player/options.js.map +1 -1
  42. package/lib/commonjs/features/player/setup.js +34 -38
  43. package/lib/commonjs/features/player/setup.js.map +1 -1
  44. package/lib/commonjs/features/queue/activeTrack.js +0 -1
  45. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  46. package/lib/commonjs/features/queue/queue.js +48 -20
  47. package/lib/commonjs/features/queue/queue.js.map +1 -1
  48. package/lib/commonjs/features/queue/repeatMode.js +2 -1
  49. package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
  50. package/lib/commonjs/features/queue/shuffle.js +0 -1
  51. package/lib/commonjs/features/queue/shuffle.js.map +1 -1
  52. package/lib/commonjs/features/remoteControls.js +59 -35
  53. package/lib/commonjs/features/remoteControls.js.map +1 -1
  54. package/lib/commonjs/features/sleepTimer.js +15 -6
  55. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  56. package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
  57. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  58. package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
  59. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  60. package/lib/commonjs/utils/getTrackIdentity.js +6 -4
  61. package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
  62. package/lib/commonjs/utils/useDebug.js +16 -3
  63. package/lib/commonjs/utils/useDebug.js.map +1 -1
  64. package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
  65. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  66. package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
  67. package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
  68. package/lib/commonjs/web/browser/sections.js +1 -1
  69. package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
  70. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  71. package/lib/module/CLAUDE.md +7 -2
  72. package/lib/module/features/battery.js +16 -12
  73. package/lib/module/features/battery.js.map +1 -1
  74. package/lib/module/features/browser-config.js +1 -1
  75. package/lib/module/features/browser.js +74 -24
  76. package/lib/module/features/browser.js.map +1 -1
  77. package/lib/module/features/carConnection.js +3 -4
  78. package/lib/module/features/carConnection.js.map +1 -1
  79. package/lib/module/features/equalizer.js +9 -5
  80. package/lib/module/features/equalizer.js.map +1 -1
  81. package/lib/module/features/errors.js +35 -21
  82. package/lib/module/features/errors.js.map +1 -1
  83. package/lib/module/features/favorites.js +15 -13
  84. package/lib/module/features/favorites.js.map +1 -1
  85. package/lib/module/features/gate.js +12 -6
  86. package/lib/module/features/gate.js.map +1 -1
  87. package/lib/module/features/metadata.js +16 -14
  88. package/lib/module/features/metadata.js.map +1 -1
  89. package/lib/module/features/network.js +5 -1
  90. package/lib/module/features/network.js.map +1 -1
  91. package/lib/module/features/nowPlaying.js +28 -14
  92. package/lib/module/features/nowPlaying.js.map +1 -1
  93. package/lib/module/features/output.js +8 -4
  94. package/lib/module/features/output.js.map +1 -1
  95. package/lib/module/features/playback/controls.js +10 -5
  96. package/lib/module/features/playback/controls.js.map +1 -1
  97. package/lib/module/features/playback/playWhenReady.js +6 -5
  98. package/lib/module/features/playback/playWhenReady.js.map +1 -1
  99. package/lib/module/features/playback/playing.js +5 -3
  100. package/lib/module/features/playback/playing.js.map +1 -1
  101. package/lib/module/features/playback/progress.js +11 -5
  102. package/lib/module/features/playback/progress.js.map +1 -1
  103. package/lib/module/features/playback/state.js +3 -3
  104. package/lib/module/features/playback/state.js.map +1 -1
  105. package/lib/module/features/playback/trackPlaybackTime.js +6 -1
  106. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  107. package/lib/module/features/playback/volume.js +6 -5
  108. package/lib/module/features/playback/volume.js.map +1 -1
  109. package/lib/module/features/player/options.js +20 -10
  110. package/lib/module/features/player/options.js.map +1 -1
  111. package/lib/module/features/player/setup.js +34 -38
  112. package/lib/module/features/player/setup.js.map +1 -1
  113. package/lib/module/features/queue/activeTrack.js +0 -1
  114. package/lib/module/features/queue/activeTrack.js.map +1 -1
  115. package/lib/module/features/queue/queue.js +48 -20
  116. package/lib/module/features/queue/queue.js.map +1 -1
  117. package/lib/module/features/queue/repeatMode.js +2 -1
  118. package/lib/module/features/queue/repeatMode.js.map +1 -1
  119. package/lib/module/features/queue/shuffle.js +0 -1
  120. package/lib/module/features/queue/shuffle.js.map +1 -1
  121. package/lib/module/features/remoteControls.js +59 -35
  122. package/lib/module/features/remoteControls.js.map +1 -1
  123. package/lib/module/features/sleepTimer.js +15 -6
  124. package/lib/module/features/sleepTimer.js.map +1 -1
  125. package/lib/module/utils/LazyNativeEmitter.js +6 -9
  126. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  127. package/lib/module/utils/NativeUpdatedValue.js +13 -12
  128. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  129. package/lib/module/utils/getTrackIdentity.js +6 -4
  130. package/lib/module/utils/getTrackIdentity.js.map +1 -1
  131. package/lib/module/utils/useDebug.js +16 -3
  132. package/lib/module/utils/useDebug.js.map +1 -1
  133. package/lib/module/web/NativeAudioBrowser.js +2 -4
  134. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  135. package/lib/module/web/browser/parseSearchResponse.js +3 -4
  136. package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
  137. package/lib/module/web/browser/sections.js +1 -1
  138. package/lib/module/web/util/BrowserPathHelper.js +1 -3
  139. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  140. package/lib/typescript/src/features/battery.d.ts +17 -12
  141. package/lib/typescript/src/features/battery.d.ts.map +1 -1
  142. package/lib/typescript/src/features/browser.d.ts +64 -24
  143. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  144. package/lib/typescript/src/features/carConnection.d.ts +3 -4
  145. package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
  146. package/lib/typescript/src/features/equalizer.d.ts +9 -5
  147. package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
  148. package/lib/typescript/src/features/errors.d.ts +37 -22
  149. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  150. package/lib/typescript/src/features/favorites.d.ts +15 -13
  151. package/lib/typescript/src/features/favorites.d.ts.map +1 -1
  152. package/lib/typescript/src/features/gate.d.ts +14 -8
  153. package/lib/typescript/src/features/gate.d.ts.map +1 -1
  154. package/lib/typescript/src/features/metadata.d.ts +37 -17
  155. package/lib/typescript/src/features/metadata.d.ts.map +1 -1
  156. package/lib/typescript/src/features/network.d.ts +5 -1
  157. package/lib/typescript/src/features/network.d.ts.map +1 -1
  158. package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
  159. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  160. package/lib/typescript/src/features/output.d.ts +8 -4
  161. package/lib/typescript/src/features/output.d.ts.map +1 -1
  162. package/lib/typescript/src/features/playback/controls.d.ts +10 -5
  163. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  164. package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
  165. package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
  166. package/lib/typescript/src/features/playback/playing.d.ts +16 -3
  167. package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
  168. package/lib/typescript/src/features/playback/progress.d.ts +11 -5
  169. package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
  170. package/lib/typescript/src/features/playback/state.d.ts +8 -3
  171. package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
  172. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
  173. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  174. package/lib/typescript/src/features/playback/volume.d.ts +6 -5
  175. package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
  176. package/lib/typescript/src/features/player/options.d.ts +52 -37
  177. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  178. package/lib/typescript/src/features/player/setup.d.ts +65 -60
  179. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  180. package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
  181. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  182. package/lib/typescript/src/features/queue/queue.d.ts +48 -20
  183. package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
  184. package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
  185. package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
  186. package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
  187. package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
  188. package/lib/typescript/src/features/remoteControls.d.ts +58 -25
  189. package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
  190. package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
  191. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  192. package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
  193. package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
  194. package/lib/typescript/src/types/browser.d.ts +181 -144
  195. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  196. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
  197. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  198. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
  199. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  200. package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
  201. package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
  202. package/lib/typescript/src/utils/useDebug.d.ts +16 -3
  203. package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
  204. package/package.json +1 -1
  205. package/src/CLAUDE.md +7 -2
  206. package/src/docs-floors.test.ts +71 -0
  207. package/src/features/battery.ts +17 -13
  208. package/src/features/browser-config.ts +1 -1
  209. package/src/features/browser.ts +65 -24
  210. package/src/features/carConnection.ts +3 -4
  211. package/src/features/equalizer.ts +9 -5
  212. package/src/features/errors.ts +37 -22
  213. package/src/features/favorites.ts +15 -13
  214. package/src/features/gate.ts +14 -8
  215. package/src/features/metadata.ts +37 -17
  216. package/src/features/network.ts +5 -1
  217. package/src/features/nowPlaying.ts +28 -14
  218. package/src/features/output.ts +8 -4
  219. package/src/features/playback/controls.ts +10 -5
  220. package/src/features/playback/playWhenReady.ts +6 -5
  221. package/src/features/playback/playing.ts +16 -3
  222. package/src/features/playback/progress.ts +11 -5
  223. package/src/features/playback/state.ts +8 -3
  224. package/src/features/playback/trackPlaybackTime.ts +9 -2
  225. package/src/features/playback/volume.ts +6 -5
  226. package/src/features/player/options.ts +54 -43
  227. package/src/features/player/setup.ts +67 -61
  228. package/src/features/queue/activeTrack.ts +0 -1
  229. package/src/features/queue/queue.ts +48 -20
  230. package/src/features/queue/repeatMode.ts +1 -1
  231. package/src/features/queue/shuffle.ts +0 -1
  232. package/src/features/remoteControls.ts +59 -35
  233. package/src/features/sleepTimer.ts +15 -7
  234. package/src/types/browser-nodes.ts +54 -57
  235. package/src/types/browser.ts +183 -146
  236. package/src/utils/LazyNativeEmitter.ts +6 -9
  237. package/src/utils/NativeUpdatedValue.ts +13 -12
  238. package/src/utils/getTrackIdentity.ts +6 -4
  239. package/src/utils/useDebug.ts +16 -3
  240. package/src/web/NativeAudioBrowser.ts +2 -4
  241. package/src/web/browser/parseSearchResponse.ts +3 -4
  242. package/src/web/browser/sections.ts +1 -1
  243. package/src/web/util/BrowserPathHelper.ts +1 -3
  244. package/website/guide/android-auto.md +25 -13
  245. package/website/guide/android-certificates.md +199 -120
  246. package/website/guide/artwork.md +93 -48
  247. package/website/guide/audio-output.md +86 -68
  248. package/website/guide/automotive.md +15 -10
  249. package/website/guide/basic-usage.md +5 -2
  250. package/website/guide/battery.md +50 -23
  251. package/website/guide/browser.md +155 -68
  252. package/website/guide/carplay.md +132 -49
  253. package/website/guide/configuration.md +85 -49
  254. package/website/guide/equalizer.md +36 -32
  255. package/website/guide/errors.md +106 -64
  256. package/website/guide/favorites.md +41 -31
  257. package/website/guide/gate.md +24 -10
  258. package/website/guide/getting-started.md +55 -2
  259. package/website/guide/hooks.md +53 -47
  260. package/website/guide/live-streams.md +80 -49
  261. package/website/guide/metadata.md +87 -53
  262. package/website/guide/migrating-from-track-player.md +94 -49
  263. package/website/guide/native-callback-fetch.md +46 -36
  264. package/website/guide/network.md +36 -20
  265. package/website/guide/now-playing.md +72 -44
  266. package/website/guide/playback.md +112 -35
  267. package/website/guide/queue.md +77 -43
  268. package/website/guide/remote-controls.md +87 -29
  269. package/website/guide/search.md +37 -22
  270. package/website/guide/sleep-timer.md +35 -14
  271. package/website/guide/track.md +59 -35
@@ -10,19 +10,22 @@ and chapter markers. These arrive as three independent event streams:
10
10
 
11
11
  - [`onTimedMetadata`](/api/features/metadata/#ontimedmetadata) — the live song
12
12
  from a stream (ICY radio or HLS in-band ID3), changing as the broadcast does.
13
- - [`onTrackMetadata`](/api/features/metadata/#ontrackmetadata) — the static tags
14
- baked into a media file, read when it loads.
13
+ - [`onTrackMetadata`](/api/features/metadata/#ontrackmetadata) — the track's
14
+ static metadata: on iOS the file's own tags, read when it loads; on Android
15
+ the player's merged view of the Track and the file.
15
16
  - [`onChapterMetadata`](/api/features/metadata/#onchaptermetadata) — chapter
16
17
  markers with time ranges, for podcasts and audiobooks.
17
18
 
18
19
  These are **read-only signals coming _in_** from the media — they don't change
19
20
  what's displayed anywhere. It's up to you to do something with them: feed the
20
21
  [Now Playing](/guide/now-playing) surfaces, render your own UI, or build a
21
- chapter list. (Each is subscription-only — there's no getter or hook; you
22
- subscribe and keep the latest value yourself, as shown below.)
22
+ chapter list.
23
+
24
+ Each is subscription-only: there's no getter or hook. You subscribe and keep the
25
+ latest value yourself, as shown below.
23
26
 
24
27
  The UI snippets below import `useEffect` / `useState` from `react`, and `Text` /
25
- `Button` / `Image` / `FlatList` from `react-native`; those import lines are
28
+ `Button` / `FlatList` from `react-native`; those import lines are
26
29
  omitted for brevity. Everything else comes from `react-native-audio-browser`.
27
30
 
28
31
  ## Subscribing
@@ -45,7 +48,7 @@ Because the cleanup function is exactly what React's `useEffect` wants returned,
45
48
  turning any of these into reactive state is a one-liner — see
46
49
  [Holding metadata in state](#holding-metadata-in-state).
47
50
 
48
- ## Timed metadata — the live song
51
+ ## Timed metadata: the live song
49
52
 
50
53
  [`onTimedMetadata`](/api/features/metadata/#ontimedmetadata) delivers the
51
54
  "now playing song" announced by a live stream. Two formats arrive through this
@@ -58,6 +61,18 @@ one event:
58
61
  It fires each time the stream announces a new song, so the value changes
59
62
  throughout a single track.
60
63
 
64
+ ::: info iOS also fires it for a file's tags
65
+ On iOS, a file without chapter markers fires `onTimedMetadata` too. It fires
66
+ once on load for each metadata format the file carries (ID3, iTunes), with the
67
+ file's own tags: `title`, `artist`, `album` and so on.
68
+
69
+ The
70
+ [Now Playing formatter](/guide/now-playing#the-formatter-derived-continuous)
71
+ then gets them as `timedMetadata` for an on-demand file too. A formatter that
72
+ reads `timedMetadata.title` shows the file's title. Android fires it only for
73
+ metadata the media sends during playback.
74
+ :::
75
+
61
76
  [`TimedMetadata`](/api/features/metadata/#timedmetadata) — every field optional:
62
77
 
63
78
  | Field | Meaning |
@@ -79,37 +94,52 @@ This is the signal behind a live station's "now playing" line. To show it on the
79
94
  lock screen / car, you usually don't subscribe here directly — you read it inside
80
95
  the Now Playing formatter, which is re-invoked on every timed-metadata update.
81
96
  See [Now Playing → the formatter](/guide/now-playing#the-formatter-derived-continuous).
97
+
82
98
  Subscribe to `onTimedMetadata` when you want the live song for _your own_ UI.
83
99
 
84
- ## Track metadata — the file's tags
100
+ ## Track metadata: the track's static fields
85
101
 
86
- [`onTrackMetadata`](/api/features/metadata/#ontrackmetadata) delivers the static
87
- metadata baked into a media file — ID3 tags on an MP3, the metadata atoms in an
88
- MP4/M4A — read when the player loads the asset. Use it for on-demand content
89
- (podcast episodes, audiobooks, downloaded files) whose tags you didn't set
90
- yourself.
102
+ [`onTrackMetadata`](/api/features/metadata/#ontrackmetadata) delivers a
103
+ track's static metadata. What it carries depends on the platform:
104
+
105
+ - **iOS** reads the file's own tags (ID3 on an MP3, the metadata atoms in an
106
+ MP4/M4A) when the player loads the asset. It fires once, and only if the file
107
+ has tags.
108
+ - **Android** reports the player's merged metadata. The Track's own fields
109
+ (`title`, `subtitle` as `artist`, `album`, `description`, `genre`, artwork)
110
+ win over the file's tags. Once the [Now Playing](/guide/now-playing) line is
111
+ rendered, its title, artist and album replace them.
112
+
113
+ The event fires again whenever that merged view changes: a new now-playing
114
+ line, new artwork, or stream metadata that fills a field the Track leaves
115
+ empty.
116
+
117
+ So on Android, `title` and `artist` are what you or your formatter set, not the
118
+ file's. On iOS, use it for on-demand content (podcast episodes, audiobooks,
119
+ downloaded files) whose tags you didn't set yourself.
91
120
 
92
121
  [`TrackMetadata`](/api/features/metadata/#trackmetadata) is richer than the
93
122
  timed shape. **Every field is an optional `string`:**
94
123
 
95
- | Field | Meaning |
96
- | -------------- | -------------------------------- |
97
- | `title` | Track title. |
98
- | `artist` | Track artist. |
99
- | `albumTitle` | Album name. |
100
- | `subtitle` | Secondary line. |
101
- | `description` | Long description / show notes. |
102
- | `artworkUri` | Artwork URL. |
103
- | `trackNumber` | Track number within the album. |
104
- | `composer` | Composer credit. |
105
- | `conductor` | Conductor credit. |
106
- | `genre` | Genre. |
107
- | `compilation` | Compilation name. |
108
- | `station` | Station/channel name. |
109
- | `mediaType` | Media type string. |
110
- | `creationDate` | Full creation date. |
111
- | `creationYear` | Creation year. |
112
- | `url` | A URL associated with the track. |
124
+ | Field | Meaning |
125
+ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
126
+ | `title` | Track title. |
127
+ | `artist` | Track artist. |
128
+ | `albumTitle` | Album name. |
129
+ | `subtitle` | Secondary line. On Android, the now-playing artist line once it is rendered. |
130
+ | `description` | Long description / show notes. |
131
+ | `artworkUri` | Android only: the artwork URL the player publishes for the Track, not the file's embedded cover art. |
132
+ | `trackNumber` | Track number within the album. |
133
+ | `composer` | Composer credit. |
134
+ | `conductor` | Conductor credit. |
135
+ | `genre` | Genre. |
136
+ | `station` | Android only: the station name from a Shoutcast / Icecast stream's headers. |
137
+ | `mediaType` | Android only, usually unset: a Media3 `MEDIA_TYPE_*` constant, as a number string. |
138
+ | `creationDate` | iOS: the tag's date string (ID3 `TDRC`, the iTunes release date). Android: day and month only, as `DDMM` (or `DD` or `MM` alone), with no year. |
139
+ | `creationYear` | Creation year. On iOS, the first four characters of `creationDate` when there is no year tag. |
140
+
141
+ `compilation` and `url` are in the type but neither platform sets them. Neither
142
+ platform exposes a file's embedded cover art.
113
143
 
114
144
  ```tsx
115
145
  import { onTrackMetadata, type TrackMetadata } from 'react-native-audio-browser'
@@ -120,7 +150,6 @@ function FileInfo() {
120
150
  if (!meta) return null
121
151
  return (
122
152
  <>
123
- {meta.artworkUri && <Image source={{ uri: meta.artworkUri }} />}
124
153
  <Text>
125
154
  {meta.title} — {meta.artist}
126
155
  </Text>
@@ -134,24 +163,29 @@ function FileInfo() {
134
163
  Two traps when moving between the streams:
135
164
 
136
165
  - **title vs title:** `TimedMetadata.title` is the _song_ (changes during a live
137
- stream); `TrackMetadata.title` is the _file's_ title (static, read once).
166
+ stream). `TrackMetadata.title` is the _file's_ title on iOS, and on Android
167
+ the Track's title or the now-playing title.
138
168
  - **album vs albumTitle:** timed metadata uses `album`; track metadata uses
139
- `albumTitle`. And `TimedMetadata` has no artwork field — only `TrackMetadata`
140
- carries `artworkUri`.
169
+ `albumTitle`. Neither carries the file's cover art. `TimedMetadata` has no
170
+ artwork field, and `TrackMetadata.artworkUri` is the Track's artwork as
171
+ Android publishes it.
141
172
  :::
142
173
 
143
- ## Chapter metadata — podcast & audiobook chapters
174
+ ## Chapter metadata: podcast & audiobook chapters
144
175
 
145
176
  [`onChapterMetadata`](/api/features/metadata/#onchaptermetadata) delivers the
146
177
  full list of chapters for the current track as a
147
178
  [`ChapterMetadata[]`](/api/features/metadata/#chaptermetadata):
148
179
 
149
- | Field | Type | Meaning |
150
- | ----------- | --------- | ---------------------------------------------- |
151
- | `startTime` | `number` | Chapter start, in **seconds**. |
152
- | `endTime` | `number` | Chapter end, in **seconds**. |
153
- | `title` | `string?` | Chapter title, if present. |
154
- | `url` | `string?` | A URL associated with the chapter, if present. |
180
+ | Field | Type | Meaning |
181
+ | ----------- | --------- | ------------------------------------------------------------------------------- |
182
+ | `startTime` | `number` | Chapter start, in **seconds**. |
183
+ | `endTime` | `number` | Chapter end, in **seconds**. |
184
+ | `title` | `string?` | Chapter title. Android falls back to the chapter's element ID (such as `chp0`). |
185
+ | `url` | `string?` | Android only: the chapter's URL link, if present. |
186
+
187
+ Because Android fills an untitled chapter with its element ID, the
188
+ `item.title ?? 'Chapter'` fallback below applies only on iOS.
155
189
 
156
190
  Because `startTime` is in seconds, it drops straight into
157
191
  [`seekTo`](/guide/playback#seeking) to make a tappable chapter list:
@@ -184,13 +218,13 @@ function ChapterList() {
184
218
 
185
219
  ## Which metadata is which
186
220
 
187
- | | `onTimedMetadata` | `onTrackMetadata` | `onChapterMetadata` |
188
- | ----------- | ----------------------- | ---------------------- | --------------------------- |
189
- | Source | Live stream (ICY / ID3) | Tags in the media file | Chapter markers in the file |
190
- | Changes | Throughout the track | Once, on load | Once, on load |
191
- | Shape | One `TimedMetadata` | One `TrackMetadata` | A `ChapterMetadata[]` |
192
- | Typical use | Live "now playing" song | Podcast/file info | Chapter navigation |
193
- | Platform | iOS, Android | iOS, Android | iOS, Android |
221
+ | | `onTimedMetadata` | `onTrackMetadata` | `onChapterMetadata` |
222
+ | ----------- | -------------------------------------------------------------------------- | ------------------------------------------------------------- | --------------------------- |
223
+ | Source | Live stream (ICY / ID3); on iOS also a file's tags | iOS: the file's tags. Android: the Track merged with the file | Chapter markers in the file |
224
+ | Changes | Throughout the track; on iOS also once on load for a file without chapters | iOS: once, on load. Android: whenever the merged view changes | Once, on load |
225
+ | Shape | One `TimedMetadata` | One `TrackMetadata` | A `ChapterMetadata[]` |
226
+ | Typical use | Live "now playing" song | Podcast/file info | Chapter navigation |
227
+ | Platform | iOS, Android | iOS, Android | iOS, Android |
194
228
 
195
229
  ::: warning Not available on web
196
230
  All three are iOS and Android only. On web they are subscribable but never
@@ -230,10 +264,10 @@ event and the state type.
230
264
 
231
265
  ## API summary
232
266
 
233
- | API | Delivers |
234
- | ------------------- | -------------------------------------------------------- |
235
- | `onTimedMetadata` | Live `TimedMetadata` (the streaming "now playing" song). |
236
- | `onTrackMetadata` | Static `TrackMetadata` (the media file's embedded tags). |
237
- | `onChapterMetadata` | `ChapterMetadata[]` (chapter markers, times in seconds). |
267
+ | API | Delivers |
268
+ | ------------------- | -------------------------------------------------------------------------------------------- |
269
+ | `onTimedMetadata` | Live `TimedMetadata` (the streaming "now playing" song; on iOS also a file's tags, on load). |
270
+ | `onTrackMetadata` | `TrackMetadata` (iOS: the file's tags; Android: the Track merged with them). |
271
+ | `onChapterMetadata` | `ChapterMetadata[]` (chapter markers, times in seconds). |
238
272
 
239
273
  All three are subscriptions: `addListener(cb)` returns an unsubscribe function.
@@ -4,23 +4,20 @@ description: 'Porting from react-native-track-player v4: what carries over uncha
4
4
 
5
5
  # Migrating from react-native-track-player
6
6
 
7
- If you're coming from [react-native-track-player](https://github.com/doublesymmetry/react-native-track-player/tree/v4)
8
- (RNTP) v4, most of your playback and queue code ports over almost unchanged — the
9
- function names and semantics were deliberately kept familiar. This page maps the
10
- parts that _do_ change.
7
+ Most playback and queue calls from
8
+ [react-native-track-player](https://github.com/doublesymmetry/react-native-track-player/tree/v4)
9
+ (RNTP) v4 keep their names and meaning in `react-native-audio-browser`. This
10
+ page lists what changes.
11
11
 
12
- `react-native-audio-browser` started as a fork of RNTP v4, and we wrote much of
13
- that original code. We've since rethought and rewritten it almost entirely. The
14
- API stays familiar by lineage, not coincidence, but almost everything underneath
15
- is new. RNTP has itself moved to a commercial license; `react-native-audio-browser`
16
- stays MIT.
12
+ RNTP v5 moved to a
13
+ [commercial license](https://github.com/doublesymmetry/react-native-track-player).
14
+ `react-native-audio-browser` is MIT.
17
15
 
18
16
  ## What ports over unchanged
19
17
 
20
- These are the same calls with the same meaning — `import` them from
18
+ These are the same calls with the same meaning. `import` them from
21
19
  `react-native-audio-browser` instead of `react-native-track-player`:
22
20
 
23
- [`setupPlayer`](/api/features/player/#setupplayer), [`updateOptions`](/api/features/player/#updateoptions),
24
21
  [`add`](/api/features/queue/#add), [`remove`](/api/features/queue/#remove), [`move`](/api/features/queue/#move),
25
22
  [`skip`](/api/features/queue/#skip), [`skipToNext`](/api/features/queue/#skiptonext),
26
23
  [`skipToPrevious`](/api/features/queue/#skiptoprevious), [`setQueue`](/api/features/queue/#setqueue),
@@ -36,33 +33,37 @@ These are the same calls with the same meaning — `import` them from
36
33
  [`getPlayWhenReady`](/api/features/playback/#getplaywhenready), [`getActiveTrack`](/api/features/queue/#getactivetrack),
37
34
  [`getActiveTrackIndex`](/api/features/queue/#getactivetrackindex).
38
35
 
36
+ [`setupPlayer`](/api/features/player/#setupplayer) and
37
+ [`updateOptions`](/api/features/player/#updateoptions) keep their names, but
38
+ their options changed shape. See [Player options](#player-options).
39
+
39
40
  The differences below are what to watch for.
40
41
 
41
42
  ## Getters are synchronous — and there are hooks
42
43
 
43
44
  RNTP getters return Promises; audio-browser getters return the value
44
45
  **synchronously**, and most have a reactive **hook**. Drop the `await` (awaiting a
45
- non-Promise still works, so this isn't urgent), and prefer the hook in React.
46
-
47
- | RNTP v4 | audio-browser |
48
- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
49
- | `await getPosition()` | [`getProgress().position`](/api/features/playback/#position) |
50
- | `await getDuration()` | [`getProgress().duration`](/api/features/playback/#duration) |
51
- | `await getBufferedPosition()` | [`getProgress().buffered`](/api/features/playback/#buffered) |
52
- | `await getProgress()` | [`getProgress()`](/api/features/playback/#getprogress) (sync) / [`usePolledProgress()`](/api/features/playback/#usepolledprogress) |
53
- | `await getState()` / `getPlaybackState()` | [`getPlayback().state`](/api/features/playback/#state) / [`usePlayback()`](/api/features/playback/#useplayback) |
54
- | `await getActiveTrack()` | [`getActiveTrack()`](/api/features/queue/#getactivetrack) / [`useActiveTrack()`](/api/features/queue/#useactivetrack) |
55
- | `await getQueue()` | [`getQueue()`](/api/features/queue/#getqueue) / [`useQueue()`](/api/features/queue/#usequeue) |
56
- | `await getRepeatMode()` | [`getRepeatMode()`](/api/features/queue/#getrepeatmode) / [`useRepeatMode()`](/api/features/queue/#userepeatmode) |
46
+ non-Promise returns the value, so this isn't urgent), and prefer the hook in React.
47
+
48
+ | RNTP v4 | audio-browser |
49
+ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
50
+ | `await getPosition()` | [`getProgress().position`](/api/features/playback/#position) |
51
+ | `await getDuration()` | [`getProgress().duration`](/api/features/playback/#duration) |
52
+ | `await getBufferedPosition()` | [`getProgress().buffered`](/api/features/playback/#buffered) |
53
+ | `await getProgress()` | [`getProgress()`](/api/features/playback/#getprogress) (sync) / [`usePolledProgress()`](/api/features/playback/#usepolledprogress) |
54
+ | `await getState()` | [`getPlayback().state`](/api/features/playback/#state) |
55
+ | `await getPlaybackState()` | [`getPlayback()`](/api/features/playback/#getplayback) / [`usePlayback()`](/api/features/playback/#useplayback) |
56
+ | `await getActiveTrack()` | [`getActiveTrack()`](/api/features/queue/#getactivetrack) / [`useActiveTrack()`](/api/features/queue/#useactivetrack) |
57
+ | `await getQueue()` | [`getQueue()`](/api/features/queue/#getqueue) / [`useQueue()`](/api/features/queue/#usequeue) |
58
+ | `await getRepeatMode()` | [`getRepeatMode()`](/api/features/queue/#getrepeatmode) / [`useRepeatMode()`](/api/features/queue/#userepeatmode) |
57
59
 
58
60
  Two hook gotchas:
59
61
 
60
62
  - **`useProgress` changed meaning.** RNTP's `useProgress(interval)` is polling;
61
63
  its drop-in is [`usePolledProgress(intervalMs)`](/api/features/playback/#usepolledprogress).
62
64
  audio-browser _also_ has a [`useProgress()`](/api/features/playback/#useprogress), but it's **event-based and takes no
63
- interval** (and needs `progressUpdateEventInterval` enabled) — so copying
64
- `useProgress(2000)` over compiles but silently ignores the arg. Use
65
- `usePolledProgress` if you relied on the polling interval.
65
+ interval**. It stays still until `progressUpdateEventInterval` is set.
66
+ TypeScript rejects `useProgress(2000)`; plain JS ignores the argument.
66
67
  - **`useIsPlaying()` → [`usePlayingState()`](/api/features/playback/#useplayingstate)**,
67
68
  but the field is renamed: RNTP's `{ playing, bufferingDuringPlay }` becomes
68
69
  `{ playing, buffering }`.
@@ -106,7 +107,9 @@ RNTP requires `registerPlaybackService(() => require('./service'))` and a servic
106
107
  file that wires `Event.RemotePlay → TrackPlayer.play()`, etc. **audio-browser has
107
108
  no playback service** — the library wires the native side itself, and remote
108
109
  controls drive the player by default. Delete the service file and the
109
- registration call. To customize a remote control, set a
110
+ registration call.
111
+
112
+ To customize a remote control, set a
110
113
  [`handleRemote*`](/guide/remote-controls) override (pass `undefined` to restore
111
114
  the default); to just observe, use `onRemote*`:
112
115
 
@@ -118,6 +121,11 @@ handleRemoteNext(() => skipToNext())
118
121
  handleRemoteNext(undefined) // restore the default
119
122
  ```
120
123
 
124
+ Audio interruptions (RNTP's `Event.RemoteDuck`) are handled natively, so the
125
+ duck handler in your service can go too. On Android,
126
+ `android.audioContentType: 'speech'` pauses on an interruption instead of
127
+ ducking.
128
+
121
129
  ## `capabilities`: an object, not an array
122
130
 
123
131
  ```ts
@@ -135,7 +143,7 @@ Pass `capabilities` to **either** [`setupPlayer`](/api/features/player/#setuppla
135
143
  (initial) or [`updateOptions`](/api/features/player/#updateoptions) (later) — both
136
144
  accept it. See
137
145
  [Configuration → Capabilities](/guide/configuration#capabilities) for the
138
- defaults (everything on except `jumpForward`, `jumpBackward`, `favorite`).
146
+ defaults.
139
147
  `Capability.Like` / `RatingType` map to the [`favorite`](/guide/favorites)
140
148
  capability.
141
149
 
@@ -158,21 +166,31 @@ The playable URL field is renamed. In audio-browser, the **playable source**
158
166
  is [`src`](/api/types/browser-nodes/#src); a track's **browse address** (for the
159
167
  [browse tree](/guide/browser)) is a separate field, `path`:
160
168
 
169
+ <!-- prettier-ignore -->
161
170
  ```ts
162
171
  // RNTP
163
- {
164
- url: ('https://cdn.example.com/song.mp3', title, artist, artwork)
165
- }
172
+ { url: 'https://cdn.example.com/song.mp3', title, artist, artwork }
166
173
 
167
174
  // audio-browser
168
- {
169
- src: ('https://cdn.example.com/song.mp3', title, artist, artwork)
170
- }
175
+ { src: 'https://cdn.example.com/song.mp3', title, artist, artwork }
171
176
  ```
172
177
 
173
- Other field changes: `isLiveStream` → [`live`](/api/types/browser-nodes/#live); per-track `headers`
174
- move to a [media request config](/guide/browser); `rating` → favorites (see
175
- above). `title` / `artist` / `album` / `artwork` / `duration` are unchanged.
178
+ Other field changes:
179
+
180
+ - `isLiveStream` → [`live`](/api/types/browser-nodes/#live).
181
+ - Per-track `headers` / `userAgent` → return them from `media.resolve(track)`
182
+ (or `resolveSync`), which receives each track. Headers that every track
183
+ shares go on the browser's `request` / `media` config
184
+ ([Shaping requests](/guide/browser#shaping-requests)).
185
+ - `rating` → favorites (see above).
186
+ - `title` is required.
187
+ - `Track` has no index signature, so it refuses fields of your own. Keep app
188
+ data in a map keyed by `id` (or by `src`).
189
+ - RNTP's `type`, `contentType`, `pitchAlgorithm` and `date` have no `Track`
190
+ field.
191
+
192
+ `title` / `artist` / `album` / `artwork` / `duration` / `description` /
193
+ `genre` are unchanged.
176
194
 
177
195
  ## Now-playing metadata
178
196
 
@@ -184,13 +202,40 @@ TrackPlayer.clearNowPlayingMetadata()
184
202
  // audio-browser
185
203
  import { updateNowPlaying } from 'react-native-audio-browser'
186
204
  updateNowPlaying({ title, artist })
187
- updateNowPlaying(null) // clear
205
+ updateNowPlaying(null) // drop the override; the track's own metadata shows
188
206
  ```
189
207
 
190
208
  For live streams, prefer the [Now Playing formatter](/guide/now-playing) over
191
209
  imperative updates — it re-derives the lock-screen lines on every metadata /
192
210
  state change.
193
211
 
212
+ ## Player options
213
+
214
+ `setupPlayer` and `updateOptions` keep `capabilities`,
215
+ `forwardJumpInterval`, `backwardJumpInterval` and
216
+ `progressUpdateEventInterval`. Other RNTP options moved or have no
217
+ equivalent:
218
+
219
+ | RNTP v4 | audio-browser |
220
+ | -------------------------------------------------------- | --------------------------------------------------------------- |
221
+ | `minBuffer` / `maxBuffer` / `backBuffer` / `playBuffer` | `android.minBuffer` / `maxBuffer` / `backBuffer` / `playBuffer` |
222
+ | `minBuffer` on iOS | `ios.buffer` |
223
+ | `maxCacheSize` | `android.maxCacheSize` |
224
+ | `androidAudioContentType` | `android.audioContentType` |
225
+ | `iosCategory` / `iosCategoryMode` / `iosCategoryOptions` | `ios.category` / `ios.categoryMode` / `ios.categoryOptions` |
226
+ | `autoUpdateMetadata` | `nowPlaying` |
227
+ | `notificationCapabilities` / `compactCapabilities` | none; place Android buttons with `android.remoteButtonLayout` |
228
+ | `icon` / `color` | none |
229
+ | `ratingType` | the `favorite` capability |
230
+
231
+ The units changed with the names. The four Android buffers and `ios.buffer`
232
+ take milliseconds where RNTP took seconds, and `maxCacheSize` takes megabytes
233
+ where RNTP took kilobytes, so a value copied across unchanged is off by a
234
+ factor of 1000.
235
+
236
+ The `android` and `ios` keys are typed, so a leftover RNTP option is a type
237
+ error. See [Configuration](/guide/configuration) for every option.
238
+
194
239
  ## Setup, before and after
195
240
 
196
241
  ```ts
@@ -231,14 +276,14 @@ ported:
231
276
 
232
277
  ## Quick reference
233
278
 
234
- | Area | RNTP v4 | audio-browser |
235
- | --------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------- |
236
- | Getters | `await TrackPlayer.getX()` | `getX()` (sync) or `useX()` |
237
- | Events | `Event` + `addEventListener` / `useTrackPlayerEvents` | per-event `onX` / `useX` |
238
- | Unsubscribe | `subscription.remove()` | the function `addListener` returns |
239
- | Remote handling | a registered playback **service** | default behavior + `handleRemote*` |
240
- | Capabilities | `Capability[]` | `capabilities` object of booleans |
241
- | Enums | `State.*`, `RepeatMode.*` | string literals (`'playing'`, `'queue'`) |
242
- | Playable URL | `track.url` | [`track.src`](/api/types/browser-nodes/#src) |
243
- | Live flag | `track.isLiveStream` | [`track.live`](/api/types/browser-nodes/#live) |
244
- | Now playing | `updateNowPlayingMetadata` / `clearNowPlayingMetadata` | [`updateNowPlaying`](/api/features/nowPlaying/#updatenowplaying)`(update \| null)` |
279
+ | Area | RNTP v4 | audio-browser |
280
+ | --------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
281
+ | Getters | `await TrackPlayer.getX()` | `getX()` (sync) or `useX()` |
282
+ | Events | `Event` + `addEventListener` / `useTrackPlayerEvents` | per-event `onX` / `useX` |
283
+ | Unsubscribe | `subscription.remove()` | the function `addListener` returns |
284
+ | Remote handling | a registered playback **service** | default behavior + `handleRemote*` |
285
+ | Capabilities | `Capability[]` | `capabilities` object of booleans |
286
+ | Enums | `State.*`, `RepeatMode.*` | string literals (`'playing'`, `'queue'`) |
287
+ | Playable URL | `track.url` | [`track.src`](/api/types/browser-nodes/#src) |
288
+ | Live flag | `track.isLiveStream` | [`track.live`](/api/types/browser-nodes/#live) |
289
+ | Now playing | `updateNowPlayingMetadata` / `clearNowPlayingMetadata` | [`updateNowPlaying`](/api/features/nowPlaying/#updatenowplaying)`(update \| null)`; `null` reverts to the track's metadata |
@@ -1,15 +1,16 @@
1
1
  ---
2
- description: "Why React Native's fetch hangs inside browse resolvers, search sources, and request transforms when the device is asleep, and what to use instead."
2
+ description: "Why React Native's fetch hangs inside the callbacks you pass to configureBrowser, such as browse route callbacks and search sources, when the device is asleep, and what to use instead."
3
3
  ---
4
4
 
5
5
  # Networking in native callbacks (don't use `fetch`)
6
6
 
7
- **If a browse route resolver, search source, or request `transform` does its own
8
- networking with React Native's built-in `fetch` — and it works in your app but
9
- _hangs_ when the device is asleep (browsing on CarPlay or Android Auto with the
10
- screen off, or answering a voice intent) — you are in the right place.** The
11
- browse screen goes blank because the request never resolves. The fix is to fetch
12
- with
7
+ **Does a callback you pass to `configureBrowser` network with React Native's
8
+ built-in `fetch`, and work in your app but _hang_ when the device is asleep?
9
+ Browsing on CarPlay or Android Auto with the screen off, or answering a voice
10
+ intent, are typical cases. Then you are in the right place.**
11
+
12
+ The browse screen goes blank because the request never resolves. The fix is to
13
+ fetch with
13
14
  [`react-native-nitro-fetch`](https://github.com/margelo/react-native-nitro-fetch),
14
15
  or to let the library do the request natively.
15
16
 
@@ -18,9 +19,12 @@ or to let the library do the request natively.
18
19
  The library invokes the async callbacks you provide **from native code**,
19
20
  whenever the system asks for content — including while your app is asleep:
20
21
 
21
- - browse **route resolvers** (`configureBrowser({ routes })`),
22
+ - browse **route callbacks** (`configureBrowser({ routes })`),
22
23
  - the **search source** (`configureBrowser({ search })`),
23
- - request **`transform`** callbacks.
24
+ - request **`transform`** callbacks,
25
+ - `media` and `artwork` **`resolve`** callbacks,
26
+ - **config resolvers**, such as `request: async () => …`,
27
+ - a **`tabs`** callback.
24
28
 
25
29
  A locked iPhone browsing your library on CarPlay, or a "play jazz" voice command
26
30
  with the screen dark, runs these callbacks with the app backgrounded. The first
@@ -29,8 +33,8 @@ it hangs until the phone wakes.
29
33
 
30
34
  ### Why `fetch` hangs while asleep
31
35
 
32
- React Native's `fetch` is the [`whatwg-fetch`](https://github.com/JakeChampion/fetch)
33
- polyfill, and it resolves its promise with a **zero-delay timer**, not a
36
+ As of React Native 0.88, its `fetch` is the [`whatwg-fetch`](https://github.com/JakeChampion/fetch)
37
+ polyfill, which resolves its promise with a **zero-delay timer**, not a
34
38
  microtask:
35
39
 
36
40
  ```js
@@ -40,27 +44,27 @@ setTimeout(function () {
40
44
  }, 0)
41
45
  ```
42
46
 
43
- When the device is asleep, React Native's timer module is paused — on iOS,
44
- `RCTTiming` pauses the `CADisplayLink` that drives JS timers — so `setTimeout`
45
- callbacks don't fire. Native networking (`RCTNetworking`) **does** perform the
46
- request and receive the response, but the `setTimeout(0)` that would hand it back
47
- to your `await` never runs. The promise sits unresolved until the screen wakes,
48
- and your browse list spins or shows blank. Android suspends JS timers the same
49
- way while the app is backgrounded behind Android Auto, so the symptom and the fix
50
- are identical there.
47
+ While the app is in the background, JS timers don't fire reliably
48
+ ([RN #54534](https://github.com/react/react-native/issues/54534)). Native
49
+ networking (`RCTNetworking`) **does** receive the response, but the
50
+ `setTimeout(0)` that hands it to your `await` doesn't run. The promise hangs
51
+ until the screen wakes, and the browse list spins or shows blank.
52
+
53
+ On Android, React Native's timer manager stops firing JS timers once the host
54
+ activity pauses, unless a headless JS task is running. An app backgrounded
55
+ behind Android Auto therefore shows the same symptom, and the same fix applies.
51
56
 
52
- This isn't specific to this library — it affects any `fetch` on a sleeping
53
- device, and upgrading doesn't help: current React Native still ships
54
- `whatwg-fetch`.
57
+ This isn't specific to this library: it affects any `fetch` on a sleeping
58
+ device.
55
59
 
56
60
  ## The fix: `react-native-nitro-fetch`
57
61
 
58
62
  [`react-native-nitro-fetch`](https://github.com/margelo/react-native-nitro-fetch)
59
- is a drop-in `fetch` replacement that runs the request on a native thread
60
- (`URLSession` on iOS, Cronet on Android) and resolves through **Nitro's
61
- microtask queue** — no `setTimeout`, no `whatwg-fetch`, no `RCTTiming`
62
- dependency. So it completes even when the callback runs while the device is
63
- asleep. Since this library is already a Nitro module, it's a natural fit.
63
+ is a drop-in `fetch` replacement that runs the request natively and resolves
64
+ its promise without a JS timer: no `setTimeout`, no `whatwg-fetch`.
65
+
66
+ It therefore completes even when the callback runs while the device is asleep.
67
+ This library is already a Nitro module, so it's a natural fit.
64
68
 
65
69
  ```bash
66
70
  npm install react-native-nitro-fetch react-native-nitro-modules
@@ -89,7 +93,8 @@ configureBrowser({
89
93
  })
90
94
  ```
91
95
 
92
- Use the same import in your search source and request `transform`s.
96
+ Do the same in every module that holds a callback from the list above, not only
97
+ routes.
93
98
 
94
99
  ## Even simpler: let the library fetch natively
95
100
 
@@ -106,22 +111,27 @@ configureBrowser({
106
111
  })
107
112
  ```
108
113
 
109
- The navigated path is appended to `baseUrl`; to remap or shape the request, use a
110
- [`transform`](/guide/browser) (still native). The search source accepts the same
111
- request-config form, so it can be served natively too. Reach for
112
- `react-native-nitro-fetch` only when you need logic a request config can't
113
- express (combining sources, reading local storage, custom shaping).
114
+ The navigated path is appended to `baseUrl`. To remap or shape the request, use
115
+ a [`transform`](/guide/browser#shaping-requests). The request itself stays
116
+ native, so a transform that does no networking of its own is safe.
117
+
118
+ The search source accepts the same request-config form, so it can be served
119
+ natively too. Reach for `react-native-nitro-fetch` only when you need logic a
120
+ request config can't express (combining sources, reading local storage, custom
121
+ shaping).
114
122
 
115
123
  ## When it's safe to use plain `fetch`
116
124
 
117
125
  This only affects code the library invokes from native while the app is asleep.
118
126
  Networking driven by **your own app UI in the foreground** — a screen the user is
119
127
  looking at — runs on the normal JS loop and is unaffected; plain `fetch` is fine
120
- there. Rule of thumb: if the OS can run the code with the screen off, don't
128
+ there.
129
+
130
+ Rule of thumb: if the OS can run the code with the screen off, don't
121
131
  depend on `fetch`.
122
132
 
123
133
  ## Further reading
124
134
 
125
135
  - [`react-native-nitro-fetch`](https://github.com/margelo/react-native-nitro-fetch)
126
- - [JS timers don't fire when the app is backgrounded (RN #38711)](https://github.com/facebook/react-native/issues/38711)
127
- - [Timers & fetch freeze behind a native activity (RN #54534)](https://github.com/facebook/react-native/issues/54534)
136
+ - [JS timers don't fire when the app is backgrounded (RN #38711, closed in 2023)](https://github.com/react/react-native/issues/38711)
137
+ - [Timers & fetch freeze behind a native activity (RN #54534)](https://github.com/react/react-native/issues/54534)