react-native-audio-browser 0.2.0-next.83 → 0.2.0-next.84

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 (41) hide show
  1. package/android/src/main/java/com/audiobrowser/player/InterceptingPlayer.kt +31 -9
  2. package/android/src/main/java/com/audiobrowser/player/MediaFactory.kt +39 -46
  3. package/android/src/main/java/com/audiobrowser/player/Player.kt +219 -54
  4. package/android/src/main/java/com/audiobrowser/player/PlayerEngineFactory.kt +5 -6
  5. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +88 -73
  6. package/android/src/main/java/com/audiobrowser/player/ReconnectPacer.kt +8 -9
  7. package/android/src/main/java/com/audiobrowser/player/RetryFocus.kt +126 -0
  8. package/android/src/main/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicy.kt +55 -121
  9. package/android/src/main/java/com/audiobrowser/player/RetryLocks.kt +52 -0
  10. package/android/src/main/java/com/audiobrowser/player/RetryLoop.kt +310 -0
  11. package/android/src/main/java/com/audiobrowser/player/RetryView.kt +31 -0
  12. package/android/src/main/java/com/audiobrowser/player/SessionViewListener.kt +148 -0
  13. package/android/src/main/java/com/audiobrowser/remote/RemoteOutputsController.kt +4 -1
  14. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +3 -1
  15. package/android/src/main/java/com/audiobrowser/util/NetworkConnectivityMonitor.kt +4 -6
  16. package/android/src/test/java/androidx/media3/session/SessionViews.kt +9 -0
  17. package/android/src/test/java/com/audiobrowser/NetworkFixtures.kt +25 -0
  18. package/android/src/test/java/com/audiobrowser/player/LiveStreamEndTest.kt +15 -53
  19. package/android/src/test/java/com/audiobrowser/player/PlayerRetryTest.kt +190 -53
  20. package/android/src/test/java/com/audiobrowser/player/RetryFocusTest.kt +97 -0
  21. package/android/src/test/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicyTest.kt +90 -152
  22. package/android/src/test/java/com/audiobrowser/player/RetryLocksTest.kt +48 -0
  23. package/android/src/test/java/com/audiobrowser/player/RetryLoopCaseTest.kt +181 -0
  24. package/android/src/test/java/com/audiobrowser/player/RetryLoopTest.kt +221 -0
  25. package/android/src/test/java/com/audiobrowser/player/RetryMaskingTest.kt +176 -0
  26. package/android/src/test/java/com/audiobrowser/player/SessionPlayTest.kt +2 -0
  27. package/android/src/test/java/com/audiobrowser/player/SessionViewListenerTest.kt +21 -0
  28. package/android/src/test/java/com/audiobrowser/player/SessionViewTest.kt +2 -0
  29. package/android/src/test/java/com/audiobrowser/util/NetworkConnectivityMonitorTest.kt +13 -4
  30. package/lib/commonjs/features/player/setup.js +5 -4
  31. package/lib/commonjs/features/player/setup.js.map +1 -1
  32. package/lib/module/features/player/setup.js +5 -4
  33. package/lib/module/features/player/setup.js.map +1 -1
  34. package/lib/typescript/src/features/player/setup.d.ts +19 -13
  35. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  36. package/package.json +1 -1
  37. package/src/features/player/setup.ts +19 -13
  38. package/website/guide/errors.md +42 -38
  39. package/website/guide/network.md +4 -3
  40. package/android/src/main/java/com/audiobrowser/player/StuckRecoveryPolicy.kt +0 -37
  41. package/android/src/test/java/com/audiobrowser/player/StuckRecoveryPolicyTest.kt +0 -40
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-native-audio-browser",
3
- "version": "0.2.0-next.83",
3
+ "version": "0.2.0-next.84",
4
4
  "description": "react-native-audio-browser is a react native package built with Nitro",
