react-native-audio-browser 0.2.0-next.75 → 0.2.0-next.77

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 (68) hide show
  1. package/android/src/main/java/com/audiobrowser/AudioBrowser.kt +20 -27
  2. package/android/src/main/java/com/audiobrowser/Service.kt +3 -0
  3. package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt +16 -8
  4. package/android/src/main/java/com/audiobrowser/browser/TrackLoadHandler.kt +5 -3
  5. package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt +10 -2
  6. package/android/src/main/java/com/audiobrowser/player/EnginePlayback.kt +9 -5
  7. package/android/src/main/java/com/audiobrowser/player/InterceptingPlayer.kt +71 -39
  8. package/android/src/main/java/com/audiobrowser/player/LiveStreamExtractor.kt +65 -0
  9. package/android/src/main/java/com/audiobrowser/player/MediaFactory.kt +12 -3
  10. package/android/src/main/java/com/audiobrowser/player/NowPlayingUpdater.kt +8 -0
  11. package/android/src/main/java/com/audiobrowser/player/Player.kt +85 -37
  12. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +38 -11
  13. package/android/src/main/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicy.kt +1 -1
  14. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +21 -0
  15. package/android/src/main/java/com/audiobrowser/util/AwaitCancellable.kt +45 -0
  16. package/android/src/test/java/androidx/media3/session/SessionViews.kt +10 -0
  17. package/android/src/test/java/com/audiobrowser/GateDecisionTest.kt +128 -0
  18. package/android/src/test/java/com/audiobrowser/ResolveFormattedErrorTest.kt +93 -0
  19. package/android/src/test/java/com/audiobrowser/ServiceTaskRemovedTest.kt +35 -0
  20. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerLayerResolutionTest.kt +75 -5
  21. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerTest.kt +42 -0
  22. package/android/src/test/java/com/audiobrowser/browser/TrackLoadHandlerTest.kt +43 -0
  23. package/android/src/test/java/com/audiobrowser/http/RequestConfigBuilderTest.kt +62 -0
  24. package/android/src/test/java/com/audiobrowser/player/BrowseTilesTest.kt +31 -32
  25. package/android/src/test/java/com/audiobrowser/player/LiveStreamEndTest.kt +372 -0
  26. package/android/src/test/java/com/audiobrowser/player/NowPlayingFormatterTest.kt +75 -0
  27. package/android/src/test/java/com/audiobrowser/player/NowPlayingUpdaterTest.kt +25 -0
  28. package/android/src/test/java/com/audiobrowser/player/PlayFromSearchTest.kt +108 -0
  29. package/android/src/test/java/com/audiobrowser/player/PlayerSetupEndedTest.kt +221 -0
  30. package/android/src/test/java/com/audiobrowser/player/PlayerSetupTest.kt +17 -7
  31. package/android/src/test/java/com/audiobrowser/player/PlayerSuppressionTest.kt +183 -7
  32. package/android/src/test/java/com/audiobrowser/player/PlayerTrackChangeTest.kt +153 -0
  33. package/android/src/test/java/com/audiobrowser/player/SessionPlayTest.kt +236 -0
  34. package/android/src/test/java/com/audiobrowser/player/SessionViewRulesTest.kt +62 -0
  35. package/android/src/test/java/com/audiobrowser/player/SessionViewTest.kt +188 -0
  36. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +11 -0
  37. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +58 -0
  38. package/android/src/test/java/com/audiobrowser/util/AwaitCancellableTest.kt +136 -0
  39. package/android/src/test/java/com/audiobrowser/util/JsPromise.kt +44 -0
  40. package/ios/AVPlayerEngine.swift +5 -1
  41. package/ios/Browser/BrowserManager.swift +2 -2
  42. package/ios/Browser/PageResolver.swift +14 -19
  43. package/ios/Browser/RequestPipeline.swift +6 -4
  44. package/ios/CarPlay/CarPlayNowPlayingManager.swift +1 -1
  45. package/ios/CarPlay/CarPlaySession+PageLoader.swift +1 -0
  46. package/ios/CarPlay/CarPlaySession+TabBar.swift +2 -0
  47. package/ios/Extension/Promise+AwaitCallback.swift +33 -0
  48. package/ios/HybridAudioBrowser+Player.swift +1 -1
  49. package/ios/HybridAudioBrowser.swift +1 -1
  50. package/ios/Player/MediaLoader.swift +1 -1
  51. package/ios/Player/PlaybackFailure.swift +3 -3
  52. package/ios/Player/Player.swift +67 -49
  53. package/ios/Player/PlayerEngine.swift +2 -0
  54. package/ios/Player/RetryLoop.swift +72 -12
  55. package/ios/Tests/AwaitCallbackTests.swift +210 -0
  56. package/ios/Tests/GenerationMemoTests.swift +57 -0
  57. package/ios/Tests/PlaybackFailureTests.swift +7 -0
  58. package/ios/Tests/PlayerPolicyTests.swift +346 -6
  59. package/ios/Tests/PlayerTests.swift +79 -1
  60. package/ios/Tests/RetryLoopTests.swift +30 -5
  61. package/ios/Tests/Support/TestTypes.swift +15 -7
  62. package/ios/Tests/Support/TimeLimit.swift +43 -0
  63. package/ios/Util/AwaitCallback.swift +80 -0
  64. package/ios/Util/GenerationMemo.swift +11 -4
  65. package/package.json +2 -1
  66. package/android/src/test/java/com/audiobrowser/player/SessionErrorMaskTest.kt +0 -63
  67. package/ios/Player/EndOfTrackJudgement.swift +0 -25
  68. package/ios/Tests/EndOfTrackJudgementTests.swift +0 -30
