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

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 (239) hide show
  1. package/android/src/cast/java/com/audiobrowser/cast/CastSupport.kt +75 -10
  2. package/android/src/main/java/com/audiobrowser/AudioBrowser.kt +41 -6
  3. package/android/src/main/java/com/audiobrowser/browser/BrowseArtworkRegistry.kt +25 -9
  4. package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt +210 -125
  5. package/android/src/main/java/com/audiobrowser/browser/FavoriteChange.kt +61 -0
  6. package/android/src/main/java/com/audiobrowser/http/HttpClient.kt +2 -59
  7. package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt +3 -3
  8. package/android/src/main/java/com/audiobrowser/model/PlayerUpdateOptions.kt +2 -0
  9. package/android/src/main/java/com/audiobrowser/player/CapabilityControls.kt +2 -0
  10. package/android/src/main/java/com/audiobrowser/player/InterceptingPlayer.kt +14 -1
  11. package/android/src/main/java/com/audiobrowser/player/MediaSessionCallback.kt +201 -107
  12. package/android/src/main/java/com/audiobrowser/player/MediaSessionCommandManager.kt +2 -0
  13. package/android/src/main/java/com/audiobrowser/player/PlaybackStateMachine.kt +55 -26
  14. package/android/src/main/java/com/audiobrowser/player/Player.kt +168 -51
  15. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +19 -8
  16. package/android/src/main/java/com/audiobrowser/player/RetryLoop.kt +1 -1
  17. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +52 -7
  18. package/android/src/main/java/com/audiobrowser/util/ArtworkContentProvider.kt +2 -3
  19. package/android/src/main/java/com/audiobrowser/util/ArtworkRoutes.kt +5 -5
  20. package/android/src/main/java/com/audiobrowser/util/ArtworkUris.kt +5 -0
  21. package/android/src/main/java/com/audiobrowser/util/AwaitCancellable.kt +35 -11
  22. package/android/src/main/java/com/audiobrowser/util/BrowserPathHelper.kt +11 -0
  23. package/android/src/main/java/com/audiobrowser/util/TrackFactory.kt +10 -7
  24. package/android/src/main/res/values/strings.xml +5 -2
  25. package/android/src/test/java/androidx/media3/session/SessionViews.kt +15 -0
  26. package/android/src/test/java/com/audiobrowser/ConfigurationStartTest.kt +72 -0
  27. package/android/src/test/java/com/audiobrowser/ContentRefreshNavigationErrorTest.kt +1 -0
  28. package/android/src/test/java/com/audiobrowser/NavigateTrackTest.kt +1 -0
  29. package/android/src/test/java/com/audiobrowser/ResolveFormattedErrorTest.kt +1 -0
  30. package/android/src/test/java/com/audiobrowser/TestFixtures.kt +9 -6
  31. package/android/src/test/java/com/audiobrowser/browser/BrowseArtworkRegistryTest.kt +19 -0
  32. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerFavoritesTest.kt +58 -0
  33. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerInvalidationTest.kt +15 -0
  34. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerSearchFailureTest.kt +168 -0
  35. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerTest.kt +32 -0
  36. package/android/src/test/java/com/audiobrowser/browser/FavoriteChangeTest.kt +106 -0
  37. package/android/src/test/java/com/audiobrowser/http/RequestConfigBuilderTest.kt +43 -18
  38. package/android/src/test/java/com/audiobrowser/player/CapabilityControlsTest.kt +1 -0
  39. package/android/src/test/java/com/audiobrowser/player/FavoriteCapabilityTest.kt +8 -19
  40. package/android/src/test/java/com/audiobrowser/player/FavoriteRestampTest.kt +117 -0
  41. package/android/src/test/java/com/audiobrowser/player/HandleTrackLoadSeekTest.kt +1 -0
  42. package/android/src/test/java/com/audiobrowser/player/LiveSeekCommandTest.kt +1 -0
  43. package/android/src/test/java/com/audiobrowser/player/PlaybackStateMachineTest.kt +58 -1
  44. package/android/src/test/java/com/audiobrowser/player/PlayerCastTest.kt +40 -1
  45. package/android/src/test/java/com/audiobrowser/player/PlayerRetryTest.kt +115 -2
  46. package/android/src/test/java/com/audiobrowser/player/QueueEventOnSessionPlayersTest.kt +40 -0
  47. package/android/src/test/java/com/audiobrowser/player/QueueEventTest.kt +153 -0
  48. package/android/src/test/java/com/audiobrowser/player/QueueItemPickTest.kt +130 -0
  49. package/android/src/test/java/com/audiobrowser/player/SessionBrowserNeverConfiguredTest.kt +98 -0
  50. package/android/src/test/java/com/audiobrowser/player/SessionUncachedIdTest.kt +396 -0
  51. package/android/src/test/java/com/audiobrowser/player/SessionViewTest.kt +6 -2
  52. package/android/src/test/java/com/audiobrowser/player/SessionVoiceSearchTest.kt +116 -14
  53. package/android/src/test/java/com/audiobrowser/player/StandardSkipTest.kt +26 -0
  54. package/android/src/test/java/com/audiobrowser/player/TabsChangedTest.kt +81 -0
  55. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +12 -1
  56. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +241 -0
  57. package/android/src/test/java/com/audiobrowser/util/ArtworkContentProviderTest.kt +11 -0
  58. package/android/src/test/java/com/audiobrowser/util/ArtworkRoutesTest.kt +25 -0
  59. package/android/src/test/java/com/audiobrowser/util/AwaitCancellableTest.kt +43 -2
  60. package/android/src/test/java/com/audiobrowser/util/CoilArtworkLoaderTest.kt +38 -0
  61. package/android/src/test/java/com/audiobrowser/util/TrackFactoryRatingTest.kt +11 -0
  62. package/android/src/testCast/java/com/audiobrowser/cast/SdkCastRemoteTest.kt +187 -2
  63. package/ios/AVPlayerEngine.swift +2 -2
  64. package/ios/Browser/BrowserPathHelper.swift +11 -9
  65. package/ios/Browser/PageResolver.swift +1 -1
  66. package/ios/CarPlay/CarPlayListItemFactory.swift +2 -2
  67. package/ios/CarPlay/CarPlayNowPlayingManager.swift +64 -31
  68. package/ios/CarPlay/NowPlayingButtonRules.swift +26 -0
  69. package/ios/CarPlay/SectionPresentation.swift +7 -0
  70. package/ios/Extension/Promise+AwaitCallback.swift +13 -4
  71. package/ios/HybridAudioBrowser+Player.swift +3 -2
  72. package/ios/HybridAudioBrowser.swift +1 -1
  73. package/ios/Model/NitroTypeStubs.swift +15 -0
  74. package/ios/Model/PlayerUpdateOptions.swift +2 -1
  75. package/ios/PlaybackEvent.swift +20 -0
  76. package/ios/Player/Player.swift +17 -3
  77. package/ios/Player/QueueManager.swift +23 -41
  78. package/ios/Tests/AwaitCallbackTests.swift +8 -0
  79. package/ios/Tests/BrowserPathHelperTests.swift +18 -0
  80. package/ios/Tests/CapabilityRemoteCommandTests.swift +4 -0
  81. package/ios/Tests/DataURLDecodingTests.swift +25 -0
  82. package/ios/Tests/GenerationMemoTests.swift +136 -0
  83. package/ios/Tests/JSCallbackErrorTests.swift +33 -0
  84. package/ios/Tests/NowPlayingButtonRulesTests.swift +35 -0
  85. package/ios/Tests/PlaybackStateMachineTests.swift +15 -0
  86. package/ios/Tests/PlayerPolicyTests.swift +51 -28
  87. package/ios/Tests/PlayerProgressTests.swift +0 -2
  88. package/ios/Tests/PlayerTests.swift +54 -0
  89. package/ios/Tests/QueueManagerTests.swift +111 -78
  90. package/ios/Tests/RequestLayerTests.swift +11 -0
  91. package/ios/Tests/RoutePickerSourceFrameTests.swift +30 -0
  92. package/ios/Tests/RoutePickerSourceLifetimeTests.swift +79 -0
  93. package/ios/Tests/SectionPresentationTests.swift +13 -0
  94. package/ios/Tests/Support/TestTypes.swift +23 -1
  95. package/ios/Util/ArtworkImageFetcher.swift +40 -16
  96. package/ios/Util/AwaitCallback.swift +16 -10
  97. package/ios/Util/GenerationMemo.swift +81 -17
  98. package/ios/Util/JSCallbackError.swift +23 -0
  99. package/ios/Util/OutputPicker.swift +25 -5
  100. package/ios/Util/RoutePickerSourceFrame.swift +17 -0
  101. package/ios/Util/RoutePickerSourceLifetime.swift +34 -0
  102. package/lib/commonjs/features/browser-config.js +3 -2
  103. package/lib/commonjs/features/browser-config.js.map +1 -1
  104. package/lib/commonjs/features/browser.js +7 -8
  105. package/lib/commonjs/features/browser.js.map +1 -1
  106. package/lib/commonjs/features/output.js +7 -3
  107. package/lib/commonjs/features/output.js.map +1 -1
  108. package/lib/commonjs/features/player/options.js.map +1 -1
  109. package/lib/commonjs/web/NativeAudioBrowser.js +43 -2
  110. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  111. package/lib/commonjs/web/browser/BrowserManager.js +37 -65
  112. package/lib/commonjs/web/browser/BrowserManager.js.map +1 -1
  113. package/lib/commonjs/web/browser/SearchManager.js +1 -4
  114. package/lib/commonjs/web/browser/SearchManager.js.map +1 -1
  115. package/lib/commonjs/web/http/RequestConfigBuilder.js +53 -55
  116. package/lib/commonjs/web/http/RequestConfigBuilder.js.map +1 -1
  117. package/lib/commonjs/web/player/NowPlayingManager.js +3 -22
  118. package/lib/commonjs/web/player/NowPlayingManager.js.map +1 -1
  119. package/lib/commonjs/web/util/BrowserPathHelper.js +5 -7
  120. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  121. package/lib/commonjs/web/util/GenerationMemo.js +92 -0
  122. package/lib/commonjs/web/util/GenerationMemo.js.map +1 -0
  123. package/lib/module/features/browser-config.js +3 -2
  124. package/lib/module/features/browser-config.js.map +1 -1
  125. package/lib/module/features/browser.js +7 -8
  126. package/lib/module/features/browser.js.map +1 -1
  127. package/lib/module/features/output.js +7 -3
  128. package/lib/module/features/output.js.map +1 -1
  129. package/lib/module/features/player/options.js.map +1 -1
  130. package/lib/module/web/NativeAudioBrowser.js +43 -2
  131. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  132. package/lib/module/web/browser/BrowserManager.js +37 -66
  133. package/lib/module/web/browser/BrowserManager.js.map +1 -1
  134. package/lib/module/web/browser/SearchManager.js +1 -5
  135. package/lib/module/web/browser/SearchManager.js.map +1 -1
  136. package/lib/module/web/http/RequestConfigBuilder.js +53 -55
  137. package/lib/module/web/http/RequestConfigBuilder.js.map +1 -1
  138. package/lib/module/web/player/NowPlayingManager.js +3 -22
  139. package/lib/module/web/player/NowPlayingManager.js.map +1 -1
  140. package/lib/module/web/util/BrowserPathHelper.js +5 -7
  141. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  142. package/lib/module/web/util/GenerationMemo.js +87 -0
  143. package/lib/module/web/util/GenerationMemo.js.map +1 -0
  144. package/lib/typescript/src/features/browser-config.d.ts.map +1 -1
  145. package/lib/typescript/src/features/browser.d.ts +7 -8
  146. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  147. package/lib/typescript/src/features/output.d.ts +8 -4
  148. package/lib/typescript/src/features/output.d.ts.map +1 -1
  149. package/lib/typescript/src/features/player/options.d.ts +19 -1
  150. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  151. package/lib/typescript/src/specs/audio-browser.nitro.d.ts +11 -0
  152. package/lib/typescript/src/specs/audio-browser.nitro.d.ts.map +1 -1
  153. package/lib/typescript/src/types/browser-native.d.ts +2 -1
  154. package/lib/typescript/src/types/browser-native.d.ts.map +1 -1
  155. package/lib/typescript/src/types/browser.d.ts +55 -8
  156. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  157. package/nitrogen/generated/android/AudioBrowserOnLoad.cpp +2 -0
  158. package/nitrogen/generated/android/c++/JArtworkRequestConfig.hpp +3 -0
  159. package/nitrogen/generated/android/c++/JFindTrackParams.hpp +57 -0
  160. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_RequestConfig___MediaTransformParams.hpp +13 -1
  161. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_RequestConfig___RequestConfig_std__optional_std__unordered_map_std__string__std__string__.hpp +13 -1
  162. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_RequestConfig___Track.hpp +13 -1
  163. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__optional_FormattedNavigationError____FormatNavigationErrorParams.hpp +13 -1
  164. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__optional_NowPlayingUpdate____FormatNowPlayingParams.hpp +13 -1
  165. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__optional_std__string____Track.hpp +13 -1
  166. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_GateDecision_____NativeGateRequest.hpp +23 -2
  167. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_RequestConfig_____MediaTransformParams.hpp +23 -2
  168. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_RequestConfig_____RequestConfig_std__optional_std__unordered_map_std__string__std__string__.hpp +23 -2
  169. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_RequestConfig_____Track.hpp +23 -2
  170. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_TransformableRequestConfig____.hpp +23 -2
  171. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_std__optional_Track______FindTrackParams.hpp +171 -0
  172. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_std__vector_Track______SearchParams.hpp +23 -2
  173. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_void_____TrackLoadEvent.hpp +23 -2
  174. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__string__.hpp +13 -1
  175. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__variant_ResolvedTrack__BrowseError__std__shared_ptr_Promise_std__variant_ResolvedTrack__BrowseError_______BrowserSourceCallbackParam.hpp +13 -1
  176. package/nitrogen/generated/android/c++/JHybridAudioBrowserSpec.cpp +15 -3
  177. package/nitrogen/generated/android/c++/JHybridAudioBrowserSpec.hpp +1 -1
  178. package/nitrogen/generated/android/c++/JMediaRequestConfig.hpp +3 -0
  179. package/nitrogen/generated/android/c++/JNativeBrowserConfiguration.hpp +20 -2
  180. package/nitrogen/generated/android/c++/JNativeRouteEntry.hpp +3 -0
  181. package/nitrogen/generated/android/c++/JNativeSetupPlayerOptions.hpp +3 -0
  182. package/nitrogen/generated/android/c++/JOutputPickerAnchor.hpp +69 -0
  183. package/nitrogen/generated/android/c++/JPlayerCapabilities.hpp +5 -1
  184. package/nitrogen/generated/android/c++/JTransformableRequestConfig.hpp +3 -0
  185. package/nitrogen/generated/android/c++/JVariant_ResolvedTrack_BrowseError_Promise_BrowseResult_.hpp +13 -1
  186. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/FindTrackParams.kt +51 -0
  187. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/Func_std__shared_ptr_Promise_std__shared_ptr_Promise_std__optional_Track______FindTrackParams.kt +78 -0
  188. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/HybridAudioBrowserSpec.kt +1 -1
  189. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/NativeBrowserConfiguration.kt +11 -6
  190. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/OutputPickerAnchor.kt +66 -0
  191. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/PlayerCapabilities.kt +7 -2
  192. package/nitrogen/generated/ios/AudioBrowser-Swift-Cxx-Bridge.cpp +35 -1
  193. package/nitrogen/generated/ios/AudioBrowser-Swift-Cxx-Bridge.hpp +144 -15
  194. package/nitrogen/generated/ios/AudioBrowser-Swift-Cxx-Umbrella.hpp +8 -0
  195. package/nitrogen/generated/ios/c++/HybridAudioBrowserSpecSwift.hpp +8 -2
  196. package/nitrogen/generated/ios/swift/FindTrackParams.swift +29 -0
  197. package/nitrogen/generated/ios/swift/Func_std__shared_ptr_Promise_std__shared_ptr_Promise_std__optional_Track______FindTrackParams.swift +67 -0
  198. package/nitrogen/generated/ios/swift/Func_void_std__optional_Track_.swift +46 -0
  199. package/nitrogen/generated/ios/swift/Func_void_std__shared_ptr_Promise_std__optional_Track___.swift +66 -0
  200. package/nitrogen/generated/ios/swift/HybridAudioBrowserSpec.swift +1 -1
  201. package/nitrogen/generated/ios/swift/HybridAudioBrowserSpec_cxx.swift +2 -2
  202. package/nitrogen/generated/ios/swift/NativeBrowserConfiguration.swift +48 -1
  203. package/nitrogen/generated/ios/swift/OutputPickerAnchor.swift +44 -0
  204. package/nitrogen/generated/ios/swift/PlayerCapabilities.swift +19 -1
  205. package/nitrogen/generated/shared/c++/FindTrackParams.hpp +83 -0
  206. package/nitrogen/generated/shared/c++/HybridAudioBrowserSpec.hpp +4 -1
  207. package/nitrogen/generated/shared/c++/NativeBrowserConfiguration.hpp +10 -3
  208. package/nitrogen/generated/shared/c++/OutputPickerAnchor.hpp +95 -0
  209. package/nitrogen/generated/shared/c++/PlayerCapabilities.hpp +5 -1
  210. package/package.json +1 -1
  211. package/src/codegen-js-error-message.test.ts +78 -0
  212. package/src/features/browser-config.test.ts +7 -0
  213. package/src/features/browser-config.ts +3 -2
  214. package/src/features/browser.ts +7 -8
  215. package/src/features/output.ts +13 -5
  216. package/src/features/player/options.ts +19 -1
  217. package/src/specs/audio-browser.nitro.ts +16 -3
  218. package/src/types/browser-native.ts +4 -1
  219. package/src/types/browser.ts +60 -8
  220. package/src/web/NativeAudioBrowser.ts +43 -3
  221. package/src/web/__tests__/nowPlayingArtwork.test.ts +191 -0
  222. package/src/web/browser/BrowserManager.ts +50 -79
  223. package/src/web/browser/SearchManager.ts +1 -8
  224. package/src/web/browser/__tests__/artwork-resolution.test.ts +33 -0
  225. package/src/web/browser/__tests__/layer-resolver.test.ts +47 -1
  226. package/src/web/http/RequestConfigBuilder.test.ts +151 -1
  227. package/src/web/http/RequestConfigBuilder.ts +72 -57
  228. package/src/web/player/NowPlayingManager.test.ts +29 -0
  229. package/src/web/player/NowPlayingManager.ts +4 -27
  230. package/src/web/util/BrowserPathHelper.test.ts +23 -0
  231. package/src/web/util/BrowserPathHelper.ts +6 -7
  232. package/src/web/util/GenerationMemo.test.ts +148 -0
  233. package/src/web/util/GenerationMemo.ts +103 -0
  234. package/website/guide/audio-output.md +34 -7
  235. package/website/guide/browser.md +21 -0
  236. package/website/guide/carplay.md +1 -1
  237. package/website/guide/configuration.md +10 -9
  238. package/website/guide/gate.md +1 -1
  239. package/website/guide/remote-controls.md +35 -0