5
5
  "keywords": [
6
6
  "react-native",
@@ -270,10 +270,11 @@ export interface AndroidAudioOffloadSettings {
270
270
  * `firstConnectMaxRetryDurationMs`. A stream that fails before ever playing
271
271
  * is usually dead, and the listener is actively waiting for a verdict —
272
272
  * seconds, not minutes.
273
- * - **Recovery** (the load played, then failed): retries are bounded by
274
- * `maxRetryDurationMs`. Playback proved the stream works; drops are usually
275
- * transient (tunnels, network handovers, a station's encoder restarting)
276
- * and patience is what recovers them unattended.
273
+ * - **Recovery**: the player gives up once it has been silent for
274
+ * `maxRetryDurationMs`; only 5 s of audio in a row ends a silence. Playback
275
+ * proved the stream works; drops are usually transient (tunnels, network
276
+ * handovers, a station's encoder restarting) and patience is what recovers
277
+ * them unattended.
277
278
  *
278
279
  * While the device is offline, the first-connect budget does not apply: the
279
280
  * player waits for connectivity to return (bounded by `maxRetryDurationMs`),
@@ -285,24 +286,28 @@ export interface AndroidAudioOffloadSettings {
285
286
  */
286
287
  export type RetryConfig = {
287
288
  /**
288
- * Maximum number of retry attempts before giving up. Omit to retry without an attempt
289
- * limit, bounded only by the duration budgets.
289
+ * The connections in a row that may deliver no audio before the player gives
290
+ * up. One that delivered audio starts the count over, so a stream that played
291
+ * and dropped reconnects once more than this. On Android, a failure media3
292
+ * retries within its connection (an HLS segment, a file of known length) is
293
+ * not a connection, and only the duration budgets bound it. Omit for no
294
+ * limit.
290
295
  */
291
296
  maxRetries?: number
292
297
 
293
298
  /**
294
- * Maximum duration in milliseconds to keep retrying a load that had been
295
- * playing before it failed, and any load while the device is offline.
296
- * This prevents surprising playback resumption after long periods offline.
299
+ * How long in milliseconds the player may stay silent, the listener wanting
300
+ * audio and hearing none, before it gives up. Time offline counts, so
301
+ * playback never resumes by surprise after a long time offline.
297
302
  *
298
303
  * @default 120000 (2 minutes)
299
304
  */
300
305
  maxRetryDurationMs?: number
301
306
 
302
307
  /**
303
- * Maximum duration in milliseconds to keep retrying a load that has never
304
- * produced audio, while the device is online. When it runs out, the terminal
305
- * error carries the real diagnosis (`unreachable`, `not-found`, …).
308
+ * How long in milliseconds a load that has never produced audio keeps
309
+ * retrying after its first failure while online. When it runs out, the
310
+ * terminal error carries the real diagnosis (`unreachable`, `not-found`, …).
306
311
  *
307
312
  * @default 12000 (12 seconds)
308
313
  */
@@ -609,7 +614,8 @@ export type SetupPlayerOptions = Pick<
609
614
  * - `false`/`undefined`: no library retry. Android keeps media3's default
610
615
  * handling, which retries a failed load a few times before surfacing the
611
616
  * error; iOS fails at once.
612
- * - `{ maxRetries: n }`: Retry up to n times with exponential backoff
617
+ * - `{ maxRetries: n }`: give up when a connection delivers no audio after
618
+ * n such connections in a row
613
619
  * - `RetryConfig`: custom attempt and duration budgets
614
620
  *
615
621
  * Backoff timing and budgets: see the
@@ -171,50 +171,54 @@ created when a track becomes current (selection, queue advance, skip) _or is
171
171
  restarted from a terminal error_ (`retry()`, or any play command while in
172
172
  `'error'`), and it survives every automatic retry of that track.
173
173
 
174
- A new load starts fresh budgets. Within a load, the recovery budget refills
175
- after a stretch of uninterrupted playback, and on Android after a recovery
176
- (see below).
174
+ A new load starts fresh budgets.
177
175
 
178
176
  How long the player keeps trying depends on one piece of evidence: **has this
179
177
  load ever produced audio?**
180
178
 
181
- | Situation | Budget | Why |
182
- | --------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
183
- | **First connect** — the load has never played | `firstConnectMaxRetryDurationMs`, default **12s** | A stream that fails before ever playing is usually dead, and the listener is actively waiting for a verdict — seconds, not minutes. |
184
- | **Recovery** — the load played, then failed | `maxRetryDurationMs`, default **2 min** | Playback proved the stream works. Drops are usually transient (tunnels, network handovers, a station's encoder restarting) and patience recovers them unattended. |
179
+ | Situation | Budget | Why |
180
+ | --------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
181
+ | **First connect** — the load has never played | `firstConnectMaxRetryDurationMs` after its first failure, default **12s** | A stream that fails before ever playing is usually dead, and the listener is actively waiting for a verdict — seconds, not minutes. |
182
+ | **Recovery** — any load | `maxRetryDurationMs` of silence, default **2 min** | Playback proved the stream works. Drops are usually transient (tunnels, network handovers, a station's encoder restarting) and patience recovers them unattended. |
185
183
 
186
- While the device is **offline**, the first-connect budget does not apply: the
187
- player parks and retries the moment connectivity returns, so a stream started
188
- in a tunnel still plays when the network comes back.
189
-
190
- Any offline observation resets the first-connect clock entirely — after
191
- restoration the load gets another full first-connect window, because the
192
- clock only ever measures a contiguous online stretch.
193
-
194
- `maxRetryDurationMs` is different: it is a wall-clock ceiling that
195
- **includes** offline time. It exists so playback can't surprise the listener
196
- by resuming after a long time offline.
197
-
198
- `maxRetries` additionally caps the retry attempts, counted across both budgets
199
- and across offline/online transitions.
184
+ **Silence** is time the listener wants audio and hears none. Only 5 s of audio
185
+ in a row ends it, so a stream that plays a moment between failures stays
186
+ silent, and a stream that closes every 10 s but plays in between keeps playing
187
+ however long it runs. The player gives up when the deadline passes, without
188
+ waiting for another failure.
200
189
 
201
- One Android caveat: for segmented formats like HLS, ExoPlayer counts attempts
202
- per internal loadable — playlist and segments separately — so an attempt cap
203
- is less predictable there. Prefer the duration budgets as the bound you rely
204
- on.
205
-
206
- After 20 seconds of uninterrupted audible playback, the stream counts as
207
- recovered and the recovery budget refills (on iOS, the attempt count too), so
208
- each later dropout of a long-lived stream gets a full window. On Android, a
209
- recovery from falling behind a live window refills it too, and so does one
210
- from a stalled player while the device is online.
211
-
212
- The load stays the same, and so does its evidence that it has played: the
213
- first-connect budget does not come back.
214
-
215
- Backoff delays grow exponentially from 1 s, capped at 5 s. Once a budget is
216
- exhausted the state lands on `'error'`, where your `PlaybackErrorView` and
217
- [`retry()`](#manual-retry) take over.
190
+ While the device is **offline**, the first-connect budget does not apply: the
191
+ player makes no connection and connects the moment connectivity returns, so a
192
+ stream started in a tunnel still plays when the network comes back. Any offline
193
+ observation resets the first-connect clock, which only ever measures a
194
+ contiguous online stretch.
195
+
196
+ Time offline **counts** toward `maxRetryDurationMs`, so playback can't surprise
197
+ the listener by resuming after a long time offline.
198
+
199
+ After a connection that delivered audio, the player reconnects at once; after
200
+ one that delivered nothing, it waits 1 s, then 1.5, 2.25 and 3.375, capped at
201
+ 5 s, starting at 1 s again once a connection delivers audio. Connections start
202
+ at least 1 s apart. `maxRetries` counts the connections in a row that delivered
203
+ nothing, so a stream that played and dropped reconnects once more than it.
204
+
205
+ On Android, a failure that media3 can resume within its connection, an HLS
206
+ segment or playlist and a file whose length the server declared, is retried in
207
+ place with the same backoff and keeps the buffered audio playing. It is not a
208
+ connection, so the rules above for connections don't hold for it: only the
209
+ duration budgets bound it, it keeps retrying every few seconds while offline,
210
+ it waits out its backoff once the network returns, and its loads can start
211
+ less than 1 s apart.
212
+
213
+ While it waits to reconnect, the player holds audio focus as it does while
214
+ playing. Another app taking the focus pauses it. A transient loss, a call
215
+ among them, holds the reconnect until the focus returns, then reconnects. At
216
+ the reconnect, the focus passes to the playing engine with a gap of a few
217
+ milliseconds: an app that asks for focus within it loses it again to the
218
+ reconnect, as it would to a tap on play.
219
+
220
+ Once a budget is exhausted the state lands on `'error'`, where your
221
+ `PlaybackErrorView` and [`retry()`](#manual-retry) take over.
218
222
 
219
223
  Restarting from `'error'` — via `retry()` or any play command — begins a
220
224
  **new load** of the same track: fresh budgets, starting with the
@@ -14,9 +14,10 @@ exposes it three ways:
14
14
 
15
15
  All three report the same boolean, but each platform decides it differently:
16
16
 
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`.
17
+ - **Android** asks the OS whether the default network offers internet. It does
18
+ not wait for the OS to validate it, so a network that never validates (a
19
+ failing Private DNS, some hotspots) reads `true`, and so can a captive or
20
+ dead Wi-Fi.
20
21
  - **iOS** reads the system path monitor (`NWPathMonitor`), which reports
21
22
  whether a usable network path exists. It does not check that the internet is
22
23
  reachable, so a captive or dead Wi-Fi can read `true`.
@@ -1,37 +0,0 @@
1
- package com.audiobrowser.player
2
-
3
- /**
4
- * Caps how often the player recovers from a media3
5
- * [androidx.media3.common.util.StuckPlayerException] before it surfaces a terminal error. Once the
6
- * cap is passed, every call gives up until [reset], so a dead stream yields one error instead of a
7
- * recover/error sawtooth.
8
- *
9
- * It holds no time window on purpose: a stream that re-stalls just outside one would recover
10
- * forever. Whether the stream is alive is the caller's call, from playback progress.
11
- */
12
- class StuckRecoveryPolicy(private val maxRecoveries: Int = DEFAULT_MAX_RECOVERIES) {
13
- enum class Decision {
14
- RECOVER,
15
- GIVE_UP,
16
- }
17
-
18
- private var recoveryCount = 0
19
-
20
- /**
21
- * Records a stuck event. [Decision.RECOVER] for the first [maxRecoveries] calls, then
22
- * [Decision.GIVE_UP] until [reset].
23
- */
24
- fun onStuck(): Decision {
25
- recoveryCount++
26
- return if (recoveryCount > maxRecoveries) Decision.GIVE_UP else Decision.RECOVER
27
- }
28
-
29
- /** Refills the budget. Call on sustained playback or a track change. */
30
- fun reset() {
31
- recoveryCount = 0
32
- }
33
-
34
- companion object {
35
- private const val DEFAULT_MAX_RECOVERIES = 3
36
- }
37
- }
@@ -1,40 +0,0 @@
1
- package com.audiobrowser.player
2
-
3
- import org.junit.Assert.assertEquals
4
- import org.junit.Test
5
-
6
- class StuckRecoveryPolicyTest {
7
- @Test
8
- fun `first stuck event recovers`() {
9
- val p = StuckRecoveryPolicy(maxRecoveries = 3)
10
- assertEquals(StuckRecoveryPolicy.Decision.RECOVER, p.onStuck())
11
- }
12
-
13
- @Test
14
- fun `recovers up to max then gives up`() {
15
- val p = StuckRecoveryPolicy(maxRecoveries = 3)
16
- assertEquals(StuckRecoveryPolicy.Decision.RECOVER, p.onStuck())
17
- assertEquals(StuckRecoveryPolicy.Decision.RECOVER, p.onStuck())
18
- assertEquals(StuckRecoveryPolicy.Decision.RECOVER, p.onStuck())
19
- assertEquals(StuckRecoveryPolicy.Decision.GIVE_UP, p.onStuck())
20
- }
21
-
22
- @Test
23
- fun `give up is sticky and does not self-refill`() {
24
- val p = StuckRecoveryPolicy(maxRecoveries = 3)
25
- repeat(3) { p.onStuck() }
26
- assertEquals(StuckRecoveryPolicy.Decision.GIVE_UP, p.onStuck())
27
- assertEquals(StuckRecoveryPolicy.Decision.GIVE_UP, p.onStuck())
28
- }
29
-
30
- @Test
31
- fun `reset refills the budget`() {
32
- val p = StuckRecoveryPolicy(maxRecoveries = 3)
33
- repeat(4) { p.onStuck() }
34
- p.reset()
35
- assertEquals(StuckRecoveryPolicy.Decision.RECOVER, p.onStuck())
36
- assertEquals(StuckRecoveryPolicy.Decision.RECOVER, p.onStuck())
37
- assertEquals(StuckRecoveryPolicy.Decision.RECOVER, p.onStuck())
38
- assertEquals(StuckRecoveryPolicy.Decision.GIVE_UP, p.onStuck())
39
- }
40
- }