@@ -0,0 +1,136 @@
1
+ package com.audiobrowser.util
2
+
3
+ import java.util.concurrent.TimeoutException
4
+ import kotlin.time.Duration.Companion.seconds
5
+ import kotlinx.coroutines.CancellationException
6
+ import kotlinx.coroutines.ExperimentalCoroutinesApi
7
+ import kotlinx.coroutines.async
8
+ import kotlinx.coroutines.test.advanceTimeBy
9
+ import kotlinx.coroutines.test.runCurrent
10
+ import kotlinx.coroutines.test.runTest
11
+ import kotlinx.coroutines.withTimeoutOrNull
12
+ import org.junit.Assert.assertEquals
13
+ import org.junit.Assert.assertFalse
14
+ import org.junit.Assert.assertTrue
15
+ import org.junit.Test
16
+
17
+ @OptIn(ExperimentalCoroutinesApi::class)
18
+ class AwaitCancellableTest {
19
+
20
+ @Test
21
+ fun `an answer resumes the await with its value`() =
22
+ runTest(timeout = 5.seconds) {
23
+ val js = JsPromise<String>()
24
+ val result = backgroundScope.async { js.promise.awaitCancellable() }
25
+ runCurrent()
26
+
27
+ js.resolve("answer")
28
+ runCurrent()
29
+
30
+ assertTrue(result.isCompleted)
31
+ assertEquals("answer", result.await())
32
+ }
33
+
34
+ @Test
35
+ fun `a rejection resumes the await with its error`() =
36
+ runTest(timeout = 5.seconds) {
37
+ val js = JsPromise<String>()
38
+ val result = backgroundScope.async { runCatching { js.promise.awaitCancellable() } }
39
+ runCurrent()
40
+
41
+ js.reject(IllegalStateException("rejected"))
42
+ runCurrent()
43
+
44
+ assertTrue(result.isCompleted)
45
+ assertEquals("rejected", result.await().exceptionOrNull()?.message)
46
+ }
47
+
48
+ @Test
49
+ fun `a cancelled caller stops waiting and ignores a later answer`() =
50
+ runTest(timeout = 5.seconds) {
51
+ val js = JsPromise<String>()
52
+ var after = false
53
+ val caller =
54
+ backgroundScope.async {
55
+ js.promise.awaitCancellable()
56
+ after = true
57
+ }
58
+ runCurrent()
59
+
60
+ caller.cancel()
61
+ runCurrent()
62
+ assertTrue(caller.isCompleted)
63
+ js.resolve("late")
64
+ runCurrent()
65
+
66
+ assertFalse(after)
67
+ }
68
+
69
+ @Test
70
+ fun `a promise that never settles fails at its timeout`() =
71
+ runTest(timeout = 5.seconds) {
72
+ val js = JsPromise<String>()
73
+ val result = backgroundScope.async { runCatching { js.promise.awaitOrTimeout() } }
74
+
75
+ advanceTimeBy(FALLBACK_TIMEOUT - 1.seconds)
76
+ runCurrent()
77
+ assertFalse(result.isCompleted)
78
+ advanceTimeBy(2.seconds)
79
+ runCurrent()
80
+
81
+ assertTrue(result.isCompleted)
82
+ val error = result.await().exceptionOrNull()
83
+ assertTrue(error is TimeoutException)
84
+ assertFalse(error is CancellationException)
85
+ }
86
+
87
+ @Test
88
+ fun `a nested promise's timeout covers both layers`() =
89
+ runTest(timeout = 5.seconds) {
90
+ val outer = JsPromise<com.margelo.nitro.core.Promise<String>>()
91
+ val inner = JsPromise<String>()
92
+ val result = backgroundScope.async { runCatching { outer.promise.awaitNestedOrTimeout() } }
93
+ runCurrent()
94
+
95
+ advanceTimeBy(FALLBACK_TIMEOUT / 2)
96
+ outer.resolve(inner.promise)
97
+ advanceTimeBy(FALLBACK_TIMEOUT / 2 + 1.seconds)
98
+ runCurrent()
99
+
100
+ assertTrue(result.isCompleted)
101
+ assertTrue(result.await().exceptionOrNull() is TimeoutException)
102
+ }
103
+
104
+ @Test
105
+ fun `a nested promise answers with the inner value`() =
106
+ runTest(timeout = 5.seconds) {
107
+ val outer = JsPromise<com.margelo.nitro.core.Promise<String>>()
108
+ val inner = JsPromise<String>()
109
+ val result = backgroundScope.async { outer.promise.awaitNestedOrTimeout() }
110
+ runCurrent()
111
+
112
+ outer.resolve(inner.promise)
113
+ runCurrent()
114
+ inner.resolve("answer")
115
+ runCurrent()
116
+
117
+ assertTrue(result.isCompleted)
118
+ assertEquals("answer", result.await())
119
+ }
120
+
121
+ @Test
122
+ fun `an outer timeout keeps its cancellation`() =
123
+ runTest(timeout = 5.seconds) {
124
+ val js = JsPromise<String>()
125
+ val result =
126
+ backgroundScope.async {
127
+ runCatching { withTimeoutOrNull(FALLBACK_TIMEOUT / 2) { js.promise.awaitOrTimeout() } }
128
+ }
129
+
130
+ advanceTimeBy(FALLBACK_TIMEOUT / 2 + 1.seconds)
131
+ runCurrent()
132
+
133
+ assertTrue(result.isCompleted)
134
+ assertEquals(Result.success(null), result.await())
135
+ }
136
+ }
@@ -0,0 +1,44 @@
1
+ package com.audiobrowser.util
2
+
3
+ import com.margelo.nitro.core.Promise
4
+ import org.mockito.ArgumentMatchers.any
5
+ import org.mockito.Mockito.doAnswer
6
+ import org.mockito.Mockito.mock
7
+
8
+ /**
9
+ * A Nitro [Promise] needs JNI, so this one is a mock the test settles; settled before anyone
10
+ * listens, it answers each listener as it registers, as Nitro's does.
11
+ */
12
+ class JsPromise<T> {
13
+ @Suppress("UNCHECKED_CAST") val promise = mock(Promise::class.java) as Promise<T>
14
+ private var result: Result<T>? = null
15
+ private val onResolved = mutableListOf<(T) -> Unit>()
16
+ private val onRejected = mutableListOf<(Throwable) -> Unit>()
17
+
18
+ init {
19
+ doAnswer {
20
+ @Suppress("UNCHECKED_CAST") val listener = it.arguments[0] as (T) -> Unit
21
+ result?.onSuccess(listener) ?: onResolved.add(listener)
22
+ promise
23
+ }
24
+ .`when`(promise)
25
+ .then(any() ?: {})
26
+ doAnswer {
27
+ @Suppress("UNCHECKED_CAST") val listener = it.arguments[0] as (Throwable) -> Unit
28
+ result?.onFailure(listener) ?: onRejected.add(listener)
29
+ promise
30
+ }
31
+ .`when`(promise)
32
+ .catch(any() ?: {})
33
+ }
34
+
35
+ fun resolve(value: T) {
36
+ result = Result.success(value)
37
+ onResolved.forEach { it(value) }
38
+ }
39
+
40
+ fun reject(error: Throwable) {
41
+ result = Result.failure(error)
42
+ onRejected.forEach { it(error) }
43
+ }
44
+ }
@@ -162,10 +162,14 @@ final class AVPlayerEngine: PlayerEngine {
162
162
  itemObserver = nil
163
163
  }
