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

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 (329) hide show
  1. package/android/src/cast/java/com/audiobrowser/cast/CastSupport.kt +8 -10
  2. package/android/src/main/java/com/audiobrowser/AudioBrowser.kt +96 -243
  3. package/android/src/main/java/com/audiobrowser/AudioBrowserLifecycleModule.kt +8 -12
  4. package/android/src/main/java/com/audiobrowser/AudioBrowserPackage.kt +1 -3
  5. package/android/src/main/java/com/audiobrowser/Callbacks.kt +1 -10
  6. package/android/src/main/java/com/audiobrowser/ForegroundStart.kt +13 -18
  7. package/android/src/main/java/com/audiobrowser/HeadlessTaskService.kt +3 -7
  8. package/android/src/main/java/com/audiobrowser/RemoteOutputs.kt +8 -10
  9. package/android/src/main/java/com/audiobrowser/Service.kt +20 -61
  10. package/android/src/main/java/com/audiobrowser/ServiceBinding.kt +9 -17
  11. package/android/src/main/java/com/audiobrowser/browser/ArtworkResolutionRegistry.kt +10 -9
  12. package/android/src/main/java/com/audiobrowser/browser/BrowseArtworkRegistry.kt +11 -8
  13. package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt +117 -448
  14. package/android/src/main/java/com/audiobrowser/browser/BrowserUrlResolution.kt +21 -60
  15. package/android/src/main/java/com/audiobrowser/browser/InertStyleDiagnostic.kt +20 -80
  16. package/android/src/main/java/com/audiobrowser/browser/JsonArtwork.kt +6 -10
  17. package/android/src/main/java/com/audiobrowser/browser/JsonModels.kt +7 -24
  18. package/android/src/main/java/com/audiobrowser/browser/RouteMatch.kt +2 -4
  19. package/android/src/main/java/com/audiobrowser/browser/SectionScope.kt +13 -31
  20. package/android/src/main/java/com/audiobrowser/browser/SimpleRouter.kt +12 -40
  21. package/android/src/main/java/com/audiobrowser/browser/StyleResolver.kt +15 -26
  22. package/android/src/main/java/com/audiobrowser/browser/TrackLoadHandler.kt +5 -15
  23. package/android/src/main/java/com/audiobrowser/extension/EnumExtensions.kt +1 -0
  24. package/android/src/main/java/com/audiobrowser/extension/NumberExt.kt +2 -0
  25. package/android/src/main/java/com/audiobrowser/extension/ResolvedTrackExt.kt +4 -8
  26. package/android/src/main/java/com/audiobrowser/extension/TappedTrack.kt +4 -6
  27. package/android/src/main/java/com/audiobrowser/extension/TrackIdentity.kt +3 -7
  28. package/android/src/main/java/com/audiobrowser/http/HttpClient.kt +13 -22
  29. package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt +17 -38
  30. package/android/src/main/java/com/audiobrowser/model/IcyTitle.kt +5 -6
  31. package/android/src/main/java/com/audiobrowser/model/PlaybackMetadata.kt +4 -9
  32. package/android/src/main/java/com/audiobrowser/model/PlayerSetupOptions.kt +18 -29
  33. package/android/src/main/java/com/audiobrowser/model/PlayerUpdateOptions.kt +6 -16
  34. package/android/src/main/java/com/audiobrowser/player/AutomaticBufferManager.kt +15 -45
  35. package/android/src/main/java/com/audiobrowser/player/CapabilityControls.kt +23 -59
  36. package/android/src/main/java/com/audiobrowser/player/CrossOriginHeaderStripper.kt +14 -26
  37. package/android/src/main/java/com/audiobrowser/player/DynamicLoadControl.kt +15 -43
  38. package/android/src/main/java/com/audiobrowser/player/EnginePlayback.kt +4 -4
  39. package/android/src/main/java/com/audiobrowser/player/EqualizerController.kt +15 -21
  40. package/android/src/main/java/com/audiobrowser/player/InterceptingPlayer.kt +14 -31
  41. package/android/src/main/java/com/audiobrowser/player/LocalEngine.kt +8 -8
  42. package/android/src/main/java/com/audiobrowser/player/MediaFactory.kt +16 -27
  43. package/android/src/main/java/com/audiobrowser/player/MediaSessionCallback.kt +119 -237
  44. package/android/src/main/java/com/audiobrowser/player/MediaSessionCommandManager.kt +48 -145
  45. package/android/src/main/java/com/audiobrowser/player/NowPlayingUpdater.kt +39 -100
  46. package/android/src/main/java/com/audiobrowser/player/PlaybackErrorClassifier.kt +16 -26
  47. package/android/src/main/java/com/audiobrowser/player/PlaybackStateMachine.kt +22 -28
  48. package/android/src/main/java/com/audiobrowser/player/PlaybackStateStore.kt +28 -64
  49. package/android/src/main/java/com/audiobrowser/player/PlaybackTimer.kt +8 -4
  50. package/android/src/main/java/com/audiobrowser/player/Player.kt +117 -405
  51. package/android/src/main/java/com/audiobrowser/player/PlayerCapabilitiesExt.kt +1 -1
  52. package/android/src/main/java/com/audiobrowser/player/PlayerEngineFactory.kt +11 -19
  53. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +30 -96
  54. package/android/src/main/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicy.kt +39 -95
  55. package/android/src/main/java/com/audiobrowser/player/ShuffleOrderLedBy.kt +7 -13
  56. package/android/src/main/java/com/audiobrowser/player/SleepTimer.kt +13 -30
  57. package/android/src/main/java/com/audiobrowser/player/SleepTimerManager.kt +7 -11
  58. package/android/src/main/java/com/audiobrowser/player/StuckRecoveryPolicy.kt +9 -22
  59. package/android/src/main/java/com/audiobrowser/player/TransformingDataSource.kt +22 -54
  60. package/android/src/main/java/com/audiobrowser/player/VolumeFader.kt +8 -15
  61. package/android/src/main/java/com/audiobrowser/remote/RemoteItem.kt +9 -8
  62. package/android/src/main/java/com/audiobrowser/remote/RemoteOutputsController.kt +13 -10
  63. package/android/src/main/java/com/audiobrowser/remote/RemotePlayback.kt +8 -8
  64. package/android/src/main/java/com/audiobrowser/remote/RemoteQueue.kt +12 -5
  65. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +35 -49
  66. package/android/src/main/java/com/audiobrowser/sonos/DeviceDescriptionParser.kt +11 -19
  67. package/android/src/main/java/com/audiobrowser/sonos/DidlLite.kt +2 -2
  68. package/android/src/main/java/com/audiobrowser/sonos/SoapClient.kt +6 -6
  69. package/android/src/main/java/com/audiobrowser/sonos/SoapEnvelopes.kt +8 -9
  70. package/android/src/main/java/com/audiobrowser/sonos/SoapResponseParser.kt +11 -18
  71. package/android/src/main/java/com/audiobrowser/sonos/SonosDiscoverer.kt +10 -10
  72. package/android/src/main/java/com/audiobrowser/sonos/SonosOutputs.kt +10 -10
  73. package/android/src/main/java/com/audiobrowser/sonos/SonosPlayer.kt +21 -33
  74. package/android/src/main/java/com/audiobrowser/sonos/SonosRemote.kt +4 -6
  75. package/android/src/main/java/com/audiobrowser/sonos/SonosRouteProviderService.kt +9 -10
  76. package/android/src/main/java/com/audiobrowser/sonos/SonosStreamUri.kt +7 -7
  77. package/android/src/main/java/com/audiobrowser/sonos/SonosTransport.kt +5 -4
  78. package/android/src/main/java/com/audiobrowser/sonos/SsdpDiscovery.kt +8 -3
  79. package/android/src/main/java/com/audiobrowser/sonos/SsdpMessages.kt +4 -6
  80. package/android/src/main/java/com/audiobrowser/sonos/ZoneGroupState.kt +13 -11
  81. package/android/src/main/java/com/audiobrowser/tls/AiaCertChaser.kt +34 -71
  82. package/android/src/main/java/com/audiobrowser/tls/AiaChasingExtendedTrustManager.kt +20 -37
  83. package/android/src/main/java/com/audiobrowser/tls/AiaChasingTrustManager.kt +18 -27
  84. package/android/src/main/java/com/audiobrowser/tls/AiaTls.kt +14 -29
  85. package/android/src/main/java/com/audiobrowser/tls/CachingCertificateFetcher.kt +68 -133
  86. package/android/src/main/java/com/audiobrowser/util/ArtworkContentProvider.kt +10 -22
  87. package/android/src/main/java/com/audiobrowser/util/ArtworkRoutes.kt +6 -6
  88. package/android/src/main/java/com/audiobrowser/util/ArtworkUris.kt +4 -3
  89. package/android/src/main/java/com/audiobrowser/util/ArtworkVariant.kt +2 -13
  90. package/android/src/main/java/com/audiobrowser/util/Automotive.kt +2 -4
  91. package/android/src/main/java/com/audiobrowser/util/BatteryOptimizationHelper.kt +3 -9
  92. package/android/src/main/java/com/audiobrowser/util/BatteryWarningStore.kt +4 -14
  93. package/android/src/main/java/com/audiobrowser/util/BrowserPathHelper.kt +21 -85
  94. package/android/src/main/java/com/audiobrowser/util/CoilArtworkLoader.kt +7 -7
  95. package/android/src/main/java/com/audiobrowser/util/CoilArtworkLoaderHolder.kt +5 -8
  96. package/android/src/main/java/com/audiobrowser/util/CoilBitmapLoader.kt +8 -24
  97. package/android/src/main/java/com/audiobrowser/util/EqualizerManager.kt +7 -39
  98. package/android/src/main/java/com/audiobrowser/util/MediaExtrasBuilder.kt +10 -14
  99. package/android/src/main/java/com/audiobrowser/util/MetadataAdapter.kt +5 -9
  100. package/android/src/main/java/com/audiobrowser/util/NetworkConnectivityMonitor.kt +5 -9
  101. package/android/src/main/java/com/audiobrowser/util/OutputMonitor.kt +21 -50
  102. package/android/src/main/java/com/audiobrowser/util/OutputSwitcher.kt +7 -20
  103. package/android/src/main/java/com/audiobrowser/util/PlayingStateFactory.kt +3 -5
  104. package/android/src/main/java/com/audiobrowser/util/RatingFavorites.kt +4 -5
  105. package/android/src/main/java/com/audiobrowser/util/StyleWire.kt +5 -5
  106. package/android/src/main/java/com/audiobrowser/util/SvgArtworkRenderer.kt +5 -9
  107. package/android/src/main/java/com/audiobrowser/util/SystemVolumeMonitor.kt +6 -9
  108. package/android/src/main/java/com/audiobrowser/util/TrackFactory.kt +25 -47
  109. package/android/src/nocast/java/com/audiobrowser/cast/CastSupport.kt +0 -2
  110. package/android/src/test/java/com/audiobrowser/ForegroundStartTest.kt +1 -2
  111. package/android/src/test/java/com/audiobrowser/LegacyRatingTest.kt +3 -3
  112. package/android/src/test/java/com/audiobrowser/ServiceBindingTest.kt +0 -13
  113. package/android/src/test/java/com/audiobrowser/ServiceTaskRemovedTest.kt +2 -3
  114. package/android/src/test/java/com/audiobrowser/TestFixtures.kt +5 -14
  115. package/android/src/test/java/com/audiobrowser/browser/BrowseArtworkRegistryTest.kt +1 -1
  116. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerBuildApiRequestTest.kt +2 -8
  117. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerFavoritesTest.kt +2 -12
  118. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerLayerResolutionTest.kt +5 -28
  119. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerTest.kt +11 -43
  120. package/android/src/test/java/com/audiobrowser/browser/BrowserUrlResolutionTest.kt +4 -13
  121. package/android/src/test/java/com/audiobrowser/browser/InertStyleDiagnosticTest.kt +2 -11
  122. package/android/src/test/java/com/audiobrowser/browser/JsonArtworkTest.kt +0 -2
  123. package/android/src/test/java/com/audiobrowser/browser/JsonStyleTest.kt +3 -8
  124. package/android/src/test/java/com/audiobrowser/browser/SectionScopeTest.kt +2 -14
  125. package/android/src/test/java/com/audiobrowser/browser/SimpleRouterTest.kt +1 -5
  126. package/android/src/test/java/com/audiobrowser/browser/StyleResolverTest.kt +2 -13
  127. package/android/src/test/java/com/audiobrowser/extension/TappedTrackTest.kt +1 -7
  128. package/android/src/test/java/com/audiobrowser/extension/TrackIdentityTest.kt +0 -5
  129. package/android/src/test/java/com/audiobrowser/http/RequestConfigBuilderTest.kt +8 -16
  130. package/android/src/test/java/com/audiobrowser/model/IcyTitleTest.kt +1 -1
  131. package/android/src/test/java/com/audiobrowser/player/BrowseTilesTest.kt +12 -29
  132. package/android/src/test/java/com/audiobrowser/player/CapabilityControlsTest.kt +3 -12
  133. package/android/src/test/java/com/audiobrowser/player/CrossOriginHeaderStripperTest.kt +0 -7
  134. package/android/src/test/java/com/audiobrowser/player/DynamicLoadControlTest.kt +0 -1
  135. package/android/src/test/java/com/audiobrowser/player/EqualizerControllerTest.kt +0 -9
  136. package/android/src/test/java/com/audiobrowser/player/LiveSeekCommandTest.kt +1 -2
  137. package/android/src/test/java/com/audiobrowser/player/MediaSessionSlotMappingTest.kt +0 -9
  138. package/android/src/test/java/com/audiobrowser/player/NowPlayingUpdaterTest.kt +15 -22
  139. package/android/src/test/java/com/audiobrowser/player/PlaybackErrorClassifierTest.kt +1 -24
  140. package/android/src/test/java/com/audiobrowser/player/PlaybackStateMachineTest.kt +0 -20
  141. package/android/src/test/java/com/audiobrowser/player/PlaybackStateStoreTrackJsonTest.kt +1 -6
  142. package/android/src/test/java/com/audiobrowser/player/PlaybackTimerTest.kt +2 -4
  143. package/android/src/test/java/com/audiobrowser/player/PlayerCastTest.kt +16 -2
  144. package/android/src/test/java/com/audiobrowser/player/PlayerEngineFactoryTest.kt +0 -3
  145. package/android/src/test/java/com/audiobrowser/player/PlayerInvalidTrackTest.kt +0 -1
  146. package/android/src/test/java/com/audiobrowser/player/PlayerSetupTest.kt +3 -2
  147. package/android/src/test/java/com/audiobrowser/player/PlayerSonosTest.kt +26 -4
  148. package/android/src/test/java/com/audiobrowser/player/PlayerSuppressionTest.kt +5 -7
  149. package/android/src/test/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicyTest.kt +4 -35
  150. package/android/src/test/java/com/audiobrowser/player/SessionErrorMaskTest.kt +0 -5
  151. package/android/src/test/java/com/audiobrowser/player/ShuffleOrderLedByTest.kt +1 -8
  152. package/android/src/test/java/com/audiobrowser/player/StandardSkipTest.kt +4 -6
  153. package/android/src/test/java/com/audiobrowser/player/StuckRecoveryPolicyTest.kt +11 -11
  154. package/android/src/test/java/com/audiobrowser/player/TransformingDataSourceTest.kt +2 -23
  155. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +15 -11
  156. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +112 -1
  157. package/android/src/test/java/com/audiobrowser/sonos/DeviceDescriptionParserTest.kt +1 -3
  158. package/android/src/test/java/com/audiobrowser/sonos/DidlLiteTest.kt +0 -1
  159. package/android/src/test/java/com/audiobrowser/sonos/SoapClientTest.kt +0 -3
  160. package/android/src/test/java/com/audiobrowser/sonos/SoapEnvelopesTest.kt +0 -1
  161. package/android/src/test/java/com/audiobrowser/sonos/SoapResponseParserTest.kt +0 -1
  162. package/android/src/test/java/com/audiobrowser/sonos/SonosDiscovererTest.kt +2 -0
  163. package/android/src/test/java/com/audiobrowser/sonos/SonosPlayerTest.kt +0 -1
  164. package/android/src/test/java/com/audiobrowser/sonos/SonosRemoteTest.kt +1 -1
  165. package/android/src/test/java/com/audiobrowser/sonos/SonosRoutesTest.kt +2 -0
  166. package/android/src/test/java/com/audiobrowser/sonos/SonosTransportTest.kt +2 -6
  167. package/android/src/test/java/com/audiobrowser/sonos/SsdpMessagesTest.kt +0 -2
  168. package/android/src/test/java/com/audiobrowser/tls/AiaCertChaserTest.kt +13 -37
  169. package/android/src/test/java/com/audiobrowser/tls/AiaChasingTrustManagerTest.kt +10 -24
  170. package/android/src/test/java/com/audiobrowser/tls/CachingCertificateFetcherCallSiteTest.kt +15 -39
  171. package/android/src/test/java/com/audiobrowser/tls/CachingCertificateFetcherTest.kt +4 -10
  172. package/android/src/test/java/com/audiobrowser/util/ArtworkContentProviderTest.kt +2 -11
  173. package/android/src/test/java/com/audiobrowser/util/ArtworkUrisTest.kt +0 -1
  174. package/android/src/test/java/com/audiobrowser/util/BrowserPathHelperTest.kt +0 -4
  175. package/android/src/test/java/com/audiobrowser/util/CoilArtworkLoaderHolderTest.kt +1 -1
  176. package/android/src/test/java/com/audiobrowser/util/CoilArtworkLoaderTest.kt +0 -5
  177. package/android/src/test/java/com/audiobrowser/util/FakeImageLoader.kt +2 -2
  178. package/android/src/test/java/com/audiobrowser/util/MediaExtrasBuilderTest.kt +4 -12
  179. package/android/src/test/java/com/audiobrowser/util/OutputMonitorTest.kt +1 -1
  180. package/android/src/test/java/com/audiobrowser/util/PlayingStateFactoryTest.kt +0 -4
  181. package/android/src/test/java/com/audiobrowser/util/TrackFactoryBrowseTest.kt +1 -1
  182. package/android/src/test/java/com/audiobrowser/util/TrackFactoryMediaIdTest.kt +4 -6
  183. package/android/src/testCast/java/com/audiobrowser/cast/CastEndsTest.kt +1 -1
  184. package/android/src/testCast/java/com/audiobrowser/cast/SendingMediaItemConverterTest.kt +1 -0
  185. package/ios/AVPlayerEngine.swift +13 -21
  186. package/ios/AVPlayerEngineCallbacks.swift +2 -4
  187. package/ios/Browser/BrowseGate.swift +7 -8
  188. package/ios/Browser/BrowserConfig.swift +19 -34
  189. package/ios/Browser/BrowserError.swift +0 -1
  190. package/ios/Browser/BrowserManager.swift +29 -75
  191. package/ios/Browser/BrowserPathHelper.swift +13 -93
  192. package/ios/Browser/FavoriteSet.swift +7 -10
  193. package/ios/Browser/InertStyleDiagnostic.swift +17 -82
  194. package/ios/Browser/JsonModels.swift +11 -51
  195. package/ios/Browser/NavigationErrorState.swift +3 -2
  196. package/ios/Browser/PageResolver.swift +13 -23
  197. package/ios/Browser/RequestLayer.swift +16 -20
  198. package/ios/Browser/RequestPipeline.swift +33 -43
  199. package/ios/Browser/SearchDrillIn.swift +7 -13
  200. package/ios/Browser/SectionScope.swift +14 -26
  201. package/ios/Browser/SimpleRouter.swift +8 -15
  202. package/ios/Browser/StyleResolver.swift +12 -29
  203. package/ios/Browser/TabBarEntries.swift +6 -11
  204. package/ios/Browser/TrackIdTemplate.swift +6 -14
  205. package/ios/CarPlay/CPInterfaceController+Safe.swift +19 -28
  206. package/ios/CarPlay/CarPlayArtworkResolver.swift +5 -9
  207. package/ios/CarPlay/CarPlayController.swift +4 -4
  208. package/ios/CarPlay/CarPlayImageLoader.swift +11 -26
  209. package/ios/CarPlay/CarPlayListItemFactory.swift +30 -80
  210. package/ios/CarPlay/CarPlayNowPlayingManager.swift +19 -54
  211. package/ios/CarPlay/CarPlaySession+Navigator.swift +10 -10
  212. package/ios/CarPlay/CarPlaySession+PageLoader.swift +6 -5
  213. package/ios/CarPlay/CarPlaySession+Refresher.swift +2 -2
  214. package/ios/CarPlay/CarPlaySession+TabBar.swift +19 -26
  215. package/ios/CarPlay/CarPlaySession.swift +13 -17
  216. package/ios/CarPlay/CarPlayTemplates.swift +6 -7
  217. package/ios/CarPlay/IntentHandlers.swift +3 -5
  218. package/ios/CarPlay/MediaIntentCriteria.swift +15 -29
  219. package/ios/CarPlay/MediaIntentHandler.swift +4 -7
  220. package/ios/CarPlay/MediaIntentPlayback.swift +9 -8
  221. package/ios/CarPlay/NowPlayingButtonRules.swift +3 -4
  222. package/ios/CarPlay/SectionPresentation.swift +18 -28
  223. package/ios/CarPlay/TopTemplateReplacer.swift +8 -9
  224. package/ios/Extension/Capability+RemoteCommand.swift +3 -3
  225. package/ios/Extension/ChapterMetadata+AVFoundation.swift +2 -5
  226. package/ios/Extension/CxxVectorConformances.swift +4 -16
  227. package/ios/Extension/NavigationError+Conversion.swift +4 -7
  228. package/ios/Extension/PlayerCapabilities+Favorite.swift +0 -1
  229. package/ios/Extension/RequestConfig+Copying.swift +2 -6
  230. package/ios/Extension/ResolvedTrack+Copying.swift +2 -8
  231. package/ios/Extension/SearchParams+Query.swift +4 -4
  232. package/ios/Extension/Section+Copying.swift +3 -6
  233. package/ios/Extension/String+IcyCharset.swift +5 -5
  234. package/ios/Extension/TimedMetadata+AVFoundation.swift +6 -12
  235. package/ios/Extension/Track+AVPlayer.swift +1 -2
  236. package/ios/Extension/Track+Copying.swift +2 -8
  237. package/ios/Extension/Track+Identity.swift +4 -9
  238. package/ios/Extension/TrackMetadata+AVFoundation.swift +10 -13
  239. package/ios/Extension/UIApplication+ActiveScene.swift +6 -14
  240. package/ios/Extension/Variant+Artwork.swift +8 -22
  241. package/ios/Http/HttpClient.swift +3 -3
  242. package/ios/HybridAudioBrowser+Browser.swift +10 -16
  243. package/ios/HybridAudioBrowser+Options.swift +6 -9
  244. package/ios/HybridAudioBrowser+Player.swift +8 -16
  245. package/ios/HybridAudioBrowser+PlayerCallbacks.swift +4 -5
  246. package/ios/HybridAudioBrowser+Stubs.swift +5 -7
  247. package/ios/HybridAudioBrowser.swift +54 -79
  248. package/ios/Model/NitroTypeStubs.swift +15 -22
  249. package/ios/Model/PlayerUpdateOptions.swift +6 -21
  250. package/ios/Model/RemoteCommand.swift +2 -2
  251. package/ios/Model/TrackPlayerError.swift +9 -22
  252. package/ios/NowPlayingInfo/NowPlayingInfoController.swift +21 -40
  253. package/ios/NowPlayingInfo/SilentAudioPrimer.swift +10 -16
  254. package/ios/Observer/ItemObserver.swift +7 -5
  255. package/ios/Observer/PlayerObserver.swift +5 -5
  256. package/ios/PlaybackEvent.swift +2 -2
  257. package/ios/Player/AirPlayStallJudgement.swift +7 -9
  258. package/ios/Player/AudioSessionController.swift +14 -15
  259. package/ios/Player/DeferredSeek.swift +2 -2
  260. package/ios/Player/EndOfTrackJudgement.swift +6 -13
  261. package/ios/Player/ErrorStatus.swift +8 -7
  262. package/ios/Player/MediaLoader.swift +20 -24
  263. package/ios/Player/NowPlayingLines.swift +1 -4
  264. package/ios/Player/NowPlayingUpdater.swift +35 -61
  265. package/ios/Player/PersistedPlaybackState.swift +1 -2
  266. package/ios/Player/PlaybackFailure.swift +20 -24
  267. package/ios/Player/PlaybackPersistence.swift +5 -6
  268. package/ios/Player/PlaybackStateMachine.swift +8 -11
  269. package/ios/Player/PlaybackTimer.swift +8 -11
  270. package/ios/Player/Player.swift +6 -13
  271. package/ios/Player/PlayerEngine.swift +20 -20
  272. package/ios/Player/PlayerStatusTypes.swift +1 -2
  273. package/ios/Player/QueueManager.swift +23 -67
  274. package/ios/Player/RetryLoop.swift +39 -50
  275. package/ios/Player/ShuffleOrder.swift +17 -57
  276. package/ios/Player/SleepTimerManager.swift +13 -28
  277. package/ios/Player/VolumeFader.swift +16 -16
  278. package/ios/RemoteCommand/RemoteCommandCallbacks.swift +6 -16
  279. package/ios/RemoteCommand/RemoteCommandController.swift +8 -10
  280. package/ios/Tests/AirPlayStallJudgementTests.swift +4 -4
  281. package/ios/Tests/BrowserPathHelperTests.swift +3 -6
  282. package/ios/Tests/DeferredSeekTests.swift +1 -3
  283. package/ios/Tests/EmitterTests.swift +0 -1
  284. package/ios/Tests/EndOfTrackJudgementTests.swift +1 -6
  285. package/ios/Tests/FavoriteSetTests.swift +1 -0
  286. package/ios/Tests/GenerationMemoTests.swift +2 -2
  287. package/ios/Tests/InertStyleDiagnosticTests.swift +4 -10
  288. package/ios/Tests/JsonModelsTests.swift +5 -12
  289. package/ios/Tests/LRUCacheTests.swift +1 -5
  290. package/ios/Tests/MediaIntentCriteriaTests.swift +2 -7
  291. package/ios/Tests/MediaLoaderTests.swift +3 -12
  292. package/ios/Tests/ObserverTests.swift +3 -3
  293. package/ios/Tests/PlaybackErrorTests.swift +7 -9
  294. package/ios/Tests/PlaybackFailureTests.swift +9 -17
  295. package/ios/Tests/PlaybackPersistenceTests.swift +1 -0
  296. package/ios/Tests/PlaybackStateMachineTests.swift +1 -16
  297. package/ios/Tests/PlaybackTimerTests.swift +2 -3
  298. package/ios/Tests/PlayerPolicyTests.swift +10 -26
  299. package/ios/Tests/PlayerTests.swift +53 -88
  300. package/ios/Tests/PlayingStateTests.swift +0 -1
  301. package/ios/Tests/QueueManagerTests.swift +30 -80
  302. package/ios/Tests/RemoteCommandControllerTests.swift +5 -13
  303. package/ios/Tests/ResolvedTrackCopyingTests.swift +0 -2
  304. package/ios/Tests/RetryLoopTests.swift +12 -35
  305. package/ios/Tests/SearchDrillInTests.swift +4 -5
  306. package/ios/Tests/SectionPresentationTests.swift +3 -16
  307. package/ios/Tests/SectionScopeTests.swift +3 -6
  308. package/ios/Tests/SimpleRouterTests.swift +1 -5
  309. package/ios/Tests/SleepTimerManagerTests.swift +8 -11
  310. package/ios/Tests/StyleResolverTests.swift +4 -13
  311. package/ios/Tests/Support/ManualSleepTimerScheduler.swift +3 -8
  312. package/ios/Tests/Support/TestTypes.swift +5 -15
  313. package/ios/Tests/TabBarEntriesTests.swift +0 -2
  314. package/ios/Tests/TimedMetadataAVFoundationTests.swift +2 -3
  315. package/ios/Tests/TopTemplateReplacerTests.swift +1 -1
  316. package/ios/Tests/TrackIdTemplateTests.swift +2 -6
  317. package/ios/Tests/TrackMetadataAVFoundationTests.swift +1 -4
  318. package/ios/Tests/TrackSelectorTests.swift +3 -15
  319. package/ios/TrackSelector.swift +13 -25
  320. package/ios/Util/ArtworkFreshness.swift +6 -6
  321. package/ios/Util/ArtworkImageFetcher.swift +19 -20
  322. package/ios/Util/ConcurrentMap.swift +2 -2
  323. package/ios/Util/Emitter.swift +8 -13
  324. package/ios/Util/NetworkMonitor.swift +4 -6
  325. package/ios/Util/OutputPicker.swift +1 -1
  326. package/ios/Util/ReadyValue.swift +3 -2
  327. package/ios/Util/SFSymbolRenderer.swift +17 -30
  328. package/ios/Util/SVGProcessor.swift +5 -9
  329. package/package.json +1 -1
