react-native-audio-browser 1.0.0-next.2 → 1.0.0-next.4

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 (190) hide show
  1. package/android/src/cast/java/com/audiobrowser/cast/CastSupport.kt +37 -14
  2. package/android/src/main/java/com/audiobrowser/AudioBrowser.kt +38 -10
  3. package/android/src/main/java/com/audiobrowser/Service.kt +6 -41
  4. package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt +40 -34
  5. package/android/src/main/java/com/audiobrowser/browser/BrowserUrlResolution.kt +6 -5
  6. package/android/src/main/java/com/audiobrowser/browser/JsonModels.kt +12 -7
  7. package/android/src/main/java/com/audiobrowser/extension/QueueIndex.kt +19 -0
  8. package/android/src/main/java/com/audiobrowser/http/HttpClient.kt +2 -1
  9. package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt +32 -18
  10. package/android/src/main/java/com/audiobrowser/model/PlayerSetupOptions.kt +2 -2
  11. package/android/src/main/java/com/audiobrowser/player/AutomaticBufferManager.kt +17 -16
  12. package/android/src/main/java/com/audiobrowser/player/InterceptingPlayer.kt +11 -0
  13. package/android/src/main/java/com/audiobrowser/player/MediaFactory.kt +5 -1
  14. package/android/src/main/java/com/audiobrowser/player/MediaSessionCallback.kt +28 -21
  15. package/android/src/main/java/com/audiobrowser/player/Player.kt +41 -31
  16. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +4 -0
  17. package/android/src/main/java/com/audiobrowser/player/ResolvingOnReloadSource.kt +38 -0
  18. package/android/src/main/java/com/audiobrowser/player/TransformingDataSource.kt +34 -19
  19. package/android/src/main/java/com/audiobrowser/remote/RemotePlayback.kt +10 -1
  20. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +48 -4
  21. package/android/src/main/java/com/audiobrowser/util/BrowserPathHelper.kt +32 -34
  22. package/android/src/main/java/com/audiobrowser/util/SearchParamsFactory.kt +64 -0
  23. package/android/src/test/java/com/audiobrowser/ContentRefreshNavigationErrorTest.kt +236 -0
  24. package/android/src/test/java/com/audiobrowser/NavigateTrackTest.kt +116 -0
  25. package/android/src/test/java/com/audiobrowser/TestFixtures.kt +41 -0
  26. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerBuildApiRequestTest.kt +21 -4
  27. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerFavoritesTest.kt +49 -0
  28. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerPageShapeTest.kt +93 -0
  29. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerUnparsableResponseTest.kt +82 -0
  30. package/android/src/test/java/com/audiobrowser/browser/BrowserUrlResolutionTest.kt +27 -0
  31. package/android/src/test/java/com/audiobrowser/browser/JsonArtworkTest.kt +7 -1
  32. package/android/src/test/java/com/audiobrowser/browser/JsonFavoritedTest.kt +34 -0
  33. package/android/src/test/java/com/audiobrowser/browser/JsonStyleTest.kt +6 -6
  34. package/android/src/test/java/com/audiobrowser/extension/QueueIndexTest.kt +44 -0
  35. package/android/src/test/java/com/audiobrowser/http/HttpClientTest.kt +34 -0
  36. package/android/src/test/java/com/audiobrowser/http/RequestConfigBuilderTest.kt +90 -7
  37. package/android/src/test/java/com/audiobrowser/model/PlayerSetupOptionsTest.kt +19 -2
  38. package/android/src/test/java/com/audiobrowser/player/AutomaticBufferManagerTest.kt +17 -0
  39. package/android/src/test/java/com/audiobrowser/player/FavoriteCapabilityTest.kt +41 -0
  40. package/android/src/test/java/com/audiobrowser/player/MediaFactoryTest.kt +39 -0
  41. package/android/src/test/java/com/audiobrowser/player/MediaUrlReloadTest.kt +212 -0
  42. package/android/src/test/java/com/audiobrowser/player/PlayerSeekSnapshotTest.kt +45 -0
  43. package/android/src/test/java/com/audiobrowser/player/SessionQueueShuffleOrderTest.kt +38 -0
  44. package/android/src/test/java/com/audiobrowser/player/SessionVoiceSearchTest.kt +173 -0
  45. package/android/src/test/java/com/audiobrowser/player/TransformingDataSourceTest.kt +127 -1
  46. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +28 -0
  47. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +116 -0
  48. package/android/src/test/java/com/audiobrowser/util/BrowserPathHelperTest.kt +44 -0
  49. package/android/src/testCast/java/com/audiobrowser/cast/SdkCastRemoteTest.kt +188 -0
  50. package/ios/Browser/BrowserError.swift +8 -0
  51. package/ios/Browser/BrowserManager.swift +29 -28
  52. package/ios/Browser/BrowserPathHelper.swift +26 -24
  53. package/ios/Browser/FavoriteSet.swift +16 -8
  54. package/ios/Browser/Favorites.swift +66 -0
  55. package/ios/Browser/JsonModels.swift +27 -7
  56. package/ios/Browser/NavigationErrorState.swift +18 -1
  57. package/ios/Browser/PageResolver.swift +2 -2
  58. package/ios/Browser/RequestLayer.swift +11 -4
  59. package/ios/Browser/RequestPipeline.swift +8 -4
  60. package/ios/Browser/TabBarEntries.swift +7 -0
  61. package/ios/CarPlay/CarPlayImageLoader.swift +3 -7
  62. package/ios/CarPlay/CarPlaySession+Navigator.swift +3 -1
  63. package/ios/CarPlay/IntentHandlers.swift +1 -7
  64. package/ios/CarPlay/MediaIntentCriteria.swift +4 -4
  65. package/ios/Extension/CGSize+AspectFit.swift +11 -0
  66. package/ios/Extension/Dictionary+Headers.swift +8 -0
  67. package/ios/Extension/NavigationError+Conversion.swift +4 -3
  68. package/ios/Extension/ResolvedTrack+Copying.swift +15 -0
  69. package/ios/Http/HttpClient.swift +37 -11
  70. package/ios/HybridAudioBrowser+Browser.swift +9 -16
  71. package/ios/HybridAudioBrowser+Options.swift +1 -0
  72. package/ios/HybridAudioBrowser+Player.swift +24 -23
  73. package/ios/HybridAudioBrowser+PlayerCallbacks.swift +1 -2
  74. package/ios/Model/NitroTypeStubs.swift +39 -0
  75. package/ios/Model/TrackPlayerError.swift +21 -2
  76. package/ios/Player/AudioSessionController.swift +2 -2
  77. package/ios/Player/MediaLoader.swift +1 -1
  78. package/ios/Player/PlaybackStateMachine.swift +1 -2
  79. package/ios/Player/Player.swift +59 -20
  80. package/ios/Player/PlayerEngine.swift +5 -0
  81. package/ios/Player/QueueManager.swift +21 -4
  82. package/ios/Tests/BrowserErrorTests.swift +21 -0
  83. package/ios/Tests/BrowserPathHelperTests.swift +18 -0
  84. package/ios/Tests/CGSizeAspectFitTests.swift +36 -0
  85. package/ios/Tests/ClampedVolumeTests.swift +26 -0
  86. package/ios/Tests/FavoriteSetTests.swift +68 -3
  87. package/ios/Tests/FavoritesTests.swift +102 -0
  88. package/ios/Tests/HttpClientUserAgentTests.swift +45 -0
  89. package/ios/Tests/JsonModelsTests.swift +74 -6
  90. package/ios/Tests/MediaIntentCriteriaTests.swift +11 -1
  91. package/ios/Tests/MediaLoaderAssetOptionsTests.swift +7 -0
  92. package/ios/Tests/NavigationErrorStateTests.swift +73 -0
  93. package/ios/Tests/PlaybackStateMachineTests.swift +6 -4
  94. package/ios/Tests/PlayerPolicyTests.swift +38 -0
  95. package/ios/Tests/PlayerProgressTests.swift +109 -0
  96. package/ios/Tests/PlayerTests.swift +106 -0
  97. package/ios/Tests/QueueIndexTests.swift +43 -0
  98. package/ios/Tests/QueueManagerTests.swift +79 -15
  99. package/ios/Tests/RequestLayerTests.swift +22 -3
  100. package/ios/Tests/TabBarEntriesTests.swift +19 -0
  101. package/ios/Tests/TrackSelectorTests.swift +154 -0
  102. package/ios/Tests/UnparsableResponseTests.swift +91 -0
  103. package/ios/TrackSelector.swift +28 -8
  104. package/ios/Util/ArtworkImageFetcher.swift +9 -8
  105. package/ios/Util/SVGProcessor.swift +6 -17
  106. package/lib/commonjs/features/browser-config.js +6 -3
  107. package/lib/commonjs/features/browser-config.js.map +1 -1
  108. package/lib/commonjs/features/errors.js +12 -7
  109. package/lib/commonjs/features/errors.js.map +1 -1
  110. package/lib/commonjs/features/nowPlaying.js +9 -3
  111. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  112. package/lib/commonjs/features/playback/controls.js +1 -2
  113. package/lib/commonjs/features/playback/controls.js.map +1 -1
  114. package/lib/commonjs/features/playback/trackPlaybackTime.js +2 -1
  115. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  116. package/lib/commonjs/features/player/setup.js +2 -2
  117. package/lib/commonjs/features/queue/activeTrack.js +4 -2
  118. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  119. package/lib/commonjs/features/sleepTimer.js +6 -5
  120. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  121. package/lib/commonjs/utils/LazyNativeEmitter.js +2 -1
  122. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  123. package/lib/commonjs/utils/NativeUpdatedValue.js +2 -1
  124. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  125. package/lib/commonjs/utils/callListener.js +23 -0
  126. package/lib/commonjs/utils/callListener.js.map +1 -0
  127. package/lib/module/features/browser-config.js +6 -3
  128. package/lib/module/features/browser-config.js.map +1 -1
  129. package/lib/module/features/errors.js +12 -7
  130. package/lib/module/features/errors.js.map +1 -1
  131. package/lib/module/features/nowPlaying.js +9 -3
  132. package/lib/module/features/nowPlaying.js.map +1 -1
  133. package/lib/module/features/playback/controls.js +1 -2
  134. package/lib/module/features/playback/controls.js.map +1 -1
  135. package/lib/module/features/playback/trackPlaybackTime.js +2 -1
  136. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  137. package/lib/module/features/player/setup.js +2 -2
  138. package/lib/module/features/queue/activeTrack.js +4 -2
  139. package/lib/module/features/queue/activeTrack.js.map +1 -1
  140. package/lib/module/features/sleepTimer.js +6 -5
  141. package/lib/module/features/sleepTimer.js.map +1 -1
  142. package/lib/module/utils/LazyNativeEmitter.js +2 -1
  143. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  144. package/lib/module/utils/NativeUpdatedValue.js +2 -1
  145. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  146. package/lib/module/utils/callListener.js +19 -0
  147. package/lib/module/utils/callListener.js.map +1 -0
  148. package/lib/typescript/src/features/browser-config.d.ts.map +1 -1
  149. package/lib/typescript/src/features/errors.d.ts +8 -6
  150. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  151. package/lib/typescript/src/features/nowPlaying.d.ts +2 -1
  152. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  153. package/lib/typescript/src/features/playback/controls.d.ts +1 -2
  154. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  155. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  156. package/lib/typescript/src/features/player/setup.d.ts +2 -2
  157. package/lib/typescript/src/features/queue/activeTrack.d.ts +2 -1
  158. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  159. package/lib/typescript/src/features/sleepTimer.d.ts +2 -1
  160. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  161. package/lib/typescript/src/types/browser.d.ts +3 -2
  162. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  163. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  164. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  165. package/lib/typescript/src/utils/callListener.d.ts +7 -0
  166. package/lib/typescript/src/utils/callListener.d.ts.map +1 -0
  167. package/package.json +1 -1
  168. package/src/features/browser-config.test.ts +15 -0
  169. package/src/features/browser-config.ts +6 -3
  170. package/src/features/errors.test.ts +83 -0
  171. package/src/features/errors.ts +12 -7
  172. package/src/features/hook-wiring.test.ts +11 -10
  173. package/src/features/nowPlaying.ts +9 -3
  174. package/src/features/playback/controls.ts +1 -2
  175. package/src/features/playback/trackPlaybackTime.test.ts +24 -1
  176. package/src/features/playback/trackPlaybackTime.ts +2 -1
  177. package/src/features/player/setup.ts +2 -2
  178. package/src/features/queue/activeTrack.test.ts +32 -0
  179. package/src/features/queue/activeTrack.ts +8 -2
  180. package/src/features/sleepTimer.test.ts +24 -0
  181. package/src/features/sleepTimer.ts +6 -5
  182. package/src/types/browser.ts +3 -2
  183. package/src/utils/LazyNativeEmitter.test.ts +32 -0
  184. package/src/utils/LazyNativeEmitter.ts +3 -1
  185. package/src/utils/NativeUpdatedValue.test.ts +32 -0
  186. package/src/utils/NativeUpdatedValue.ts +3 -1
  187. package/src/utils/callListener.ts +17 -0
  188. package/website/guide/configuration.md +3 -3
  189. package/website/guide/errors.md +3 -1
  190. package/website/guide/live-streams.md +22 -20