@@ -0,0 +1,103 @@
1
+ /** How long a caller joins a running computation before starting another. */
2
+ const SHARE_RUN_MS = 10_000
3
+
4
+ type Run<T> = {
5
+ generation: number
6
+ started: number
7
+ settled: Promise<T>
8
+ resolve: (value: T) => void
9
+ reject: (error: unknown) => void
10
+ }
11
+
12
+ /**
13
+ * A value kept per generation and shared by its callers; the iOS
14
+ * `GenerationMemo` holds the same contract.
15
+ *
16
+ * `invalidate()` starts a new generation. A caller whose computation settles
17
+ * after an invalidation computes again, so `value` never returns a stale
18
+ * result; `compute` must read the state it depends on when it runs. A failure
19
+ * is not kept: the next caller tries again.
20
+ *
21
+ * A caller joins the newest run of its generation only while that run is
22
+ * younger than `shareForMs`; past that it starts another, so one silent
23
+ * computation does not hold every later caller. The current generation's first
24
+ * value releases the callers of every run, earlier generations' included; a
25
+ * run's failure releases only its own.
26
+ */
27
+ export class GenerationMemo<T> {
28
+ private generation = 0
29
+ private kept?: { value: T }
30
+ /** Runs of every generation still computing and not yet released, oldest first. */
31
+ private running: Run<T>[] = []
32
+
33
+ constructor(
34
+ private readonly shareForMs = SHARE_RUN_MS,
35
+ private readonly now: () => number = () => performance.now()
36
+ ) {}
37
+
38
+ invalidate(): void {
39
+ this.generation += 1
40
+ this.kept = undefined
41
+ }
42
+
43
+ async value(compute: () => Promise<T>): Promise<T> {
44
+ for (;;) {
45
+ if (this.kept) return this.kept.value
46
+ const generation = this.generation
47
+ const newest = this.running
48
+ .filter((run) => run.generation === generation)
49
+ .pop()
50
+ const run =
51
+ newest && this.now() - newest.started < this.shareForMs
52
+ ? newest
53
+ : this.start(compute)
54
+ try {
55
+ const value = await run.settled
56
+ if (generation === this.generation) return value
57
+ } catch (error) {
58
+ if (generation === this.generation) throw error
59
+ }
60
+ }
61
+ }
62
+
63
+ private start(compute: () => Promise<T>): Run<T> {
64
+ let resolve!: (value: T) => void
65
+ let reject!: (error: unknown) => void
66
+ const settled = new Promise<T>((res, rej) => {
67
+ resolve = res
68
+ reject = rej
69
+ })
70
+ const run: Run<T> = {
71
+ generation: this.generation,
72
+ started: this.now(),
73
+ settled,
74
+ resolve,
75
+ reject
76
+ }
77
+ this.running.push(run)
78
+ Promise.resolve()
79
+ .then(compute)
80
+ .then(
81
+ (value) => this.finish(run, { ok: true, value }),
82
+ (error: unknown) => this.finish(run, { ok: false, error })
83
+ )
84
+ return run
85
+ }
86
+
87
+ private finish(
88
+ run: Run<T>,
89
+ result: { ok: true; value: T } | { ok: false; error: unknown }
90
+ ): void {
91
+ if (run.generation !== this.generation || this.kept || !result.ok) {
92
+ this.running = this.running.filter((other) => other !== run)
93
+ if (result.ok) run.resolve(result.value)
94
+ else run.reject(result.error)
95
+ return
96
+ }
97
+ const { value } = result
98
+ this.kept = { value }
99
+ const released = this.running
100
+ this.running = []
101
+ for (const other of released) other.resolve(value)
102
+ }
103
+ }
@@ -345,6 +345,33 @@ function OutputButton() {
345
345
  switcher exists — but gating the button on `supportsOutputSwitcher()` keeps you
346
346
  from showing a control that would do nothing.
347
347
 
348
+ On iOS the picker opens from a source view at the window's top-left corner,
349
+ unless you pass an anchor: the frame of your button, in points in the key
350
+ window's coordinates. A picker shown as a menu then appears at your button; a
351
+ full-screen sheet does not move. React Native's `measureInWindow` gives the
352
+ frame:
353
+
354
+ ```tsx
355
+ import { useRef } from 'react'
356
+ import { Button, View } from 'react-native'
357
+ import { openOutputPicker } from 'react-native-audio-browser'
358
+
359
+ function AnchoredOutputButton() {
360
+ const ref = useRef<View>(null)
361
+ const open = () =>
362
+ ref.current?.measureInWindow((x, y, width, height) =>
363
+ openOutputPicker({ x, y, width, height })
364
+ )
365
+ return (
366
+ <View ref={ref}>
367
+ <Button title="Output" onPress={open} />
368
+ </View>
369
+ )
370
+ }
371
+ ```
372
+
373
+ Android ignores the anchor: its switcher is a dialog with no position.
374
+
348
375
  On Android the switcher is the system one (the picker from the media
349
376
  notification); selecting a Bluetooth speaker there routes audio at the OS level.
350
377
  The library can't force playback to a _specific_ Bluetooth device itself — route
@@ -369,13 +396,13 @@ turns the pause off. On iOS it always happens.
369
396
 
370
397
  ## API summary
371
398
 
372
- | API | Platforms | Purpose |
373
- | -------------------------- | ---------------- | -------------------------------------------------------------------------- |
374
- | `openOutputPicker()` | iOS, Android 11+ | Present the system output switcher (Bluetooth / AirPlay / speaker / Cast). |
375
- | `supportsOutputSwitcher()` | all | Whether a switcher can be shown — gate your output button on it. |
376
- | `useOutput()` | iOS, Android | Reactive current output (`Output \| undefined`). |
377
- | `getOutput()` | iOS, Android | One-off snapshot of the current output. |
378
- | `onOutputChanged` | iOS, Android | Subscribe outside React; `addListener(cb)` returns an unsubscribe fn. |
399
+ | API | Platforms | Purpose |
400
+ | --------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |
401
+ | `openOutputPicker(anchor?)` | iOS, Android 11+ | Present the system output switcher (Bluetooth / AirPlay / speaker / Cast); iOS opens it from `anchor`. |
402
+ | `supportsOutputSwitcher()` | all | Whether a switcher can be shown — gate your output button on it. |
403
+ | `useOutput()` | iOS, Android | Reactive current output (`Output \| undefined`). |
404
+ | `getOutput()` | iOS, Android | One-off snapshot of the current output. |
405
+ | `onOutputChanged` | iOS, Android | Subscribe outside React; `addListener(cb)` returns an unsubscribe fn. |
379
406
 
380
407
  The whole API is cross-platform; only the switcher needs Android 11+ (gate on
381
408
  `supportsOutputSwitcher()`). Below Android 13, the output can miss a reroute
@@ -464,6 +464,27 @@ In the video branch, returning without calling the player tells the library the
464
464
 
465
465
  Native **awaits the promise your handler returns**. Anything you `await` inside, such as an auth check or a fetch, delays the tap being treated as handled. Keep slow work out of the handler, or start it without awaiting it.
466
466
 
467
+ ### Playing an id that was never browsed
468
+
469
+ Android only. A car can ask to play a row's `id` in a process that never showed that row: it resumes the last track after the app was closed, or acts on a voice pick. The library knows which track an `id` names only from browsing, so give it **`findTrack`** to answer the rest:
470
+
471
+ ```ts
472
+ configureBrowser({
473
+ findTrack: async ({ id }) => {
474
+ const item = await api.item(id)
475
+ return item && { id, title: item.name, src: item.audioUrl }
476
+ }
477
+ })
478
+ ```
479
+
480
+ It is called for an `id` that is neither browsed in this process, a path, nor an http(s) URL, both for a play and for an item lookup. Return a Track with a `src`, or `undefined` for an `id` you don't know. The answer plays and is reported under the `id` the car sent, and it is remembered, so the same `id` is not asked again. An answer without `src`, a throw, or no answer within 10 seconds fails the play, and the car is told it failed. Once `findTrack` is set, such an `id` is never browsed as a path.
481
+
482
+ If your app sets a queue, loads, skips or clears while `findTrack` is answering, the app's choice wins and the car's play is dropped. So don't restore a last queue at startup in a process a car may have started.
483
+
484
+ The [Gate](/guide/gate) doesn't apply to these plays: they are hearing, not finding, so the resolver isn't asked and `onGate` doesn't fire. To refuse one, return `undefined` from `findTrack`; the play fails as for an unknown `id`.
485
+
486
+ A car can start your app's process with no activity in the foreground. React Native pauses JavaScript timers there, so anything in `findTrack` that waits on a timer does not run until an activity opens.
487
+
467
488
  ## Reading and driving browse state
468
489
 
469
490
  The Browser exposes its current state through getters, React hooks, and event emitters — so your in-app UI can mirror exactly what the car shows.
@@ -617,7 +617,7 @@ You can also change them later with `updateOptions({ ios: { carPlayNowPlayingBut
617
617
  - **More than five entries log a warning.** Five is CarPlay's limit for the row; the count includes repeats.
618
618
  - **A [gate](/guide/gate) hides them.** While a gate is active the row is empty. The transport controls stay.
619
619
 
620
- The **Up Next** button is separate. It opens the queue and shows only when the queue has more than one track. Set `ios.carPlayUpNextButton: false` to never show it.
620
+ The **Up Next** button is separate. It opens the tracks that follow the current one, in the order `skipToNext` plays them: shuffled when shuffle is on, wrapping past the end on repeat-queue, never the current track. It shows only when a track follows the current one. Set `ios.carPlayUpNextButton: false` to never show it. It also needs the [`skipToQueueItem`](/guide/remote-controls#picking-a-queue-item) capability, which is on by default.
621
621
 
622
622
  ## Playing Indicator
623
623
 
@@ -117,15 +117,16 @@ updateOptions({
117
117
  })
118
118
  ```
119
119
 
120
- | Capability | Default | Notes |
121
- | ------------------------------- | ------- | ---------------------------------------------- |
122
- | `play` / `pause` / `stop` | `true` | Core transport. |
123
- | `seekTo` | `true` | Scrub the timeline. |
124
- | `skipToNext` / `skipToPrevious` | `true` | Move between queue items. |
125
- | `jumpForward` / `jumpBackward` | `false` | Podcast/audiobook seek by interval. |
126
- | `playbackRate` | `true` | Speed control (Control Center / CarPlay). |
127
- | `shuffleMode` / `repeatMode` | `true` | Shuffle / repeat toggles. |
128
- | `favorite` | `false` | The heart — see [Favorites](/guide/favorites). |
120
+ | Capability | Default | Notes |
121
+ | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
122
+ | `play` / `pause` / `stop` | `true` | Core transport. |
123
+ | `seekTo` | `true` | Scrub the timeline. |
124
+ | `skipToNext` / `skipToPrevious` | `true` | Move between queue items. |
125
+ | `skipToQueueItem` | `true` | Pick any queue item from an external surface — see [Picking a queue item](/guide/remote-controls#picking-a-queue-item). |
126
+ | `jumpForward` / `jumpBackward` | `false` | Podcast/audiobook seek by interval. |
127
+ | `playbackRate` | `true` | Speed control (Control Center / CarPlay). |
128
+ | `shuffleMode` / `repeatMode` | `true` | Shuffle / repeat toggles. |
129
+ | `favorite` | `false` | The heart — see [Favorites](/guide/favorites). |
129
130
 
130
131
  ## Controls & progress
131
132
 
@@ -8,7 +8,7 @@ A **Gate** replaces the browse content on **CarPlay**, **Android Auto** and **An
8
8
 
9
9
  Use it when part of your catalog is premium, login-only or region-locked, and you want to block it in the car without building a separate UI there.
10
10
 
11
- One rule worth keeping in mind: **a Gate blocks _finding_, never _hearing_.** Whatever is already playing keeps going, a voice "resume" is never gated, and the queue is left alone.
11
+ One rule worth keeping in mind: **a Gate blocks _finding_, never _hearing_.** Whatever is already playing keeps going, a voice "resume" is never gated, and the queue is left alone. On Android, a car's play of an `id` through [`findTrack`](/guide/browser#playing-an-id-that-was-never-browsed) isn't gated either.
12
12
 
13
13
  A voice request to play something new is a search. The Gate refuses it unless your resolver lets search through (see [Gating some requests, not others](#gating-some-requests-not-others)).
14
14
 
@@ -223,6 +223,41 @@ on the platform:
223
223
  and call `seekBy(±interval)`.
224
224
  - **Web** seeks by the offset the browser sends, or 10s when it sends none.
225
225
 
226
+ ### Picking a queue item
227
+
228
+ Next and previous are not the only way an external surface changes the track.
229
+ A surface that draws the queue lets the listener pick any item in it: the
230
+ Android Auto queue list, a watch or a Bluetooth now-playing list on Android,
231
+ and the CarPlay Up Next list on iOS. A pick has no `handleRemote*` override. It
232
+ is governed by the `skipToQueueItem` capability, which is on by default:
233
+
234
+ ```ts
235
+ updateOptions({
236
+ capabilities: {
237
+ skipToNext: false,
238
+ skipToPrevious: false,
239
+ skipToQueueItem: false
240
+ }
241
+ })
242
+ ```
243
+
244
+ With `skipToQueueItem: false`:
245
+
246
+ - **Android** stops offering the command to controllers, and drops a pick that
247
+ a controller sends anyway. A controller may still show the queue; a pick in
248
+ it does nothing. A seek within the current track is not affected.
249
+ - **iOS** turns the CarPlay Up Next button off, whatever
250
+ `ios.carPlayUpNextButton` says. Rows of an Up Next list that is already open
251
+ do nothing.
252
+ - **Web** has no such surface, so the capability is ignored.
253
+
254
+ Your own calls are never restricted: [`skip`](/api/features/queue/#skip) and
255
+ [`setQueue`](/api/features/queue/#setqueue) work whatever the capability says.
256
+
257
+ The capability covers the pick of a queue item, not queue edits: on Android a
258
+ controller that replaces or reorders the queue's items can still change what
259
+ plays.
260
+
226
261
  ## Listening to presses
227
262
 
228
263
  [`onRemote*`](/api/features/remoteControls/#onremotenext) subscribes to a press