react-native-audio-browser 1.0.0-next.5 → 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 (192) 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 +14 -2
  3. package/android/src/main/java/com/audiobrowser/browser/BrowseArtworkRegistry.kt +25 -9
  4. package/android/src/main/java/com/audiobrowser/browser/BrowserManager.kt +183 -122
  5. package/android/src/main/java/com/audiobrowser/http/HttpClient.kt +2 -59
  6. package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt +3 -3
  7. package/android/src/main/java/com/audiobrowser/player/MediaSessionCallback.kt +201 -107
  8. package/android/src/main/java/com/audiobrowser/player/Player.kt +117 -20
  9. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +14 -1
  10. package/android/src/main/java/com/audiobrowser/player/RetryLoop.kt +1 -1
  11. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +52 -7
  12. package/android/src/main/java/com/audiobrowser/util/ArtworkContentProvider.kt +2 -3
  13. package/android/src/main/java/com/audiobrowser/util/ArtworkRoutes.kt +5 -5
  14. package/android/src/main/java/com/audiobrowser/util/ArtworkUris.kt +5 -0
  15. package/android/src/main/java/com/audiobrowser/util/AwaitCancellable.kt +35 -11
  16. package/android/src/main/java/com/audiobrowser/util/BrowserPathHelper.kt +11 -0
  17. package/android/src/main/java/com/audiobrowser/util/TrackFactory.kt +10 -7
  18. package/android/src/main/res/values/strings.xml +5 -2
  19. package/android/src/test/java/androidx/media3/session/SessionViews.kt +15 -0
  20. package/android/src/test/java/com/audiobrowser/ContentRefreshNavigationErrorTest.kt +1 -0
  21. package/android/src/test/java/com/audiobrowser/NavigateTrackTest.kt +1 -0
  22. package/android/src/test/java/com/audiobrowser/ResolveFormattedErrorTest.kt +1 -0
  23. package/android/src/test/java/com/audiobrowser/TestFixtures.kt +9 -6
  24. package/android/src/test/java/com/audiobrowser/browser/BrowseArtworkRegistryTest.kt +19 -0
  25. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerSearchFailureTest.kt +168 -0
  26. package/android/src/test/java/com/audiobrowser/browser/BrowserManagerTest.kt +32 -0
  27. package/android/src/test/java/com/audiobrowser/http/RequestConfigBuilderTest.kt +43 -18
  28. package/android/src/test/java/com/audiobrowser/player/HandleTrackLoadSeekTest.kt +1 -0
  29. package/android/src/test/java/com/audiobrowser/player/PlayerCastTest.kt +40 -1
  30. package/android/src/test/java/com/audiobrowser/player/PlayerRetryTest.kt +115 -2
  31. package/android/src/test/java/com/audiobrowser/player/SessionBrowserNeverConfiguredTest.kt +98 -0
  32. package/android/src/test/java/com/audiobrowser/player/SessionUncachedIdTest.kt +396 -0
  33. package/android/src/test/java/com/audiobrowser/player/SessionViewTest.kt +6 -2
  34. package/android/src/test/java/com/audiobrowser/player/SessionVoiceSearchTest.kt +116 -14
  35. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +12 -1
  36. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +241 -0
  37. package/android/src/test/java/com/audiobrowser/util/ArtworkContentProviderTest.kt +11 -0
  38. package/android/src/test/java/com/audiobrowser/util/ArtworkRoutesTest.kt +25 -0
  39. package/android/src/test/java/com/audiobrowser/util/AwaitCancellableTest.kt +43 -2
  40. package/android/src/test/java/com/audiobrowser/util/CoilArtworkLoaderTest.kt +38 -0
  41. package/android/src/test/java/com/audiobrowser/util/TrackFactoryRatingTest.kt +11 -0
  42. package/android/src/testCast/java/com/audiobrowser/cast/SdkCastRemoteTest.kt +187 -2
  43. package/ios/AVPlayerEngine.swift +2 -2
  44. package/ios/Browser/BrowserPathHelper.swift +3 -2
  45. package/ios/Browser/PageResolver.swift +1 -1
  46. package/ios/Extension/Promise+AwaitCallback.swift +13 -4
  47. package/ios/HybridAudioBrowser+Player.swift +3 -2
  48. package/ios/HybridAudioBrowser.swift +1 -1
  49. package/ios/Player/Player.swift +4 -2
  50. package/ios/Tests/AwaitCallbackTests.swift +8 -0
  51. package/ios/Tests/DataURLDecodingTests.swift +25 -0
  52. package/ios/Tests/GenerationMemoTests.swift +136 -0
  53. package/ios/Tests/JSCallbackErrorTests.swift +33 -0
  54. package/ios/Tests/PlayerPolicyTests.swift +19 -28
  55. package/ios/Tests/PlayerProgressTests.swift +0 -2
  56. package/ios/Tests/RequestLayerTests.swift +5 -0
  57. package/ios/Tests/RoutePickerSourceFrameTests.swift +30 -0
  58. package/ios/Tests/RoutePickerSourceLifetimeTests.swift +79 -0
  59. package/ios/Tests/Support/TestTypes.swift +14 -0
  60. package/ios/Util/ArtworkImageFetcher.swift +40 -16
  61. package/ios/Util/AwaitCallback.swift +16 -10
  62. package/ios/Util/GenerationMemo.swift +81 -17
  63. package/ios/Util/JSCallbackError.swift +23 -0
  64. package/ios/Util/OutputPicker.swift +25 -5
  65. package/ios/Util/RoutePickerSourceFrame.swift +17 -0
  66. package/ios/Util/RoutePickerSourceLifetime.swift +34 -0
  67. package/lib/commonjs/features/browser-config.js +3 -2
  68. package/lib/commonjs/features/browser-config.js.map +1 -1
  69. package/lib/commonjs/features/browser.js +7 -8
  70. package/lib/commonjs/features/browser.js.map +1 -1
  71. package/lib/commonjs/features/output.js +7 -3
  72. package/lib/commonjs/features/output.js.map +1 -1
  73. package/lib/commonjs/web/NativeAudioBrowser.js +43 -2
  74. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  75. package/lib/commonjs/web/browser/BrowserManager.js +37 -65
  76. package/lib/commonjs/web/browser/BrowserManager.js.map +1 -1
  77. package/lib/commonjs/web/browser/SearchManager.js +1 -4
  78. package/lib/commonjs/web/browser/SearchManager.js.map +1 -1
  79. package/lib/commonjs/web/http/RequestConfigBuilder.js +53 -55
  80. package/lib/commonjs/web/http/RequestConfigBuilder.js.map +1 -1
  81. package/lib/commonjs/web/player/NowPlayingManager.js +3 -22
  82. package/lib/commonjs/web/player/NowPlayingManager.js.map +1 -1
  83. package/lib/commonjs/web/util/BrowserPathHelper.js +5 -7
  84. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  85. package/lib/commonjs/web/util/GenerationMemo.js +92 -0
  86. package/lib/commonjs/web/util/GenerationMemo.js.map +1 -0
  87. package/lib/module/features/browser-config.js +3 -2
  88. package/lib/module/features/browser-config.js.map +1 -1
  89. package/lib/module/features/browser.js +7 -8
  90. package/lib/module/features/browser.js.map +1 -1
  91. package/lib/module/features/output.js +7 -3
  92. package/lib/module/features/output.js.map +1 -1
  93. package/lib/module/web/NativeAudioBrowser.js +43 -2
  94. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  95. package/lib/module/web/browser/BrowserManager.js +37 -66
  96. package/lib/module/web/browser/BrowserManager.js.map +1 -1
  97. package/lib/module/web/browser/SearchManager.js +1 -5
  98. package/lib/module/web/browser/SearchManager.js.map +1 -1
  99. package/lib/module/web/http/RequestConfigBuilder.js +53 -55
  100. package/lib/module/web/http/RequestConfigBuilder.js.map +1 -1
  101. package/lib/module/web/player/NowPlayingManager.js +3 -22
  102. package/lib/module/web/player/NowPlayingManager.js.map +1 -1
  103. package/lib/module/web/util/BrowserPathHelper.js +5 -7
  104. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  105. package/lib/module/web/util/GenerationMemo.js +87 -0
  106. package/lib/module/web/util/GenerationMemo.js.map +1 -0
  107. package/lib/typescript/src/features/browser-config.d.ts.map +1 -1
  108. package/lib/typescript/src/features/browser.d.ts +7 -8
  109. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  110. package/lib/typescript/src/features/output.d.ts +8 -4
  111. package/lib/typescript/src/features/output.d.ts.map +1 -1
  112. package/lib/typescript/src/specs/audio-browser.nitro.d.ts +11 -0
  113. package/lib/typescript/src/specs/audio-browser.nitro.d.ts.map +1 -1
  114. package/lib/typescript/src/types/browser-native.d.ts +2 -1
  115. package/lib/typescript/src/types/browser-native.d.ts.map +1 -1
  116. package/lib/typescript/src/types/browser.d.ts +55 -8
  117. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  118. package/nitrogen/generated/android/AudioBrowserOnLoad.cpp +2 -0
  119. package/nitrogen/generated/android/c++/JArtworkRequestConfig.hpp +3 -0
  120. package/nitrogen/generated/android/c++/JFindTrackParams.hpp +57 -0
  121. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_RequestConfig___MediaTransformParams.hpp +13 -1
  122. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_RequestConfig___RequestConfig_std__optional_std__unordered_map_std__string__std__string__.hpp +13 -1
  123. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_RequestConfig___Track.hpp +13 -1
  124. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__optional_FormattedNavigationError____FormatNavigationErrorParams.hpp +13 -1
  125. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__optional_NowPlayingUpdate____FormatNowPlayingParams.hpp +13 -1
  126. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__optional_std__string____Track.hpp +13 -1
  127. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_GateDecision_____NativeGateRequest.hpp +23 -2
  128. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_RequestConfig_____MediaTransformParams.hpp +23 -2
  129. 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
  130. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_RequestConfig_____Track.hpp +23 -2
  131. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_TransformableRequestConfig____.hpp +23 -2
  132. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_std__optional_Track______FindTrackParams.hpp +171 -0
  133. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_std__vector_Track______SearchParams.hpp +23 -2
  134. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__shared_ptr_Promise_void_____TrackLoadEvent.hpp +23 -2
  135. package/nitrogen/generated/android/c++/JFunc_std__shared_ptr_Promise_std__string__.hpp +13 -1
  136. 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
  137. package/nitrogen/generated/android/c++/JHybridAudioBrowserSpec.cpp +15 -3
  138. package/nitrogen/generated/android/c++/JHybridAudioBrowserSpec.hpp +1 -1
  139. package/nitrogen/generated/android/c++/JMediaRequestConfig.hpp +3 -0
  140. package/nitrogen/generated/android/c++/JNativeBrowserConfiguration.hpp +20 -2
  141. package/nitrogen/generated/android/c++/JNativeRouteEntry.hpp +3 -0
  142. package/nitrogen/generated/android/c++/JNativeSetupPlayerOptions.hpp +3 -0
  143. package/nitrogen/generated/android/c++/JOutputPickerAnchor.hpp +69 -0
  144. package/nitrogen/generated/android/c++/JTransformableRequestConfig.hpp +3 -0
  145. package/nitrogen/generated/android/c++/JVariant_ResolvedTrack_BrowseError_Promise_BrowseResult_.hpp +13 -1
  146. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/FindTrackParams.kt +51 -0
  147. 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
  148. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/HybridAudioBrowserSpec.kt +1 -1
  149. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/NativeBrowserConfiguration.kt +11 -6
  150. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/OutputPickerAnchor.kt +66 -0
  151. package/nitrogen/generated/ios/AudioBrowser-Swift-Cxx-Bridge.cpp +35 -1
  152. package/nitrogen/generated/ios/AudioBrowser-Swift-Cxx-Bridge.hpp +144 -15
  153. package/nitrogen/generated/ios/AudioBrowser-Swift-Cxx-Umbrella.hpp +8 -0
  154. package/nitrogen/generated/ios/c++/HybridAudioBrowserSpecSwift.hpp +8 -2
  155. package/nitrogen/generated/ios/swift/FindTrackParams.swift +29 -0
  156. package/nitrogen/generated/ios/swift/Func_std__shared_ptr_Promise_std__shared_ptr_Promise_std__optional_Track______FindTrackParams.swift +67 -0
  157. package/nitrogen/generated/ios/swift/Func_void_std__optional_Track_.swift +46 -0
  158. package/nitrogen/generated/ios/swift/Func_void_std__shared_ptr_Promise_std__optional_Track___.swift +66 -0
  159. package/nitrogen/generated/ios/swift/HybridAudioBrowserSpec.swift +1 -1
  160. package/nitrogen/generated/ios/swift/HybridAudioBrowserSpec_cxx.swift +2 -2
  161. package/nitrogen/generated/ios/swift/NativeBrowserConfiguration.swift +48 -1
  162. package/nitrogen/generated/ios/swift/OutputPickerAnchor.swift +44 -0
  163. package/nitrogen/generated/shared/c++/FindTrackParams.hpp +83 -0
  164. package/nitrogen/generated/shared/c++/HybridAudioBrowserSpec.hpp +4 -1
  165. package/nitrogen/generated/shared/c++/NativeBrowserConfiguration.hpp +10 -3
  166. package/nitrogen/generated/shared/c++/OutputPickerAnchor.hpp +95 -0
  167. package/package.json +1 -1
  168. package/src/codegen-js-error-message.test.ts +78 -0
  169. package/src/features/browser-config.test.ts +7 -0
  170. package/src/features/browser-config.ts +3 -2
  171. package/src/features/browser.ts +7 -8
  172. package/src/features/output.ts +13 -5
  173. package/src/specs/audio-browser.nitro.ts +16 -3
  174. package/src/types/browser-native.ts +4 -1
  175. package/src/types/browser.ts +60 -8
  176. package/src/web/NativeAudioBrowser.ts +43 -3
  177. package/src/web/__tests__/nowPlayingArtwork.test.ts +191 -0
  178. package/src/web/browser/BrowserManager.ts +50 -79
  179. package/src/web/browser/SearchManager.ts +1 -8
  180. package/src/web/browser/__tests__/artwork-resolution.test.ts +33 -0
  181. package/src/web/browser/__tests__/layer-resolver.test.ts +47 -1
  182. package/src/web/http/RequestConfigBuilder.test.ts +151 -1
  183. package/src/web/http/RequestConfigBuilder.ts +72 -57
  184. package/src/web/player/NowPlayingManager.test.ts +29 -0
  185. package/src/web/player/NowPlayingManager.ts +4 -27
  186. package/src/web/util/BrowserPathHelper.test.ts +23 -0
  187. package/src/web/util/BrowserPathHelper.ts +6 -7
  188. package/src/web/util/GenerationMemo.test.ts +148 -0
  189. package/src/web/util/GenerationMemo.ts +103 -0
  190. package/website/guide/audio-output.md +34 -7
  191. package/website/guide/browser.md +21 -0
  192. package/website/guide/gate.md +1 -1
@@ -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.
@@ -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