@@ -54,4 +54,19 @@ extension ResolvedTrack {
54
54
  icyCharset: icyCharset ?? self.icyCharset,
55
55
  )
56
56
  }
57
+
58
+ /// A copy with each section track `transform` returns a track for replaced; nil when it
59
+ /// replaces none.
60
+ func replacingEachTrack(_ transform: (Track) -> Track?) -> ResolvedTrack? {
61
+ guard let sections else { return nil }
62
+ var replaced = false
63
+ let updated = sections.map { section in
64
+ section.copying(children: section.children.map { track in
65
+ guard let replacement = transform(track) else { return track }
66
+ replaced = true
67
+ return replacement
68
+ })
69
+ }
70
+ return replaced ? copying(sections: updated) : nil
71
+ }
57
72
  }
@@ -1,6 +1,11 @@
1
1
  import Foundation
2
2
  import os.log
3
3
 
4
+ /// A response that failed with its HTTP status.
5
+ protocol HttpStatusError: LocalizedError {
6
+ var code: Int { get }
7
+ }
8
+
4
9
  /// Counterpart of the Kotlin `HttpClient`; change request building and error messages in both.
5
10
  final class HttpClient: @unchecked Sendable {
6
11
  static let defaultUserAgent = "react-native-audio-browser"
@@ -20,7 +25,7 @@ final class HttpClient: @unchecked Sendable {
20
25
  }
21
26
 
22
27
  /// A non-2xx response.
23
- struct HttpException: LocalizedError {
28
+ struct HttpException: HttpStatusError {
24
29
  let code: Int
25
30
  let responseBody: String
26
31
 
@@ -36,18 +41,26 @@ final class HttpClient: @unchecked Sendable {
36
41
  }
37
42
  }
38
43
 
44
+ /// A 2xx response whose body does not decode as the type asked for.
45
+ struct UndecodableResponse: HttpStatusError {
46
+ let code: Int
47
+ let reason: String
48
+
49
+ var errorDescription: String? {
50
+ reason
51
+ }
52
+ }
53
+
39
54
  enum HttpClientError: LocalizedError {
40
55
  case invalidUrl(String)
41
56
  case unsupportedMethod(HttpMethod)
42
57
  case notHttp
43
- case undecodable(String)
44
58
 
45
59
  var errorDescription: String? {
46
60
  switch self {
47
61
  case let .invalidUrl(url): "Invalid URL: \(url)"
48
62
  case let .unsupportedMethod(method): "Unsupported HTTP method: \(method.stringValue)"
49
63
  case .notHttp: "Invalid response type"
50
- case let .undecodable(reason): reason
51
64
  }
52
65
  }
53
66
  }
@@ -66,7 +79,7 @@ final class HttpClient: @unchecked Sendable {
66
79
  urlRequest.setValue(value, forHTTPHeaderField: name)
67
80
  }
68
81
  // A `User-Agent` header wins over `userAgent`, as in the media and artwork paths.
69
- if httpRequest.headers?["User-Agent"] == nil {
82
+ if urlRequest.value(forHTTPHeaderField: "User-Agent") == nil {
70
83
  urlRequest.setValue(httpRequest.userAgent, forHTTPHeaderField: "User-Agent")
71
84
  }
72
85
 
@@ -98,7 +111,8 @@ final class HttpClient: @unchecked Sendable {
98
111
  }
99
112
  }
100
113
 
101
- /// Sends `httpRequest` and decodes a 2xx body as `T`; any other status throws `HttpException`.
114
+ /// Sends `httpRequest` and decodes a 2xx body as `T`, throwing `UndecodableResponse` when it
115
+ /// does not decode; any other status throws `HttpException`.
102
116
  /// A GET sends no body; HEAD and OPTIONS throw `HttpClientError.unsupportedMethod`.
103
117
  func requestJson<T: Decodable>(_ httpRequest: HttpRequest, as type: T.Type) async throws -> T {
104
118
  let (code, data) = try await request(httpRequest)
@@ -107,12 +121,24 @@ final class HttpClient: @unchecked Sendable {
107
121
  }
108
122
  do {
109
123
  return try JSONDecoder().decode(type, from: data)
110
- } catch let DecodingError.keyNotFound(key, context) {
111
- throw HttpClientError.undecodable("Missing required key '\(key.stringValue)' at path: \(Self.path(context))")
112
- } catch let DecodingError.typeMismatch(type, context) {
113
- throw HttpClientError.undecodable("Type mismatch for \(type) at path: \(Self.path(context))")
114
- } catch let DecodingError.valueNotFound(type, context) {
115
- throw HttpClientError.undecodable("Value not found for \(type) at path: \(Self.path(context))")
124
+ } catch {
125
+ throw UndecodableResponse(code: code, reason: Self.reason(error))
126
+ }
127
+ }
128
+
129
+ private static func reason(_ error: Error) -> String {
130
+ guard let error = error as? DecodingError else { return error.localizedDescription }
131
+ return switch error {
132
+ case let .keyNotFound(key, context):
133
+ "Missing required key '\(key.stringValue)' at path: \(path(context))"
134
+ case let .typeMismatch(type, context):
135
+ "Type mismatch for \(type) at path: \(path(context))"
136
+ case let .valueNotFound(type, context):
137
+ "Value not found for \(type) at path: \(path(context))"
138
+ case let .dataCorrupted(context):
139
+ context.debugDescription
140
+ @unknown default:
141
+ error.localizedDescription
116
142
  }
117
143
  }
118
144
 
@@ -18,17 +18,11 @@ public extension HybridAudioBrowser {
18
18
  }
19
19
 
20
20
  @MainActor
21
- private func loadPath(_ path: String) async {
22
- do {
23
- try await browserManager.load(path)
24
- } catch {
25
- await reportNavigationError(error, path: path)
26
- }
27
- }
28
-
29
- @MainActor
30
- private func reportNavigationError(_ error: Error, path: String) async {
31
- await navigationError.report(NavigationError.from(error)) { [browserManager] in
21
+ private func loadPath(_ path: String, bypassCache: Bool = false) async {
22
+ await navigationError.follow(
23
+ { try await browserManager.load(path, bypassCache: bypassCache) },
24
+ describe: { NavigationError.from($0) },
25
+ ) { [browserManager] in
32
26
  await browserManager.formatted($0, path: path)
33
27
  }
34
28
  }
@@ -46,7 +40,7 @@ public extension HybridAudioBrowser {
46
40
  switch result {
47
41
  case let .play(intent):
48
42
  player.execute(intent)
49
- case .intercepted:
43
+ case .intercepted, .superseded:
50
44
  break
51
45
  case let .browse(path):
52
46
  navigate(path, clearError: true)
@@ -88,14 +82,13 @@ public extension HybridAudioBrowser {
88
82
  return browserManager.path == path
89
83
  }
90
84
  externalContentChangedEmitter.emit(path)
91
- if isCurrentPath { Task { @MainActor in await loadPath(path) } }
85
+ if isCurrentPath { Task { @MainActor in await loadPath(path, bypassCache: true) } }
92
86
  }
93
87
 
94
88
  func invalidateAllContent() throws {
95
89
  onMainActor {
96
- browserManager.invalidateAll { error, path in
97
- await self.reportNavigationError(error, path: path)
98
- }
90
+ browserManager.invalidateAll()
91
+ Task { @MainActor in await loadPath(browserManager.path, bypassCache: true) }
99
92
  }
100
93
  externalContentChangedEmitter.emit(Self.invalidateAllSentinel)
101
94
  }
@@ -35,6 +35,7 @@ public extension HybridAudioBrowser {
35
35
  engine = newEngine
36
36
  player = newPlayer
37
37
  audioSession.player = newPlayer
38
+ browserManager.favorites.queue = newPlayer
38
39
 
39
40
  // `options.keepSessionAliveOnError` is ignored: on iOS an error never clears the now-playing
40
41
  // info, and next/previous follow the queue, not the state.
@@ -71,7 +71,11 @@ public extension HybridAudioBrowser {
71
71
  }
72
72
 
73
73
  func setVolume(level: Double) throws {
74
- onMainActor { engine?.volume = Float(level) }
74
+ guard let volume = clampedVolume(level) else {
75
+ logger.error("setVolume ignored a NaN level")
76
+ return
77
+ }
78
+ onMainActor { engine?.volume = volume }
75
79
  }
76
80
 
77
81
  func getVolume() throws -> Double {
@@ -90,8 +94,8 @@ public extension HybridAudioBrowser {
90
94
  onMainActor {
91
95
  Progress(
92
96
  position: player?.currentTime ?? 0,
93
- duration: engine?.duration ?? 0,
94
- buffered: engine?.bufferedPosition ?? 0,
97
+ duration: player?.duration ?? 0,
98
+ buffered: player?.bufferedPosition ?? 0,
95
99
  )
96
100
  }
97
101
  }
@@ -167,7 +171,7 @@ public extension HybridAudioBrowser {
167
171
  try onMainActor {
168
172
  guard let player else { return }
169
173
  if let index = insertBeforeIndex {
170
- try player.add(tracks, at: Int(index))
174
+ try player.add(tracks, at: Int(queueIndex: index))
171
175
  } else {
172
176
  try player.add(tracks)
173
177
  }
@@ -176,7 +180,7 @@ public extension HybridAudioBrowser {
176
180
 
177
181
  func move(fromIndex: Double, toIndex: Double) throws {
178
182
  try onMainActor {
179
- try player?.move(fromIndex: Int(fromIndex), toIndex: Int(toIndex))
183
+ try player?.move(fromIndex: Int(queueIndex: fromIndex), toIndex: Int(queueIndex: toIndex))
180
184
  }
181
185
  }
182
186
 
@@ -184,8 +188,8 @@ public extension HybridAudioBrowser {
184
188
  try onMainActor {
185
189
  guard let player else { return }
186
190
  // Highest index first, so earlier removals don't shift the ones still to go.
187
- for index in indexes.sorted().reversed() {
188
- try player.remove(Int(index))
191
+ for index in try indexes.map({ try Int(queueIndex: $0) }).sorted().reversed() {
192
+ try player.remove(index)
189
193
  }
190
194
  }
191
195
  }
@@ -196,7 +200,7 @@ public extension HybridAudioBrowser {
196
200
 
197
201
  func skip(index: Double, initialPosition: Double?) throws {
198
202
  try onMainActor {
199
- try player?.skipTo(Int(index))
203
+ try player?.skipTo(Int(queueIndex: index))
200
204
  if let position = initialPosition.flatMap({ finite($0, "skip") }) {
201
205
  player?.seek(to: position)
202
206
  }
@@ -222,20 +226,18 @@ public extension HybridAudioBrowser {
222
226
  }
223
227
 
224
228
  func setActiveTrackFavorited(favorited: Bool) throws {
225
- try favoriteActiveTrack(favorited)
229
+ favoriteActiveTrack(favorited)
226
230
  }
227
231
 
228
- /// Sets the active track's favorite state: in the favorite set first, so the now-playing
229
- /// heart (hydrated from it) flips at once, then on the queued track. False when nothing is
230
- /// playing or the track has no identity.
232
+ /// Sets the active track's favorite state in the favorite set, which restamps every copy of
233
+ /// the track, on screen and queued. False when nothing is playing or the track has no
234
+ /// identity.
231
235
  @discardableResult
232
- internal func favoriteActiveTrack(_ favorited: Bool) throws -> Bool {
233
- try onMainActor {
236
+ internal func favoriteActiveTrack(_ favorited: Bool) -> Bool {
237
+ onMainActor {
234
238
  guard let player, let track = player.currentTrack, let identity = track.identity else { return false }
235
239
  browserManager.setFavorited(identity: identity, favorited: favorited)
236
- // Hydration never overrides a track's own flag, so the queued copy must carry it.
237
- let updated = track.copying(favorited: favorited)
238
- try player.replace(player.queue.currentIndex, updated)
240
+ let updated = player.currentTrack ?? track
239
241
  // The only emit: a favorite toggle mutates the active track in place, so
240
242
  // onPlaybackActiveTrackChanged stays transition-only.
241
243
  let event = FavoriteChangedEvent(track: updated, favorited: favorited)
@@ -250,7 +252,7 @@ public extension HybridAudioBrowser {
250
252
  }
251
253
 
252
254
  func toggleActiveTrackFavorited() throws {
253
- try favoriteActiveTrack(!isActiveTrackFavorited())
255
+ favoriteActiveTrack(!isActiveTrackFavorited())
254
256
  }
255
257
 
256
258
  func setQueue(tracks: [Track], startIndex: Double?, startPosition: Double?) throws {
@@ -258,7 +260,7 @@ public extension HybridAudioBrowser {
258
260
  guard let player else { return }
259
261
  try player.setQueue(
260
262
  tracks,
261
- initialIndex: startIndex.map { Int($0) } ?? 0,
263
+ initialIndex: startIndex.map { try Int(queueIndex: $0) } ?? 0,
262
264
  startPositionMs: startPosition.flatMap { finite($0, "setQueue") }.map { $0 * 1000 },
263
265
  )
264
266
  }
@@ -274,8 +276,7 @@ public extension HybridAudioBrowser {
274
276
 
275
277
  func getTrack(index: Double) throws -> Track? {
276
278
  onMainActor {
277
- guard let tracks = player?.tracks else { return nil }
278
- let i = Int(index)
279
+ guard let tracks = player?.tracks, let i = try? Int(queueIndex: index) else { return nil }
279
280
  guard i >= 0, i < tracks.count else { return nil }
280
281
  return tracks[i]
281
282
  }
@@ -289,8 +290,8 @@ public extension HybridAudioBrowser {
289
290
  }
290
291
 
291
292
  func getActiveTrack() throws -> Track? {
292
- // The now-playing track is loaded outside the browse cache: a missing `favorited` is filled
293
- // from the favorite set, but a track's own value wins, so writers must update the queued copy too.
293
+ // A queued track that carries no `favorited` (a queue set from JS) is filled from the
294
+ // favorite set; one that carries it is kept current by `setFavorites` and the heart toggle.
294
295
  onMainActor { player?.currentTrack.map(browserManager.hydrateFavorite) }
295
296
  }
296
297
 
@@ -13,8 +13,7 @@ extension HybridAudioBrowser: PlayerCallbacks, AVPlayerEngineCallbacks {
13
13
  }
14
14
 
15
15
  public func playerDidChangeActiveTrack(_ event: PlaybackActiveTrackChangedEvent) {
16
- // The queue track's `favorited` is not kept in sync; hydrate it so useActiveTrack matches
17
- // getActiveTrack().
16
+ // A queued track that carries no `favorited` is hydrated here, as getActiveTrack() does.
18
17
  let hydrated = PlaybackActiveTrackChangedEvent(
19
18
  lastIndex: event.lastIndex,
20
19
  lastTrack: event.lastTrack,
@@ -121,6 +121,45 @@
121
121
  case delete
122
122
  case head
123
123
  case options
124
+
125
+ var stringValue: String {
126
+ switch self {
127
+ case .get: "GET"
128
+ case .post: "POST"
129
+ case .put: "PUT"
130
+ case .patch: "PATCH"
131
+ case .delete: "DELETE"
132
+ case .head: "HEAD"
133
+ case .options: "OPTIONS"
134
+ }
135
+ }
136
+ }
137
+
138
+ enum NavigationErrorType {
139
+ case contentNotFound
140
+ case networkError
141
+ case httpError
142
+ case callbackError
143
+ case unknownError
144
+ case emptyContent
145
+ case timeout
146
+ }
147
+
148
+ struct NavigationError: Equatable {
149
+ var code: NavigationErrorType
150
+ var message: String
151
+ var statusCode: Double?
152
+ var statusCodeSuccess: Bool?
153
+ }
154
+
155
+ struct FormattedNavigationError: Equatable {
156
+ var title: String
157
+ var message: String?
158
+ }
159
+
160
+ enum NavigationErrorKind {
161
+ case browse
162
+ case search
124
163
  }
125
164
 
126
165
  enum SearchMode {
@@ -18,7 +18,8 @@ public enum TrackPlayerError: Error {
18
18
 
19
19
  public enum QueueError: Error {
20
20
  case noCurrentItem
21
- case invalidIndex(index: Int, message: String)
21
+ /// `index` is nil when the number JS passed names no `Int`.
22
+ case invalidIndex(index: Int?, message: String)
22
23
  case empty
23
24
  case invalidTrack(title: String)
24
25
  }
@@ -52,8 +53,10 @@ extension TrackPlayerError.QueueError: LocalizedError {
52
53
  switch self {
53
54
  case .noCurrentItem:
54
55
  "No current track"
55
- case let .invalidIndex(index, message):
56
+ case let .invalidIndex(index?, message):
56
57
  "Invalid track index \(index): \(message)"
58
+ case let .invalidIndex(nil, message):
59
+ "Invalid track index: \(message)"
57
60
  case .empty:
58
61
  "Queue is empty"
59
62
  case let .invalidTrack(title):
@@ -62,6 +65,22 @@ extension TrackPlayerError.QueueError: LocalizedError {
62
65
  }
63
66
  }
64
67
 
68
+ // MARK: - Index Conversion
69
+
70
+ extension Int {
71
+ /// The queue index a JS number names, its fraction dropped. Throws `QueueError.invalidIndex`
72
+ /// for a number no `Int` holds: NaN, infinite, or beyond `Int`'s range.
73
+ init(queueIndex number: Double) throws {
74
+ guard let index = Int(exactly: number.rounded(.towardZero)) else {
75
+ throw TrackPlayerError.QueueError.invalidIndex(
76
+ index: nil,
77
+ message: "index must be a finite number within the range of Int, got \(number)",
78
+ )
79
+ }
80
+ self = index
81
+ }
82
+ }
83
+
65
84
  // MARK: - Cross-platform Classification
66
85
 
67
86
  public extension TrackPlayerError.PlaybackError {
@@ -4,7 +4,7 @@ import NitroModules
4
4
  /// What `AudioSessionController` tells the player about the audio session.
5
5
  @MainActor
6
6
  protocol AudioSessionPlayer: AnyObject {
7
- var playWhenReady: Bool { get }
7
+ var canReleaseAudioSession: Bool { get }
8
8
  var willResumeAfterInterruption: Bool { get }
9
9
  func handleInterruptionBegan()
10
10
  func handleInterruptionEnded(shouldResume: Bool)
@@ -108,7 +108,7 @@ final class AudioSessionController {
108
108
  func scheduleRelease() {
109
109
  releaseWork?.cancel()
110
110
  let release = DispatchWorkItem { [weak self] in
111
- guard let self, player?.playWhenReady == false else { return }
111
+ guard let self, player?.canReleaseAudioSession == true else { return }
112
112
  releaseWork = nil
113
113
  activationQueue.async {
114
114
  try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
@@ -174,7 +174,7 @@ final class MediaLoader {
174
174
  userAgent: String?,
175
175
  ) -> [String: Any]? {
176
176
  var merged = headers ?? [:]
177
- if let userAgent, !userAgent.isEmpty, merged["User-Agent"] == nil {
177
+ if let userAgent, !userAgent.isEmpty, !merged.hasHeader("User-Agent") {
178
178
  merged["User-Agent"] = userAgent
179
179
  }
180
180
  return merged.isEmpty ? nil : ["AVURLAssetHTTPHeaderFieldsKey": merged]
@@ -20,11 +20,10 @@ func nextPlaybackState(from current: PlaybackState, on event: PlaybackEvent) ->
20
20
  return .ready
21
21
  case let .avPlayerPaused(hasAsset):
22
22
  guard current != .stopped else { return nil }
23
- if !hasAsset { return PlaybackState.none }
24
23
  // .error and .ended hold against stray pause observations; .ended sees them because the
25
24
  // natural-end intent clear opens the call site's `!playWhenReady` gate.
26
25
  guard current != .error, current != .ended else { return nil }
27
- return .paused
26
+ return hasAsset ? .paused : PlaybackState.none
28
27
  case .bufferingSufficient:
29
28
  // .ended still has the play intent: a move to .ready would restart the finished track.
30
29
  guard current != .playing, !current.isTerminal else { return nil }
@@ -29,9 +29,9 @@ final class Player {
29
29
  guard let self, queue.currentIndex >= 0 else { return }
30
30
  let progressEvent = PlaybackProgressUpdatedEvent(
31
31
  track: Double(queue.currentIndex),
32
- position: engine.currentTime,
33
- duration: engine.duration,
34
- buffered: engine.bufferedPosition,
32
+ position: currentTime,
33
+ duration: duration,
34
+ buffered: bufferedPosition,
35
35
  )
36
36
  callbacks?.playerDidUpdateProgress(progressEvent)
37
37
  }
@@ -101,8 +101,7 @@ final class Player {
101
101
  ) { [unowned self] in
102
102
  currentTrack.map {
103
103
  PlaybackPersistence.snapshot(
104
- of: $0, state: state, position: deferredSeek.target ?? (enginePositionIsCurrent ? engine.currentTime : 0),
105
- repeatMode: repeatMode,
104
+ of: $0, state: state, position: currentTime, repeatMode: repeatMode,
106
105
  shuffleEnabled: shuffleEnabled, rate: rate,
107
106
  )
108
107
  }
@@ -120,6 +119,27 @@ final class Player {
120
119
  !awaitingItem && load?.itemPrepared == true
121
120
  }
122
121
 
122
+ /// Whether the engine's item is one of this Load's, which a reload of the track keeps until the
123
+ /// next is prepared.
124
+ private var engineItemIsCurrent: Bool {
125
+ load?.itemPrepared == true
126
+ }
127
+
128
+ /// The current track's position: a pending seek's target, and 0 before the engine reports it.
129
+ var currentTime: Double {
130
+ deferredSeek.target ?? (enginePositionIsCurrent ? engine.currentTime : 0)
131
+ }
132
+
133
+ /// The current track's duration, 0 until one of its items is in the engine.
134
+ var duration: Double {
135
+ engineItemIsCurrent ? engine.duration : 0
136
+ }
137
+
138
+ /// How far the current track is buffered, 0 until one of its items is in the engine.
139
+ var bufferedPosition: Double {
140
+ engineItemIsCurrent ? engine.bufferedPosition : 0
141
+ }
142
+
123
143
  private var resumePosition: TimeInterval? {
124
144
  deferredSeek.target ?? (enginePositionIsCurrent ? engine.resumePosition : nil)
125
145
  }
@@ -140,7 +160,6 @@ final class Player {
140
160
  var queueVersion: Int { queue.version }
141
161
  var queueSourcePath: String? { queue.queueSourcePath }
142
162
  var currentTrack: Track? { queue.currentTrack }
143
- var currentTime: Double { engine.currentTime }
144
163
  var nitroPlaybackError: PlaybackError? { errorStatus.nitroError }
145
164
 
146
165
  var repeatMode: RepeatMode {
@@ -300,9 +319,7 @@ final class Player {
300
319
  state = newState
301
320
  applySideEffects(old: oldState, new: newState)
302
321
  publish()
303
- // While nothing plays, no periodic save runs: every transition rewrites the snapshot, so it
304
- // never keeps a position from before a track change or a seek.
305
- if !(playbackActive && playWhenReady) { persistence.save() }
322
+ saveSnapshotWhileNothingPlays()
306
323
  // Repeat modes never end the queue (matches web's endsQueue()): a repeat-track pause at the
307
324
  // track boundary (e.g. the end-of-track sleep timer) must not read as "playlist over".
308
325
  if newState == .ended, queue.isLastInPlaybackOrder, repeatMode == .off {
@@ -388,6 +405,8 @@ final class Player {
388
405
  // must not play it under the error.
389
406
  engine.pause()
390
407
  retry.cancel()
408
+ // The intent holds through .error: no pause follows to request the release.
409
+ if playWhenReady { evaluateSessionRelease() }
391
410
  default: break
392
411
  }
393
412
 
@@ -441,8 +460,9 @@ final class Player {
441
460
  /// iOS has already paused the AVPlayer, but that pause is swallowed while the intent holds, so
442
461
  /// the paused state is forced here.
443
462
  func handleInterruptionBegan() {
444
- // A nested interruption keeps the intent the first one captured.
445
- shouldResumeAfterInterruption = shouldResumeAfterInterruption || playWhenReady
463
+ // A nested interruption keeps what the first one captured. `.error` holds the intent with
464
+ // nothing playing: there is nothing to resume.
465
+ shouldResumeAfterInterruption = shouldResumeAfterInterruption || playingState.playing
446
466
  pause()
447
467
  if playbackActive, state != .loading, state != .paused {
448
468
  transition(.avPlayerPaused(hasAsset: engine.hasLoadedAsset))
@@ -462,14 +482,18 @@ final class Player {
462
482
  }
463
483
  }
464
484
 
465
- /// Requests a session release once playback is deliberately stopped: no intent, no
466
- /// interruption to resume from, and no retry pending, whose reconnect needs the session. The
467
- /// engine debounces it.
485
+ /// Whether nothing needs the audio session: playback is deliberately stopped or has failed for
486
+ /// good (`.error` keeps the intent), with no interruption to resume from and no retry pending,
487
+ /// whose reconnect needs the session.
488
+ var canReleaseAudioSession: Bool {
489
+ (!playWhenReady || state == .error)
490
+ && !shouldResumeAfterInterruption
491
+ && retry.pendingTask == nil
492
+ }
493
+
494
+ /// Requests a session release when nothing needs the session. The engine debounces it.
468
495
  private func evaluateSessionRelease() {
469
- guard !playWhenReady,
470
- !shouldResumeAfterInterruption,
471
- retry.pendingTask == nil
472
- else { return }
496
+ guard canReleaseAudioSession else { return }
473
497
  engine.scheduleAudioSessionRelease()
474
498
  }
475
499
 
@@ -521,6 +545,12 @@ final class Player {
521
545
  try afterQueueMutation(queue.replace(index, track))
522
546
  }
523
547
 
548
+ /// Replaces, in place, each track `transform` returns a track for; the current track keeps
549
+ /// playing.
550
+ func replaceEach(_ transform: (Track) -> Track?) {
551
+ afterQueueMutation(queue.replaceEach(transform))
552
+ }
553
+
524
554
  func setQueue(
525
555
  _ newTracks: [Track],
526
556
  initialIndex: Int = 0,
@@ -642,6 +672,8 @@ final class Player {
642
672
  defer { pushSkipAvailability() }
643
673
  sleepTimerManager.onTrackChanged()
644
674
 
675
+ // Read before the new Load replaces the one it belongs to.
676
+ let lastPosition = currentTime
645
677
  engine.cancelLoading()
646
678
  beginLoad()
647
679
  if let start { deferredSeek.capture(start) }
@@ -649,7 +681,6 @@ final class Player {
649
681
  // Published by the .trackLoading or .trackUnloaded transition below, even when it is a no-op.
650
682
  errorStatus = .none
651
683
 
652
- let lastPosition = engine.currentTime
653
684
  let shouldContinuePlayback = playWhenReady
654
685
  engine.nowPlayingTrackChanged()
655
686
  if let currentTrack {
@@ -688,6 +719,12 @@ final class Player {
688
719
  lastIndex = queue.currentIndex
689
720
  }
690
721
 
722
+ /// While nothing plays, no periodic save runs: every transition and every seek rewrites the
723
+ /// snapshot, so it never keeps a position from before a track change or a seek.
724
+ private func saveSnapshotWhileNothingPlays() {
725
+ if !(playbackActive && playWhenReady) { persistence.save() }
726
+ }
727
+
691
728
  // MARK: - Seeking
692
729
 
693
730
  /// Seeks the current item. While it awaits the next item, or in .error for the restart, the
@@ -698,6 +735,7 @@ final class Player {
698
735
  completion(false)
699
736
  } else if awaitingItem || state == .error {
700
737
  deferredSeek.capture(seconds)
738
+ saveSnapshotWhileNothingPlays()
701
739
  completion(false)
702
740
  } else if engine.hasItem {
703
741
  seekItem(to: seconds, completion: completion)
@@ -739,6 +777,7 @@ final class Player {
739
777
  return
740
778
  }
741
779
  seekDidLand(finished: finished)
780
+ if finished { saveSnapshotWhileNothingPlays() }
742
781
  completion(finished)
743
782
  }
744
783
  }
@@ -939,7 +978,7 @@ final class Player {
939
978
  recoverIfAirPlayStalled(transitioningTo: status, waitingForNoItem: waitingForNoItem)
940
979
  timeControlStatusDidChange(status)
941
980
  case .audioDidStart:
942
- if !awaitingItem { transition(.audioFrameDecoded) }
981
+ if !awaitingItem, playWhenReady { transition(.audioFrameDecoded) }
943
982
  case .playedToEnd:
944
983
  itemDidPlayToEnd()
945
984
  case .stalled:
@@ -28,6 +28,11 @@ enum EngineEvent {
28
28
  case timedMetadata(TimedMetadata)
29
29
  }
30
30
 
31
+ /// `level` clamped to the engine's 0–1 volume; nil for NaN, which is nearer neither end.
32
+ func clampedVolume(_ level: Double) -> Float? {
33
+ level.isNaN ? nil : Float(min(max(level, 0), 1))
34
+ }
35
+
31
36
  /// The media stack under the Player: the AVPlayer and its items, loading, now playing, remote
32
37
  /// commands and the audio session. It carries out what the Player decides and reports what it
33
38
  /// observes through `onEvent`; it holds no playback policy (ADR 0012). Tests use a mock.