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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (599) hide show
  1. package/README.md +32 -19
  2. package/android/src/cast/java/com/audiobrowser/cast/CastSupport.kt +8 -10
  3. package/android/src/main/java/com/audiobrowser/AudioBrowser.kt +96 -243
  4. package/android/src/main/java/com/audiobrowser/AudioBrowserLifecycleModule.kt +8 -12
  5. package/android/src/main/java/com/audiobrowser/AudioBrowserPackage.kt +1 -3
  6. package/android/src/main/java/com/audiobrowser/Callbacks.kt +1 -10
  7. package/android/src/main/java/com/audiobrowser/ForegroundStart.kt +13 -18
  8. package/android/src/main/java/com/audiobrowser/HeadlessTaskService.kt +3 -7
  9. package/android/src/main/java/com/audiobrowser/RemoteOutputs.kt +8 -10
  10. package/android/src/main/java/com/audiobrowser/Service.kt +20 -61
  11. package/android/src/main/java/com/audiobrowser/ServiceBinding.kt +9 -17
  12. package/android/src/main/java/com/audiobrowser/browser/ArtworkResolutionRegistry.kt +10 -9
  13. package/android/src/main/java/com/audiobrowser/browser/BrowseArtworkRegistry.kt +11 -8
  14. package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt +117 -448
  15. package/android/src/main/java/com/audiobrowser/browser/BrowserUrlResolution.kt +21 -60
  16. package/android/src/main/java/com/audiobrowser/browser/InertStyleDiagnostic.kt +20 -80
  17. package/android/src/main/java/com/audiobrowser/browser/JsonArtwork.kt +6 -10
  18. package/android/src/main/java/com/audiobrowser/browser/JsonModels.kt +7 -24
  19. package/android/src/main/java/com/audiobrowser/browser/RouteMatch.kt +2 -4
  20. package/android/src/main/java/com/audiobrowser/browser/SectionScope.kt +13 -31
  21. package/android/src/main/java/com/audiobrowser/browser/SimpleRouter.kt +12 -40
  22. package/android/src/main/java/com/audiobrowser/browser/StyleResolver.kt +15 -26
  23. package/android/src/main/java/com/audiobrowser/browser/TrackLoadHandler.kt +5 -15
  24. package/android/src/main/java/com/audiobrowser/extension/EnumExtensions.kt +1 -0
  25. package/android/src/main/java/com/audiobrowser/extension/NumberExt.kt +2 -0
  26. package/android/src/main/java/com/audiobrowser/extension/ResolvedTrackExt.kt +4 -8
  27. package/android/src/main/java/com/audiobrowser/extension/TappedTrack.kt +4 -6
  28. package/android/src/main/java/com/audiobrowser/extension/TrackIdentity.kt +3 -7
  29. package/android/src/main/java/com/audiobrowser/http/HttpClient.kt +13 -22
  30. package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt +17 -38
  31. package/android/src/main/java/com/audiobrowser/model/IcyTitle.kt +5 -6
  32. package/android/src/main/java/com/audiobrowser/model/PlaybackMetadata.kt +4 -9
  33. package/android/src/main/java/com/audiobrowser/model/PlayerSetupOptions.kt +18 -29
  34. package/android/src/main/java/com/audiobrowser/model/PlayerUpdateOptions.kt +6 -16
  35. package/android/src/main/java/com/audiobrowser/player/AutomaticBufferManager.kt +15 -45
  36. package/android/src/main/java/com/audiobrowser/player/CapabilityControls.kt +23 -59
  37. package/android/src/main/java/com/audiobrowser/player/CrossOriginHeaderStripper.kt +14 -26
  38. package/android/src/main/java/com/audiobrowser/player/DynamicLoadControl.kt +15 -43
  39. package/android/src/main/java/com/audiobrowser/player/EnginePlayback.kt +4 -4
  40. package/android/src/main/java/com/audiobrowser/player/EqualizerController.kt +15 -21
  41. package/android/src/main/java/com/audiobrowser/player/InterceptingPlayer.kt +14 -31
  42. package/android/src/main/java/com/audiobrowser/player/LocalEngine.kt +8 -8
  43. package/android/src/main/java/com/audiobrowser/player/MediaFactory.kt +16 -27
  44. package/android/src/main/java/com/audiobrowser/player/MediaSessionCallback.kt +119 -237
  45. package/android/src/main/java/com/audiobrowser/player/MediaSessionCommandManager.kt +48 -145
  46. package/android/src/main/java/com/audiobrowser/player/NowPlayingUpdater.kt +39 -100
  47. package/android/src/main/java/com/audiobrowser/player/PlaybackErrorClassifier.kt +16 -26
  48. package/android/src/main/java/com/audiobrowser/player/PlaybackStateMachine.kt +22 -28
  49. package/android/src/main/java/com/audiobrowser/player/PlaybackStateStore.kt +28 -64
  50. package/android/src/main/java/com/audiobrowser/player/PlaybackTimer.kt +8 -4
  51. package/android/src/main/java/com/audiobrowser/player/Player.kt +117 -405
  52. package/android/src/main/java/com/audiobrowser/player/PlayerCapabilitiesExt.kt +1 -1
  53. package/android/src/main/java/com/audiobrowser/player/PlayerEngineFactory.kt +11 -19
  54. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +30 -96
  55. package/android/src/main/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicy.kt +39 -95
  56. package/android/src/main/java/com/audiobrowser/player/ShuffleOrderLedBy.kt +7 -13
  57. package/android/src/main/java/com/audiobrowser/player/SleepTimer.kt +13 -30
  58. package/android/src/main/java/com/audiobrowser/player/SleepTimerManager.kt +7 -11
  59. package/android/src/main/java/com/audiobrowser/player/StuckRecoveryPolicy.kt +9 -22
  60. package/android/src/main/java/com/audiobrowser/player/TransformingDataSource.kt +22 -54
  61. package/android/src/main/java/com/audiobrowser/player/VolumeFader.kt +8 -15
  62. package/android/src/main/java/com/audiobrowser/remote/RemoteItem.kt +9 -8
  63. package/android/src/main/java/com/audiobrowser/remote/RemoteOutputsController.kt +13 -10
  64. package/android/src/main/java/com/audiobrowser/remote/RemotePlayback.kt +8 -8
  65. package/android/src/main/java/com/audiobrowser/remote/RemoteQueue.kt +12 -5
  66. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +28 -48
  67. package/android/src/main/java/com/audiobrowser/sonos/DeviceDescriptionParser.kt +11 -19
  68. package/android/src/main/java/com/audiobrowser/sonos/DidlLite.kt +2 -2
  69. package/android/src/main/java/com/audiobrowser/sonos/SoapClient.kt +6 -6
  70. package/android/src/main/java/com/audiobrowser/sonos/SoapEnvelopes.kt +8 -9
  71. package/android/src/main/java/com/audiobrowser/sonos/SoapResponseParser.kt +11 -18
  72. package/android/src/main/java/com/audiobrowser/sonos/SonosDiscoverer.kt +10 -10
  73. package/android/src/main/java/com/audiobrowser/sonos/SonosOutputs.kt +10 -10
  74. package/android/src/main/java/com/audiobrowser/sonos/SonosPlayer.kt +21 -33
  75. package/android/src/main/java/com/audiobrowser/sonos/SonosRemote.kt +4 -6
  76. package/android/src/main/java/com/audiobrowser/sonos/SonosRouteProviderService.kt +9 -10
  77. package/android/src/main/java/com/audiobrowser/sonos/SonosStreamUri.kt +7 -7
  78. package/android/src/main/java/com/audiobrowser/sonos/SonosTransport.kt +5 -4
  79. package/android/src/main/java/com/audiobrowser/sonos/SsdpDiscovery.kt +8 -3
  80. package/android/src/main/java/com/audiobrowser/sonos/SsdpMessages.kt +4 -6
  81. package/android/src/main/java/com/audiobrowser/sonos/ZoneGroupState.kt +13 -11
  82. package/android/src/main/java/com/audiobrowser/tls/AiaCertChaser.kt +34 -71
  83. package/android/src/main/java/com/audiobrowser/tls/AiaChasingExtendedTrustManager.kt +20 -37
  84. package/android/src/main/java/com/audiobrowser/tls/AiaChasingTrustManager.kt +18 -27
  85. package/android/src/main/java/com/audiobrowser/tls/AiaTls.kt +14 -29
  86. package/android/src/main/java/com/audiobrowser/tls/CachingCertificateFetcher.kt +68 -133
  87. package/android/src/main/java/com/audiobrowser/util/ArtworkContentProvider.kt +10 -22
  88. package/android/src/main/java/com/audiobrowser/util/ArtworkRoutes.kt +6 -6
  89. package/android/src/main/java/com/audiobrowser/util/ArtworkUris.kt +4 -3
  90. package/android/src/main/java/com/audiobrowser/util/ArtworkVariant.kt +2 -13
  91. package/android/src/main/java/com/audiobrowser/util/Automotive.kt +2 -4
  92. package/android/src/main/java/com/audiobrowser/util/BatteryOptimizationHelper.kt +3 -9
  93. package/android/src/main/java/com/audiobrowser/util/BatteryWarningStore.kt +4 -14
  94. package/android/src/main/java/com/audiobrowser/util/BrowserPathHelper.kt +21 -85
  95. package/android/src/main/java/com/audiobrowser/util/CoilArtworkLoader.kt +7 -7
  96. package/android/src/main/java/com/audiobrowser/util/CoilArtworkLoaderHolder.kt +5 -8
  97. package/android/src/main/java/com/audiobrowser/util/CoilBitmapLoader.kt +8 -24
  98. package/android/src/main/java/com/audiobrowser/util/EqualizerManager.kt +7 -39
  99. package/android/src/main/java/com/audiobrowser/util/MediaExtrasBuilder.kt +10 -14
  100. package/android/src/main/java/com/audiobrowser/util/MetadataAdapter.kt +5 -9
  101. package/android/src/main/java/com/audiobrowser/util/NetworkConnectivityMonitor.kt +5 -9
  102. package/android/src/main/java/com/audiobrowser/util/OutputMonitor.kt +21 -50
  103. package/android/src/main/java/com/audiobrowser/util/OutputSwitcher.kt +7 -20
  104. package/android/src/main/java/com/audiobrowser/util/PlayingStateFactory.kt +3 -5
  105. package/android/src/main/java/com/audiobrowser/util/RatingFavorites.kt +4 -5
  106. package/android/src/main/java/com/audiobrowser/util/StyleWire.kt +5 -5
  107. package/android/src/main/java/com/audiobrowser/util/SvgArtworkRenderer.kt +5 -9
  108. package/android/src/main/java/com/audiobrowser/util/SystemVolumeMonitor.kt +6 -9
  109. package/android/src/main/java/com/audiobrowser/util/TrackFactory.kt +25 -47
  110. package/android/src/nocast/java/com/audiobrowser/cast/CastSupport.kt +0 -2
  111. package/android/src/test/java/com/audiobrowser/ForegroundStartTest.kt +1 -2
  112. package/android/src/test/java/com/audiobrowser/LegacyRatingTest.kt +3 -3
  113. package/android/src/test/java/com/audiobrowser/ServiceBindingTest.kt +0 -13
  114. package/android/src/test/java/com/audiobrowser/ServiceTaskRemovedTest.kt +2 -3
  115. package/android/src/test/java/com/audiobrowser/TestFixtures.kt +5 -14
  116. package/android/src/test/java/com/audiobrowser/browser/BrowseArtworkRegistryTest.kt +1 -1
  117. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerBuildApiRequestTest.kt +2 -8
  118. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerFavoritesTest.kt +2 -12
  119. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerLayerResolutionTest.kt +5 -28
  120. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerTest.kt +11 -43
  121. package/android/src/test/java/com/audiobrowser/browser/BrowserUrlResolutionTest.kt +4 -13
  122. package/android/src/test/java/com/audiobrowser/browser/InertStyleDiagnosticTest.kt +2 -11
  123. package/android/src/test/java/com/audiobrowser/browser/JsonArtworkTest.kt +0 -2
  124. package/android/src/test/java/com/audiobrowser/browser/JsonStyleTest.kt +3 -8
  125. package/android/src/test/java/com/audiobrowser/browser/SectionScopeTest.kt +2 -14
  126. package/android/src/test/java/com/audiobrowser/browser/SimpleRouterTest.kt +1 -5
  127. package/android/src/test/java/com/audiobrowser/browser/StyleResolverTest.kt +2 -13
  128. package/android/src/test/java/com/audiobrowser/extension/TappedTrackTest.kt +1 -7
  129. package/android/src/test/java/com/audiobrowser/extension/TrackIdentityTest.kt +0 -5
  130. package/android/src/test/java/com/audiobrowser/http/RequestConfigBuilderTest.kt +8 -16
  131. package/android/src/test/java/com/audiobrowser/model/IcyTitleTest.kt +1 -1
  132. package/android/src/test/java/com/audiobrowser/player/BrowseTilesTest.kt +12 -29
  133. package/android/src/test/java/com/audiobrowser/player/CapabilityControlsTest.kt +3 -12
  134. package/android/src/test/java/com/audiobrowser/player/CrossOriginHeaderStripperTest.kt +0 -7
  135. package/android/src/test/java/com/audiobrowser/player/DynamicLoadControlTest.kt +0 -1
  136. package/android/src/test/java/com/audiobrowser/player/EqualizerControllerTest.kt +0 -9
  137. package/android/src/test/java/com/audiobrowser/player/LiveSeekCommandTest.kt +1 -2
  138. package/android/src/test/java/com/audiobrowser/player/MediaSessionSlotMappingTest.kt +0 -9
  139. package/android/src/test/java/com/audiobrowser/player/NowPlayingUpdaterTest.kt +15 -22
  140. package/android/src/test/java/com/audiobrowser/player/PlaybackErrorClassifierTest.kt +1 -24
  141. package/android/src/test/java/com/audiobrowser/player/PlaybackStateMachineTest.kt +0 -20
  142. package/android/src/test/java/com/audiobrowser/player/PlaybackStateStoreTrackJsonTest.kt +1 -6
  143. package/android/src/test/java/com/audiobrowser/player/PlaybackTimerTest.kt +2 -4
  144. package/android/src/test/java/com/audiobrowser/player/PlayerCastTest.kt +2 -2
  145. package/android/src/test/java/com/audiobrowser/player/PlayerEngineFactoryTest.kt +0 -3
  146. package/android/src/test/java/com/audiobrowser/player/PlayerInvalidTrackTest.kt +0 -1
  147. package/android/src/test/java/com/audiobrowser/player/PlayerSetupTest.kt +3 -2
  148. package/android/src/test/java/com/audiobrowser/player/PlayerSonosTest.kt +5 -1
  149. package/android/src/test/java/com/audiobrowser/player/PlayerSuppressionTest.kt +5 -7
  150. package/android/src/test/java/com/audiobrowser/player/RetryLoadErrorHandlingPolicyTest.kt +4 -35
  151. package/android/src/test/java/com/audiobrowser/player/SessionErrorMaskTest.kt +0 -5
  152. package/android/src/test/java/com/audiobrowser/player/ShuffleOrderLedByTest.kt +1 -8
  153. package/android/src/test/java/com/audiobrowser/player/StandardSkipTest.kt +4 -6
  154. package/android/src/test/java/com/audiobrowser/player/StuckRecoveryPolicyTest.kt +11 -11
  155. package/android/src/test/java/com/audiobrowser/player/TransformingDataSourceTest.kt +2 -23
  156. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +9 -10
  157. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +0 -1
  158. package/android/src/test/java/com/audiobrowser/sonos/DeviceDescriptionParserTest.kt +1 -3
  159. package/android/src/test/java/com/audiobrowser/sonos/DidlLiteTest.kt +0 -1
  160. package/android/src/test/java/com/audiobrowser/sonos/SoapClientTest.kt +0 -3
  161. package/android/src/test/java/com/audiobrowser/sonos/SoapEnvelopesTest.kt +0 -1
  162. package/android/src/test/java/com/audiobrowser/sonos/SoapResponseParserTest.kt +0 -1
  163. package/android/src/test/java/com/audiobrowser/sonos/SonosDiscovererTest.kt +2 -0
  164. package/android/src/test/java/com/audiobrowser/sonos/SonosPlayerTest.kt +0 -1
  165. package/android/src/test/java/com/audiobrowser/sonos/SonosRemoteTest.kt +1 -1
  166. package/android/src/test/java/com/audiobrowser/sonos/SonosRoutesTest.kt +2 -0
  167. package/android/src/test/java/com/audiobrowser/sonos/SonosTransportTest.kt +2 -6
  168. package/android/src/test/java/com/audiobrowser/sonos/SsdpMessagesTest.kt +0 -2
  169. package/android/src/test/java/com/audiobrowser/tls/AiaCertChaserTest.kt +13 -37
  170. package/android/src/test/java/com/audiobrowser/tls/AiaChasingTrustManagerTest.kt +10 -24
  171. package/android/src/test/java/com/audiobrowser/tls/CachingCertificateFetcherCallSiteTest.kt +15 -39
  172. package/android/src/test/java/com/audiobrowser/tls/CachingCertificateFetcherTest.kt +4 -10
  173. package/android/src/test/java/com/audiobrowser/util/ArtworkContentProviderTest.kt +2 -11
  174. package/android/src/test/java/com/audiobrowser/util/ArtworkUrisTest.kt +0 -1
  175. package/android/src/test/java/com/audiobrowser/util/BrowserPathHelperTest.kt +0 -4
  176. package/android/src/test/java/com/audiobrowser/util/CoilArtworkLoaderHolderTest.kt +1 -1
  177. package/android/src/test/java/com/audiobrowser/util/CoilArtworkLoaderTest.kt +0 -5
  178. package/android/src/test/java/com/audiobrowser/util/FakeImageLoader.kt +2 -2
  179. package/android/src/test/java/com/audiobrowser/util/MediaExtrasBuilderTest.kt +4 -12
  180. package/android/src/test/java/com/audiobrowser/util/OutputMonitorTest.kt +1 -1
  181. package/android/src/test/java/com/audiobrowser/util/PlayingStateFactoryTest.kt +0 -4
  182. package/android/src/test/java/com/audiobrowser/util/TrackFactoryBrowseTest.kt +1 -1
  183. package/android/src/test/java/com/audiobrowser/util/TrackFactoryMediaIdTest.kt +4 -6
  184. package/android/src/testCast/java/com/audiobrowser/cast/CastEndsTest.kt +1 -1
  185. package/android/src/testCast/java/com/audiobrowser/cast/SendingMediaItemConverterTest.kt +1 -0
  186. package/ios/AVPlayerEngine.swift +13 -21
  187. package/ios/AVPlayerEngineCallbacks.swift +2 -4
  188. package/ios/Browser/BrowseGate.swift +7 -8
  189. package/ios/Browser/BrowserConfig.swift +19 -34
  190. package/ios/Browser/BrowserError.swift +0 -1
  191. package/ios/Browser/BrowserManager.swift +29 -75
  192. package/ios/Browser/BrowserPathHelper.swift +13 -93
  193. package/ios/Browser/FavoriteSet.swift +7 -10
  194. package/ios/Browser/InertStyleDiagnostic.swift +17 -82
  195. package/ios/Browser/JsonModels.swift +11 -51
  196. package/ios/Browser/NavigationErrorState.swift +3 -2
  197. package/ios/Browser/PageResolver.swift +13 -23
  198. package/ios/Browser/RequestLayer.swift +16 -20
  199. package/ios/Browser/RequestPipeline.swift +33 -43
  200. package/ios/Browser/SearchDrillIn.swift +7 -13
  201. package/ios/Browser/SectionScope.swift +14 -26
  202. package/ios/Browser/SimpleRouter.swift +8 -15
  203. package/ios/Browser/StyleResolver.swift +12 -29
  204. package/ios/Browser/TabBarEntries.swift +6 -11
  205. package/ios/Browser/TrackIdTemplate.swift +6 -14
  206. package/ios/CarPlay/CPInterfaceController+Safe.swift +19 -28
  207. package/ios/CarPlay/CarPlayArtworkResolver.swift +5 -9
  208. package/ios/CarPlay/CarPlayController.swift +4 -4
  209. package/ios/CarPlay/CarPlayImageLoader.swift +11 -26
  210. package/ios/CarPlay/CarPlayListItemFactory.swift +30 -80
  211. package/ios/CarPlay/CarPlayNowPlayingManager.swift +19 -54
  212. package/ios/CarPlay/CarPlaySession+Navigator.swift +10 -10
  213. package/ios/CarPlay/CarPlaySession+PageLoader.swift +6 -5
  214. package/ios/CarPlay/CarPlaySession+Refresher.swift +2 -2
  215. package/ios/CarPlay/CarPlaySession+TabBar.swift +19 -26
  216. package/ios/CarPlay/CarPlaySession.swift +13 -17
  217. package/ios/CarPlay/CarPlayTemplates.swift +6 -7
  218. package/ios/CarPlay/IntentHandlers.swift +3 -5
  219. package/ios/CarPlay/MediaIntentCriteria.swift +15 -29
  220. package/ios/CarPlay/MediaIntentHandler.swift +4 -7
  221. package/ios/CarPlay/MediaIntentPlayback.swift +9 -8
  222. package/ios/CarPlay/NowPlayingButtonRules.swift +3 -4
  223. package/ios/CarPlay/SectionPresentation.swift +18 -28
  224. package/ios/CarPlay/TopTemplateReplacer.swift +8 -9
  225. package/ios/Extension/Capability+RemoteCommand.swift +3 -3
  226. package/ios/Extension/ChapterMetadata+AVFoundation.swift +2 -5
  227. package/ios/Extension/CxxVectorConformances.swift +4 -16
  228. package/ios/Extension/NavigationError+Conversion.swift +4 -7
  229. package/ios/Extension/PlayerCapabilities+Favorite.swift +0 -1
  230. package/ios/Extension/RequestConfig+Copying.swift +2 -6
  231. package/ios/Extension/ResolvedTrack+Copying.swift +2 -8
  232. package/ios/Extension/SearchParams+Query.swift +4 -4
  233. package/ios/Extension/Section+Copying.swift +3 -6
  234. package/ios/Extension/String+IcyCharset.swift +5 -5
  235. package/ios/Extension/TimedMetadata+AVFoundation.swift +6 -12
  236. package/ios/Extension/Track+AVPlayer.swift +1 -2
  237. package/ios/Extension/Track+Copying.swift +2 -8
  238. package/ios/Extension/Track+Identity.swift +4 -9
  239. package/ios/Extension/TrackMetadata+AVFoundation.swift +10 -13
  240. package/ios/Extension/UIApplication+ActiveScene.swift +6 -14
  241. package/ios/Extension/Variant+Artwork.swift +8 -22
  242. package/ios/Http/HttpClient.swift +3 -3
  243. package/ios/HybridAudioBrowser+Browser.swift +10 -16
  244. package/ios/HybridAudioBrowser+Options.swift +6 -9
  245. package/ios/HybridAudioBrowser+Player.swift +8 -16
  246. package/ios/HybridAudioBrowser+PlayerCallbacks.swift +4 -5
  247. package/ios/HybridAudioBrowser+Stubs.swift +5 -7
  248. package/ios/HybridAudioBrowser.swift +54 -79
  249. package/ios/Model/NitroTypeStubs.swift +15 -22
  250. package/ios/Model/PlayerUpdateOptions.swift +6 -21
  251. package/ios/Model/RemoteCommand.swift +2 -2
  252. package/ios/Model/TrackPlayerError.swift +9 -22
  253. package/ios/NowPlayingInfo/NowPlayingInfoController.swift +21 -40
  254. package/ios/NowPlayingInfo/SilentAudioPrimer.swift +10 -16
  255. package/ios/Observer/ItemObserver.swift +7 -5
  256. package/ios/Observer/PlayerObserver.swift +5 -5
  257. package/ios/PlaybackEvent.swift +2 -2
  258. package/ios/Player/AirPlayStallJudgement.swift +7 -9
  259. package/ios/Player/AudioSessionController.swift +14 -15
  260. package/ios/Player/DeferredSeek.swift +2 -2
  261. package/ios/Player/EndOfTrackJudgement.swift +6 -13
  262. package/ios/Player/ErrorStatus.swift +8 -7
  263. package/ios/Player/MediaLoader.swift +20 -24
  264. package/ios/Player/NowPlayingLines.swift +1 -4
  265. package/ios/Player/NowPlayingUpdater.swift +35 -61
  266. package/ios/Player/PersistedPlaybackState.swift +1 -2
  267. package/ios/Player/PlaybackFailure.swift +20 -24
  268. package/ios/Player/PlaybackPersistence.swift +5 -6
  269. package/ios/Player/PlaybackStateMachine.swift +8 -11
  270. package/ios/Player/PlaybackTimer.swift +8 -11
  271. package/ios/Player/Player.swift +6 -13
  272. package/ios/Player/PlayerEngine.swift +20 -20
  273. package/ios/Player/PlayerStatusTypes.swift +1 -2
  274. package/ios/Player/QueueManager.swift +23 -67
  275. package/ios/Player/RetryLoop.swift +39 -50
  276. package/ios/Player/ShuffleOrder.swift +17 -57
  277. package/ios/Player/SleepTimerManager.swift +13 -28
  278. package/ios/Player/VolumeFader.swift +16 -16
  279. package/ios/RemoteCommand/RemoteCommandCallbacks.swift +6 -16
  280. package/ios/RemoteCommand/RemoteCommandController.swift +8 -10
  281. package/ios/Tests/AirPlayStallJudgementTests.swift +4 -4
  282. package/ios/Tests/BrowserPathHelperTests.swift +3 -6
  283. package/ios/Tests/DeferredSeekTests.swift +1 -3
  284. package/ios/Tests/EmitterTests.swift +0 -1
  285. package/ios/Tests/EndOfTrackJudgementTests.swift +1 -6
  286. package/ios/Tests/FavoriteSetTests.swift +1 -0
  287. package/ios/Tests/GenerationMemoTests.swift +2 -2
  288. package/ios/Tests/InertStyleDiagnosticTests.swift +4 -10
  289. package/ios/Tests/JsonModelsTests.swift +5 -12
  290. package/ios/Tests/LRUCacheTests.swift +1 -5
  291. package/ios/Tests/MediaIntentCriteriaTests.swift +2 -7
  292. package/ios/Tests/MediaLoaderTests.swift +3 -12
  293. package/ios/Tests/ObserverTests.swift +3 -3
  294. package/ios/Tests/PlaybackErrorTests.swift +7 -9
  295. package/ios/Tests/PlaybackFailureTests.swift +9 -17
  296. package/ios/Tests/PlaybackPersistenceTests.swift +1 -0
  297. package/ios/Tests/PlaybackStateMachineTests.swift +1 -16
  298. package/ios/Tests/PlaybackTimerTests.swift +2 -3
  299. package/ios/Tests/PlayerPolicyTests.swift +10 -26
  300. package/ios/Tests/PlayerTests.swift +53 -88
  301. package/ios/Tests/PlayingStateTests.swift +0 -1
  302. package/ios/Tests/QueueManagerTests.swift +30 -80
  303. package/ios/Tests/RemoteCommandControllerTests.swift +5 -13
  304. package/ios/Tests/ResolvedTrackCopyingTests.swift +0 -2
  305. package/ios/Tests/RetryLoopTests.swift +12 -35
  306. package/ios/Tests/SearchDrillInTests.swift +4 -5
  307. package/ios/Tests/SectionPresentationTests.swift +3 -16
  308. package/ios/Tests/SectionScopeTests.swift +3 -6
  309. package/ios/Tests/SimpleRouterTests.swift +1 -5
  310. package/ios/Tests/SleepTimerManagerTests.swift +8 -11
  311. package/ios/Tests/StyleResolverTests.swift +4 -13
  312. package/ios/Tests/Support/ManualSleepTimerScheduler.swift +3 -8
  313. package/ios/Tests/Support/TestTypes.swift +5 -15
  314. package/ios/Tests/TabBarEntriesTests.swift +0 -2
  315. package/ios/Tests/TimedMetadataAVFoundationTests.swift +2 -3
  316. package/ios/Tests/TopTemplateReplacerTests.swift +1 -1
  317. package/ios/Tests/TrackIdTemplateTests.swift +2 -6
  318. package/ios/Tests/TrackMetadataAVFoundationTests.swift +1 -4
  319. package/ios/Tests/TrackSelectorTests.swift +3 -15
  320. package/ios/TrackSelector.swift +13 -25
  321. package/ios/Util/ArtworkFreshness.swift +6 -6
  322. package/ios/Util/ArtworkImageFetcher.swift +19 -20
  323. package/ios/Util/ConcurrentMap.swift +2 -2
  324. package/ios/Util/Emitter.swift +8 -13
  325. package/ios/Util/NetworkMonitor.swift +4 -6
  326. package/ios/Util/OutputPicker.swift +1 -1
  327. package/ios/Util/ReadyValue.swift +3 -2
  328. package/ios/Util/SFSymbolRenderer.swift +17 -30
  329. package/ios/Util/SVGProcessor.swift +5 -9
  330. package/lib/commonjs/CLAUDE.md +7 -2
  331. package/lib/commonjs/features/battery.js +16 -12
  332. package/lib/commonjs/features/battery.js.map +1 -1
  333. package/lib/commonjs/features/browser-config.js +1 -1
  334. package/lib/commonjs/features/browser.js +74 -24
  335. package/lib/commonjs/features/browser.js.map +1 -1
  336. package/lib/commonjs/features/carConnection.js +3 -4
  337. package/lib/commonjs/features/carConnection.js.map +1 -1
  338. package/lib/commonjs/features/equalizer.js +9 -5
  339. package/lib/commonjs/features/equalizer.js.map +1 -1
  340. package/lib/commonjs/features/errors.js +35 -21
  341. package/lib/commonjs/features/errors.js.map +1 -1
  342. package/lib/commonjs/features/favorites.js +15 -13
  343. package/lib/commonjs/features/favorites.js.map +1 -1
  344. package/lib/commonjs/features/gate.js +12 -6
  345. package/lib/commonjs/features/gate.js.map +1 -1
  346. package/lib/commonjs/features/metadata.js +16 -14
  347. package/lib/commonjs/features/metadata.js.map +1 -1
  348. package/lib/commonjs/features/network.js +5 -1
  349. package/lib/commonjs/features/network.js.map +1 -1
  350. package/lib/commonjs/features/nowPlaying.js +28 -14
  351. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  352. package/lib/commonjs/features/output.js +8 -4
  353. package/lib/commonjs/features/output.js.map +1 -1
  354. package/lib/commonjs/features/playback/controls.js +10 -5
  355. package/lib/commonjs/features/playback/controls.js.map +1 -1
  356. package/lib/commonjs/features/playback/playWhenReady.js +6 -5
  357. package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
  358. package/lib/commonjs/features/playback/playing.js +5 -3
  359. package/lib/commonjs/features/playback/playing.js.map +1 -1
  360. package/lib/commonjs/features/playback/progress.js +11 -5
  361. package/lib/commonjs/features/playback/progress.js.map +1 -1
  362. package/lib/commonjs/features/playback/state.js +3 -3
  363. package/lib/commonjs/features/playback/state.js.map +1 -1
  364. package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
  365. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  366. package/lib/commonjs/features/playback/volume.js +6 -5
  367. package/lib/commonjs/features/playback/volume.js.map +1 -1
  368. package/lib/commonjs/features/player/options.js +20 -10
  369. package/lib/commonjs/features/player/options.js.map +1 -1
  370. package/lib/commonjs/features/player/setup.js +34 -38
  371. package/lib/commonjs/features/player/setup.js.map +1 -1
  372. package/lib/commonjs/features/queue/activeTrack.js +0 -1
  373. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  374. package/lib/commonjs/features/queue/queue.js +48 -20
  375. package/lib/commonjs/features/queue/queue.js.map +1 -1
  376. package/lib/commonjs/features/queue/repeatMode.js +2 -1
  377. package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
  378. package/lib/commonjs/features/queue/shuffle.js +0 -1
  379. package/lib/commonjs/features/queue/shuffle.js.map +1 -1
  380. package/lib/commonjs/features/remoteControls.js +59 -35
  381. package/lib/commonjs/features/remoteControls.js.map +1 -1
  382. package/lib/commonjs/features/sleepTimer.js +15 -6
  383. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  384. package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
  385. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  386. package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
  387. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  388. package/lib/commonjs/utils/getTrackIdentity.js +6 -4
  389. package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
  390. package/lib/commonjs/utils/useDebug.js +16 -3
  391. package/lib/commonjs/utils/useDebug.js.map +1 -1
  392. package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
  393. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  394. package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
  395. package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
  396. package/lib/commonjs/web/browser/sections.js +1 -1
  397. package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
  398. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  399. package/lib/module/CLAUDE.md +7 -2
  400. package/lib/module/features/battery.js +16 -12
  401. package/lib/module/features/battery.js.map +1 -1
  402. package/lib/module/features/browser-config.js +1 -1
  403. package/lib/module/features/browser.js +74 -24
  404. package/lib/module/features/browser.js.map +1 -1
  405. package/lib/module/features/carConnection.js +3 -4
  406. package/lib/module/features/carConnection.js.map +1 -1
  407. package/lib/module/features/equalizer.js +9 -5
  408. package/lib/module/features/equalizer.js.map +1 -1
  409. package/lib/module/features/errors.js +35 -21
  410. package/lib/module/features/errors.js.map +1 -1
  411. package/lib/module/features/favorites.js +15 -13
  412. package/lib/module/features/favorites.js.map +1 -1
  413. package/lib/module/features/gate.js +12 -6
  414. package/lib/module/features/gate.js.map +1 -1
  415. package/lib/module/features/metadata.js +16 -14
  416. package/lib/module/features/metadata.js.map +1 -1
  417. package/lib/module/features/network.js +5 -1
  418. package/lib/module/features/network.js.map +1 -1
  419. package/lib/module/features/nowPlaying.js +28 -14
  420. package/lib/module/features/nowPlaying.js.map +1 -1
  421. package/lib/module/features/output.js +8 -4
  422. package/lib/module/features/output.js.map +1 -1
  423. package/lib/module/features/playback/controls.js +10 -5
  424. package/lib/module/features/playback/controls.js.map +1 -1
  425. package/lib/module/features/playback/playWhenReady.js +6 -5
  426. package/lib/module/features/playback/playWhenReady.js.map +1 -1
  427. package/lib/module/features/playback/playing.js +5 -3
  428. package/lib/module/features/playback/playing.js.map +1 -1
  429. package/lib/module/features/playback/progress.js +11 -5
  430. package/lib/module/features/playback/progress.js.map +1 -1
  431. package/lib/module/features/playback/state.js +3 -3
  432. package/lib/module/features/playback/state.js.map +1 -1
  433. package/lib/module/features/playback/trackPlaybackTime.js +6 -1
  434. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  435. package/lib/module/features/playback/volume.js +6 -5
  436. package/lib/module/features/playback/volume.js.map +1 -1
  437. package/lib/module/features/player/options.js +20 -10
  438. package/lib/module/features/player/options.js.map +1 -1
  439. package/lib/module/features/player/setup.js +34 -38
  440. package/lib/module/features/player/setup.js.map +1 -1
  441. package/lib/module/features/queue/activeTrack.js +0 -1
  442. package/lib/module/features/queue/activeTrack.js.map +1 -1
  443. package/lib/module/features/queue/queue.js +48 -20
  444. package/lib/module/features/queue/queue.js.map +1 -1
  445. package/lib/module/features/queue/repeatMode.js +2 -1
  446. package/lib/module/features/queue/repeatMode.js.map +1 -1
  447. package/lib/module/features/queue/shuffle.js +0 -1
  448. package/lib/module/features/queue/shuffle.js.map +1 -1
  449. package/lib/module/features/remoteControls.js +59 -35
  450. package/lib/module/features/remoteControls.js.map +1 -1
  451. package/lib/module/features/sleepTimer.js +15 -6
  452. package/lib/module/features/sleepTimer.js.map +1 -1
  453. package/lib/module/utils/LazyNativeEmitter.js +6 -9
  454. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  455. package/lib/module/utils/NativeUpdatedValue.js +13 -12
  456. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  457. package/lib/module/utils/getTrackIdentity.js +6 -4
  458. package/lib/module/utils/getTrackIdentity.js.map +1 -1
  459. package/lib/module/utils/useDebug.js +16 -3
  460. package/lib/module/utils/useDebug.js.map +1 -1
  461. package/lib/module/web/NativeAudioBrowser.js +2 -4
  462. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  463. package/lib/module/web/browser/parseSearchResponse.js +3 -4
  464. package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
  465. package/lib/module/web/browser/sections.js +1 -1
  466. package/lib/module/web/util/BrowserPathHelper.js +1 -3
  467. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  468. package/lib/typescript/src/features/battery.d.ts +17 -12
  469. package/lib/typescript/src/features/battery.d.ts.map +1 -1
  470. package/lib/typescript/src/features/browser.d.ts +64 -24
  471. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  472. package/lib/typescript/src/features/carConnection.d.ts +3 -4
  473. package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
  474. package/lib/typescript/src/features/equalizer.d.ts +9 -5
  475. package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
  476. package/lib/typescript/src/features/errors.d.ts +37 -22
  477. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  478. package/lib/typescript/src/features/favorites.d.ts +15 -13
  479. package/lib/typescript/src/features/favorites.d.ts.map +1 -1
  480. package/lib/typescript/src/features/gate.d.ts +14 -8
  481. package/lib/typescript/src/features/gate.d.ts.map +1 -1
  482. package/lib/typescript/src/features/metadata.d.ts +37 -17
  483. package/lib/typescript/src/features/metadata.d.ts.map +1 -1
  484. package/lib/typescript/src/features/network.d.ts +5 -1
  485. package/lib/typescript/src/features/network.d.ts.map +1 -1
  486. package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
  487. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  488. package/lib/typescript/src/features/output.d.ts +8 -4
  489. package/lib/typescript/src/features/output.d.ts.map +1 -1
  490. package/lib/typescript/src/features/playback/controls.d.ts +10 -5
  491. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  492. package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
  493. package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
  494. package/lib/typescript/src/features/playback/playing.d.ts +16 -3
  495. package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
  496. package/lib/typescript/src/features/playback/progress.d.ts +11 -5
  497. package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
  498. package/lib/typescript/src/features/playback/state.d.ts +8 -3
  499. package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
  500. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
  501. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  502. package/lib/typescript/src/features/playback/volume.d.ts +6 -5
  503. package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
  504. package/lib/typescript/src/features/player/options.d.ts +52 -37
  505. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  506. package/lib/typescript/src/features/player/setup.d.ts +65 -60
  507. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  508. package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
  509. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  510. package/lib/typescript/src/features/queue/queue.d.ts +48 -20
  511. package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
  512. package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
  513. package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
  514. package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
  515. package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
  516. package/lib/typescript/src/features/remoteControls.d.ts +58 -25
  517. package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
  518. package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
  519. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  520. package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
  521. package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
  522. package/lib/typescript/src/types/browser.d.ts +181 -144
  523. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  524. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
  525. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  526. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
  527. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  528. package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
  529. package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
  530. package/lib/typescript/src/utils/useDebug.d.ts +16 -3
  531. package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
  532. package/package.json +1 -1
  533. package/src/CLAUDE.md +7 -2
  534. package/src/docs-floors.test.ts +71 -0
  535. package/src/features/battery.ts +17 -13
  536. package/src/features/browser-config.ts +1 -1
  537. package/src/features/browser.ts +65 -24
  538. package/src/features/carConnection.ts +3 -4
  539. package/src/features/equalizer.ts +9 -5
  540. package/src/features/errors.ts +37 -22
  541. package/src/features/favorites.ts +15 -13
  542. package/src/features/gate.ts +14 -8
  543. package/src/features/metadata.ts +37 -17
  544. package/src/features/network.ts +5 -1
  545. package/src/features/nowPlaying.ts +28 -14
  546. package/src/features/output.ts +8 -4
  547. package/src/features/playback/controls.ts +10 -5
  548. package/src/features/playback/playWhenReady.ts +6 -5
  549. package/src/features/playback/playing.ts +16 -3
  550. package/src/features/playback/progress.ts +11 -5
  551. package/src/features/playback/state.ts +8 -3
  552. package/src/features/playback/trackPlaybackTime.ts +9 -2
  553. package/src/features/playback/volume.ts +6 -5
  554. package/src/features/player/options.ts +54 -43
  555. package/src/features/player/setup.ts +67 -61
  556. package/src/features/queue/activeTrack.ts +0 -1
  557. package/src/features/queue/queue.ts +48 -20
  558. package/src/features/queue/repeatMode.ts +1 -1
  559. package/src/features/queue/shuffle.ts +0 -1
  560. package/src/features/remoteControls.ts +59 -35
  561. package/src/features/sleepTimer.ts +15 -7
  562. package/src/types/browser-nodes.ts +54 -57
  563. package/src/types/browser.ts +183 -146
  564. package/src/utils/LazyNativeEmitter.ts +6 -9
  565. package/src/utils/NativeUpdatedValue.ts +13 -12
  566. package/src/utils/getTrackIdentity.ts +6 -4
  567. package/src/utils/useDebug.ts +16 -3
  568. package/src/web/NativeAudioBrowser.ts +2 -4
  569. package/src/web/browser/parseSearchResponse.ts +3 -4
  570. package/src/web/browser/sections.ts +1 -1
  571. package/src/web/util/BrowserPathHelper.ts +1 -3
  572. package/website/guide/android-auto.md +25 -13
  573. package/website/guide/android-certificates.md +199 -120
  574. package/website/guide/artwork.md +93 -48
  575. package/website/guide/audio-output.md +86 -68
  576. package/website/guide/automotive.md +15 -10
  577. package/website/guide/basic-usage.md +5 -2
  578. package/website/guide/battery.md +50 -23
  579. package/website/guide/browser.md +155 -68
  580. package/website/guide/carplay.md +132 -49
  581. package/website/guide/configuration.md +85 -49
  582. package/website/guide/equalizer.md +36 -32
  583. package/website/guide/errors.md +106 -64
  584. package/website/guide/favorites.md +41 -31
  585. package/website/guide/gate.md +24 -10
  586. package/website/guide/getting-started.md +55 -2
  587. package/website/guide/hooks.md +53 -47
  588. package/website/guide/live-streams.md +80 -49
  589. package/website/guide/metadata.md +87 -53
  590. package/website/guide/migrating-from-track-player.md +94 -49
  591. package/website/guide/native-callback-fetch.md +46 -36
  592. package/website/guide/network.md +36 -20
  593. package/website/guide/now-playing.md +72 -44
  594. package/website/guide/playback.md +112 -35
  595. package/website/guide/queue.md +77 -43
  596. package/website/guide/remote-controls.md +87 -29
  597. package/website/guide/search.md +37 -22
  598. package/website/guide/sleep-timer.md +35 -14
  599. package/website/guide/track.md +59 -35