164
164
 
165
+ var playerFailed: Bool { avPlayer.status == .failed }
166
+
165
167
  func recreate() {
166
168
  playerObserver?.invalidate()
167
169
  nowPlayingInfoController.unlinkPlayer()
170
+ let volume = avPlayer.volume
168
171
  avPlayer = AVPlayer()
172
+ avPlayer.volume = volume
169
173
  setUpAVPlayer()
170
174
  }
171
175
 
@@ -264,7 +268,7 @@ final class AVPlayerEngine: PlayerEngine {
264
268
  private func playerDidEmit(_ event: PlayerObserver.Event) {
265
269
  switch event {
266
270
  case let .status(status):
267
- if status == .failed { reportFailure(nil) }
271
+ if status == .failed { reportFailure(avPlayer.error) }
268
272
  case let .timeControlStatus(status):
269
273
  let mapped: PlayerTimeControlStatus
270
274
  switch status {
@@ -87,7 +87,7 @@ final class BrowserManager {
87
87
  func awaitTrackLoadHandler(event: TrackLoadEvent) async -> Bool {
88
88
  guard let handler = config.handleTrackLoad else { return false }
89
89
  do {
90
- try await handler(event).await().await()
90
+ try await handler(event).awaitNested()
91
91
  } catch {
92
92
  logger.error("handleTrackLoad failed: \(error.localizedDescription)")
93
93
  }
@@ -204,7 +204,7 @@ final class BrowserManager {
204
204
  let params = FormatNavigationErrorParams(
205
205
  error: error, defaultFormatted: fallback, path: path, kind: NavigationErrorKind(path: path),
206
206
  )
207
- return await (try? formatter(params).await()) ?? fallback
207
+ return await (try? formatter(params).awaitOrTimeout()) ?? fallback
208
208
  }
209
209
 
210
210
  // MARK: - Search
@@ -57,7 +57,7 @@ final class PageResolver {
57
57
  throw BrowserError.contentNotFound(path: SimpleRouter.searchRoutePath)
58
58
  }
59
59
  if let callback = searchEntry.searchCallback {
60
- return try await callback(params).await().await()
60
+ return try await callback(params).awaitNested()
61
61
  }
62
62
  if let searchConfig = searchEntry.searchConfig {
63
63
  return try await requests.fetchSearch(searchConfig, params: params)
@@ -76,13 +76,13 @@ final class PageResolver {
76
76
  let callbackParam = BrowserSourceCallbackParam(path: path, routeParams: params)
77
77
  // Nitro flattens `(ResolvedTrack | BrowseError) | Promise<BrowseResult>` into three arms:
78
78
  // a sync track, a sync error, or a promise of the same two.
79
- switch try await callback(callbackParam).await() {
79
+ switch try await callback(callbackParam).awaitCancellable() {
80
80
  case let .first(resolvedTrack):
81
81
  return resolvedTrack
82
82
  case let .second(browseError):
83
83
  throw BrowserError.callbackError(browseError.error)
84
84
  case let .third(promise):
85
- switch try await promise.await() {
85
+ switch try await promise.awaitCancellable() {
86
86
  case let .first(resolvedTrack):
87
87
  return resolvedTrack
88
88
  case let .second(browseError):
@@ -115,23 +115,18 @@ final class PageResolver {
115
115
  ) async throws -> [Section] {
116
116
  let stamped = try BrowserPathHelper.stampingContextualPaths(sections, parentPath: parentPath)
117
117
  let artworkConfig = routeEntry?.artwork
118
- let artworkLoads = stamped.map { section in
119
- section.children.map { track in
120
- Task<ImageSource?, Never> { @MainActor in
121
- await self.requests.resolveArtworkUrl(track: track, perRouteConfig: artworkConfig)
122
- }
123
- }
118
+ let tracks = stamped.flatMap(\.children)
119
+ let artwork = await Array(tracks.indices).concurrentMap { index in
120
+ await self.requests.resolveArtworkUrl(track: tracks[index], perRouteConfig: artworkConfig)
124
121
  }
125
-
126
- var transformed: [Section] = []
127
- for (section, loads) in zip(stamped, artworkLoads) {
128
- var children: [Track] = []
129
- for (track, load) in zip(section.children, loads) {
130
- let artwork = await load.value
131
- children.append(artwork.map { track.copying(artworkSource: $0) } ?? track)
132
- }
133
- transformed.append(section.copying(children: children))
122
+ // A cancelled resolve gives no artwork; that page must not reach the cache.
123
+ try Task.checkCancellation()
124
+ var next = 0
125
+ return stamped.map { section in
126
+ section.copying(children: section.children.map { track in
127
+ defer { next += 1 }
128
+ return artwork[next].map { track.copying(artworkSource: $0) } ?? track
129
+ })
134
130
  }
135
- return transformed
136
131
  }
137
132
  }
@@ -37,8 +37,8 @@ final class RequestPipeline {
37
37
  let config = self.config
38
38
  // Double await: the TS side wraps a sync-or-async thunk in a JS promise, behind the
39
39
  // bridge's promise.
40
- let request = try await config.requestResolver?().await().await() ?? config.request
41
- let browse = try await config.browseResolver?().await().await() ?? config.browse
40
+ let request = try await config.requestResolver?().awaitNested() ?? config.request
41
+ let browse = try await config.browseResolver?().awaitNested() ?? config.browse
42
42
  return ResolvedLayers(request: request, browse: browse)
43
43
  }
44
44
  }
@@ -246,6 +246,8 @@ final class RequestPipeline {
246
246
  headers: RequestLayer.imageHeaders(request),
247
247
  body: request.body,
248
248
  )
249
+ } catch is CancellationError {
250
+ return nil
249
251
  } catch {
250
252
  logger.error("Failed to transform artwork URL for track: \(track.title), error: \(error.localizedDescription)")
251
253
  return nil
@@ -258,12 +260,12 @@ final class RequestPipeline {
258
260
  /// bridge hop, then the JS promise): a single await hands a `Promise` downstream. Copies the
259
261
  /// result out.
260
262
  func awaitAsyncConfig(_ promise: Promise<Promise<RequestConfig>>) async throws -> RequestConfig {
261
- try await extractConfig(promise.await().await())
263
+ try await extractConfig(promise.awaitNested())
262
264
  }
263
265
 
264
266
  /// Awaits a sync config callback (one bridge await) and copies the result out.
265
267
  func awaitSyncConfig(_ promise: Promise<RequestConfig>) async throws -> RequestConfig {
266
- try await extractConfig(promise.await())
268
+ try await extractConfig(promise.awaitCancellable())
267
269
  }
268
270
 
269
271
  /// A copy of `config`, so nothing reads the Nitro bridge's value after its Promise is gone.
@@ -202,7 +202,7 @@ final class CarPlayNowPlayingManager {
202
202
  Task { @MainActor [weak self] in
203
203
  let path: String?
204
204
  do {
205
- path = try await resolver(track).await()
205
+ path = try await resolver(track).awaitCancellable()
206
206
  } catch {
207
207
  self?.logger.error("resolveAlbumPath failed: \(error.localizedDescription)")
208
208
  path = nil
@@ -48,6 +48,7 @@ extension CarPlaySession {
48
48
  await showNavigationError(.code(.emptyContent), path: path, on: template)
49
49
  }
50
50
  case let .failure(error):
51
+ guard !(error is CancellationError || Task.isCancelled) else { return }
51
52
  logger.error("Failed to load content for \(path): \(error.localizedDescription)")
52
53
  await showNavigationError(NavigationError.from(error), path: path, on: template)
53
54
  }
@@ -119,6 +119,8 @@ extension CarPlaySession {
119
119
  /// The chrome to show if the Browse Gate gates this request, reported to JS; nil when allowed.
120
120
  func gate(_ reason: GateReason, path: String?, search: SearchParams? = nil) async -> Gate? {
121
121
  let chrome = await audioBrowser.browseGate.decide(NativeGateRequest(reason: reason, path: path, search: search))
122
+ // A cancelled decision fails closed, but the user never met this gate.
123
+ guard !Task.isCancelled else { return chrome }
122
124
  reportGates([chrome], reason: reason)
123
125
  return chrome
124
126
  }
@@ -0,0 +1,33 @@
1
+ import NitroModules
2
+
3
+ /// Awaits for JS callbacks in place of Nitro's `await()`, which ignores cancellation: see
4
+ /// `awaitCallback`. The nested forms are for a callback returning a promise, which crosses the
5
+ /// bridge as `Promise<Promise<U>>`.
6
+ extension Promise {
7
+ func awaitCancellable() async throws -> T {
8
+ try await awaitCallback(subscribe)
9
+ }
10
+
11
+ /// Throws `CallbackTimeoutError` after `callbackFallbackTimeout`; only for a caller with a
12
+ /// fallback.
13
+ func awaitOrTimeout() async throws -> T {
14
+ try await awaitCallback(timeout: callbackFallbackTimeout, subscribe)
15
+ }
16
+
17
+ func awaitNested<U>() async throws -> U where T == Promise<U> {
18
+ try await awaitCallback(subscribeNested)
19
+ }
20
+
21
+ /// The timeout covers both promises.
22
+ func awaitNestedOrTimeout<U>() async throws -> U where T == Promise<U> {
23
+ try await awaitCallback(timeout: callbackFallbackTimeout, subscribeNested)
24
+ }
25
+
26
+ private func subscribe(_ deliver: @escaping @Sendable (Result<T, Error>) -> Void) {
27
+ then { deliver(.success($0)) }.catch { deliver(.failure($0)) }
28
+ }
29
+
30
+ private func subscribeNested<U>(_ deliver: @escaping @Sendable (Result<U, Error>) -> Void) where T == Promise<U> {
31
+ then { $0.subscribe(deliver) }.catch { deliver(.failure($0)) }
32
+ }
33
+ }
@@ -132,7 +132,7 @@ public extension HybridAudioBrowser {
132
132
  func retry() throws {
133
133
  // Re-resolves rather than replaying the cached URL: short-lived URLs or tokens may have
134
134
  // expired since the failure.
135
- onMainActor { player?.reloadResolving(startFromCurrentTime: true) }
135
+ onMainActor { player?.retryNow() }
136
136
  }
137
137
 
138
138
  // MARK: - Sleep Timer
@@ -262,7 +262,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
262
262
  }
263
263
  browseGate.resolve = { [weak self] request in
264
264
  guard let self else { throw CancellationError() }
265
- return try await resolveGate(request).await().await()
265
+ return try await resolveGate(request).awaitNestedOrTimeout()
266
266
  }
267
267
  // Unconditional: `shared` is weak, so after a reload the old instance may be gone while
268
268
  // CarPlay is still subscribed to its emitters.
@@ -54,7 +54,7 @@ final class MediaLoader {
54
54
  func resolveAndLoad(src: String, track: Track? = nil) {
55
55
  mediaResolverTask?.cancel()
56
56
  // `self` stays weak across the await: a consumer resolver that never settles must not pin
57
- // the loader, and cancellation cannot force its `await` to return.
57
+ // the loader.
58
58
  let resolveUrl = resolveUrl
59
59
  mediaResolverTask = Task { [weak self] in
60
60
  guard !Task.isCancelled else { return }
@@ -15,8 +15,8 @@ enum PlaybackFailure {
15
15
  /// The two answers rank the evidence differently, on purpose:
16
16
  /// - The error: a transport failure first (no response arrived, so a logged status belongs to
17
17
  /// an earlier attempt), then a non-2xx status, then undecodable media.
18
- /// - Retrying: a status first (a retry cannot change what the server refused), then the error
19
- /// chain. An unrecognized failure counts as retryable, bounded by the retry budgets, as on
18
+ /// - Retrying: a non-2xx status first (a retry cannot change what the server refused), then the
19
+ /// error chain. An unrecognized failure counts as retryable, bounded by the retry budgets, as on
20
20
  /// Android: AVFoundation reports most stream failures opaquely.
21
21
  static func classify(
22
22
  _ error: Error?,
@@ -93,7 +93,7 @@ enum PlaybackFailure {
93
93
  ])
94
94
 
95
95
  private static func isRetryable(_ error: Error?, httpStatusCode: Int?) -> Bool {
96
- if let status = httpStatusCode {
96
+ if let status = httpStatusCode, !(200 ... 299).contains(status) {
97
97
  return retryableHTTPStatusCodes.contains(status) || (500 ... 599).contains(status)
98
98
  }
99
99
  guard let error else { return false }
@@ -123,6 +123,11 @@ final class Player {
123
123
  deferredSeek.target ?? (enginePositionIsCurrent ? engine.resumePosition : nil)
124
124
  }
125
125
 
126
+ /// Where a reload resumes: nowhere after the end, or after a stop whose rewind may not have landed.
127
+ private var reloadPosition: TimeInterval? {
128
+ state == .ended || state == .stopped ? nil : resumePosition
129
+ }
130
+
126
131
  // MARK: - Track State (for active track changed events)
127
132
 
128
133
  private var lastIndex: Int = -1
@@ -183,18 +188,14 @@ final class Player {
183
188
  if newValue, resumes || state == .stopped || state == .ended {
184
189
  reloadResolving(startFromCurrentTime: resumes)
185
190
  }
186
- if state != .loading {
187
- if newValue { engine.play() } else { engine.pause() }
188
- }
191
+ // While loading, the engine may still hold the previous track's item: a play waits for the new one.
192
+ if !newValue { engine.pause() } else if state != .loading { engine.play() }
189
193
 
190
194
  guard changed else { return }
195
+ // A resume can find the state still .buffering (a pause near the end leaves it), with no watch.
196
+ if newValue, state == .buffering { retry.startStallWatch() }
191
197
  // Left to run, the retry would give up on the dropped intent and surface .error.
192
- if !newValue, retry.pendingTask != nil {
193
- retry.reset()
194
- if let position = resumePosition { deferredSeek.capture(position) }
195
- load?.reloadOnPlay = true
196
- transition(.retryCancelled)
197
- }
198
+ if !newValue, retry.pendingTask != nil { parkForReloadOnPlay() }
198
199
  // A pause during the sleep fade ends the timer early, restoring the pre-fade volume.
199
200
  if !newValue, sleepTimerManager.isFading { sleepTimerManager.clear() }
200
201
  publish()
@@ -252,9 +253,11 @@ final class Player {
252
253
 
253
254
  retry.onError = { [weak self] in self?.transition(.errorOccurred($0)) }
254
255
  retry.onRetryingError = { [weak self] in self?.reportRetryingError($0) }
256
+ retry.onFailedWithoutIntent = { [weak self] in self?.parkForReloadOnPlay() }
255
257
  retry.onRetry = { [weak self] in self?.reloadResolving(startFromCurrentTime: $0) }
256
258
  retry.shouldRetry = { [weak self] in self?.playWhenReady ?? false }
257
259
  retry.hasPlayed = { [weak self] in self?.load?.hasPlayed ?? false }
260
+ retry.bufferedPosition = { [weak self] in self?.engine.bufferedPosition ?? 0 }
258
261
  }
259
262
 
260
263
  /// Shows a failure the retry loop is still working on over the current state: not a
@@ -345,6 +348,11 @@ final class Player {
345
348
  } else if old == .playing {
346
349
  retry.playbackStoppedBeingAudible()
347
350
  }
351
+ if new == .buffering, playWhenReady {
352
+ retry.startStallWatch()
353
+ } else if old == .buffering {
354
+ retry.stopStallWatch()
355
+ }
348
356
 
349
357
  switch new {
350
358
  case .ready:
@@ -355,6 +363,10 @@ final class Player {
355
363
  case .ended:
356
364
  // A natural end exhausts the play intent; the setter also requests the session release.
357
365
  setPlayWhenReady(false)
366
+ case .error:
367
+ // A stall or a lost connection can fail an item that is still alive: data arriving later
368
+ // must not play it under the error.
369
+ engine.pause()
358
370
  default: break
359
371
  }
360
372
 
@@ -717,19 +729,34 @@ final class Player {
717
729
  transition(.errorOccurred(.invalidSourceUrl("nil")))
718
730
  return
719
731
  }
720
- prepareForReload(resumingAt: startFromCurrentTime ? resumePosition : nil)
732
+ prepareForReload(resumingAt: startFromCurrentTime ? reloadPosition : nil)
721
733
  engine.resolveAndLoad(src: src, track: track)
722
734
  }
723
735
 
736
+ /// The caller's retry: reloads now, resuming where it was, in place of any retry pending.
737
+ func retryNow() {
738
+ retry.cancel()
739
+ reloadResolving(startFromCurrentTime: true)
740
+ }
741
+
742
+ private func parkForReloadOnPlay() {
743
+ retry.reset()
744
+ if let position = reloadPosition { deferredSeek.capture(position) }
745
+ load?.reloadOnPlay = true
746
+ transition(.retryCancelled)
747
+ }
748
+
724
749
  /// A restart from a terminal error begins a new Load on a new AVPlayer; automatic retries
725
- /// never get here in .error, since the retry loop keeps the state non-terminal. `time`, else the
726
- /// pending target, is held as the deferred seek before the loading transition saves the snapshot.
750
+ /// never get here in .error, since the retry loop keeps the state non-terminal, but get a new
751
+ /// AVPlayer in the same Load when the AVPlayer itself failed. `time`, else the pending target,
752
+ /// is held as the deferred seek before the loading transition saves the snapshot.
727
753
  private func prepareForReload(resumingAt time: TimeInterval?) {
728
754
  load?.reloadOnPlay = false
729
755
  let target = time ?? deferredSeek.target
730
756
  deferredSeek.reset()
731
- if state == .error {
732
- beginLoad()
757
+ let restart = state == .error
758
+ if restart { beginLoad() }
759
+ if restart || engine.playerFailed {
733
760
  engine.clearItem()
734
761
  engine.recreate()
735
762
  } else {
@@ -749,11 +776,13 @@ final class Player {
749
776
  /// Recovers from a media-services reset: every AVPlayer and session handle is invalid, so a
750
777
  /// new player reloads the current track, keeping the play intent, so a live stream reconnects
751
778
  /// instead of going silent. An on-demand track resumes where it was, unless it ended, or was
752
- /// stopped and its rewind may not have landed. No-op when nothing is loaded.
779
+ /// stopped and its rewind may not have landed. Replaces any retry pending. No-op when nothing is
780
+ /// loaded.
753
781
  func mediaServicesWereReset() {
754
782
  guard let track = currentTrack else { return }
755
783
  logger.info("Media services were reset — recreating player and reloading current track")
756
- if track.live != true, state != .ended, state != .stopped, let position = resumePosition {
784
+ retry.cancel()
785
+ if track.live != true, let position = reloadPosition {
757
786
  deferredSeek.capture(position)
758
787
  }
759
788
  engine.clearItem()
@@ -792,8 +821,8 @@ final class Player {
792
821
  case .playedToEnd:
793
822
  itemDidPlayToEnd()
794
823
  case .stalled:
795
- // Nudge, don't reconnect: a genuine drop is recovered by the retry and network paths.
796
- recoverFromStall(reconnectIfLive: false)
824
+ // A nudge only: this also arrives while audio plays, so the stall watch keys on .buffering.
825
+ if playWhenReady, state != .error { engine.play() }
797
826
  case let .timedMetadata(metadata):
798
827
  callbacks?.playerDidReceiveTimedMetadata(metadata)
799
828
  engine.applyTimedMetadata(metadata)
@@ -833,43 +862,32 @@ final class Player {
833
862
  engine.primeNowPlaying()
834
863
  }
835
864
 
836
- /// A genuine end advances the queue; a dropped live stream or an underrun reported as an end
837
- /// is recovered instead (see `EndOfTrackJudgement`).
865
+ /// An on-demand item's end is the end, whatever its duration estimate said: a truncated file
866
+ /// stalls instead, which is the stall watch's. A live stream's is a dropped connection, a
867
+ /// failure for the retry loop, since AVPlayer will not play on from an item it has ended.
838
868
  private func itemDidPlayToEnd() {
839
- let judgement = EndOfTrackJudgement(
840
- isLive: currentTrack?.live == true,
841
- currentTime: engine.currentTime,
842
- duration: engine.duration,
843
- )
844
- switch judgement.outcome {
845
- case .ended: trackDidPlayToEnd()
846
- case .stalled: recoverFromStall(reconnectIfLive: true)
847
- }
848
- }
849
-
850
- /// Recovers from a stall while the play intent holds: a live stream that ran out of data
851
- /// (`reconnectIfLive`) rejoins the edge; otherwise play() un-parks AVPlayer from waiting.
852
- private func recoverFromStall(reconnectIfLive: Bool) {
853
- guard playWhenReady else { return }
854
- if reconnectIfLive, currentTrack?.live == true {
855
- seekToLiveEdge()
856
- } else {
857
- engine.play()
858
- }
869
+ guard currentTrack?.live == true else { return trackDidPlayToEnd() }
870
+ // The engine stops observing the item it replaces: an end delivered during the load is stale.
871
+ guard state != .loading else { return }
872
+ // AVPlayer pauses an ended item, which the play intent hides: the state would read playing.
873
+ if playWhenReady, retry.isEnabled { transition(.avPlayerWaiting) }
874
+ retry.handleFailure(.liveEnd)
859
875
  }
860
876
 
861
877
  private var previousTimeControlStatus: PlayerTimeControlStatus?
862
878
  private var previousWaitingForNoItem = false
863
879
 
864
880
  /// AVPlayer can strand itself in .paused after a `.noItemToPlay` wait over AirPlay while the
865
- /// intent is to play: play() is re-issued on exactly that transition.
881
+ /// intent is to play: play() is re-issued on exactly that transition. Outside the retry loop:
882
+ /// nothing failed, and play() is the whole recovery; an item that is dead fails, and that
883
+ /// failure goes through the loop.
866
884
  private func recoverIfAirPlayStalled(transitioningTo current: PlayerTimeControlStatus, waitingForNoItem: Bool) {
867
885
  let stalled = AirPlayStallJudgement(
868
886
  previous: previousTimeControlStatus,
869
887
  current: current,
870
888
  previousWaitingReasonWasNoItemToPlay: previousWaitingForNoItem,
871
889
  isAirPlay: engine.isAirPlayRoute,
872
- playWhenReady: playWhenReady,
890
+ playWhenReady: playWhenReady && state != .error,
873
891
  ).shouldNudge
874
892
  previousTimeControlStatus = current
875
893
  previousWaitingForNoItem = current == .waitingToPlayAtSpecifiedRate && waitingForNoItem
@@ -882,15 +900,15 @@ final class Player {
882
900
  // MARK: - Connectivity
883
901
 
884
902
  /// Re-renders the now-playing lines, whose stall line tells offline from buffering, and when
885
- /// connectivity returns re-establishes a stalled stream. AVPlayer doesn't reliably report a
886
- /// live stream's mid-stream drop as a failure: it waits with no error, so the retry loop never
887
- /// engages. Only while stalled (.buffering) with play intent, so a pause or a retry that gave up
888
- /// isn't resumed; and not while a retry is pending, which owns that reload.
903
+ /// connectivity returns retries a stalled stream at once, spending an attempt, rather than wait
904
+ /// for AVPlayer to fail it. Only while stalled (.buffering) with play intent, so a pause or a
905
+ /// retry that gave up isn't resumed; not while a retry is pending, whose wait watches connectivity
906
+ /// itself; and not with retry off, which leaves the stall to AVPlayer.
889
907
  func networkStatusDidChange(isOnline: Bool) {
890
908
  engine.renderNowPlaying()
891
- guard isOnline, playWhenReady, state == .buffering, retry.pendingTask == nil else { return }
892
- logger.info("Connectivity restored while stalled — re-resolving to reconnect")
893
- reloadResolving(startFromCurrentTime: true)
909
+ guard isOnline, playWhenReady, state == .buffering, retry.isEnabled, retry.pendingTask == nil else { return }
910
+ logger.info("Connectivity restored while stalled — retrying now")
911
+ retry.handleFailure(.stall, immediately: true)
894
912
  }
895
913
 
896
914
  /// Time playback must have progressed before a buffer dip counts as a stall, so the initial
@@ -62,6 +62,8 @@ enum EngineEvent {
62
62
  /// Drops the asset and removes the item.
63
63
  func clearItem()
64
64
  func stopObservingItem()
65
+ /// Whether the AVPlayer itself has failed, not only its item: it plays nothing until recreated.
66
+ var playerFailed: Bool { get }
65
67
  /// Replaces the AVPlayer: every handle to the old one is invalid.
66
68
  func recreate()
67
69