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
@@ -5,7 +5,7 @@ description: 'Build and edit the queue, move between tracks with next and previo
5
5
  # Queue
6
6
 
7
7
  The **queue** is the ordered list of tracks the player works through. The track
8
- at the current position is the **active track** — it's what plays, and what
8
+ at the current position is the **active track**: what plays, and what
9
9
  next/previous move between. This guide covers building the queue, editing it,
10
10
  moving between tracks, and reading it back for an "up next" UI.
11
11
 
@@ -26,21 +26,23 @@ Optionally pass which track to make active and where to start it:
26
26
  ```ts
27
27
  import { setQueue, play } from 'react-native-audio-browser'
28
28
 
29
- setQueue(tracks) // replace; first track becomes active
29
+ setQueue(tracks, 0) // replace; first track becomes active
30
30
  setQueue(tracks, 2) // start on index 2
31
31
  setQueue(tracks, 2, 30) // ...30 seconds in
32
32
  ```
33
33
 
34
- One thing to know:
34
+ On iOS and Android, `startIndex` defaults to 0. iOS clamps an index outside
35
+ the queue to its first or last track, and Android throws. On the web, an
36
+ omitted or out-of-range `startIndex` leaves no track active, so pass one (0 for
37
+ the first track).
35
38
 
36
- - **It doesn't start playback.** `setQueue` leaves the play/pause state as-is —
37
- if the player was paused it stays paused. Call
38
- [`play()`](/api/features/playback/#play) to begin (see [Playback](/guide/playback)).
39
-
40
- So the usual "load these and play" is two calls:
39
+ `setQueue` doesn't start playback. On iOS and Android it keeps the current
40
+ play/pause state; on the web it stops playback. Either way, call
41
+ [`play()`](/api/features/playback/#play) after it (see
42
+ [Playback](/guide/playback)):
41
43
 
42
44
  ```ts
43
- setQueue(tracks) // or setQueue(tracks, startIndex)
45
+ setQueue(tracks, 0) // or setQueue(tracks, startIndex)
44
46
  play() // start playback
45
47
  ```
46
48
 
@@ -70,7 +72,12 @@ Outside React, read a snapshot with
70
72
  [`getTrack(index)`](/api/features/queue/#gettrack) (returns `undefined` if the
71
73
  index is empty). To react to changes without a hook, subscribe to
72
74
  [`onQueueChanged`](/api/features/queue/#onqueuechanged) — it fires with the new
73
- queue on every add, remove, reorder, or metadata update.
75
+ queue on every add, remove, or reorder.
76
+
77
+ A favorite toggle also fires it on iOS
78
+ and Android, but on web it fires only
79
+ [`onFavoriteChanged`](/api/features/favorites/#onfavoritechanged), so listen to
80
+ both, as `useQueue` does.
74
81
 
75
82
  ## The active track
76
83
 
@@ -116,6 +123,9 @@ skipToPrevious() // previous track
116
123
  skipToNext(10) // next track, starting 10 seconds in
117
124
  ```
118
125
 
126
+ On iOS and Android, if there is no next (or previous) track, the position
127
+ still applies: the active track seeks to it. On the web the call does nothing.
128
+
119
129
  This is how you move _between_ tracks
120
130
  ([`skip`](/api/features/queue/#skip),
121
131
  [`skipToNext`](/api/features/queue/#skiptonext),
@@ -144,7 +154,8 @@ add(track) // append one track (also accepts a Track[])
144
154
  add(track, 0) // insert before index 0 (front of the queue)
145
155
 
146
156
  move(4, 1) // move index 4 to index 1
147
- // toIndex past the end moves the track to the end.
157
+ // On iOS and Android, toIndex past the end moves the track to the end;
158
+ // the web throws.
148
159
 
149
160
  remove(2) // remove index 2 (also accepts number[])
150
161
  removeUpcomingTracks() // drop everything after the active track
@@ -162,19 +173,32 @@ const i = getActiveTrackIndex()
162
173
  add(track, i === undefined ? 0 : i + 1)
163
174
  ```
164
175
 
165
- **Removing the active track** doesn't stop playback: the next track becomes
166
- active, or — if you removed the last one — the first track does.
176
+ With shuffle on, the inserted track goes to a random place in the shuffle
177
+ order, so it may not play next.
178
+
179
+ **Removing the active track** makes the track after it active. On iOS and the
180
+ web that is the next index, wrapping to the first track, and playback carries
181
+ on.
182
+
183
+ On Android it is the next track in playback order, with shuffle and repeat
184
+ applied. If you remove the last track there, the first track becomes active,
185
+ and with repeat `'off'` playback ends.
186
+
187
+ With several indexes, Android checks them all first and throws on a repeated
188
+ one. iOS removes from the highest index down. A repeated index then also removes
189
+ the track that moved into its place, and an invalid index can throw after some
190
+ tracks are already gone. Pass each index once.
167
191
 
168
192
  ## Repeat and shuffle
169
193
 
170
- [Repeat mode](/api/features/queue/#userepeatmode) is one of `'off'`, `'track'`,
194
+ [Repeat mode](/api/features/queue/#repeatmode) is one of `'off'`, `'track'`,
171
195
  or `'queue'`:
172
196
 
173
- | Mode | Behavior |
174
- | --------- | ------------------------------------------------ |
175
- | `'off'` | Stop when the last track finishes (the default). |
176
- | `'track'` | Repeat the active track forever. |
177
- | `'queue'` | Loop the whole queue. |
197
+ | Mode | Behavior |
198
+ | --------- | -------------------------------------------------------------------------- |
199
+ | `'off'` | Pause at the end of the last track; state becomes `'ended'` (the default). |
200
+ | `'track'` | Repeat the active track forever. |
201
+ | `'queue'` | Loop the whole queue. |
178
202
 
179
203
  ```tsx
180
204
  import {
@@ -204,7 +228,16 @@ function ShuffleButton() {
204
228
  ```
205
229
 
206
230
  [`setShuffle(true | false)`](/api/features/queue/#setshuffle) sets it directly;
207
- [`toggleShuffle()`](/api/features/queue/#toggleshuffle) flips it.
231
+ [`toggleShuffle()`](/api/features/queue/#toggleshuffle) flips it. Outside
232
+ React, read the current values with
233
+ [`getRepeatMode()`](/api/features/queue/#getrepeatmode) and
234
+ [`getShuffle()`](/api/features/queue/#getshuffle), and subscribe to
235
+ [`onRepeatModeChanged`](/api/features/queue/#onrepeatmodechanged) and
236
+ [`onShuffleChanged`](/api/features/queue/#onshufflechanged).
237
+
238
+ Shuffle changes only the playback order. Indexes, `getQueue` and `useQueue`
239
+ keep list order, while `skipToNext` and `skipToPrevious` follow the shuffle
240
+ order.
208
241
 
209
242
  ## When the queue ends
210
243
 
@@ -233,6 +266,7 @@ import {
233
266
  useQueue,
234
267
  useActiveTrack,
235
268
  getActiveTrackIndex,
269
+ getTrackIdentity,
236
270
  skip,
237
271
  move,
238
272
  remove
@@ -240,16 +274,16 @@ import {
240
274
 
241
275
  function UpNext() {
242
276
  const queue = useQueue()
243
- // `useActiveTrack` re-renders the list when the active track changes; we
244
- // compare each row by index (more robust than by id, which is optional on a
245
- // Track). `getActiveTrackIndex()` is fresh on each render.
277
+ // `useActiveTrack` re-renders the list when the active track changes.
278
+ // Compare by index: the same track can be queued twice.
279
+ // `getActiveTrackIndex()` is read fresh on each render.
246
280
  const active = useActiveTrack()
247
281
  const activeIndex = active ? getActiveTrackIndex() : undefined
248
282
 
249
283
  return (
250
284
  <FlatList
251
285
  data={queue}
252
- keyExtractor={(track, i) => track.id ?? String(i)}
286
+ keyExtractor={(track, i) => `${getTrackIdentity(track) ?? ''}:${i}`}
253
287
  renderItem={({ item, index }) => (
254
288
  <View style={{ flexDirection: 'row', alignItems: 'center' }}>
255
289
  <Text
@@ -270,10 +304,9 @@ function UpNext() {
270
304
  ```
271
305
 
272
306
  A `<Button>` can't be a child of `<Text>`, so each row is a `<View>` with the
273
- title and buttons as siblings. The `keyExtractor` falls back to the array index
274
- when a track has no `id` — fine for a static list, but for a **reorderable**
275
- list like this one, give your tracks a stable `id` so `move`/`remove` don't
276
- confuse row identity.
307
+ title and buttons as siblings. A key built from the track's `id` alone, or from
308
+ [`getTrackIdentity`](/api/utils/getTrackIdentity/) alone, collides when the same
309
+ track is queued twice, so the `keyExtractor` adds the index.
277
310
 
278
311
  ## A note on units
279
312
 
@@ -283,18 +316,19 @@ All position arguments are **seconds** — `seekTo`, `seekBy`, the
283
316
 
284
317
  ## API summary
285
318
 
286
- | API | Purpose |
287
- | ----------------------------------------------------------------- | --------------------------------------------------------------- |
288
- | `setQueue(tracks, startIndex?, startPosition?)` | Replace the queue (doesn't auto-play; position in **seconds**). |
289
- | `add(track \| tracks, insertBeforeIndex?)` | Append, or insert before an index. |
290
- | `load(track)` | Replace the active track (or start the queue if empty). |
291
- | `move(from, to)` | Reorder; `to` past the end → end. |
292
- | `remove(index \| indexes)` | Remove track(s); active removal advances. |
293
- | `removeUpcomingTracks()` | Drop everything after the active track. |
294
- | `skip(index, initialPosition?)` | Jump to a track (position in **seconds**). |
295
- | `skipToNext()` / `skipToPrevious()` | Step between tracks. |
296
- | `useQueue()` / `getQueue()` / `getTrack(i)` | Read the queue. |
297
- | `useActiveTrack()` / `getActiveTrack()` / `getActiveTrackIndex()` | Read the active track. |
298
- | `onActiveTrackChanged` / `onQueueChanged` / `onQueueEnded` | Subscribe to changes. |
299
- | `setRepeatMode(mode)` / `useRepeatMode()` | `'off'` / `'track'` / `'queue'`. |
300
- | `setShuffle(bool)` / `toggleShuffle()` / `useShuffle()` | Shuffle order. |
319
+ | API | Purpose |
320
+ | ------------------------------------------------------------------------ | ---------------------------------------------------------------- |
321
+ | `setQueue(tracks, startIndex?, startPosition?)` | Replace the queue (doesn't auto-play; position in **seconds**). |
322
+ | `add(track \| tracks, insertBeforeIndex?)` | Append, or insert before an index. |
323
+ | `load(track)` | Replace the active track (or start the queue if empty). |
324
+ | `move(from, to)` | Reorder; `to` past the end → end (iOS, Android; the web throws). |
325
+ | `remove(index \| indexes)` | Remove track(s); see Removing the active track above. |
326
+ | `removeUpcomingTracks()` | Drop everything after the active track. |
327
+ | `skip(index, initialPosition?)` | Jump to a track (position in **seconds**). |
328
+ | `skipToNext()` / `skipToPrevious()` | Step between tracks. |
329
+ | `useQueue()` / `getQueue()` / `getTrack(i)` | Read the queue. |
330
+ | `useActiveTrack()` / `getActiveTrack()` / `getActiveTrackIndex()` | Read the active track. |
331
+ | `onActiveTrackChanged` / `onQueueChanged` / `onQueueEnded` | Subscribe to changes. |
332
+ | `setRepeatMode(mode)` / `useRepeatMode()` / `getRepeatMode()` | `'off'` / `'track'` / `'queue'`. |
333
+ | `setShuffle(bool)` / `toggleShuffle()` / `useShuffle()` / `getShuffle()` | Shuffle order. |
334
+ | `onRepeatModeChanged` / `onShuffleChanged` | Subscribe to repeat and shuffle changes. |
@@ -1,21 +1,23 @@
1
1
  ---
2
- description: 'Override what the lock-screen, notification, car, and headset buttons do with handleRemote*, and observe presses with the onRemote* events.'
2
+ description: 'Override what the lock-screen, notification, car, and headset buttons do with handleRemote*, observe presses with the onRemote* events, and resume the last session after the app is killed.'
3
3
  ---
4
4
 
5
5
  # Remote Controls
6
6
 
7
7
  **Remote controls** are the playback buttons on surfaces outside your app — the
8
8
  iOS lock screen and Control Center, the Android notification, CarPlay and Android
9
- Auto, and Bluetooth/headset buttons. By default they just work: the system
10
- play/pause/next/seek buttons drive the player for you. This guide is for the two
11
- times you need more — **overriding** what a button does, and **observing** when
12
- one is pressed.
9
+ Auto, and Bluetooth/headset buttons.
10
+
11
+ By default they just work: the system play/pause/next/seek buttons drive the
12
+ player for you. This guide is for the two times you need more — **overriding**
13
+ what a button does, and **observing** when one is pressed.
13
14
 
14
15
  There are two families:
15
16
 
16
17
  - [`handleRemote*`](#overriding-a-control) — **override** a control's behavior.
17
18
  A plain setter: `handleRemoteNext(cb)`, or `handleRemoteNext(undefined)` to
18
- clear it.
19
+ restore the default behavior. To remove a button on iOS or Android, turn off
20
+ its capability.
19
21
  - [`onRemote*`](#listening-to-presses) — **listen** to presses without changing
20
22
  behavior (analytics, logging). An emitter:
21
23
  `onRemoteNext.addListener(cb)` returns an unsubscribe function.
@@ -36,7 +38,7 @@ Without any wiring, each control drives the player:
36
38
  | play / pause / stop | `play()` / `pause()` / `stop()` |
37
39
  | next / previous | `skipToNext()` / `skipToPrevious()` |
38
40
  | seek | `seekTo(position)` |
39
- | jump forward / backward | `seekBy(±interval)` |
41
+ | jump forward / backward | seek forward / back (see below) |
40
42
 
41
43
  So you only reach for the APIs below to _change_ or _watch_ that behavior.
42
44
 
@@ -100,7 +102,11 @@ This catches people out, because `jumpForward` and `jumpBackward` default to
100
102
  // ✗ Both jump buttons are silently dropped — no error, no warning.
101
103
  updateOptions({
102
104
  android: {
103
- remoteButtonLayout: { back: 'jump-backward', forward: 'jump-forward' }
105
+ remoteButtonLayout: {
106
+ back: 'jump-backward',
107
+ forward: 'jump-forward',
108
+ overflow: []
109
+ }
104
110
  }
105
111
  })
106
112
 
@@ -108,7 +114,11 @@ updateOptions({
108
114
  updateOptions({
109
115
  capabilities: { jumpBackward: true, jumpForward: true },
110
116
  android: {
111
- remoteButtonLayout: { back: 'jump-backward', forward: 'jump-forward' }
117
+ remoteButtonLayout: {
118
+ back: 'jump-backward',
119
+ forward: 'jump-forward',
120
+ overflow: []
121
+ }
112
122
  }
113
123
  })
114
124
  ```
@@ -122,12 +132,12 @@ capability is enabled.
122
132
  `overflow` is an ordered list, and each surface renders as many buttons as it
123
133
  has room for, **taking them from the front**:
124
134
 
125
- | Surface | Roughly how many |
126
- | -------------------------- | ----------------------------- |
127
- | Collapsed notification | 3 — back, play/pause, forward |
128
- | Expanded notification | all of them |
129
- | Android 13+ media controls | about 5 |
130
- | Android Auto | the head unit decides |
135
+ | Surface | Roughly how many |
136
+ | -------------------------------------------- | ----------------------------- |
137
+ | Collapsed notification | 3 — back, play/pause, forward |
138
+ | Expanded notification (Android 12 and below) | up to 5, play/pause included |
139
+ | Android 13+ media controls | about 5 |
140
+ | Android Auto | the head unit decides |
131
141
 
132
142
  Two consequences worth knowing:
133
143
 
@@ -143,7 +153,7 @@ buttons so there's nothing to promote.
143
153
  ::: tip iOS
144
154
  This option is Android-only. CarPlay's Now Playing buttons are configured
145
155
  separately with `ios.carPlayNowPlayingButtons` — see
146
- [CarPlay](/guide/carplay).
156
+ [CarPlay → Now Playing Buttons](/guide/carplay#now-playing-buttons).
147
157
  :::
148
158
 
149
159
  ## Overriding a control
@@ -151,9 +161,10 @@ separately with `ios.carPlayNowPlayingButtons` — see
151
161
  [`handleRemote*(callback)`](/api/features/remoteControls/#handleremotenext)
152
162
  **replaces** a control's default action with your own. Pass `undefined` to remove
153
163
  your override (restoring the default); the callback itself does nothing but what
154
- you write — if you still want the normal action, call it yourself. Each control
155
- has a **single** override: calling `handleRemote*` again replaces the previous one
156
- (unlike `onRemote*`, which supports multiple listeners).
164
+ you write — if you still want the normal action, call it yourself.
165
+
166
+ Each control has a **single** override: calling `handleRemote*` again replaces
167
+ the previous one (unlike `onRemote*`, which supports multiple listeners).
157
168
 
158
169
  The canonical use is gating a control — e.g. a radio product with a skip
159
170
  allowance — paired with a [now-playing flash](/guide/now-playing#the-flash-transient-top-priority)
@@ -192,14 +203,25 @@ handleRemoteSeek(({ position }) => {
192
203
  // position is in seconds
193
204
  })
194
205
  handleRemoteJumpForward(({ interval }) => {
195
- // interval is in seconds (from forwardJumpInterval)
206
+ // interval is in seconds
196
207
  })
197
208
  ```
198
209
 
199
- The jump controls only appear when `jumpForward` / `jumpBackward` are enabled in
200
- [`capabilities`](/guide/configuration#capabilities) (off by default). The jump
201
- distance is the separate `forwardJumpInterval` / `backwardJumpInterval` option
202
- (default 15s) — that's the `interval` your handler receives.
210
+ On iOS and Android the jump controls only appear when `jumpForward` /
211
+ `jumpBackward` are enabled in [`capabilities`](/guide/configuration#capabilities)
212
+ (off by default); on web capabilities are ignored and the browser's seek
213
+ forward and back actions are always handled. On iOS and Android your handler
214
+ receives the `forwardJumpInterval` / `backwardJumpInterval` option (default
215
+ 15s) as `interval`; on web it receives the offset the browser sends, or 10s
216
+ when it sends none. Without a handler, the distance of the default jump depends
217
+ on the platform:
218
+
219
+ - **iOS** seeks by the interval.
220
+ - **Android** seeks by Media3's default increments (15s forward, 5s back),
221
+ whatever the interval. There the interval sets only the button's icon and the
222
+ handler's `interval`. To jump by the interval on Android, override the control
223
+ and call `seekBy(±interval)`.
224
+ - **Web** seeks by the offset the browser sends, or 10s when it sends none.
203
225
 
204
226
  ## Listening to presses
205
227
 
@@ -225,14 +247,50 @@ intercepted it (and even when that override refused to act). Use it to _observe_
225
247
  use `handleRemote*` to _change behavior_.
226
248
  :::
227
249
 
250
+ ## Resuming after the app is killed
251
+
252
+ The library saves the last session natively, with nothing to configure: the
253
+ active track (with the browse path it was tapped from), its position, and the
254
+ repeat mode, shuffle and rate.
255
+
256
+ It saves on every pause, track change and setting change, and periodically
257
+ while playing, so a kill loses at most a few seconds of position. A live stream
258
+ keeps no position, so it resumes at the live edge; a track that had ended
259
+ resumes from the start.
260
+
261
+ That session plays again when a listener asks for playback while your app isn't
262
+ running:
263
+
264
+ - **Android**: a Bluetooth or headset play button, a car head unit, or the play
265
+ button on the system media controls, which keep your app's last session after
266
+ it is killed.
267
+ - **iOS**: Siri — "play «App»" or a bare "play" / "resume" (see
268
+ [Search → Voice playback](/guide/search#voice-playback-siri-google-assistant)).
269
+ Siri is the only path that resumes a saved session on iOS.
270
+
271
+ Resuming restores the settings, then rebuilds the queue by expanding the saved
272
+ track's path through your browse configuration, as if the listener had tapped it
273
+ again, and plays from the saved position.
274
+
275
+ If the path doesn't expand, the saved track plays alone. A saved track marked
276
+ [`disabled`](/guide/track) is never resumed.
277
+
278
+ Resuming waits for your JS: call `setupPlayer()` and `configureBrowser()` at the
279
+ top level of `index.js`. Resuming gives up within seconds if they haven't run
280
+ (on iOS, see
281
+ [CarPlay → AppDelegate intent handler](/guide/carplay#_4-appdelegate-intent-handler)).
282
+ On Android 12+, battery restrictions can block the background start; see
283
+ [Battery](/guide/battery).
284
+
228
285
  ## Voice commands ("play X")
229
286
 
230
287
  A voice command like "play jazz on Android Auto" or a Siri "play …" is **not**
231
- delivered as a remote-control event. It's handled by the library's
232
- [search source](/guide/search) and play funnel: you provide
233
- `configureBrowser({ search })`, and the library resolves the query and starts
234
- playback for you (Android routes the system `MEDIA_PLAY_FROM_SEARCH` intent
235
- through it). See [Search](/guide/search) for wiring voice intents.
288
+ delivered as a remote-control event.
289
+
290
+ It's handled by the library's [search source](/guide/search) and play funnel:
291
+ you provide `configureBrowser({ search })`, and the library resolves the query
292
+ and starts playback for you (Android routes the system `MEDIA_PLAY_FROM_SEARCH`
293
+ intent through it). See [Search](/guide/search) for wiring voice intents.
236
294
 
237
295
  ## Payloads at a glance
238
296
 
@@ -38,27 +38,31 @@ configureBrowser({
38
38
  })
39
39
  ```
40
40
 
41
- **An HTTP endpoint** — a `TransformableRequestConfig`. The library issues the request natively and appends the query parameters for you. The endpoint must return a **page object** — `{ title?, children: Track[] }` — the same shape a browse endpoint returns. (iOS and Android require the page object; the web implementation additionally accepts a bare `Track[]` for back-compat, but return the page object so all three platforms work.)
41
+ **An HTTP endpoint** — a `TransformableRequestConfig`. The library issues the request natively and appends the query parameters for you.
42
+
43
+ The endpoint must return a **bare `Track[]`**, a JSON array of results, not the page object a browse endpoint returns. iOS and Android decode only the array. On Android a page object gives no results, and on iOS the search rejects. The web accepts either shape. See [`SearchSource`](/api/types/browser/#searchsource).
42
44
 
43
45
  ```ts
44
46
  configureBrowser({
45
47
  search: {
46
48
  baseUrl: 'https://api.example.com/search',
47
- // "play jazz" → GET .../search?q=jazz&genre=jazz&limit=20
49
+ // "play jazz" → GET .../search with q=jazz, genre=jazz and limit=20
48
50
  // (q always; genre because the intent carried one; no mode here
49
- // because "play jazz" carries none; limit added by transform below)
50
- transform(request) {
51
+ // because "play jazz" carries none; limit added by transformSync)
52
+ transformSync(request) {
51
53
  return { ...request, query: { ...request.query, limit: '20' } }
52
54
  }
53
55
  }
54
56
  })
55
57
  ```
56
58
 
57
- With the HTTP form the library appends to `request.query`: `q` (always, even when empty), then `mode`, `reference` (only when it is `'my'` — see below), and the filter fields, each included only when the intent carried it. Query-param order doesn't matter to a server, but that is the order the library writes them in. Note the spoken text is the `query` field in a **callback** (`SearchParams.query`) but is sent as the **`q`** wire param on the **HTTP** form — same value, named `query` in JS and `q` on the URL.
59
+ With the HTTP form the library adds to `request.query`: `q` (always, even when empty), `mode`, `reference` (only when it is `'my'`, see below), and the filter fields, each only when the intent carried it. The callback's `query` is sent as `q`.
58
60
 
59
61
  ## Searching from your own UI
60
62
 
61
- The same source powers your in-app search box. [`search(query)`](/api/features/browser/#search) runs it and resolves to a `Track[]` — it only _returns_ results, it never queues or plays anything. [`hasSearch()`](/api/features/browser/#hassearch) tells you (synchronously) whether a search source is configured at all, so you can hide the search UI when it isn't:
63
+ The same source powers your in-app search box. [`search(query)`](/api/features/browser/#search) runs it and resolves to a `Track[]` — it only _returns_ results, it never queues or plays anything.
64
+
65
+ [`hasSearch()`](/api/features/browser/#hassearch) tells you (synchronously) whether a search source is configured at all, so you can hide the search UI when it isn't. Check it before calling [`search()`](/api/features/browser/#search): with no source configured, Android and web resolve `[]` but iOS rejects. With a source configured, `[]` means it found nothing:
62
66
 
63
67
  ```tsx
64
68
  import { search, hasSearch, navigate } from 'react-native-audio-browser'
@@ -80,11 +84,12 @@ function SearchScreen() {
80
84
  }
81
85
  ```
82
86
 
83
- Three things to know about the in-app call:
87
+ Four things to know about the in-app call:
84
88
 
85
- - **Your resolver sees a plain query.** An in-app `search('jazz')` arrives as `{ query: 'jazz', reference: 'unknown' }` — no `mode`, no filter fields. Those are extracted by the voice assistants; a text box has nothing to extract. (On the HTTP form, only `q` is appended.) A resolver written against _the fields that are present_ handles both callers with the same code.
86
- - **You get the flat list, untouched.** The [browsable-first-result drill-in](#voice-playback-siri-google-assistant) is voice-only — in-app results are handed to you as returned (minus any result lacking both a `path` and a `src`, which is dropped as unrenderable), and the user picks.
89
+ - **Your resolver sees a plain query.** An in-app `search('jazz')` arrives as `{ query: 'jazz', reference: 'unknown' }` — no `mode`, no filter fields. Only the voice assistants extract those. (On the HTTP form, only `q` is appended.) A resolver written against _the fields that are present_ handles both callers.
90
+ - **You get the flat list, untouched.** The [browsable-first-result drill-in](#voice-playback-siri-google-assistant) is voice-only — in-app results are handed to you as returned, and the user picks. A result with neither a `path` nor a `src` can't be rendered, so don't return one.
87
91
  - **Route taps through `navigate(track)`** rather than `setQueue` + `play` — that gives a tapped result the library's load path ([`handleTrackLoad`](#mixed-audio-video), [Gate](/guide/gate) checks, favorite hearts) just like a tap on a browse row.
92
+ - **A failed search rejects; catch it** to tell a failure from no results. On web a failed HTTP search's error carries a `code`: `'http-error'` or `'network-error'`; a callback's rejection reaches you unchanged. On Android an HTTP source never rejects: it resolves `[]` on any failure (status, network, decoding), so there a failure looks like no results. See [`search`](/api/features/browser/#search).
88
93
 
89
94
  ## SearchParams
90
95
 
@@ -137,17 +142,21 @@ Those are **filters**, not result shapes — read them from `params.genre` / `pa
137
142
 
138
143
  The two voice platforms feed the **same** `SearchParams`; they just differ in how many fields they fill:
139
144
 
140
- - **iOS (SiriKit)** supplies the richer set — all the `mode` verticals and the `reference` axis.
141
- - **Android (`onPlayFromSearch`)** supplies the subset it can express: `query`, the music focuses (`song` / `playlist` and the genre/artist/album filters), and always `reference: 'unknown'`.
145
+ - **iOS (SiriKit)** supplies the richer set: every `mode` except `any`, and the `reference` axis.
146
+ - **Android (`onPlayFromSearch`)** supplies the subset it can express: `query`, the modes `any` (for "play music" with no query), `song` and `playlist`, the genre, artist, album, title and playlist filters, and always `reference: 'unknown'`.
142
147
 
143
148
  Write your resolver against the _fields that are present_ (`if (params.genre) …`), not against the platform. A field that's empty on one platform simply means "the assistant didn't provide it."
144
149
 
145
150
  ## Voice playback (Siri & Google Assistant)
146
151
 
147
- A spoken command — "play jazz on «App»" — funnels to the **same `search` source** on both platforms, then the result is queued and played. Any active **[Gate](/guide/gate)** sees the search first, so voice can't slip past a paywall or region block unless your gate lets it through. You configure `search` once; both assistants use it.
152
+ A spoken command — "play jazz on «App»" — funnels to the **same `search` source** on both platforms, then the result is queued and played. Any active **[Gate](/guide/gate)** sees the search first, so voice can't slip past a paywall or region block unless your gate lets it through.
148
153
 
149
154
  ::: tip A browsable first result is drilled into
150
- For voice playback specifically, the library inspects the **first** result. If it is a browsable-only container — a `path` (a place/genre page) with no `src` of its own — the library resolves that page and queues _its_ playable children, so "play jazz" plays the first station _inside_ the jazz page rather than the page itself. If the first result is already playable (has a `src`), or the drill-in finds nothing playable, the flat list of results is queued as-is. This applies on both platforms, and only to voice playback — an in-app search UI renders your results and lets the user pick.
155
+ The library inspects the **first** voice result. If it is browsable-only — a `path` with no `src` — the library resolves that page and queues _its_ playable children. So "play jazz" plays the first station _inside_ the jazz page, not the page itself.
156
+
157
+ Disabled results are skipped, so a disabled first result never counts. If the first result is already playable (has a `src`), or the drill-in finds nothing playable, the playable results (those with a `src` that are not `disabled`) are queued in order.
158
+
159
+ This applies on both platforms, and only to voice playback — an in-app search UI renders your results and lets the user pick.
151
160
  :::
152
161
 
153
162
  For ordinary queries ("play jazz", "play «station name»") the two behave identically — same resolver, same queue, same playback. The entry point and a few conveniences differ:
@@ -162,7 +171,7 @@ For ordinary queries ("play jazz", "play «station name»") the two behave ident
162
171
 
163
172
  The gaps are all iOS-only conveniences — collection-by-voice and resume-by-name. Everything in the shared column is fully cross-platform.
164
173
 
165
- ## Playing the user's own collection
174
+ ## Playing the user's own collection {#playing-the-users-own-collection}
166
175
 
167
176
  When the user says **"play my favorites"**, the intent carries `reference: 'my'`. Resolve it however your collection lives:
168
177
 
@@ -178,14 +187,14 @@ configureBrowser({
178
187
  })
179
188
  ```
180
189
 
181
- **Server collection** — when you use the HTTP form, `reference=my` is appended to `request.query`, so branch in `transform` to route the request — for example, to a favorites endpoint, injecting locally-stored identifiers:
190
+ **Server collection** — when you use the HTTP form, `reference=my` is appended to `request.query`, so branch in `transformSync` to route the request — for example, to a favorites endpoint, injecting locally-stored identifiers:
182
191
 
183
192
  ```ts
184
193
  configureBrowser({
185
194
  search: {
186
195
  baseUrl: 'https://api.example.com/search',
187
- transform(request) {
188
- // `transform` runs for every search — pass normal queries straight
196
+ transformSync(request) {
197
+ // `transformSync` runs for every search — pass normal queries straight
189
198
  // through to /search; only "play my favorites" is rewritten below.
190
199
  if (request.query?.reference !== 'my') return request
191
200
  return {
@@ -207,11 +216,13 @@ configureBrowser({
207
216
 
208
217
  ## Voice phrase → params
209
218
 
210
- These mappings are **illustrative, not guaranteed.** The assistant (Siri / Google Assistant) decides how to parse a spoken phrase, and the same words can arrive structured differently — or as a bare `query` — depending on the platform, locale, and the assistant's own interpretation. Treat the table as _plausible_ shapes to handle, and always write your resolver against the fields actually present (see [Cross-platform differences](#cross-platform-differences)) rather than assuming a phrase produces a specific shape.
219
+ These mappings are **illustrative, not guaranteed.** The assistant (Siri / Google Assistant) decides how to parse a spoken phrase, and the same words can arrive structured differently — or as a bare `query` — depending on the platform, locale, and the assistant's own interpretation.
220
+
221
+ Treat the table as _plausible_ shapes to handle, and always write your resolver against the fields actually present (see [Cross-platform differences](#cross-platform-differences)) rather than assuming a phrase produces a specific shape.
211
222
 
212
223
  | Phrase | Resulting `SearchParams` |
213
224
  | --------------------- | ------------------------------------------------------------- |
214
- | "play something" | `{ query: 'something' }` |
225
+ | "play something" | `{ mode: 'any', query: '' }` |
215
226
  | "play music" | `{ mode: 'any', query: '' }` _(iOS may send `mode: 'music'`)_ |
216
227
  | "play jazz" | `{ genre: 'jazz', query: 'jazz' }` |
217
228
  | "play The Stalk 88.5" | `{ mode: 'station', query: 'The Stalk 88.5' }` |
@@ -223,7 +234,9 @@ These mappings are **illustrative, not guaranteed.** The assistant (Siri / Googl
223
234
 
224
235
  This is an **audio** library — its player streams audio and has no video surface, and CarPlay / Android Auto forbid video playback while driving. So video is fundamentally an **in-app** concern: a search can _signal_ a video request (via the video `mode` values), but the library will not render video.
225
236
 
226
- To play video from your in-app search, intercept the load with [`handleTrackLoad`](/api/types/browser/#handletrackload). It runs whenever a track is loaded through [`navigate(track)`](/api/features/browser/#navigate) (or the library's own browse UI) — so route your in-app search-result taps through `navigate(track)` rather than calling `setQueue` / `play` yourself, or this hook never fires. When set, it is called **instead of** the library auto-playing the track — for **every** such load, not just video — so your handler must either route the track elsewhere or hand it back to the library to play:
237
+ To play video from your in-app search, intercept the load with [`handleTrackLoad`](/api/types/browser/#handletrackload). It runs whenever a track is loaded through [`navigate(track)`](/api/features/browser/#navigate) (or the library's own browse UI) — so route your in-app search-result taps through `navigate(track)` rather than calling `setQueue` / `play` yourself, or this hook never fires.
238
+
239
+ When set, it is called **instead of** the library auto-playing the track — for **every** such load, not just video — so your handler must either route the track elsewhere or hand it back to the library to play:
227
240
 
228
241
  ```ts
229
242
  import {
@@ -250,6 +263,8 @@ configureBrowser({
250
263
  })
251
264
  ```
252
265
 
253
- `setQueue` and `play` are top-level named exports, like `configureBrowser` — not methods on a browser object. `setQueue` only loads the queue; it never changes play/pause state, which is why the audio branch calls `play()` after it.
266
+ The `mode` you saw at **search** time (`music-video` / `movie` / …) is not carried onto the `Track`, and `handleTrackLoad` runs at **load** time with no `mode`.
267
+
268
+ The tracks your `search` source returns for a video request are _yours_, though — so tag them with a recognizable `src` (as above) when you build them, and read that tag in `isVideo` here.
254
269
 
255
- The `mode` you saw at **search** time (`music-video` / `movie` / …) is not carried onto the `Track`, and `handleTrackLoad` runs at **load** time with no `mode`. The tracks your `search` source returns for a video request are _yours_, though — so tag them with a recognizable `src` (as above) when you build them, and read that tag in `isVideo` here. On external surfaces (CarPlay / Android Auto), a video request falls back to audio or is declined — there is no video playback path there.
270
+ On external surfaces (CarPlay / Android Auto), a video request falls back to audio or is declined — there is no video playback path there.