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
@@ -44,9 +44,10 @@ export function getProgress(): Progress {
44
44
  // MARK: - Event Callbacks
45
45
 
46
46
  /**
47
- * Subscribes to playback progress updates.
48
- * @param callback - Called periodically with playback progress updates
49
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
47
+ * Emits the progress every `progressUpdateEventInterval` seconds while the
48
+ * player is loading, buffering or playing. Off by default (the interval is
49
+ * `null`). Subscribe with `onProgressUpdated.addListener(cb)`, which returns
50
+ * an unsubscribe function.
50
51
  */
51
52
  export const onProgressUpdated =
52
53
  NativeUpdatedValue.emitterize<PlaybackProgressUpdatedEvent>(
@@ -56,9 +57,14 @@ export const onProgressUpdated =
56
57
  // MARK: - Hooks
57
58
 
58
59
  /**
59
- * Hook that returns the current playback progress and updates when it changes.
60
+ * Hook that returns the current playback progress and updates on each
61
+ * progress event.
60
62
  *
61
- * Progress update frequency is controlled globally via `updateOptions({ progressUpdateEventInterval })`.
63
+ * Progress events are off by default (`progressUpdateEventInterval: null`), so
64
+ * this hook does not update until you set an interval in `setupPlayer` or
65
+ * `updateOptions`. Events fire only while loading, buffering or playing, so a
66
+ * seek while paused does not show. For updates without configuration, use
67
+ * {@link usePolledProgress}.
62
68
  * @returns The current playback progress
63
69
  */
64
70
  export function useProgress(): Progress {
@@ -36,6 +36,11 @@ export type PlaybackState =
36
36
 
37
37
  export type Playback = {
38
38
  state: PlaybackState
39
+ /**
40
+ * What made playback fail, in the `'error'` state. On iOS and Android, also
41
+ * a failure still being retried (`retrying: true`) while loading, buffering
42
+ * or paused.
43
+ */
39
44
  error?: PlaybackError
40
45
  }
41
46
 
@@ -52,9 +57,9 @@ export function getPlayback(): Playback {
52
57
  // MARK: - Event Callbacks
53
58
 
54
59
  /**
55
- * Subscribes to playback state changes.
56
- * @param callback - Called when the playback state changes
57
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
60
+ * Emits the {@link Playback} each time the playback state or error changes.
61
+ * Subscribe with `onPlaybackChanged.addListener(cb)`, which returns an
62
+ * unsubscribe function.
58
63
  */
59
64
  export const onPlaybackChanged = NativeUpdatedValue.emitterize<Playback>(
60
65
  (cb) => (nativeBrowser.onPlaybackChanged = cb)
@@ -4,12 +4,16 @@ import { onActiveTrackChanged } from '../queue/activeTrack'
4
4
 
5
5
  // MARK: - Types
6
6
 
7
+ /** What a {@link trackPlaybackTime} callback receives each period. */
7
8
  export interface PlaybackElapsed {
8
9
  /** Cumulative seconds spent `playing` since this subscription started. */
9
10
  total: number
10
11
  /** Seconds played since the previous callback (≈ `period`). */
11
12
  sinceLast: number
12
- /** The currently playing track (id / src / path / title …), if any. */
13
+ /**
14
+ * The active track as of the latest track change since the first
15
+ * subscription; `undefined` until one happens.
16
+ */
13
17
  track?: Track
14
18
  }
15
19
 
@@ -72,8 +76,11 @@ function install() {
72
76
  * subscribe to {@link onActiveTrackChanged} and cancel + re-subscribe here on each
73
77
  * change, so every track gets a fresh `total` starting at zero.
74
78
  *
79
+ * On Android, subscribe after `setupPlayer` resolves. After a service restart
80
+ * no callback fires until every subscription is cancelled and a new one is made.
81
+ *
75
82
  * @param callback Invoked once per elapsed `period`, with cumulative play time
76
- * and the currently playing track.
83
+ * and the active track (see {@link PlaybackElapsed.track}).
77
84
  * @param period Seconds of playback between calls. Must be >= 1.
78
85
  * @returns A function that cancels this subscription (idempotent — safe to call
79
86
  * more than once).
@@ -12,7 +12,7 @@ export function getVolume(): number {
12
12
  }
13
13
 
14
14
  /**
15
- * Gets the current system volume as a number between 0 and 1.
15
+ * Gets the current system volume as a number between 0 and 1. On web, always 1.
16
16
  */
17
17
  export function getSystemVolume(): number {
18
18
  return nativeBrowser.getSystemVolume()
@@ -31,7 +31,7 @@ export function setVolume(level: number): void {
31
31
  /**
32
32
  * Sets the system volume.
33
33
  * @param level - The volume as a number between 0 and 1.
34
- * @remarks On iOS this is a no-op as Apple doesn't provide a public API to set system volume.
34
+ * @remarks A no-op on iOS, which has no public API for it, and on web.
35
35
  */
36
36
  export function setSystemVolume(level: number): void {
37
37
  nativeBrowser.setSystemVolume(level)
@@ -40,9 +40,9 @@ export function setSystemVolume(level: number): void {
40
40
  // MARK: - Event Callbacks
41
41
 
42
42
  /**
43
- * Subscribes to system volume changes.
44
- * @param callback - Called when the system volume changes
45
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
43
+ * Emits the system volume (0 to 1) each time it changes. Never fires on web.
44
+ * Subscribe with `onSystemVolumeChanged.addListener(cb)`, which returns an
45
+ * unsubscribe function.
46
46
  */
47
47
  export const onSystemVolumeChanged = NativeUpdatedValue.emitterize<number>(
48
48
  (cb) => (nativeBrowser.onSystemVolumeChanged = cb)
@@ -52,6 +52,7 @@ export const onSystemVolumeChanged = NativeUpdatedValue.emitterize<number>(
52
52
 
53
53
  /**
54
54
  * Hook that returns the current system volume and updates when it changes.
55
+ * On web, always 1.
55
56
  * @returns The current system volume (0 to 1)
56
57
  */
57
58
  export function useSystemVolume(): number {
@@ -71,8 +71,10 @@ export interface PlayerCapabilities {
71
71
  /**
72
72
  * Enable track favoriting.
73
73
  *
74
- * Turns on the favorite/like heart across all surfaces:
75
- * - iOS: Control Center + CarPlay now-playing.
74
+ * - iOS: turns on matching tracks against `setFavorites`. It shows no heart
75
+ * of its own: the CarPlay now-playing heart appears when
76
+ * `ios.carPlayNowPlayingButtons` includes `'favorite'`. Control Center
77
+ * and the lock screen show none.
76
78
  * - Android: a place in the {@link RemoteButtonLayout} — the notification,
77
79
  * Android Auto and the Android 13+ system media controls — and an
78
80
  * (empty or filled) heart on playable browse rows.
@@ -195,14 +197,13 @@ export type RemoteButtonLayout = {
195
197
  * AppKilledPlaybackBehavior options:
196
198
  * - `'continue-playback'`: This option will continue playing audio in the
197
199
  * background when the app is removed from recents. The notification remains.
198
- * This is the default.
199
200
  * - `'pause-playback'`: This option will pause playing audio in the background
200
201
  * when the app is removed from recents. The notification remains and can be
201
202
  * used to resume playback.
202
203
  * - `'stop-playback-and-remove-notification'`: This option will stop playing
203
204
  * audio in the background when the app is removed from recents. The
204
205
  * notification is removed and can't be used to resume playback. Users would
205
- * need to open the app again to start playing audio.
206
+ * need to open the app again to start playing audio. This is the default.
206
207
  */
207
208
  export type AppKilledPlaybackBehavior =
208
209
  | 'continue-playback'
@@ -210,15 +211,17 @@ export type AppKilledPlaybackBehavior =
210
211
  | 'stop-playback-and-remove-notification'
211
212
 
212
213
  /**
213
- * Current player options with resolved defaults.
214
- * This is what you receive from getOptions() - all properties are present with their current values.
214
+ * Current player options, as {@link getOptions} reports them. The intervals and the platform
215
+ * block come with their defaults filled in; `capabilities` holds the values set, plus,
216
+ * on Android and iOS, `jumpForward` and `jumpBackward`, which are `false` until set.
215
217
  * Platform-specific properties (android/ios) are only available on their respective platforms.
216
218
  *
217
219
  * @example
218
220
  * ```typescript
219
221
  * const options = getOptions();
220
222
  * console.log(options.forwardJumpInterval); // 15
221
- * console.log(options.capabilities); // { shuffleMode: false } - only disabled caps shown
223
+ * console.log(options.capabilities);
224
+ * // { jumpForward: false, jumpBackward: false, shuffleMode: false }
222
225
  * console.log(options.android?.skipSilence); // true (Android only)
223
226
  * ```
224
227
  */
@@ -229,9 +232,13 @@ export interface Options {
229
232
  /**
230
233
  * Jump forward interval in seconds when using jump forward controls.
231
234
  *
232
- * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
233
- * showing that number; any other interval gets an icon without one. Other
234
- * values are perfectly valid — the interval also sets the seek distance.
235
+ * On Android, Media3 has icons for intervals of exactly 5, 10, 15 or 30
236
+ * seconds, which show that number; any other interval gets an icon without
237
+ * one. Other values are valid. On iOS a jump with no `handleRemoteJump*`
238
+ * override seeks by the interval. On Android it seeks by Media3's default
239
+ * seek increment (15 seconds forward, 5 seconds back), and the interval sets
240
+ * only the icon and the event's `interval`; to jump by the interval,
241
+ * override the control and call `seekBy`.
235
242
  *
236
243
  * @default 15
237
244
  */
@@ -240,9 +247,7 @@ export interface Options {
240
247
  /**
241
248
  * Jump backward interval in seconds when using jump backward controls.
242
249
  *
243
- * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
244
- * showing that number; any other interval gets an icon without one. Other
245
- * values are perfectly valid — the interval also sets the seek distance.
250
+ * Platform differences as for {@link Options.forwardJumpInterval}.
246
251
  *
247
252
  * @default 15
248
253
  */
@@ -256,8 +261,10 @@ export interface Options {
256
261
  progressUpdateEventInterval: number | null
257
262
 
258
263
  /**
259
- * The capabilities that the player has.
260
- * Most capabilities are enabled by default - this shows which ones are disabled.
264
+ * The capabilities as set, plus, on Android and iOS, `jumpForward` and
265
+ * `jumpBackward`, which are `false` until set. An absent field means its
266
+ * default: off for `jumpForward`, `jumpBackward` and `favorite`, on for the
267
+ * rest.
261
268
  */
262
269
  capabilities: PlayerCapabilities
263
270
 
@@ -284,7 +291,7 @@ export interface IOSOptions {
284
291
  carPlayUpNextButton: boolean
285
292
 
286
293
  /**
287
- * Buttons shown on the CarPlay Now Playing screen (left-to-right, up to 5).
294
+ * Buttons shown on the CarPlay Now Playing screen (left to right, at most one of each kind).
288
295
  * @default []
289
296
  */
290
297
  carPlayNowPlayingButtons: CarPlayNowPlayingButton[]
@@ -297,11 +304,16 @@ export interface IOSOptions {
297
304
  carPlayPlayingIndicatorLocation: CarPlayPlayingIndicatorLocation
298
305
  }
299
306
 
307
+ /**
308
+ * Android runtime options as {@link getOptions} reports them.
309
+ * @platform android
310
+ */
300
311
  export interface AndroidOptions {
301
312
  /**
302
- * Whether the audio playback notification is also removed when the playback
303
- * stops. **If `stoppingAppPausesPlayback` is set to false, this will be
304
- * ignored.**
313
+ * What happens to playback and the notification when the user removes the
314
+ * app from recents.
315
+ *
316
+ * @default 'stop-playback-and-remove-notification'
305
317
  */
306
318
  appKilledPlaybackBehavior: AppKilledPlaybackBehavior
307
319
 
@@ -324,11 +336,16 @@ export interface AndroidOptions {
324
336
  remoteButtonLayout: RemoteButtonLayout | null
325
337
  }
326
338
 
339
+ /**
340
+ * Android options {@link updateOptions} can change at runtime.
341
+ * @platform android
342
+ */
327
343
  export interface AndroidUpdateOptions {
328
344
  /**
329
- * Whether the audio playback notification is also removed when the playback
330
- * stops. **If `stoppingAppPausesPlayback` is set to false, this will be
331
- * ignored.**
345
+ * What happens to playback and the notification when the user removes the
346
+ * app from recents.
347
+ *
348
+ * @default 'stop-playback-and-remove-notification'
332
349
  */
333
350
  appKilledPlaybackBehavior?: AppKilledPlaybackBehavior
334
351
 
@@ -381,8 +398,9 @@ export interface IOSUpdateOptions {
381
398
  carPlayUpNextButton?: boolean
382
399
 
383
400
  /**
384
- * Configure up to 5 buttons on the CarPlay Now Playing screen, arranged in
385
- * array order (left to right).
401
+ * Configure buttons, at most one of each {@link CarPlayNowPlayingButton}
402
+ * kind, on the CarPlay Now Playing screen, arranged in array order (left to
403
+ * right).
386
404
  *
387
405
  * @example
388
406
  * ```typescript
@@ -444,9 +462,7 @@ export interface UpdateOptions {
444
462
  /**
445
463
  * Jump forward interval in seconds when using jump forward controls.
446
464
  *
447
- * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
448
- * showing that number; any other interval gets an icon without one. Other
449
- * values are perfectly valid — the interval also sets the seek distance.
465
+ * See {@link Options.forwardJumpInterval} for how iOS and Android treat it.
450
466
  *
451
467
  * @default 15
452
468
  */
@@ -455,9 +471,7 @@ export interface UpdateOptions {
455
471
  /**
456
472
  * Jump backward interval in seconds when using jump backward controls.
457
473
  *
458
- * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
459
- * showing that number; any other interval gets an icon without one. Other
460
- * values are perfectly valid — the interval also sets the seek distance.
474
+ * See {@link Options.forwardJumpInterval} for how iOS and Android treat it.
461
475
  *
462
476
  * @default 15
463
477
  */
@@ -471,8 +485,10 @@ export interface UpdateOptions {
471
485
  progressUpdateEventInterval?: number | null
472
486
 
473
487
  /**
474
- * Player capabilities to enable or disable.
475
- * All capabilities are enabled by default - only specify ones you want to disable.
488
+ * Player capabilities to enable or disable. Most default to on;
489
+ * `jumpForward`, `jumpBackward` and `favorite` default to off. On Android
490
+ * and iOS, fields you omit keep their current value; on web, the object
491
+ * passed replaces the previous one.
476
492
  *
477
493
  * @example
478
494
  * ```typescript
@@ -502,9 +518,7 @@ export interface NativeUpdateOptions {
502
518
  /**
503
519
  * Jump forward interval in seconds when using jump forward controls.
504
520
  *
505
- * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
506
- * showing that number; any other interval gets an icon without one. Other
507
- * values are perfectly valid — the interval also sets the seek distance.
521
+ * See {@link Options.forwardJumpInterval}.
508
522
  *
509
523
  * @default 15
510
524
  */
@@ -513,9 +527,7 @@ export interface NativeUpdateOptions {
513
527
  /**
514
528
  * Jump backward interval in seconds when using jump backward controls.
515
529
  *
516
- * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
517
- * showing that number; any other interval gets an icon without one. Other
518
- * values are perfectly valid — the interval also sets the seek distance.
530
+ * See {@link Options.forwardJumpInterval}.
519
531
  *
520
532
  * @default 15
521
533
  */
@@ -556,10 +568,10 @@ export function updateOptions(options: UpdateOptions): void {
556
568
  // MARK: - Getters
557
569
 
558
570
  /**
559
- * Gets the current player options with resolved defaults.
560
- * Returns all current option values - use this to read the current state.
571
+ * Gets the current player options. `capabilities` holds the values set, plus, on Android
572
+ * and iOS, `jumpForward` and `jumpBackward` (`false` until set); a missing capability
573
+ * means its default.
561
574
  *
562
- * @returns The current player options with all properties resolved to their current values
563
575
  * @example
564
576
  * ```typescript
565
577
  * const options = getOptions();
@@ -575,8 +587,7 @@ export function getOptions(): Options {
575
587
  // MARK: - Event Callbacks
576
588
 
577
589
  /**
578
- * Subscribes to player options changes.
579
- * @param callback - Called when the player options change
590
+ * Emits each time the player options change.
580
591
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
581
592
  */
582
593
  export const onOptionsChanged = NativeUpdatedValue.emitterize<Options>(
@@ -17,8 +17,8 @@ import { validateIOSUpdateOptions } from './validateOptions'
17
17
  * Parameters passed to the {@link FormatNowPlayingCallback}.
18
18
  *
19
19
  * The formatter owns every line shown on the now-playing surface — the track text, the live song,
20
- * *and* any transient status (reconnecting / error). The library no longer renders status copy
21
- * itself, so these fields give you what you need to render (and localize) it yourself. The formatter
20
+ * *and* any transient status (reconnecting / error). The library renders no status text; these
21
+ * fields let you render (and localize) it yourself. The formatter
22
22
  * is re-invoked on track change, each timed-metadata update, play/pause + error/rebuffer
23
23
  * transitions, and device connectivity changes.
24
24
  */
@@ -27,6 +27,7 @@ export type FormatNowPlayingParams = {
27
27
  track: Track
28
28
  /**
29
29
  * Timed metadata (ICY / ID3 "now playing song") received during playback, if any.
30
+ * On iOS, also a file's own tags when the file has no chapters.
30
31
  * Always `undefined` on web — see `onTimedMetadata` for why.
31
32
  */
32
33
  timedMetadata?: TimedMetadata
@@ -57,44 +58,28 @@ export type StallReason = 'buffering' | 'offline'
57
58
  * Customizes what's rendered on the now-playing surface — lock screen, notification, Control Center,
58
59
  * CarPlay, and Android Auto — for the currently playing track.
59
60
  *
60
- * Configure it via {@link SetupPlayerOptions.nowPlaying}. Where the default behavior
61
- * simply publishes the track's own `title` / `artist`, the formatter hands you the two now-playing
62
- * text lines outright: render the live timed metadata (the ICY / ID3 "now playing song"), surface a
63
- * transient status line ("Reconnecting…", an error message), drop the song while paused — anything
64
- * you can derive from the {@link FormatNowPlayingParams} for that moment.
61
+ * Configure it via {@link SetupPlayerOptions.nowPlaying}. It is re-invoked on track change, each
62
+ * timed-metadata update and every playback transition; identical results are de-duplicated
63
+ * natively, so they don't flicker the surface.
65
64
  *
66
- * The callback is **synchronous** and should stay cheap: it's a pure formatting function, run on the
67
- * JS thread and awaited natively. Don't do I/O in it. If you need asynchronously-fetched data (e.g.
68
- * album art), resolve it out-of-band and stamp it imperatively rather than awaiting inside here.
69
- *
70
- * ### When it's invoked
71
- * The player re-invokes the formatter whenever the now-playing could change:
72
- * - on track change (a new item becomes current);
73
- * - on each timed-metadata update ({@link FormatNowPlayingParams.timedMetadata} arrives or changes);
74
- * - on every playback transition — play / pause, a stall starting or recovering, an error.
75
- *
76
- * Identical results are de-duplicated natively before they reach the media session, so returning the
77
- * same fields across a rapid burst of transitions is cheap and won't flicker the surface.
78
- *
79
- * ### What to return
80
- * Return a {@link NowPlayingUpdate} with the fields to display. Each field falls back **independently**
81
- * to the track's own value when omitted — so `{ artist: 'Some Song' }` replaces only the secondary
82
- * line and leaves the title as the track's title. Return `undefined` (or `{}`) to use the library
83
- * default entirely (the track's own `title` / `artist`).
84
- *
85
- * @param params - The current track, latest timed metadata, and playback signals for this moment
86
- * ({@link FormatNowPlayingParams}), including a {@link StallReason} that already classifies an
87
- * offline stall — no separate connectivity read needed for the now-playing line.
88
- * @returns The now-playing fields to display, or `undefined` to fall back to the track's own
89
- * `title` / `artist`.
65
+ * The callback is **synchronous**, run on the JS thread and awaited natively: no I/O in it.
66
+ * Each returned field falls back **independently** to the track's own value, so
67
+ * `{ artist: 'Some Song' }` replaces only the secondary line; `undefined` (or `{}`) keeps the
68
+ * track's own `title` / `artist`. See the [Now playing guide](https://audiobrowser.dev/guide/now-playing).
90
69
  *
91
70
  * @example
92
71
  * ```ts
93
72
  * setupPlayer({
94
73
  * nowPlaying: ({ timedMetadata, playWhenReady, stalled, error }) => {
95
74
  * if (error) return { artist: error.message ?? 'Playback error' }
96
- * if (stalled) return { artist: stalled === 'offline' ? 'No internet connection' : 'Reconnecting…' }
97
- * // Show the live song only while actually playing; otherwise fall back to the track default.
75
+ * if (stalled) {
76
+ * return {
77
+ * artist: stalled === 'offline'
78
+ * ? 'No internet connection'
79
+ * : 'Reconnecting…'
80
+ * }
81
+ * }
82
+ * // Show the live song only while playing; else use the track default.
98
83
  * if (!playWhenReady || !timedMetadata?.title) return
99
84
  * return {
100
85
  * artist: timedMetadata.artist
@@ -152,7 +137,8 @@ export type AndroidAudioContentType =
152
137
  * - `'ambient'`: The category for an app in which sound playback is nonprimary
153
138
  * — that is, your app also works with the sound turned off. See
154
139
  * https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616560-ambient
155
- * - `'soloAmbient'`: The default audio session category. See
140
+ * - `'soloAmbient'`: The system's default audio session category; the library
141
+ * uses `'playback'` when `category` is omitted. See
156
142
  * https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616488-soloambient
157
143
  * - `'record'`: The category for recording audio while also silencing playback
158
144
  * audio. See
@@ -252,18 +238,24 @@ export type IOSCategoryOptions =
252
238
  */
253
239
  export type IOSCategoryPolicy = 'default' | 'longFormAudio' | 'longFormVideo'
254
240
 
241
+ /**
242
+ * Requirements for Android audio offload; see `audioOffload`.
243
+ * @platform android
244
+ */
255
245
  export interface AndroidAudioOffloadSettings {
256
246
  /**
257
247
  * Whether gapless playback support is required for offload.
258
248
  * Enables smooth transitions between tracks without silence gaps.
259
- * @default true
249
+ * Omitting it here means not required; `audioOffload: true` requires it.
250
+ * @default false
260
251
  */
261
252
  gaplessSupportRequired?: boolean
262
253
 
263
254
  /**
264
255
  * Whether playback rate change support is required for offload.
265
256
  * Enables variable playback speeds (0.5x, 1.25x, 2x, etc.) during offload.
266
- * @default true
257
+ * Omitting it here means not required; `audioOffload: true` requires it.
258
+ * @default false
267
259
  */
268
260
  rateChangeSupportRequired?: boolean
269
261
  }
@@ -336,8 +328,8 @@ export type AndroidPlayerWakeMode = 'none' | 'local' | 'network'
336
328
  export interface AndroidSetupOptions extends AndroidUpdateOptions {
337
329
  /**
338
330
  * Minimum duration of media that the player will attempt to buffer in ms.
331
+ * Has no effect: the player keeps loading until `maxBuffer` is buffered.
339
332
  *
340
- * @throws Will throw if min buffer is higher than max buffer.
341
333
  * @default 50000
342
334
  */
343
335
  minBuffer?: number
@@ -350,8 +342,9 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
350
342
  *
351
343
  * - `true`: Enable with default settings (gapless + rate change support required)
352
344
  * - `false`/`undefined`: Disabled
353
- * - `{ gaplessSupportRequired: boolean, rateChangeSupportRequired: boolean }`:
354
- * Enable with specific requirements for gapless playback and playback rate changes
345
+ * - `{ gaplessSupportRequired?: boolean, rateChangeSupportRequired?: boolean }`:
346
+ * Enable with specific requirements for gapless playback and playback rate changes;
347
+ * an omitted field is not required, so `{}` enables offload with no requirements
355
348
  *
356
349
  * @default false
357
350
  */
@@ -359,9 +352,7 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
359
352
 
360
353
  /**
361
354
  * Maximum duration of media that the player will attempt to buffer in ms.
362
- * Max buffer may not be lower than min buffer.
363
355
  *
364
- * @throws Will throw if max buffer is lower than min buffer.
365
356
  * @default 50000
366
357
  */
367
358
  maxBuffer?: number
@@ -378,7 +369,7 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
378
369
  * Duration of media in ms that must be buffered for playback to start or
379
370
  * resume following a user action such as a seek.
380
371
  *
381
- * @default 2500
372
+ * @default 1000 (media3's `DEFAULT_BUFFER_FOR_PLAYBACK_MS`)
382
373
  */
383
374
  playBuffer?: number
384
375
 
@@ -389,7 +380,6 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
389
380
  * When null (the default), uses automatic mode:
390
381
  * - Starts at `playBuffer` value
391
382
  * - On rebuffer, measures how fast the buffer drained
392
- * - Calculates how much buffer is needed to sustain 60s of playback
393
383
  * - Increases threshold accordingly (up to 8000ms max)
394
384
  * - Resets when changing tracks
395
385
  *
@@ -412,11 +402,11 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
412
402
  * The audio content type indicates to the android system how
413
403
  * you intend to use audio in your app.
414
404
  *
415
- * With `audioContentType: AndroidAudioContentType.Speech`, the audio will be
405
+ * With `audioContentType: 'speech'`, the audio will be
416
406
  * paused during short interruptions, such as when a message arrives.
417
407
  * Otherwise the playback volume is reduced while the notification is playing.
418
408
  *
419
- * @default AndroidAudioContentType.Music
409
+ * @default 'music'
420
410
  */
421
411
  audioContentType?: AndroidAudioContentType
422
412
 
@@ -455,7 +445,10 @@ export interface IOSSetupOptions extends IOSUpdateOptions {
455
445
 
456
446
  /**
457
447
  * [AVAudioSession.Category](https://developer.apple.com/documentation/avfoundation/avaudiosession/1616615-category)
458
- * for iOS. Sets on `play()`.
448
+ * for iOS. Applied at `setupPlayer`; the session is activated when playback
449
+ * starts.
450
+ *
451
+ * @default 'playback'
459
452
  */
460
453
  category?: IOSCategory
461
454
 
@@ -464,21 +457,27 @@ export interface IOSSetupOptions extends IOSUpdateOptions {
464
457
  * indicates to the system how you intend to use audio in your app. You can use
465
458
  * a mode to configure the audio system for specific use cases such as video
466
459
  * recording, voice or video chat, or audio analysis.
467
- * Sets on `play()`.
460
+ * Applied at `setupPlayer`; the session is activated when playback starts.
468
461
  *
469
462
  * See https://developer.apple.com/documentation/avfoundation/avaudiosession/1616508-mode
463
+ *
464
+ * @default 'default'
470
465
  */
471
466
  categoryMode?: IOSCategoryMode
472
467
 
473
468
  /**
474
469
  * [AVAudioSession.CategoryOptions](https://developer.apple.com/documentation/avfoundation/avaudiosession/1616503-categoryoptions) for iOS.
475
- * Sets on `play()`.
470
+ * Applied at `setupPlayer`; the session is activated when playback starts.
471
+ *
472
+ * @default []
476
473
  */
477
474
  categoryOptions?: IOSCategoryOptions[]
478
475
 
479
476
  /**
480
477
  * [AVAudioSession.RouteSharingPolicy](https://developer.apple.com/documentation/AVFAudio/AVAudioSession/RouteSharingPolicy-swift.enum) for iOS.
481
- * Sets on `play()`.
478
+ * Applied at `setupPlayer`; the session is activated when playback starts.
479
+ *
480
+ * @default 'default'
482
481
  */
483
482
  categoryPolicy?: IOSCategoryPolicy
484
483
  }
@@ -606,13 +605,15 @@ export type SetupPlayerOptions = Pick<
606
605
  /**
607
606
  * Retry policy for load errors (network failures, timeouts, etc.)
608
607
  * - `true`: Retry indefinitely with exponential backoff, under the default
609
- * duration budgets (12s before first audio, 2 minutes after — see
610
- * {@link RetryConfig})
611
- * - `false`/`undefined`: No automatic retry (default)
608
+ * duration budgets of {@link RetryConfig}
609
+ * - `false`/`undefined`: no library retry. Android keeps media3's default
610
+ * handling, which retries a failed load a few times before surfacing the
611
+ * error; iOS fails at once.
612
612
  * - `{ maxRetries: n }`: Retry up to n times with exponential backoff
613
613
  * - `RetryConfig`: custom attempt and duration budgets
614
614
  *
615
- * Exponential backoff delays: 1s → 1.5s → 2.3s → 3.4s → 5s (capped)
615
+ * Backoff timing and budgets: see the
616
+ * [Errors guide](https://audiobrowser.dev/guide/errors#two-duration-budgets).
616
617
  *
617
618
  * @default false
618
619
  */
@@ -620,7 +621,7 @@ export type SetupPlayerOptions = Pick<
620
621
 
621
622
  /**
622
623
  * Keep the media session alive and controllable through a terminal playback error (e.g. a dead
623
- * stream), so external controllers (Android Auto / CarPlay) keep their transport controls
624
+ * stream), so External Surfaces such as Android Auto keep their transport controls
624
625
  * (next / previous) instead of tearing the session down. The error is still reported via
625
626
  * `onPlaybackError` / `playbackState`; this only affects what the OS media session observes.
626
627
  *
@@ -643,7 +644,7 @@ export type SetupPlayerOptions = Pick<
643
644
  * Each `setupPlayer` sets it: left out, remote outputs are off, and playback on one comes back
644
645
  * to the phone.
645
646
  *
646
- * Android 11+ only for now; ignored on iOS, whose route picker already lists AirPlay devices.
647
+ * Android 11+; ignored on iOS, whose route picker already lists AirPlay devices.
647
648
  * @default off
648
649
  */
649
650
  remoteOutputs?: RemoteOutputsOptions
@@ -659,8 +660,7 @@ export type SetupPlayerOptions = Pick<
659
660
  * - `true` (default): publish the track's own title / artist.
660
661
  * - `false`: don't manage the now-playing metadata at all.
661
662
  * - a {@link FormatNowPlayingCallback}: render it yourself — the callback owns every line,
662
- * including any transient status (buffering / reconnecting / offline / error), which the
663
- * library no longer renders on your behalf.
663
+ * including any transient status (buffering / reconnecting / offline / error).
664
664
  *
665
665
  * @default true
666
666
  */
@@ -710,7 +710,8 @@ function wrapNowPlayingFormatter(
710
710
  /**
711
711
  * The object's entries whose values aren't `undefined`. `null` stays: it's meaningful on some
712
712
  * fields (`progressUpdateEventInterval: null` disables progress events, `remoteButtonLayout:
713
- * null` empties the layout), so only `undefined` means "not provided".
713
+ * null` goes back to the layout derived from capabilities), so only `undefined` means "not
714
+ * provided".
714
715
  */
715
716
  function definedFields<T extends object>(obj: T): Partial<T> {
716
717
  const out: Partial<T> = {}
@@ -737,9 +738,14 @@ function nonEmpty<K extends string, T extends object>(
737
738
  * natively as part of setup itself, so there is no setup-then-command ordering for consumers
738
739
  * to know about, and no window where the player exists without its options.
739
740
  *
740
- * Calling it again reconfigures the player in place: newly provided fields are merged over
741
- * the previous ones, and the audio engine is rebuilt when construction-bound fields (buffers,
742
- * wake mode, …) changed.
741
+ * Calling it again is how a setup-only option changes after launch, and works differently per
742
+ * platform. On Android, newly provided fields are merged over the previous ones, except
743
+ * `remoteOutputs`, which is off when left out, and `nowPlaying`, which is on when left out
744
+ * and keeps an earlier formatter until a call passes another one. The audio engine is rebuilt
745
+ * only when construction-bound fields (buffers, wake mode, …) changed. On iOS, each call
746
+ * replaces the player: the queue is cleared, and setup-only fields you omit (`ios` session
747
+ * category and `buffer`, `retry`, …) go back to their defaults. Runtime options set earlier
748
+ * carry over on both.
743
749
  *
744
750
  * @param options - The options to initialize the player with.
745
751
  *