@@ -93,7 +93,7 @@ internal constructor(
93
93
  EqualizerController(onSettingsChanged = { settings -> callbacks?.onEqualizerChanged(settings) })
94
94
  private val mediaSessionCallback = MediaSessionCallback(this)
95
95
  internal val playbackStateStore = PlaybackStateStore(this)
96
- // The local engine's own volume: a receiver plays on at its own while the fade runs here.
96
+ // Fades the local engine only: a remote receiver keeps its own volume.
97
97
  internal val volumeFader =
98
98
  VolumeFader(getVolume = { exoPlayer.volume }, setVolume = { exoPlayer.volume = it })
99
99
  internal val sleepTimer =
@@ -108,7 +108,7 @@ internal constructor(
108
108
  private set
109
109
 
110
110
  /**
111
- * What plays: [exoPlayer], or while a remote output is on, the [RemoteSwitchingPlayer] around it.
111
+ * What plays: [exoPlayer], or while a remote output is on, the remote-switching player around it.
112
112
  * Every playback read and command goes here. Local-only work that would disturb a remote (retry,
113
113
  * reconnect, stuck recovery, the shuffle order) goes through [localEngine]; the equalizer,
114
114
  * skip-silence, buffering and the volume fade act on [exoPlayer] alone.
@@ -127,25 +127,25 @@ internal constructor(
127
127
 
128
128
  private var keepSessionAliveOnError = true
129
129
 
130
- /** Thread-safe cache of playWhenReady for access from non-main threads (e.g., retry policy) */
130
+ /**
131
+ * [playWhenReady] for the retry policy, which reads it off the main thread. Written eagerly by
132
+ * the setter, ahead of ExoPlayer's listener round-trip.
133
+ */
131
134
  @Volatile internal var playWhenReadyCache = false
132
135
 
133
136
  /**
134
- * Whether the current load has ever produced audio — selects between the retry policy's
135
- * first-connect and recovery budgets. Volatile: read from ExoPlayer's loader thread. Set when
136
- * playback starts, cleared on media-item transition (a new load starts unproven); retry reloads
137
- * of the same load keep it.
137
+ * Whether the current load has produced audio: picks the retry policy's first-connect or recovery
138
+ * budget. Read on ExoPlayer's loader thread. Cleared on a media-item transition; retry reloads of
139
+ * the same load keep it.
138
140
  */
139
141
  @Volatile internal var hasPlayedCache = false
140
142
 
141
- /** Last playWhenReady value emitted to JS — see [emitPlayWhenReadyChanged]. */
142
143
  private var lastEmittedPlayWhenReady: Boolean? = null
143
144
 
144
145
  /**
145
- * Emits the playWhenReady change to JS exactly once per value. Two producers exist: the
146
- * synchronous clear at ENDED in [setPlaybackState] (ordered before the state / queue-ended
147
- * callbacks, matching iOS) and the async media3 listener (authoritative for changes ExoPlayer
148
- * makes on its own, e.g. audio focus); the guard deduplicates their overlap.
146
+ * Emits a playWhenReady change to JS once per value. Both the synchronous clear at ENDED in
147
+ * [setPlaybackState] and the media3 listener (changes ExoPlayer makes itself, e.g. audio focus)
148
+ * call it; their overlap is dropped.
149
149
  */
150
150
  internal fun emitPlayWhenReadyChanged(value: Boolean) {
151
151
  if (lastEmittedPlayWhenReady == value) return
@@ -157,25 +157,21 @@ internal constructor(
157
157
  private lateinit var loadControl: DynamicLoadControl
158
158
  private var automaticBufferManager: AutomaticBufferManager? = null
159
159
 
160
- /**
161
- * Tracks whether a network-related retry is pending. When true, network restoration will trigger
162
- * an immediate retry via exoPlayer.prepare().
163
- */
160
+ /** A network-caused retry is waiting; regaining connectivity retries at once. */
164
161
  @Volatile private var pendingNetworkRetry = false
165
162
 
166
163
  private var browserRegistered = CompletableDeferred<AudioBrowser>()
167
164
  private var _coilBitmapLoader: CoilBitmapLoader? = null
168
165
 
169
- /**
170
- * Coil ImageLoader for SVG pre-rendering in Android Auto browse items. Set by Service after
171
- * creation.
172
- */
166
+ /** For SVG pre-rendering of Android Auto browse items. Set by the service. */
173
167
  var imageLoader: coil3.ImageLoader? = null
174
168
 
175
- /** Called on the main thread when a resumption meant to start playback fails. Set by Service. */
169
+ /**
170
+ * Called on the main thread when a resumption meant to start playback fails. Set by the service.
171
+ */
176
172
  var onPlaybackResumptionFailed: () -> Unit = {}
177
173
 
178
- /** Registry that maps content:// tokens to artwork URLs for the browse content provider. */
174
+ /** Maps the browse content provider's content:// tokens to artwork URLs. */
179
175
  val browseArtworkRegistry = com.audiobrowser.browser.BrowseArtworkRegistry()
180
176
 
181
177
  init {
@@ -185,24 +181,19 @@ internal constructor(
185
181
  ArtworkRoutes(browseArtworkRegistry, ArtworkUris.authorityFor(context.packageName))
186
182
  }
187
183
 
188
- /**
189
- * Set the CoilBitmapLoader for display-time bitmap loading. Called from Service after creation.
190
- */
191
184
  var coilBitmapLoader: CoilBitmapLoader?
192
185
  get() = _coilBitmapLoader
193
186
  set(value) {
194
187
  _coilBitmapLoader = value
195
188
  }
196
189
 
197
- // NOTE: setting the browser does NOT complete browserRegistered.
198
- // Configuration (routes/tabs) must be set before Android Auto can browse.
199
- // Call notifyBrowserConfigurationReady() after configuration is set.
190
+ // Setting this does not release callers already waiting in [awaitBrowser]: call
191
+ // [notifyBrowserConfigurationReady] once its routes and tabs are configured.
200
192
  var browser: AudioBrowser? = null
201
193
 
202
194
  /**
203
- * Notifies that the browser configuration is ready (routes/tabs are configured). This should be
204
- * called after setting the browser AND its configuration. Only then will Android Auto be able to
205
- * browse content.
195
+ * Marks the browser's routes and tabs configured: completes [awaitBrowser] and lets Android Auto
196
+ * browse. Call after setting [browser] and its configuration.
206
197
  */
207
198
  fun notifyBrowserConfigurationReady() {
208
199
  val audioBrowser = browser ?: return
@@ -210,15 +201,13 @@ internal constructor(
210
201
  if (!browserRegistered.isCompleted) {
211
202
  Timber.d("Browser configuration ready - completing deferred")
212
203
  browserRegistered.complete(audioBrowser)
213
- // Notify any subscribed controllers that content is now available
214
- // This handles the cold-start case where AA subscribed before browser was ready
204
+ // Android Auto may have subscribed on a cold start before the browser was ready.
215
205
  mediaSessionCallback.notifyBrowserReady()
216
206
  }
217
207
 
218
- // Update MediaSession commands when browser becomes available with search configured
219
- // Only update if search is available, since default state is "no search"
220
208
  if (::mediaSession.isInitialized) {
221
209
  val searchAvailable = audioBrowser.browserManager.config.hasSearch
210
+ // The session starts without search, so only a configured search needs an update.
222
211
  if (searchAvailable) {
223
212
  mediaSessionCallback.updateMediaSession(
224
213
  mediaSession,
@@ -233,9 +222,8 @@ internal constructor(
233
222
  }
234
223
 
235
224
  /**
236
- * Drops a completed browser registration so [awaitBrowser] waits for the replacement instead of
237
- * handing out the disposed browser. A [CompletableDeferred] completes once, so it would otherwise
238
- * pin the first browser for the life of the process.
225
+ * Makes [awaitBrowser] wait for a replacement browser instead of returning the disposed one; a
226
+ * [CompletableDeferred] completes only once.
239
227
  */
240
228
  fun forgetBrowserRegistration() {
241
229
  if (browserRegistered.isCompleted) {
@@ -244,9 +232,9 @@ internal constructor(
244
232
  }
245
233
 
246
234
  /**
247
- * Suspends until the browser is registered, with a timeout.
235
+ * [browser] if set, else the one [notifyBrowserConfigurationReady] registers next.
248
236
  *
249
- * @throws TimeoutCancellationException if browser is not registered within timeout
237
+ * @throws TimeoutCancellationException if it is not registered within 10 seconds
250
238
  */
251
239
  suspend fun awaitBrowser(): AudioBrowser =
252
240
  browser
@@ -309,9 +297,8 @@ internal constructor(
309
297
  }
310
298
 
311
299
  /**
312
- * Re-derives [playingState] from the current [shouldPlayWhenReady] + [playbackState] and emits
313
- * `onPlaybackPlayingState` when it changed. The only writer of [playingState], called at every
314
- * change point of its inputs.
300
+ * Re-derives [playingState] from [shouldPlayWhenReady] and [playbackState], emitting when it
301
+ * changed. Its only writer: call it wherever either input changes.
315
302
  */
316
303
  internal fun refreshPlayingState() {
317
304
  val newPlayingState = PlayingStateFactory.derive(shouldPlayWhenReady, playbackState)
@@ -326,11 +313,9 @@ internal constructor(
326
313
  var playWhenReady: Boolean
327
314
  get() = sessionPlayer.playWhenReady
328
315
  set(value) {
329
- // Raising the intent at STATE_ENDED must replay, not silently no-op:
330
- // ExoPlayer's setPlayWhenReady(true) never restarts an ended player (the
331
- // ENDED→seekToDefaultPosition replay lives in media3's media-button
332
- // path, not the Player API). In the setter so every writer gets it —
333
- // play(), togglePlayback() and JS setPlayWhenReady alike.
316
+ // ExoPlayer's setPlayWhenReady(true) never restarts an ended player (media3 replays only on
317
+ // its media-button path). Here in the setter so every writer replays: play(),
318
+ // togglePlayback(), JS.
334
319
  if (value && sessionPlayer.playbackState == MediaPlayer.STATE_ENDED) {
335
320
  sessionPlayer.seekToDefaultPosition()
336
321
  }
@@ -353,7 +338,7 @@ internal constructor(
353
338
  if (sessionPlayer.bufferedPosition == C.INDEX_UNSET.toLong()) 0
354
339
  else sessionPlayer.bufferedPosition
355
340
 
356
- /** The volume, from 0 to 1: the local engine's, or while remote, the receiver's. */
341
+ /** From 0 to 1: the local engine's, or while remote, the receiver's. */
357
342
  var volume: Float
358
343
  get() = sessionPlayer.volume
359
344
  set(value) {
@@ -371,7 +356,7 @@ internal constructor(
371
356
 
372
357
  /**
373
358
  * False while ExoPlayer suppresses output (a transient audio focus loss) though [playWhenReady]
374
- * stays raised for it to resume on; mirrors media3's `ExoPlayerImplInternal.shouldPlayWhenReady`.
359
+ * stays raised to resume on; mirrors media3's `ExoPlayerImplInternal.shouldPlayWhenReady`.
375
360
  */
376
361
  internal val shouldPlayWhenReady
377
362
  get() =
@@ -407,28 +392,15 @@ internal constructor(
407
392
  .map { index -> TrackFactory.fromMedia3(sessionPlayer.getMediaItemAt(index)) }
408
393
  .toTypedArray()
409
394
 
410
- /**
411
- * Whether nothing follows the current item in *playback order* — shuffle- and repeat-aware via
412
- * media3's own order computation (the linear `currentMediaItemIndex == count - 1` check missed a
413
- * shuffled queue whose playback order ends on a different linear index). Matches iOS's
414
- * `isLastInPlaybackOrder`.
415
- */
395
+ /** In playback order, so shuffle and repeat count; not the last linear index. */
416
396
  val isLastInPlaybackOrder: Boolean
417
397
  get() = sessionPlayer.nextMediaItemIndex == C.INDEX_UNSET
418
398
 
419
- /**
420
- * The source path from which the current queue was expanded (e.g., from a contextual path). Used
421
- * to avoid re-expanding the queue when selecting tracks from the same source.
422
- */
399
+ /** The path the queue was expanded from, so selecting from the same source skips re-expanding. */
423
400
  var queueSourcePath: String? = null
424
401
  internal set
425
402
 
426
- /**
427
- * Get track at index with bounds checking.
428
- *
429
- * @param index The index of the track to retrieve.
430
- * @throws IllegalArgumentException if index is out of bounds.
431
- */
403
+ /** @throws IllegalArgumentException if [index] is out of bounds. */
432
404
  fun getTrack(index: Int): Track {
433
405
  if (index < 0 || index >= sessionPlayer.mediaItemCount) {
434
406
  throw IllegalArgumentException(
@@ -447,14 +419,12 @@ internal constructor(
447
419
  private var engineOptions: PlayerSetupOptions? = null
448
420
 
449
421
  /**
450
- * Applies [setupOptions]: builds the ExoPlayer on the first call, and rebuilds it only when the
451
- * engine options differ from the ones it was built with. A rebuild carries over the queue, the
452
- * position and the play intent, so playback that has started goes on with the new engine.
422
+ * Builds the ExoPlayer on the first call, and rebuilds it only when the engine options changed. A
423
+ * rebuild carries over the queue, the position and the play intent.
453
424
  */
454
425
  fun setup(setupOptions: PlayerSetupOptions) {
455
426
  nowPlaying.enabled = setupOptions.autoUpdateNowPlayingMetadata
456
- // Wrap the Nitro Func into a plain suspend call so the updater (and its tests) never touch
457
- // bridge types; the double-await depth is unchanged (invoke -> bridge Promise -> JS promise).
427
+ // Unwrapped from the Nitro Func so the updater never touches bridge types.
458
428
  nowPlaying.formatter =
459
429
  setupOptions.nowPlayingMetadataFormatter?.let { f -> { params -> f.invoke(params).await() } }
460
430
 
@@ -480,15 +450,15 @@ internal constructor(
480
450
  }
481
451
 
482
452
  if (setupOptions.maxCacheSize > 0) {
483
- // SimpleCache locks its folder — re-setup must release the previous
484
- // instance first or the constructor throws.
453
+ // SimpleCache locks its folder: the constructor throws until the previous one is released.
485
454
  cache?.release()
486
455
  cache =
487
456
  SimpleCache(
488
457
  File(context.cacheDir, "RNAB"),
489
458
  LeastRecentlyUsedCacheEvictor(
459
+ // MB to bytes
490
460
  setupOptions.maxCacheSize.toLong() * 1_000_000
491
- ), // MB to bytes
461
+ ),
492
462
  StandaloneDatabaseProvider(context),
493
463
  )
494
464
  } else {
@@ -496,8 +466,6 @@ internal constructor(
496
466
  cache = null
497
467
  }
498
468
 
499
- // One engine generation: load control, media factory, ExoPlayer (pure construction —
500
- // see buildPlayerEngine; lifecycle and wiring stay here).
501
469
  val engine =
502
470
  buildPlayerEngine(
503
471
  context,
@@ -507,7 +475,6 @@ internal constructor(
507
475
  isOnline = { networkMonitor.getOnline() },
508
476
  hasPlayed = { hasPlayedCache },
509
477
  onRetryPending = { exception, isNetworkError ->
510
- // Track pending network retries for acceleration when connectivity returns
511
478
  pendingNetworkRetry = isNetworkError
512
479
  if (isNetworkError) {
513
480
  Timber.d("Network retry pending, will accelerate on connectivity restoration")
@@ -531,26 +498,22 @@ internal constructor(
531
498
  callbacks?.onPlaybackChanged(Playback(PlaybackState.NONE, null))
532
499
  equalizer.initialize(exoPlayer.audioSessionId)
533
500
  } else if (localEngine.isActive) {
534
- // No listener heard the restore; its prepare() leaves the engine buffering. While remote,
501
+ // No listener heard the restore, and its prepare() leaves the engine buffering. While remote,
535
502
  // the receiver plays on unchanged.
536
503
  setPlaybackState(
537
504
  if (exoPlayer.playbackState == ExoPlayer.STATE_IDLE) PlaybackState.NONE
538
505
  else PlaybackState.BUFFERING
539
506
  )
540
- // The new engine can refuse the carried intent (audio focus denied) without a change event:
541
- // sync the eager cache and tell JS, or a stale true sticks.
507
+ // The new engine can refuse the carried intent (audio focus denied) without a change event,
508
+ // which would leave a stale true in the cache and in JS.
542
509
  playWhenReadyCache = exoPlayer.playWhenReady
543
510
  emitPlayWhenReadyChanged(exoPlayer.playWhenReady)
544
511
  }
545
512
 
546
- // Set up automatic buffer management if enabled
547
513
  setupAutomaticBufferManager(setupOptions.automaticBuffer)
548
514
  }
549
515
 
550
- /**
551
- * Wraps [sessionPlayer] for the session: the remote switch while there is one, else [exoPlayer].
552
- * Called when either changes.
553
- */
516
+ // Call whenever [exoPlayer] or the remote player changes.
554
517
  private fun attachSessionPlayer() {
555
518
  if (::forwardingPlayer.isInitialized) forwardingPlayer.removeListener(playerListener)
556
519
  sessionPlayer = remoteOutputs.player ?: exoPlayer
@@ -560,9 +523,6 @@ internal constructor(
560
523
  if (::mediaSession.isInitialized) mediaSession.player = forwardingPlayer
561
524
  }
562
525
 
563
- /**
564
- * The URLs a receiver fetches for [track]: through the media transform, which can call into JS.
565
- */
566
526
  private suspend fun resolveRemoteUrls(track: Track): RemoteUrls {
567
527
  val src = checkNotNull(track.src) { "The track has no src" }
568
528
  val browserManager = browser?.browserManager
@@ -572,9 +532,7 @@ internal constructor(
572
532
  )
573
533
  }
574
534
 
575
- /** Sets up or tears down the automatic buffer manager based on the enabled flag. */
576
535
  private fun setupAutomaticBufferManager(enabled: Boolean) {
577
- // Detach existing manager if any
578
536
  automaticBufferManager?.detach()
579
537
 
580
538
  if (enabled) {
@@ -588,21 +546,13 @@ internal constructor(
588
546
  }
589
547
  }
590
548
 
591
- /**
592
- * Starts observing network connectivity changes and invokes the callback when state changes. Also
593
- * handles accelerating pending network retries when connectivity is restored.
594
- *
595
- * @param scope The coroutine scope to use for observation
596
- */
597
549
  fun observeNetworkConnectivity(scope: kotlinx.coroutines.CoroutineScope) {
598
550
  networkMonitor.observeOnline(scope) { isOnline ->
599
551
  callbacks?.onOnlineChanged(isOnline)
600
552
 
601
- // Re-render now-playing so the formatter's stall classification (buffering vs offline) tracks
602
- // connectivity immediately, not only on the next playback transition.
553
+ // The formatter tells a stall from being offline, so it renders on a connectivity change too.
603
554
  nowPlaying.render()
604
555
 
605
- // Accelerate pending network retry when connectivity is restored
606
556
  if (isOnline && pendingNetworkRetry) {
607
557
  Timber.d("Network restored with pending retry, triggering immediate retry")
608
558
  pendingNetworkRetry = false
@@ -612,12 +562,7 @@ internal constructor(
612
562
  }
613
563
  }
614
564
 
615
- /**
616
- * Loads a track into the player. If there is a current track, it will be replaced. If the queue
617
- * is empty, the track will be added.
618
- *
619
- * @param track The [Track] to load.
620
- */
565
+ /** Replaces the current track, keeping the rest of the queue; on an empty queue, adds it. */
621
566
  fun load(track: Track) {
622
567
  if (sessionPlayer.mediaItemCount == 0) {
623
568
  add(track)
@@ -629,37 +574,19 @@ internal constructor(
629
574
  }
630
575
  }
631
576
 
632
- /**
633
- * Add a single track to the queue. If the AudioPlayer has no track loaded, it will load the
634
- * `track`.
635
- *
636
- * @param track The [Track] to add.
637
- */
638
577
  fun add(track: Track) {
639
578
  val mediaItem = TrackFactory.toMedia3(track)
640
579
  sessionPlayer.addMediaItem(mediaItem)
641
580
  sessionPlayer.prepare()
642
581
  }
643
582
 
644
- /**
645
- * Add multiple tracks to the queue. If the AudioPlayer has no track loaded, it will load the
646
- * first track in the list.
647
- *
648
- * @param tracks The [Track]s to add.
649
- */
650
583
  fun add(tracks: Array<Track>) {
651
584
  val mediaItems = TrackFactory.toMedia3(tracks)
652
585
  sessionPlayer.addMediaItems(mediaItems.toList())
653
586
  sessionPlayer.prepare()
654
587
  }
655
588
 
656
- /**
657
- * Add multiple tracks to the queue.
658
- *
659
- * @param tracks The [Track]s to add.
660
- * @param atIndex Index to insert tracks at. Use -1 to append to the end of the queue.
661
- * @throws IllegalArgumentException if index is out of bounds.
662
- */
589
+ /** @throws IllegalArgumentException unless [atIndex] is within the queue, or -1 to append. */
663
590
  fun add(tracks: Array<Track>, atIndex: Int) {
664
591
  validateInsertIndex(atIndex)
665
592
  val index = if (atIndex == -1) sessionPlayer.mediaItemCount else atIndex
@@ -668,24 +595,13 @@ internal constructor(
668
595
  sessionPlayer.prepare()
669
596
  }
670
597
 
671
- /**
672
- * Remove a track from the queue.
673
- *
674
- * @param index The index of the track to remove.
675
- * @throws IllegalArgumentException if index is out of bounds.
676
- */
598
+ /** @throws IllegalArgumentException if [index] is out of bounds. */
677
599
  fun remove(index: Int) {
678
600
  validateIndex(index)
679
601
  sessionPlayer.removeMediaItem(index)
680
602
  }
681
603
 
682
- /**
683
- * Remove tracks from the queue.
684
- *
685
- * @param indexes The indexes of the tracks to remove.
686
- * @throws IllegalArgumentException if any index is out of bounds or if duplicate indexes are
687
- * provided.
688
- */
604
+ /** @throws IllegalArgumentException if an index is out of bounds or repeated. */
689
605
  fun remove(indexes: List<Int>) {
690
606
  if (indexes.toSet().size != indexes.size) {
691
607
  throw IllegalArgumentException("Duplicate indexes provided")
@@ -695,59 +611,33 @@ internal constructor(
695
611
  sorted.forEach { sessionPlayer.removeMediaItem(it) }
696
612
  }
697
613
 
698
- /**
699
- * Skip to the next track in the queue, which may depend on the current repeat mode. Does nothing
700
- * if there is no next track to skip to.
701
- */
702
614
  fun next() {
703
615
  sessionPlayer.seekToNextMediaItem()
704
616
  sessionPlayer.prepare()
705
617
  }
706
618
 
707
- /**
708
- * Skip to the previous track in the queue, which may depend on the current repeat mode. Does
709
- * nothing if there is no previous track to skip to.
710
- */
711
619
  fun previous() {
712
620
  sessionPlayer.seekToPreviousMediaItem()
713
621
  sessionPlayer.prepare()
714
622
  }
715
623
 
716
624
  /**
717
- * Move an track in the queue from one position to another.
625
+ * A [toIndex] past the end moves the track to the end.
718
626
  *
719
- * @param fromIndex The index of the track to move.
720
- * @param toIndex The index to move the track to. If the index is larger than the size of the
721
- * queue, the track is moved to the end of the queue instead.
722
- * @throws IllegalArgumentException if fromIndex is out of bounds.
627
+ * @throws IllegalArgumentException if [fromIndex] is out of bounds.
723
628
  */
724
629
  fun move(fromIndex: Int, toIndex: Int) {
725
630
  validateIndex(fromIndex)
726
631
  sessionPlayer.moveMediaItem(fromIndex, toIndex)
727
632
  }
728
633
 
729
- /**
730
- * Skips to a track in the queue.
731
- *
732
- * @param index the index to skip to
733
- * @throws IllegalArgumentException if index is out of bounds.
734
- */
634
+ /** @throws IllegalArgumentException if [index] is out of bounds. */
735
635
  fun skipTo(index: Int) {
736
636
  validateIndex(index)
737
637
  sessionPlayer.seekTo(index, C.TIME_UNSET)
738
638
  sessionPlayer.prepare()
739
639
  }
740
640
 
741
- /**
742
- * Sets the queue with new tracks, optionally starting at a specific index and position. This is
743
- * more efficient than calling clear() + add() + skipTo() separately.
744
- *
745
- * @param tracks The tracks to set as the new queue.
746
- * @param startIndex The index to start playback from (default: 0).
747
- * @param startPositionMs The position in milliseconds to start from (default: 0).
748
- * @param sourcePath Optional path from which this queue was expanded (for contextual path
749
- * optimization).
750
- */
751
641
  fun setQueue(
752
642
  tracks: Array<Track>,
753
643
  startIndex: Int = 0,
@@ -764,11 +654,7 @@ internal constructor(
764
654
  sessionPlayer.prepare()
765
655
  }
766
656
 
767
- /**
768
- * Replaces track at index in queue.
769
- *
770
- * @throws IllegalArgumentException if index is out of bounds.
771
- */
657
+ /** @throws IllegalArgumentException if [index] is out of bounds. */
772
658
  fun replaceTrack(index: Int, track: Track) {
773
659
  validateIndex(index)
774
660
  val isCurrent = index == currentIndex
@@ -778,50 +664,31 @@ internal constructor(
778
664
  }
779
665
 
780
666
  /**
781
- * Sets the favorited state of the currently playing track. Updates the heart icon in media
782
- * controllers without interrupting playback.
783
- *
784
- * @return whether the gesture applied — false only when there is no current track (nothing to
785
- * favorite), so MediaSession callers can report an invalid state instead of a success the
786
- * controller then watches revert.
667
+ * @return false only when there is no current track, so MediaSession callers can report an
668
+ * invalid state instead of a success the controller then watches revert.
787
669
  */
788
670
  fun setActiveTrackFavorited(favorited: Boolean): Boolean {
789
671
  val currentTrack = this.currentTrack ?: return false
790
672
 
791
- // Persist to the native favorites cache regardless of player state — the
792
- // user's gesture is durable even when there's no active media item to
793
- // update (queue tear-down, between-track gaps, etc.). Keyed by the track
794
- // identity (id when non-blank, else src).
795
673
  currentTrack.identity?.let { identity ->
796
674
  browser?.browserManager?.updateFavorite(identity, favorited)
797
675
  }
798
676
 
799
- // Cache written above: the gesture is durably recorded even without a media
800
- // item to restamp (queue tear-down, between-track gaps) — that counts as
801
- // applied; there is also no visible heart to revert in that state.
802
677
  val index = sessionPlayer.currentMediaItemIndex
678
+ // Still applied: the favorite is persisted above, and there is no heart to revert.
803
679
  if (index == C.INDEX_UNSET) return true
804
680
 
805
681
  val updatedTrack = currentTrack.copy(favorited = favorited)
806
682
  restampMediaItem(index, updatedTrack) { setFavorite(favorited) }
807
683
 
808
- // Update the heart button icon in notification/Android Auto
809
684
  updateFavoriteButtonState(favorited)
810
685
 
811
- // Notify JS of the favorite state change. This is the ONLY emit: a favorite
812
- // toggle is an in-place mutation of the active track, not a transition —
813
- // onPlaybackActiveTrackChanged / onPlaybackQueueChanged stay
814
- // transition-only, and the useActiveTrack / useQueue hooks subscribe to
815
- // onFavoriteChanged themselves.
686
+ // The only emit: a favorite toggle mutates the active track in place, so the track and queue
687
+ // change events stay transition-only.
816
688
  callbacks?.onFavoriteChanged(FavoriteChangedEvent(updatedTrack, favorited))
817
689
  return true
818
690
  }
819
691
 
820
- /**
821
- * Toggles the favorited state of the currently playing track.
822
- *
823
- * @return whether the toggle applied — false when there is no current track.
824
- */
825
692
  fun toggleActiveTrackFavorited(): Boolean {
826
693
  val currentTrack = this.currentTrack ?: return false
827
694
  return setActiveTrackFavorited(currentTrack.favorited != true)
@@ -829,11 +696,7 @@ internal constructor(
829
696
 
830
697
  // MARK: - Now Playing Metadata
831
698
 
832
- /**
833
- * Now Playing rendering (flash/override/formatter precedence, dedupe, stale guards, artwork
834
- * keying) lives in [NowPlayingUpdater]; this object is its platform surface — current playback
835
- * reads plus MediaItem stamping via [replaceMediaItem], and artwork resolution via the browser.
836
- */
699
+ /** [NowPlayingUpdater] does the rendering; this is its platform surface. */
837
700
  val nowPlaying: NowPlayingUpdater =
838
701
  NowPlayingUpdater(
839
702
  object : NowPlayingSurface {
@@ -872,9 +735,8 @@ internal constructor(
872
735
  setTitle(title)
873
736
  .setDisplayTitle(title)
874
737
  .setArtist(secondaryLine)
875
- // Android Auto reads DISPLAY_SUBTITLE (not ARTIST) once DISPLAY_TITLE is set, so
876
- // mirror the line into `subtitle`; `artist` still drives the lock screen /
877
- // notification.
738
+ // Android Auto reads DISPLAY_SUBTITLE, not ARTIST, once DISPLAY_TITLE is set;
739
+ // `artist` still drives the lock screen and notification.
878
740
  .setSubtitle(secondaryLine)
879
741
  .setAlbumTitle(album)
880
742
  }
@@ -895,9 +757,8 @@ internal constructor(
895
757
  val uri = resolved?.uri?.takeIf { it.isNotEmpty() } ?: return null
896
758
  val published =
897
759
  TrackFactory.sessionArtworkUri(uri, resolved.headers, SvgArtworkRenderer.isSvgUrl(uri))
898
- // Remember how this URI was produced: Media3 hands it back to the bitmap loader, which
899
- // re-resolves Track-first (with the nowPlayingArtwork kind, not the global artwork
900
- // config).
760
+ // Media3 hands this URI back to the bitmap loader, which re-resolves it with the
761
+ // nowPlayingArtwork config rather than the global artwork config.
901
762
  browserManager.artworkResolutions.register(published, track, config)
902
763
  return published
903
764
  }
@@ -910,8 +771,8 @@ internal constructor(
910
771
  )
911
772
 
912
773
  /**
913
- * Restamps every queued item's heart rating after the favorite capability changed, in one
914
- * replacement: each separate one would be a timeline change, and a queue event to JS.
774
+ * One replacement for the whole queue: each separate one is a timeline change and a queue event
775
+ * to JS.
915
776
  */
916
777
  private fun restampFavorites() {
917
778
  if (!::sessionPlayer.isInitialized || sessionPlayer.mediaItemCount == 0) return
@@ -924,7 +785,6 @@ internal constructor(
924
785
  sessionPlayer.replaceMediaItems(0, items.size, items)
925
786
  }
926
787
 
927
- /** Republishes the item at [index] with mutated metadata, preserving uri and Track tag. */
928
788
  private fun restampMediaItem(
929
789
  index: Int,
930
790
  track: Track,
@@ -936,10 +796,7 @@ internal constructor(
936
796
  )
937
797
  }
938
798
 
939
- /**
940
- * This item with mutated metadata and [track] as its tag, its uri unchanged so ExoPlayer updates
941
- * it in place instead of reloading it.
942
- */
799
+ /** Keeps the uri so ExoPlayer updates the item in place instead of reloading it. */
943
800
  private fun MediaItem.restamped(
944
801
  track: Track,
945
802
  mutate: MediaMetadata.Builder.() -> MediaMetadata.Builder,
@@ -951,14 +808,9 @@ internal constructor(
951
808
  .build()
952
809
 
953
810
  /**
954
- * Resets the retry timer when track changes. Called from PlayerListener.onMediaItemTransition.
955
- */
956
- /**
957
- * A restart from a terminal error begins a new load of the same track: fresh retry budgets and
958
- * unproven playback, so the user's tap yields a visible first-connect retry window instead of a
959
- * single silent attempt — the same behavior as re-selecting the track (ADR 0004). Hooked off the
960
- * player error clearing: every recovery path (retry(), play(), the transport controls' idle-error
961
- * recovery) goes through exoPlayer.prepare(), which clears the error.
811
+ * Fresh retry budgets and unproven playback, as when the track is selected again (ADR 0004).
812
+ * Called when the player error clears: every restart from a terminal error goes through
813
+ * prepare().
962
814
  */
963
815
  internal fun resetForNewLoad() {
964
816
  resetRetryTimer()
@@ -969,11 +821,7 @@ internal constructor(
969
821
  mediaFactory.resetRetryTimer()
970
822
  }
971
823
 
972
- /**
973
- * Finds the queue Track whose published artwork URI matches [uri], for display-time artwork
974
- * resolution of app-supplied queue tracks that never went through browse (so they are not in the
975
- * resolution registry). Must run on the main thread (ExoPlayer access).
976
- */
824
+ /** Main thread only (ExoPlayer access). */
977
825
  private fun findQueueTrackByArtworkUri(uri: String): Track? {
978
826
  for (i in 0 until sessionPlayer.mediaItemCount) {
979
827
  val item = sessionPlayer.getMediaItemAt(i)
@@ -985,10 +833,8 @@ internal constructor(
985
833
  }
986
834
 
987
835
  /**
988
- * Track-first display-time artwork resolution for [CoilBitmapLoader]: registry hit
989
- * (browse/now-playing-resolved URIs) → queue-tag lookup (app-supplied tracks with raw artwork) →
990
- * header-only fallback for unattributable URIs (registry eviction / process-death restore). Null
991
- * means "fetch the URI as-is".
836
+ * For [CoilBitmapLoader]: the resolution registry, then the queue track that published [uri],
837
+ * then headers alone for a URI nothing attributes. Null means fetch the URI as-is.
992
838
  */
993
839
  suspend fun resolveDisplayArtwork(uri: String, sizeHintPixels: Int?): ImageSource? {
994
840
  val browserManager = browser?.browserManager ?: return null
@@ -1012,10 +858,6 @@ internal constructor(
1012
858
  return browserManager.unattributedArtworkSource(uri)
1013
859
  }
1014
860
 
1015
- /**
1016
- * Updates the favorite button icon in the notification/Android Auto. Call this when track changes
1017
- * or favorite state changes.
1018
- */
1019
861
  internal fun updateFavoriteButtonState(favorited: Boolean?) {
1020
862
  if (!::mediaSession.isInitialized) return
1021
863
  mediaSessionCallback.commandManager.updateFavoriteState(mediaSession, favorited)
@@ -1026,7 +868,6 @@ internal constructor(
1026
868
  mediaSessionCallback.commandManager.updateLiveState(mediaSession, live)
1027
869
  }
1028
870
 
1029
- /** Removes all the upcoming tracks, if any (the ones returned by [next]). */
1030
871
  fun removeUpcomingTracks() {
1031
872
  val index = sessionPlayer.currentMediaItemIndex
1032
873
  if (index == C.INDEX_UNSET) return
@@ -1037,24 +878,19 @@ internal constructor(
1037
878
  }
1038
879
 
1039
880
  fun play() {
1040
- // Through the setter so the STATE_ENDED replay handling applies
1041
- // (ExoPlayer.play() is only setPlayWhenReady(true)).
881
+ // Through the setter for its replay of an ended player.
1042
882
  playWhenReady = true
1043
883
  if (currentTrack != null) {
1044
- // No-op unless the player is STATE_IDLE (ExoPlayer.prepare early-returns
1045
- // otherwise), so this only reconnects after a stop() or error and never
1046
- // re-buffers a healthy stream. Reconnecting is also how live streams
1047
- // rejoin the live edge on resume.
884
+ // No-op unless the player is idle, so this reconnects only after stop() or an error and never
885
+ // re-buffers a healthy stream. Reconnecting is also how a live stream rejoins its live edge.
1048
886
  sessionPlayer.prepare()
1049
887
  }
1050
888
  }
1051
889
 
1052
890
  /**
1053
- * Jump to the live edge of the current track; no-op unless it declares `live` — the track's own
1054
- * declaration is the gate (matching iOS and the spec), not ExoPlayer's stream-derived liveness,
1055
- * which never marks progressive ICY radio live. A stream with a live window seeks to its edge;
1056
- * anything else reconnects — for a non-seekable stream a fresh connection IS the live edge. A
1057
- * stale URL recovers through the failure-armed re-resolve in [TransformingDataSource].
891
+ * No-op unless the track declares `live`; ExoPlayer never marks progressive ICY radio live. A
892
+ * stream with a live window seeks to its edge; anything else reconnects, which for a non-seekable
893
+ * stream is the live edge.
1058
894
  */
1059
895
  fun seekToLiveEdge() {
1060
896
  if (currentTrack?.live != true) return
@@ -1063,18 +899,13 @@ internal constructor(
1063
899
  }
1064
900
 
1065
901
  /**
1066
- * Executes a search and plays the results. Used for voice commands with structured search
1067
- * parameters.
1068
- *
1069
- * @param params The structured search parameters (mode, query, artist, album, etc.)
1070
- * @return true if search succeeded and playback started, false otherwise
902
+ * @return whether a result started playing: false when gated (after onGate), with no results, or
903
+ * on any error, the browser's registration timeout included.
1071
904
  */
1072
905
  suspend fun playFromSearch(params: SearchParams): Boolean {
1073
906
  return try {
1074
907
  val audioBrowser = awaitBrowser()
1075
- // A gate blocks external-surface "play" search too — otherwise voice search is a way around
1076
- // the gate (mirrors the iOS play-media intent guard). Resolved per request; a gated decision
1077
- // fires onGate(search) and refuses.
908
+ // Gated like browsing, or voice search would be a way around the gate.
1078
909
  val gateOutcome =
1079
910
  audioBrowser.gateDecision(
1080
911
  NativeGateRequest(reason = GateReason.SEARCH, path = null, search = params)
@@ -1113,9 +944,7 @@ internal constructor(
1113
944
  }
1114
945
 
1115
946
  fun pause() {
1116
- // Through the setter so the eager playWhenReadyCache write holds for the
1117
- // drop direction too — the retry policy reads it off-main before
1118
- // ExoPlayer's listener round-trip syncs it.
947
+ // Through the setter, so the retry policy sees playWhenReadyCache drop at once.
1119
948
  playWhenReady = false
1120
949
  }
1121
950
 
@@ -1123,21 +952,15 @@ internal constructor(
1123
952
  when {
1124
953
  shouldPlayWhenReady -> pause()
1125
954
  // Suppressed with the intent raised: ExoPlayer resumes when focus returns. play() would
1126
- // request focus again, and a call refuses it, which drops the intent.
955
+ // request focus again, and during a call that refusal drops the intent.
1127
956
  playWhenReady -> Unit
1128
957
  else -> play()
1129
958
  }
1130
959
  }
1131
960
 
1132
- /**
1133
- * Stops playback, without clearing the active track. Calling this method will cause the playback
1134
- * state to transition to State.NONE and the player will release the loaded media and resources
1135
- * required for playback.
1136
- */
961
+ /** Keeps the queue; the state becomes STOPPED. */
1137
962
  fun stop() {
1138
- // State first so the machine's STOPPED guard suppresses the PAUSED transition
1139
- // from the playWhenReady drop below; through setPlaybackState so the change
1140
- // is emitted (direct field assignment bypasses events — see its docstring).
963
+ // State first, so the state machine's STOPPED guard swallows the PAUSED the drop below causes.
1141
964
  setPlaybackState(PlaybackState.STOPPED)
1142
965
  playWhenReady = false
1143
966
  sessionPlayer.stop()
@@ -1148,16 +971,11 @@ internal constructor(
1148
971
  queueSourcePath = null
1149
972
  }
1150
973
 
1151
- /**
1152
- * Stops and destroys the player. Only call this when you are finished using the player, otherwise
1153
- * use [pause].
1154
- */
1155
974
  fun destroy() {
1156
- // Cancel without a final save: the loop would tick against the released
1157
- // player and persist position 0 over the real resumption position.
975
+ // No final save: it would persist position 0 from the released player over the real one.
1158
976
  playbackStateStore.cancelPeriodicSave()
1159
- // An armed timer's Runnable would outlive the release and fire pause() into the
1160
- // released player. Cleared here, while a mid-ramp fade can still restore volume.
977
+ // An armed timer would fire pause() into the released player. Cleared before the release,
978
+ // while a mid-ramp fade can still restore the volume.
1161
979
  sleepTimer.clear()
1162
980
  stop()
1163
981
  nowPlaying.destroy()
@@ -1184,27 +1002,23 @@ internal constructor(
1184
1002
  }
1185
1003
 
1186
1004
  /**
1187
- * Invalidates in-flight [reportRetryingError] posts: bumped on track change so a report
1188
- * classified for the outgoing track can't land on the incoming one's spinner. Written on main,
1189
- * read on ExoPlayer's loader thread.
1005
+ * Bumped on track change so a [reportRetryingError] post for the outgoing track is dropped.
1006
+ * Written on main, read on ExoPlayer's loader thread.
1190
1007
  */
1191
1008
  @Volatile private var retryingErrorGeneration = 0
1192
1009
 
1193
1010
  /**
1194
- * Surfaces a load failure the retry policy is still working on: attached to the current
1195
- * (non-terminal) state via [Callbacks.onPlaybackChanged], so UIs can show the cause over the
1196
- * spinner. Not an ERROR transition, and not a [Callbacks.onPlaybackError] — that event stays
1197
- * reserved for terminal errors. Called from ExoPlayer's loader thread, hence the main hop.
1011
+ * Attaches a load failure the retry policy is still working on to the current state, for UIs to
1012
+ * show over the spinner. Not an ERROR and not [Callbacks.onPlaybackError], which stays terminal.
1013
+ * Called on ExoPlayer's loader thread.
1198
1014
  */
1199
1015
  private fun reportRetryingError(exception: IOException) {
1200
1016
  val error = PlaybackErrorClassifier.retryingLoadError(exception, networkMonitor.getOnline())
1201
1017
  val generation = retryingErrorGeneration
1202
1018
  mainHandler.post {
1203
- // The track changed while this post was in flight — the error belongs to the old one.
1204
1019
  if (generation != retryingErrorGeneration) return@post
1205
- // Only attach while the failure is what the listener is looking at. During PLAYING/READY
1206
- // buffered audio is still audibly fine, and ExoPlayer's in-place retry can succeed without
1207
- // any state change — an advisory attached there would never clear.
1020
+ // Only over a spinner: while PLAYING, buffered audio still plays and ExoPlayer's in-place
1021
+ // retry can succeed with no state change, so an error attached there would never clear.
1208
1022
  if (
1209
1023
  playbackState != PlaybackState.LOADING &&
1210
1024
  playbackState != PlaybackState.BUFFERING &&
@@ -1212,8 +1026,7 @@ internal constructor(
1212
1026
  ) {
1213
1027
  return@post
1214
1028
  }
1215
- // Each failed attempt re-reports; identical repeats add nothing (and would
1216
- // re-render now-playing every backoff tick).
1029
+ // Each backoff tick re-reports the same error.
1217
1030
  if (playbackError == error) return@post
1218
1031
  playbackError = error
1219
1032
  callbacks?.onPlaybackChanged(Playback(playbackState, error))
@@ -1222,9 +1035,8 @@ internal constructor(
1222
1035
  }
1223
1036
 
1224
1037
  /**
1225
- * Drops a retrying error whose track is gone. The new track may keep the state on
1226
- * LOADING/BUFFERING — no state-change emit — so the clear is emitted here, or the old track's
1227
- * error would linger over the new one's spinner.
1038
+ * Drops the retrying error of a track that is gone. The new track may stay LOADING or BUFFERING
1039
+ * with no state change to emit the clear.
1228
1040
  */
1229
1041
  internal fun clearRetryingError() {
1230
1042
  retryingErrorGeneration++
@@ -1234,56 +1046,36 @@ internal constructor(
1234
1046
  nowPlaying.render()
1235
1047
  }
1236
1048
 
1237
- /**
1238
- * Updates the player state and emits a state change event if the state has changed. Only emits an
1239
- * event if the new state differs from the current state.
1240
- *
1241
- * IMPORTANT: This method also triggers the queue ended event when the player reaches State.ENDED
1242
- * and is on the last track. All state transitions should go through this method to ensure proper
1243
- * event dispatching. Direct assignments to playerState will bypass event emission.
1244
- *
1245
- * @param state The new player state to set
1246
- */
1049
+ /** Every state change goes through here: it emits the change and the events that follow it. */
1247
1050
  internal fun setPlaybackState(state: PlaybackState) {
1248
1051
  if (state != playbackState) {
1249
1052
  val oldState = playbackState
1250
1053
  playbackState = state
1251
1054
 
1252
- // Audio rendered: this load has proven itself — retries from here on get
1253
- // the retry policy's full recovery budget, not the short first-connect one.
1254
1055
  if (state == PlaybackState.PLAYING) {
1255
1056
  hasPlayedCache = true
1256
1057
  }
1257
1058
 
1258
- // A natural end exhausts the play intent — nothing is left to play. Keeping
1259
- // playWhenReady true inverted the play/pause toggle, held audio focus forever
1260
- // (ExoPlayer abandons it only at IDLE or on the intent dropping), and kept the
1261
- // periodic position save running. Cleared and emitted before the state /
1262
- // queue-ended callbacks so JS observes the native order (intent → state →
1263
- // queueEnded); the media3 listener's later echo is deduplicated by
1264
- // emitPlayWhenReadyChanged. The state machine's ENDED guard keeps the drop
1265
- // from re-reporting the state as PAUSED.
1059
+ // A natural end exhausts the play intent; held, it inverts the toggle, keeps audio focus and
1060
+ // the periodic save. Emitted before the state and queue-ended callbacks, matching iOS. The
1061
+ // state machine's ENDED guard keeps the drop from reporting PAUSED.
1266
1062
  if (state == PlaybackState.ENDED && playWhenReady) {
1267
1063
  playWhenReady = false
1268
1064
  emitPlayWhenReadyChanged(false)
1269
1065
  }
1270
1066
 
1271
- // The last track fires no AUTO media-item transition, so an armed
1272
- // end-of-track sleep timer would stay set forever and pause the next
1273
- // track played instead.
1067
+ // The last track fires no AUTO transition, so the end-of-track sleep timer would stay armed.
1274
1068
  if (state == PlaybackState.ENDED) {
1275
1069
  sleepTimer.onTrackEnd()
1276
1070
  }
1277
1071
 
1278
- // Clear error when transitioning away from error state
1279
1072
  if (oldState == PlaybackState.ERROR) {
1280
1073
  playbackError = null
1281
1074
  callbacks?.onPlaybackError(null)
1282
1075
  }
1283
1076
 
1284
- // A retrying error rides along through LOADING/BUFFERING/PAUSED; a state that
1285
- // proves recovery (READY/PLAYING — data flowed) or abandons the attempt clears
1286
- // it, before the Playback below is built so the emitted event is already clean.
1077
+ // A retrying error rides through LOADING, BUFFERING and PAUSED; any other state proves
1078
+ // recovery or abandons the attempt.
1287
1079
  if (
1288
1080
  playbackError?.retrying == true &&
1289
1081
  state != PlaybackState.LOADING &&
@@ -1296,25 +1088,16 @@ internal constructor(
1296
1088
  val playback = Playback(state, playbackError)
1297
1089
  callbacks?.onPlaybackChanged(playback)
1298
1090
 
1299
- // Re-render the now-playing on every state change: the metadata formatter receives
1300
- // `playbackState` (plus isRebuffering / isOnline / error), so any transition can change its
1301
- // output — the live song while paused, a "Reconnecting…" line on a rebuffer, an offline/error
1302
- // line. The publish-dedupe in applyNowPlayingFields drops redundant updates, so re-running
1303
- // through the rapid startup sequence (none→loading→buffering→ready→playing) is cheap.
1091
+ // The formatter sees the state, so any transition can change what it renders.
1304
1092
  nowPlaying.render()
1305
1093
 
1306
- // Emit queue ended event when playback ends on the last track. Repeat modes never
1307
- // conceptually end the queue (matches web's endsQueue()): an ENDED that surfaces while
1308
- // repeating (e.g. a seek to the end) must not read as "playlist over".
1309
- // This coupling ensures queue ended events are always triggered consistently with state
1310
- // changes
1094
+ // A repeat mode never ends the queue, even on an ENDED from a seek to the end.
1311
1095
  if (state == PlaybackState.ENDED && isLastInPlaybackOrder && repeatMode == RepeatMode.OFF) {
1312
1096
  currentIndex?.let { index ->
1313
1097
  val event =
1314
1098
  PlaybackQueueEndedEvent(track = index.toDouble(), position = position.toSeconds())
1315
1099
  callbacks?.onPlaybackQueueEnded(event)
1316
1100
  }
1317
- // Reset saved position to 0 so resumption starts from beginning
1318
1101
  playbackStateStore.savePositionZero()
1319
1102
  }
1320
1103
 
@@ -1324,11 +1107,7 @@ internal constructor(
1324
1107
  }
1325
1108
  }
1326
1109
 
1327
- /**
1328
- * Sets the progress update interval.
1329
- *
1330
- * @param interval The interval in seconds, or null to disable progress updates
1331
- */
1110
+ /** [interval] in seconds; null stops the progress events. */
1332
1111
  fun setProgressUpdateInterval(interval: Double?) {
1333
1112
  progressTimer.setInterval(interval)
1334
1113
  }
@@ -1337,21 +1116,11 @@ internal constructor(
1337
1116
  intervalTimer.setInterval(if (enabled) 1.0 else null)
1338
1117
  }
1339
1118
 
1340
- /**
1341
- * Applies update options with change detection. Only updates properties that have actually
1342
- * changed and emits events accordingly.
1343
- *
1344
- * @param options The new options to apply
1345
- * @param mediaSession The MediaSession to update when capabilities change
1346
- */
1347
1119
  fun applyOptions(options: PlayerUpdateOptions) {
1348
- // Store previous values for change detection
1349
1120
  val previousOptions = this.options
1350
1121
 
1351
- // Update current options
1352
1122
  this.options = options.copy()
1353
1123
 
1354
- // Check what changed
1355
1124
  val skipSilenceChanged = previousOptions.skipSilence != options.skipSilence
1356
1125
  val progressUpdateEventIntervalChanged =
1357
1126
  previousOptions.progressUpdateEventInterval != options.progressUpdateEventInterval
@@ -1374,14 +1143,13 @@ internal constructor(
1374
1143
  remoteButtonLayoutChanged ||
1375
1144
  appKilledPlaybackBehaviorChanged
1376
1145
 
1377
- // Apply only changed properties
1378
1146
  if (skipSilenceChanged) {
1379
1147
  skipSilence = options.skipSilence
1380
1148
  }
1381
1149
 
1382
1150
  if (capabilitiesChanged) {
1383
- // The `favorite` capability is the single favoriting switch — propagate
1384
- // it to the browser so it can hydrate row hearts.
1151
+ // The favorite capability is the one favoriting switch; the browser hydrates row hearts from
1152
+ // it.
1385
1153
  browser?.browserManager?.setFavoriteEnabled(options.capabilities.favoriteEnabled)
1386
1154
  TrackFactory.favoriteEnabled = options.capabilities.favoriteEnabled
1387
1155
  if (previousOptions.capabilities.favoriteEnabled != options.capabilities.favoriteEnabled) {
@@ -1393,8 +1161,7 @@ internal constructor(
1393
1161
  setProgressUpdateInterval(options.progressUpdateEventInterval)
1394
1162
  }
1395
1163
 
1396
- // The jump intervals pick the button icons (ICON_SKIP_BACK_15 and friends), so a changed
1397
- // interval has to rebuild the layout even when capabilities and placement are untouched.
1164
+ // The jump intervals pick the button icons, so a changed interval rebuilds the layout.
1398
1165
  if (
1399
1166
  capabilitiesChanged ||
1400
1167
  remoteButtonLayoutChanged ||
@@ -1417,20 +1184,10 @@ internal constructor(
1417
1184
  }
1418
1185
  }
1419
1186
 
1420
- /**
1421
- * Sets the callbacks for player events.
1422
- *
1423
- * @param callbacks The callbacks to set, or null to clear callbacks
1424
- */
1425
1187
  fun setCallbacks(callbacks: Callbacks?) {
1426
1188
  this.callbacks = callbacks
1427
1189
  }
1428
1190
 
1429
- /**
1430
- * Gets the current callbacks instance.
1431
- *
1432
- * @return The current callbacks, or null if none are set
1433
- */
1434
1191
  fun getCallbacks(): Callbacks? {
1435
1192
  return this.callbacks
1436
1193
  }
@@ -1443,21 +1200,10 @@ internal constructor(
1443
1200
  return options
1444
1201
  }
1445
1202
 
1446
- /**
1447
- * Gets the current network connectivity state.
1448
- *
1449
- * @return true if device is online, false otherwise
1450
- */
1451
1203
  fun getOnline(): Boolean {
1452
1204
  return networkMonitor.getOnline()
1453
1205
  }
1454
1206
 
1455
- /**
1456
- * Validates that an index is within bounds [0, trackCount).
1457
- *
1458
- * @param index The index to validate.
1459
- * @throws IllegalArgumentException if index is out of bounds.
1460
- */
1461
1207
  private fun validateIndex(index: Int) {
1462
1208
  if (index < 0 || index >= sessionPlayer.mediaItemCount) {
1463
1209
  throw IllegalArgumentException(
@@ -1466,12 +1212,6 @@ internal constructor(
1466
1212
  }
1467
1213
  }
1468
1214
 
1469
- /**
1470
- * Validates that an insertion index is within bounds [0, trackCount] or -1 (append).
1471
- *
1472
- * @param index The index to validate.
1473
- * @throws IllegalArgumentException if index is out of bounds.
1474
- */
1475
1215
  private fun validateInsertIndex(index: Int) {
1476
1216
  if (index < -1 || index > sessionPlayer.mediaItemCount) {
1477
1217
  throw IllegalArgumentException(
@@ -1480,21 +1220,10 @@ internal constructor(
1480
1220
  }
1481
1221
  }
1482
1222
 
1483
- /**
1484
- * Gets the MediaSessionCallback for this AudioBrowser.
1485
- *
1486
- * @return MediaLibrarySession.Callback instance
1487
- */
1488
1223
  fun getMediaSessionCallback(): MediaLibraryService.MediaLibrarySession.Callback {
1489
1224
  return mediaSessionCallback
1490
1225
  }
1491
1226
 
1492
- /**
1493
- * Notifies external controllers (Android Auto, etc.) that content at the given path has changed.
1494
- * Controllers subscribed to this path will refresh their UI.
1495
- *
1496
- * @param path The path where content has changed
1497
- */
1498
1227
  fun notifyContentChanged(path: String) {
1499
1228
  mediaSessionCallback.notifyContentChanged(path)
1500
1229
  }
@@ -1503,41 +1232,24 @@ internal constructor(
1503
1232
  mediaSessionCallback.invalidateAllContent()
1504
1233
  }
1505
1234
 
1506
- /**
1507
- * Returns the recommended artwork size in pixels from the connected media browser (e.g., Android
1508
- * Auto), or null if not provided.
1509
- */
1235
+ /** From the connected media browser (e.g. Android Auto), when it gives one. */
1510
1236
  val artworkSizeHintPixels: Int?
1511
1237
  get() = mediaSessionCallback.artworkSizeHintPixels
1512
1238
 
1513
- /** Returns true if the current media item is a live stream. */
1514
1239
  val isCurrentItemLive: Boolean
1515
1240
  get() = sessionPlayer.isCurrentMediaItemLive
1516
1241
 
1517
1242
  // MARK: - Buffer Configuration
1518
1243
 
1519
- /**
1520
- * Updates the buffer configuration at runtime.
1521
- *
1522
- * The new configuration takes effect immediately for future buffering decisions. Already-buffered
1523
- * data is not affected.
1524
- *
1525
- * @param config The new buffer configuration to apply.
1526
- */
1244
+ /** Takes effect for future buffering; what is buffered stays. */
1527
1245
  fun updateBufferConfig(config: BufferConfig) {
1528
1246
  loadControl.updateBufferConfig(config)
1529
1247
  }
1530
1248
 
1531
- /**
1532
- * Gets the current buffer configuration.
1533
- *
1534
- * @return The current buffer configuration.
1535
- */
1536
1249
  fun getBufferConfig(): BufferConfig {
1537
1250
  return loadControl.getBufferConfig()
1538
1251
  }
1539
1252
 
1540
- /** Resets the buffer configuration to defaults. */
1541
1253
  fun resetBufferConfig() {
1542
1254
  loadControl.resetToDefaults()
1543
1255
  }