@@ -3,13 +3,12 @@ import Foundation
3
3
  import NitroModules
4
4
  #endif
5
5
 
6
- /// A playback-gated repeating timer. Runs `onTick` every `interval` seconds while
7
- /// the current playback state satisfies `isActive`. `interval == nil` (or <= 0)
8
- /// means stopped — that is the single off-switch.
6
+ /// A repeating timer gated on playback state: runs `onTick` every `interval` seconds while
7
+ /// `isActive` holds for the current state. A nil or non-positive interval turns it off.
9
8
  @MainActor
10
9
  final class PlaybackTimer {
11
- // nonisolated(unsafe) for deinit cleanup — Timer must be invalidated to break
12
- // the RunLoop retain, and deinit is always nonisolated in Swift 6.
10
+ // nonisolated(unsafe) so the nonisolated deinit (Swift 6) can invalidate it; the run loop
11
+ // retains a timer until it is invalidated.
13
12
  private nonisolated(unsafe) var timer: Timer?
14
13
  private var interval: TimeInterval?
15
14
  private var active = false
@@ -29,7 +28,7 @@ final class PlaybackTimer {
29
28
  let normalized = (interval ?? 0) > 0 ? interval : nil
30
29
  if normalized == self.interval { return }
31
30
  self.interval = normalized
32
- stop() // restart with the new interval on the next reconcile
31
+ stop() // start() keeps a running timer, so drop it for the new interval
33
32
  reconcile()
34
33
  }
35
34
 
@@ -48,11 +47,9 @@ final class PlaybackTimer {
48
47
 
49
48
  private func start(_ interval: TimeInterval) {
50
49
  guard timer == nil else { return }
51
- // `.common`, not the `.default` mode `Timer.scheduledTimer` installs: UIKit
52
- // runs the main run loop in tracking mode while a list is being dragged, and
53
- // a default-mode timer does not fire there. Missed repeats are dropped rather
54
- // than replayed, so progress events would freeze and interval ticks would be
55
- // lost for as long as the user scrolls. (VolumeFader already does this.)
50
+ // `.common`, not the `.default` mode `Timer.scheduledTimer` uses: while a list is dragged the
51
+ // main run loop is in tracking mode, where a default-mode timer does not fire and its missed
52
+ // repeats are dropped, freezing progress events and losing interval ticks.
56
53
  let timer = Timer(timeInterval: interval, repeats: true) { [weak self] _ in
57
54
  MainActor.assumeIsolated { self?.onTick() }
58
55
  }
@@ -5,10 +5,9 @@ import os.log
5
5
  import NitroModules
6
6
  #endif
7
7
 
8
- /// The player: the playback state machine, the queue, retries, the sleep timer, persistence,
9
- /// and every decision about loading, seeking and recovering. The media stack under it is a
10
- /// `PlayerEngine` (AVPlayerEngine in production, a mock in tests), which carries the decisions out
11
- /// and reports what it observes.
8
+ /// The playback state machine, the queue, retries, the sleep timer and persistence: every
9
+ /// decision about loading, seeking and recovering. A `PlayerEngine` (AVPlayerEngine, a mock in
10
+ /// tests) carries the decisions out and reports what it observes.
12
11
  @MainActor
13
12
  final class Player {
14
13
  let logger = Logger(subsystem: "com.audiobrowser", category: "Player")
@@ -57,7 +56,6 @@ final class Player {
57
56
  /// One of this load's items is in the engine; until then it reports the previous one's position.
58
57
  var itemPrepared = false
59
58
 
60
- /// True the first time it is asked, so the silent primer runs once per load.
61
59
  mutating func claimNowPlayingPrime() -> Bool {
62
60
  guard !primedNowPlaying else { return false }
63
61
  primedNowPlaying = true
@@ -80,8 +78,8 @@ final class Player {
80
78
  /// The play intent captured when the current interruption began; its end resumes only then.
81
79
  private var shouldResumeAfterInterruption = false
82
80
 
83
- /// Playback rate (1.0 = normal speed). A non-positive rate, which could never play, is refused.
84
- /// Speed and play intent are independent, as on Android and web.
81
+ /// A non-positive rate, which could never play, is refused and the old value kept. Setting it
82
+ /// never starts or stops playback: speed and play intent are independent, as on Android and web.
85
83
  var rate: Float = 1.0 {
86
84
  didSet {
87
85
  guard rate > 0 else {
@@ -113,7 +111,6 @@ final class Player {
113
111
  state != .loading && load?.itemPrepared == true
114
112
  }
115
113
 
116
- /// Where a reload resumes this Load.
117
114
  private var resumePosition: TimeInterval? {
118
115
  enginePositionIsCurrent ? engine.resumePosition : deferredSeek.target
119
116
  }
@@ -164,7 +161,6 @@ final class Player {
164
161
 
165
162
  // MARK: - playWhenReady
166
163
 
167
- /// The intent to play, applied through `setPlayWhenReady`.
168
164
  private(set) var playWhenReady = false
169
165
 
170
166
  func setPlayWhenReady(_ newValue: Bool) {
@@ -189,7 +185,6 @@ final class Player {
189
185
  evaluateSessionRelease()
190
186
  }
191
187
 
192
- /// Playing with intent, in a state that can play; buffering while loading or rebuffering.
193
188
  static func playingState(playWhenReady: Bool, state: PlaybackState) -> PlayingState {
194
189
  PlayingState(
195
190
  playing: playWhenReady && ![.error, .ended, .none, .stopped].contains(state),
@@ -422,7 +417,7 @@ final class Player {
422
417
  Playback(state: state, error: errorStatus.nitroError)
423
418
  }
424
419
 
425
- /// Drops the intent before `action` or raises it after, as `playWhenReady` asks.
420
+ /// Applies `false` before `action` and `true` after it; nil leaves the intent alone.
426
421
  private func handlePlayWhenReady(_ playWhenReady: Bool?, action: () throws -> Void) rethrows {
427
422
  if playWhenReady == false { setPlayWhenReady(false) }
428
423
  try action()
@@ -431,7 +426,6 @@ final class Player {
431
426
 
432
427
  // MARK: - Queue Methods
433
428
 
434
- /// Refuses a track with neither `src` nor `path`, before the queue changes.
435
429
  private func throwIfInvalid(_ tracks: [Track]) throws {
436
430
  if let track = tracks.first(where: { $0.src == nil && $0.path == nil }) {
437
431
  throw TrackPlayerError.QueueError.invalidTrack(title: track.title)
@@ -444,7 +438,6 @@ final class Player {
444
438
  if queue.currentIndex == -1 {
445
439
  afterQueueMutation(queue.add([track], initialIndex: 0))
446
440
  } else {
447
- // In bounds, as -1 took the branch above.
448
441
  do {
449
442
  try queue.replace(queue.currentIndex, track)
450
443
  afterQueueMutation(.tracksAndCurrent)
@@ -4,11 +4,11 @@ import Foundation
4
4
  import NitroModules
5
5
  #endif
6
6
 
7
- /// What the media stack reports to the Player.
7
+ /// What the engine reports to the Player.
8
8
  enum EngineEvent {
9
- /// The loaded item is now current and observed.
9
+ /// The loaded item is now the player's current item, and observed.
10
10
  case itemPrepared(likelyToKeepUp: Bool)
11
- /// Loading the asset failed; the retry loop classifies the error.
11
+ /// Loading the resolved asset failed; the retry loop classifies the error.
12
12
  case loadFailed(Error)
13
13
  /// The asset loaded but cannot play.
14
14
  case unplayable
@@ -19,25 +19,24 @@ enum EngineEvent {
19
19
  case likelyToKeepUp(Bool)
20
20
  /// `waitingForNoItem`: the player waits because it has no item to play.
21
21
  case timeControlStatus(PlayerTimeControlStatus, waitingForNoItem: Bool)
22
- /// Playback crossed the first millisecond.
22
+ /// Playback crossed its first millisecond.
23
23
  case audioDidStart
24
24
  case playedToEnd
25
25
  /// The buffer emptied mid-playback.
26
26
  case stalled
27
- /// A timed-metadata group (a live stream's song line), decoded with the loaded track's ICY
28
- /// charset.
27
+ /// A timed-metadata group (a live stream's song line), decoded with the track's ICY charset.
29
28
  case timedMetadata(TimedMetadata)
30
29
  }
31
30
 
32
- /// The media stack under the Player: the AVPlayer and its items, media loading, now playing and
33
- /// the remote commands. It carries out what the Player decides and reports what it observes
34
- /// through `onEvent`; it holds no playback policy. AVPlayerEngine is the one implementation;
35
- /// tests use a mock.
31
+ /// The media stack under the Player: the AVPlayer and its items, loading, now playing, remote
32
+ /// commands and the audio session. It carries out what the Player decides and reports what it
33
+ /// observes through `onEvent`; it holds no playback policy (ADR 0012). Tests use a mock.
36
34
  @MainActor protocol PlayerEngine: AnyObject {
37
35
  var onEvent: (@MainActor (EngineEvent) -> Void)? { get set }
38
36
 
39
37
  // MARK: The current item
40
38
 
39
+ /// True also for the item a failed load leaves in place to carry now playing.
41
40
  var hasItem: Bool { get }
42
41
  var hasLoadedAsset: Bool { get }
43
42
  var currentTime: Double { get }
@@ -45,20 +44,20 @@ enum EngineEvent {
45
44
  var bufferedPosition: Double { get }
46
45
  /// The position a reload resumes from: nil without an item, or for an indefinite duration.
47
46
  var resumePosition: Double? { get }
48
- /// The end of a live stream's seekable window, when it has one.
47
+ /// The end of the seekable window; nil when there is none.
49
48
  var liveEdge: Double? { get }
50
49
  var isPlaybackLikelyToKeepUp: Bool { get }
51
50
  var isAirPlayRoute: Bool { get }
52
- /// 0–1; ramped by the sleep-timer fade.
51
+ /// 0–1.
53
52
  var volume: Float { get set }
54
53
 
55
54
  // MARK: Loading
56
55
 
57
- /// Runs the media-URL resolver for `track`, so a short-lived URL is minted afresh, and loads
58
- /// the result.
56
+ /// Resolves `src` for `track` afresh, so a short-lived URL is minted anew, and loads it. The
57
+ /// outcome arrives as `itemPrepared`, `loadFailed`, `unplayable` or `invalidSource`.
59
58
  func resolveAndLoad(src: String, track: Track)
60
59
  func cancelLoading()
61
- /// Drops the asset and stops observing the item, leaving it in place for the reload.
60
+ /// Drops the asset and stops observing the item, leaving the item in place for the reload.
62
61
  func dropAsset()
63
62
  /// Drops the asset and removes the item.
64
63
  func clearItem()
@@ -71,15 +70,16 @@ enum EngineEvent {
71
70
  func play()
72
71
  func pause()
73
72
  /// Stages `rate` for the next play; applies it now only when `playing`, since a nonzero
74
- /// AVPlayer rate is a play.
73
+ /// AVPlayer rate starts playback.
75
74
  func setRate(_ rate: Float, playing: Bool)
76
- /// Seeks the current item exactly; `completion` runs on the main actor.
75
+ /// Seeks exactly, with no tolerance; `completion` gets false when the seek was interrupted.
77
76
  func seek(to seconds: Double, completion: @escaping @MainActor (Bool) -> Void)
78
77
  func applyTimePitchAlgorithm()
79
78
 
80
79
  // MARK: Now playing and remote commands
81
80
 
82
- /// Renders silence so iOS elects the app onto the now-playing surfaces (ADR 0005).
81
+ /// Renders silence so iOS elects the app onto the now-playing surfaces when a load renders
82
+ /// no audio (ADR 0005).
83
83
  func primeNowPlaying()
84
84
  func loadNowPlayingMetadata(for track: Track)
85
85
  func clearNowPlaying()
@@ -90,7 +90,6 @@ enum EngineEvent {
90
90
  func applyTimedMetadata(_ metadata: TimedMetadata)
91
91
  func updateRemoteRepeatMode(_ mode: RepeatMode)
92
92
  func updateRemoteShuffleMode(_ enabled: Bool)
93
- /// Greys out next/previous on the remote surfaces when the queue has nowhere to skip.
94
93
  func updateSkipAvailability(canNext: Bool, canPrevious: Bool)
95
94
 
96
95
  // MARK: Audio session
@@ -99,6 +98,7 @@ enum EngineEvent {
99
98
  /// which the system may have declined while the audio session was inactive.
100
99
  func activateAudioSession()
101
100
  func cancelAudioSessionRelease()
102
- /// Releases the audio session after a debounce, unless playback resumes first.
101
+ /// Releases the audio session after a debounce, unless playback resumes or
102
+ /// `cancelAudioSessionRelease()` runs first.
103
103
  func scheduleAudioSessionRelease()
104
104
  }
@@ -1,5 +1,4 @@
1
- /// Decouples Player from AVFoundation enum types.
2
- /// AVPlayerEngine maps from AVPlayer.TimeControlStatus → PlayerTimeControlStatus at the call boundary.
1
+ /// AVPlayer's time-control status, mirrored so the Player and its tests stay free of AVFoundation.
3
2
  enum PlayerTimeControlStatus {
4
3
  case paused, waitingToPlayAtSpecifiedRate, playing
5
4
  }
@@ -3,9 +3,8 @@ import Foundation
3
3
  import NitroModules
4
4
  #endif
5
5
 
6
- /// What a queue mutation changed, reported once the queue has settled.
6
+ /// What a queue mutation changed.
7
7
  struct QueueChange: Equatable {
8
- /// The track list changed.
9
8
  var tracks = false
10
9
  /// A different track became current, or the current track was cleared.
11
10
  var currentTrack = false
@@ -15,42 +14,34 @@ struct QueueChange: Equatable {
15
14
  static let tracksAndCurrent = QueueChange(tracks: true, currentTrack: true)
16
15
  }
17
16
 
18
- /// Result of a navigation action (next/previous/skipTo).
19
17
  enum QueueNavigationResult {
20
- /// A different track was selected as current.
21
18
  case trackChanged
22
- /// Single-track queue with repeat-queue — caller decides whether to replay based on playWhenReady.
19
+ /// A one-track queue on repeat-queue: the caller replays the track if it means to play.
23
20
  case sameTrackReplay
24
- /// Nothing happened (boundary without wrap, or guards failed).
25
21
  case noChange
26
22
  }
27
23
 
28
- /// Pure queue logic: tracks, indices, shuffle, repeat.
29
- /// Has no knowledge of AVPlayer or playback — Player and its engine own that.
24
+ /// The queue's tracks, current index, shuffle and repeat, with no knowledge of playback.
30
25
  @MainActor
31
26
  class QueueManager {
32
27
  // MARK: - Stored Properties
33
28
 
34
- /// The index of the current track. `-1` when there is no current track.
29
+ /// -1 when there is no current track.
35
30
  private(set) var currentIndex: Int = -1
36
31
 
37
- /// The source path from which the current queue was expanded (e.g., from a contextual URL).
32
+ /// The path the queue was expanded from, if any.
38
33
  private(set) var queueSourcePath: String?
39
34
 
40
- /// All tracks held by the queue.
41
35
  private(set) var tracks: [Track] = []
42
36
 
43
- /// The shuffle order for randomized playback.
44
37
  private(set) var shuffleOrder = ShuffleOrder()
45
38
 
46
- /// The repeat mode for the queue. Plain property — no side effects.
47
39
  var repeatMode: RepeatMode = .off
48
40
 
49
- /// Whether shuffle mode is enabled.
50
41
  var shuffleEnabled: Bool = false {
51
42
  didSet {
52
- // Re-pin on enable: the existing order has the current track wherever it happened to land,
53
- // so without this, turning shuffle on near the end of the queue ends it right away.
43
+ // Re-pin on enable: the current track can sit anywhere in the old order, and near its end
44
+ // turning shuffle on would end the queue at once.
54
45
  guard shuffleEnabled, shuffleEnabled != oldValue else { return }
55
46
  shuffleOrder.reshuffle(keepingFirst: currentIndex)
56
47
  }
@@ -63,8 +54,7 @@ class QueueManager {
63
54
  return tracks[currentIndex]
64
55
  }
65
56
 
66
- /// The upcoming tracks in playback order.
67
- /// When shuffle is enabled, returns tracks in shuffled order.
57
+ /// In playback order, so shuffled when shuffle is on; no wrap.
68
58
  var nextTracks: [Track] {
69
59
  guard currentIndex >= 0, currentIndex < tracks.count else { return [] }
70
60
 
@@ -82,8 +72,7 @@ class QueueManager {
82
72
  return Array(tracks[currentIndex + 1 ..< tracks.count])
83
73
  }
84
74
 
85
- /// The previous tracks in playback order.
86
- /// When shuffle is enabled, returns tracks in shuffled order.
75
+ /// In playback order, so shuffled when shuffle is on; no wrap.
87
76
  var previousTracks: [Track] {
88
77
  guard currentIndex >= 0, currentIndex < tracks.count else { return [] }
89
78
 
@@ -101,7 +90,6 @@ class QueueManager {
101
90
  return Array(tracks[0 ..< currentIndex])
102
91
  }
103
92
 
104
- /// Whether the current track is the last track in playback order.
105
93
  var isLastInPlaybackOrder: Bool {
106
94
  if shuffleEnabled {
107
95
  return shuffleOrder.isLast(currentIndex)
@@ -109,12 +97,10 @@ class QueueManager {
109
97
  return currentIndex == tracks.count - 1
110
98
  }
111
99
 
112
- /// Whether `next()` would move to a distinct track — drives remote/CarPlay
113
- /// next-button enablement. Shares `nextIndex` with `next()` so the button
114
- /// state and the actual navigation can't diverge (shuffle/repeat-wrap aware).
100
+ /// Whether `next()` moves to a different track; drives the remote next button.
115
101
  var canNext: Bool { nextIndex != nil }
116
102
 
117
- /// Whether `previous()` would move to a distinct track. Symmetric to `canNext`.
103
+ /// Whether `previous()` moves to a different track; drives the remote previous button.
118
104
  var canPrevious: Bool { previousIndex != nil }
119
105
 
120
106
  // MARK: - Validation
@@ -141,11 +127,8 @@ class QueueManager {
141
127
 
142
128
  // MARK: - Navigation (returns QueueNavigationResult)
143
129
 
144
- /// The index `next()` will move to — a distinct track in playback order, or
145
- /// nil when there's nowhere to go (empty/single-track queue, or a real end
146
- /// with no wrap). Single source of truth shared by `next()` and `canNext`, so
147
- /// the button state and the actual navigation can't disagree. Shuffle wraps
148
- /// the order unconditionally (like Media3); sequential wraps only on repeat-all.
130
+ // Shared by `next()` and `canNext` so the button and the navigation agree. Shuffle wraps
131
+ // whatever the repeat mode, as Media3 does; sequential order wraps only on repeat-queue.
149
132
  private var nextIndex: Int? {
150
133
  guard currentTrack != nil, tracks.count > 1 else { return nil }
151
134
  let candidate: Int? = if shuffleEnabled {
@@ -159,7 +142,6 @@ class QueueManager {
159
142
  return candidate
160
143
  }
161
144
 
162
- /// The index `previous()` will move to. Symmetric to `nextIndex`.
163
145
  private var previousIndex: Int? {
164
146
  guard currentTrack != nil, tracks.count > 1 else { return nil }
165
147
  let candidate: Int? = if shuffleEnabled {
@@ -173,18 +155,15 @@ class QueueManager {
173
155
  return candidate
174
156
  }
175
157
 
176
- /// Step to the next track in the queue.
177
158
  func next() -> QueueNavigationResult {
178
159
  guard currentTrack != nil, !tracks.isEmpty else { return .noChange }
179
160
  if let nextIndex {
180
161
  currentIndex = nextIndex
181
162
  return .trackChanged
182
163
  }
183
- // No distinct next: single-track + repeat-all replays; otherwise a real end.
184
164
  return tracks.count == 1 && repeatMode == .queue ? .sameTrackReplay : .noChange
185
165
  }
186
166
 
187
- /// Step to the previous track in the queue.
188
167
  func previous() -> QueueNavigationResult {
189
168
  guard currentTrack != nil, !tracks.isEmpty else { return .noChange }
190
169
  if let previousIndex {
@@ -194,7 +173,6 @@ class QueueManager {
194
173
  return tracks.count == 1 && repeatMode == .queue ? .sameTrackReplay : .noChange
195
174
  }
196
175
 
197
- /// Skip to a specific track in the queue.
198
176
  @discardableResult
199
177
  func skipTo(_ index: Int) throws -> QueueNavigationResult {
200
178
  try throwIfQueueEmpty()
@@ -206,7 +184,7 @@ class QueueManager {
206
184
 
207
185
  // MARK: - Mutations
208
186
 
209
- /// Replace the entire queue with new tracks. The current track always changes.
187
+ /// Clamps `initialIndex` into the new tracks.
210
188
  @discardableResult
211
189
  func setQueue(_ newTracks: [Track], initialIndex: Int = 0, sourcePath: String? = nil) -> QueueChange {
212
190
  let clampedIndex = max(0, min(initialIndex, newTracks.count - 1))
@@ -217,7 +195,7 @@ class QueueManager {
217
195
  return .tracksAndCurrent
218
196
  }
219
197
 
220
- /// Add tracks to the end of the queue. The current track changes only when the queue was empty.
198
+ /// `initialIndex` picks the current track only when the queue was empty.
221
199
  @discardableResult
222
200
  func add(_ newTracks: [Track], initialIndex: Int = 0) -> QueueChange {
223
201
  guard !newTracks.isEmpty else { return .none }
@@ -229,8 +207,6 @@ class QueueManager {
229
207
  return .tracksOnly
230
208
  }
231
209
 
232
- /// Add tracks at a specific index in the queue. The current track changes only when the queue
233
- /// was empty.
234
210
  @discardableResult
235
211
  func addAt(_ newTracks: [Track], at index: Int) throws -> QueueChange {
236
212
  guard !newTracks.isEmpty else { return .none }
@@ -241,7 +217,6 @@ class QueueManager {
241
217
  )
242
218
  }
243
219
  let wasEmpty = tracks.isEmpty
244
- // Correct index when tracks were inserted in front of it:
245
220
  if currentIndex >= 0, currentIndex >= index {
246
221
  currentIndex += newTracks.count
247
222
  }
@@ -251,26 +226,15 @@ class QueueManager {
251
226
  return .tracksOnly
252
227
  }
253
228
 
254
- /// The queue was empty: `index` becomes the current track AND leads the
255
- /// shuffle order. One operation because the two must not be separable —
256
- /// forgetting the second half is the bug this exists to prevent.
257
- ///
258
- /// `insert(at:count:)` drops new indices at *random* shuffle positions, so
259
- /// without the pin the starting track can land last in the order, which reads
260
- /// as `isLastInPlaybackOrder`: the queue "ends" (and fires
261
- /// `playerDidEndQueue`) the moment the first track finishes. Pins
262
- /// unconditionally, like `setQueue` — the order has to be sane whether or not
263
- /// shuffle is on right now, since `shuffleEnabled`'s didSet only re-pins on
264
- /// the off→on edge.
265
- ///
266
- /// Returns the change, so callers can `return adoptInitialCurrent(…)`.
229
+ // Also pins the current track first in the shuffle order, shuffle on or not: an inserted index
230
+ // lands at a random shuffle position, and landing last would end the queue after one track.
267
231
  private func adoptInitialCurrent(_ index: Int) -> QueueChange {
268
232
  currentIndex = max(0, min(index, tracks.count - 1))
269
233
  shuffleOrder = ShuffleOrder(length: tracks.count, firstIndex: currentIndex)
270
234
  return .tracksAndCurrent
271
235
  }
272
236
 
273
- /// Remove a track from the queue. The current track changes when it is the one removed.
237
+ /// Removing the current track makes the one after it current, wrapping to the first.
274
238
  @discardableResult
275
239
  func remove(_ index: Int) throws -> QueueChange {
276
240
  try throwIfQueueEmpty()
@@ -286,8 +250,7 @@ class QueueManager {
286
250
  return .tracksOnly
287
251
  }
288
252
 
289
- /// Move a track in the queue from one position to another. The current track never changes:
290
- /// the pointer follows the playing track.
253
+ /// A `toIndex` past the end moves the track to the end. The current track stays current.
291
254
  @discardableResult
292
255
  func move(fromIndex: Int, toIndex: Int) throws -> QueueChange {
293
256
  try throwIfQueueEmpty()
@@ -296,13 +259,8 @@ class QueueManager {
296
259
  let track = tracks.remove(at: fromIndex)
297
260
  let insertion = min(tracks.count, toIndex)
298
261
  tracks.insert(track, at: insertion)
299
- // Carry the moved track's shuffle position across the move. `insert(at:count:)`
300
- // would drop it at a RANDOM position instead — reordering the queue would then
301
- // silently reorder shuffled playback, and moving the playing track could land it
302
- // last in the order, ending the queue at the next track boundary with tracks
303
- // still unplayed (the failure `adoptInitialCurrent` guards against elsewhere).
304
- // `remove` shifts every later position down by one, so re-inserting at the
305
- // captured position restores the exact prior order.
262
+ // Keep the moved track's shuffle position: a plain insert lands it at random, reordering
263
+ // shuffled playback and possibly putting the playing track last.
306
264
  let shufflePosition = shuffleOrder.shufflePosition(of: fromIndex)
307
265
  shuffleOrder.remove(from: fromIndex, to: fromIndex + 1)
308
266
  shuffleOrder.insert(
@@ -318,7 +276,7 @@ class QueueManager {
318
276
  return .tracksOnly
319
277
  }
320
278
 
321
- /// Remove all tracks and reset state. Does nothing when there is no current track.
279
+ /// Does nothing when `currentIndex` is already -1.
322
280
  @discardableResult
323
281
  func clear() -> QueueChange {
324
282
  guard currentIndex != -1 else { return .none }
@@ -329,8 +287,6 @@ class QueueManager {
329
287
  return .tracksAndCurrent
330
288
  }
331
289
 
332
- /// Replace the track at a specific index; which index is current does not change.
333
- /// Throws like every other index-taking mutation here, rather than trapping.
334
290
  @discardableResult
335
291
  func replace(_ index: Int, _ track: Track) throws -> QueueChange {
336
292
  try throwIfIndexInvalid(index: index)
@@ -338,7 +294,7 @@ class QueueManager {
338
294
  return .tracksOnly
339
295
  }
340
296
 
341
- /// Remove all upcoming tracks (those after currentIndex).
297
+ /// Removes the tracks after the current one in queue order, not shuffle order.
342
298
  @discardableResult
343
299
  func removeUpcomingTracks() -> QueueChange {
344
300
  guard !tracks.isEmpty else { return .none }