react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.56
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.
- package/README.md +32 -19
- package/lib/commonjs/CLAUDE.md +7 -2
- package/lib/commonjs/features/battery.js +16 -12
- package/lib/commonjs/features/battery.js.map +1 -1
- package/lib/commonjs/features/browser-config.js +1 -1
- package/lib/commonjs/features/browser.js +74 -24
- package/lib/commonjs/features/browser.js.map +1 -1
- package/lib/commonjs/features/carConnection.js +3 -4
- package/lib/commonjs/features/carConnection.js.map +1 -1
- package/lib/commonjs/features/equalizer.js +9 -5
- package/lib/commonjs/features/equalizer.js.map +1 -1
- package/lib/commonjs/features/errors.js +35 -21
- package/lib/commonjs/features/errors.js.map +1 -1
- package/lib/commonjs/features/favorites.js +15 -13
- package/lib/commonjs/features/favorites.js.map +1 -1
- package/lib/commonjs/features/gate.js +12 -6
- package/lib/commonjs/features/gate.js.map +1 -1
- package/lib/commonjs/features/metadata.js +16 -14
- package/lib/commonjs/features/metadata.js.map +1 -1
- package/lib/commonjs/features/network.js +5 -1
- package/lib/commonjs/features/network.js.map +1 -1
- package/lib/commonjs/features/nowPlaying.js +28 -14
- package/lib/commonjs/features/nowPlaying.js.map +1 -1
- package/lib/commonjs/features/output.js +8 -4
- package/lib/commonjs/features/output.js.map +1 -1
- package/lib/commonjs/features/playback/controls.js +10 -5
- package/lib/commonjs/features/playback/controls.js.map +1 -1
- package/lib/commonjs/features/playback/playWhenReady.js +6 -5
- package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
- package/lib/commonjs/features/playback/playing.js +5 -3
- package/lib/commonjs/features/playback/playing.js.map +1 -1
- package/lib/commonjs/features/playback/progress.js +11 -5
- package/lib/commonjs/features/playback/progress.js.map +1 -1
- package/lib/commonjs/features/playback/state.js +3 -3
- package/lib/commonjs/features/playback/state.js.map +1 -1
- package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
- package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
- package/lib/commonjs/features/playback/volume.js +6 -5
- package/lib/commonjs/features/playback/volume.js.map +1 -1
- package/lib/commonjs/features/player/options.js +20 -10
- package/lib/commonjs/features/player/options.js.map +1 -1
- package/lib/commonjs/features/player/setup.js +34 -38
- package/lib/commonjs/features/player/setup.js.map +1 -1
- package/lib/commonjs/features/queue/activeTrack.js +0 -1
- package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
- package/lib/commonjs/features/queue/queue.js +48 -20
- package/lib/commonjs/features/queue/queue.js.map +1 -1
- package/lib/commonjs/features/queue/repeatMode.js +2 -1
- package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
- package/lib/commonjs/features/queue/shuffle.js +0 -1
- package/lib/commonjs/features/queue/shuffle.js.map +1 -1
- package/lib/commonjs/features/remoteControls.js +59 -35
- package/lib/commonjs/features/remoteControls.js.map +1 -1
- package/lib/commonjs/features/sleepTimer.js +15 -6
- package/lib/commonjs/features/sleepTimer.js.map +1 -1
- package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
- package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
- package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
- package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
- package/lib/commonjs/utils/getTrackIdentity.js +6 -4
- package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
- package/lib/commonjs/utils/useDebug.js +16 -3
- package/lib/commonjs/utils/useDebug.js.map +1 -1
- package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
- package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
- package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
- package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
- package/lib/commonjs/web/browser/sections.js +1 -1
- package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
- package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
- package/lib/module/CLAUDE.md +7 -2
- package/lib/module/features/battery.js +16 -12
- package/lib/module/features/battery.js.map +1 -1
- package/lib/module/features/browser-config.js +1 -1
- package/lib/module/features/browser.js +74 -24
- package/lib/module/features/browser.js.map +1 -1
- package/lib/module/features/carConnection.js +3 -4
- package/lib/module/features/carConnection.js.map +1 -1
- package/lib/module/features/equalizer.js +9 -5
- package/lib/module/features/equalizer.js.map +1 -1
- package/lib/module/features/errors.js +35 -21
- package/lib/module/features/errors.js.map +1 -1
- package/lib/module/features/favorites.js +15 -13
- package/lib/module/features/favorites.js.map +1 -1
- package/lib/module/features/gate.js +12 -6
- package/lib/module/features/gate.js.map +1 -1
- package/lib/module/features/metadata.js +16 -14
- package/lib/module/features/metadata.js.map +1 -1
- package/lib/module/features/network.js +5 -1
- package/lib/module/features/network.js.map +1 -1
- package/lib/module/features/nowPlaying.js +28 -14
- package/lib/module/features/nowPlaying.js.map +1 -1
- package/lib/module/features/output.js +8 -4
- package/lib/module/features/output.js.map +1 -1
- package/lib/module/features/playback/controls.js +10 -5
- package/lib/module/features/playback/controls.js.map +1 -1
- package/lib/module/features/playback/playWhenReady.js +6 -5
- package/lib/module/features/playback/playWhenReady.js.map +1 -1
- package/lib/module/features/playback/playing.js +5 -3
- package/lib/module/features/playback/playing.js.map +1 -1
- package/lib/module/features/playback/progress.js +11 -5
- package/lib/module/features/playback/progress.js.map +1 -1
- package/lib/module/features/playback/state.js +3 -3
- package/lib/module/features/playback/state.js.map +1 -1
- package/lib/module/features/playback/trackPlaybackTime.js +6 -1
- package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
- package/lib/module/features/playback/volume.js +6 -5
- package/lib/module/features/playback/volume.js.map +1 -1
- package/lib/module/features/player/options.js +20 -10
- package/lib/module/features/player/options.js.map +1 -1
- package/lib/module/features/player/setup.js +34 -38
- package/lib/module/features/player/setup.js.map +1 -1
- package/lib/module/features/queue/activeTrack.js +0 -1
- package/lib/module/features/queue/activeTrack.js.map +1 -1
- package/lib/module/features/queue/queue.js +48 -20
- package/lib/module/features/queue/queue.js.map +1 -1
- package/lib/module/features/queue/repeatMode.js +2 -1
- package/lib/module/features/queue/repeatMode.js.map +1 -1
- package/lib/module/features/queue/shuffle.js +0 -1
- package/lib/module/features/queue/shuffle.js.map +1 -1
- package/lib/module/features/remoteControls.js +59 -35
- package/lib/module/features/remoteControls.js.map +1 -1
- package/lib/module/features/sleepTimer.js +15 -6
- package/lib/module/features/sleepTimer.js.map +1 -1
- package/lib/module/utils/LazyNativeEmitter.js +6 -9
- package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
- package/lib/module/utils/NativeUpdatedValue.js +13 -12
- package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
- package/lib/module/utils/getTrackIdentity.js +6 -4
- package/lib/module/utils/getTrackIdentity.js.map +1 -1
- package/lib/module/utils/useDebug.js +16 -3
- package/lib/module/utils/useDebug.js.map +1 -1
- package/lib/module/web/NativeAudioBrowser.js +2 -4
- package/lib/module/web/NativeAudioBrowser.js.map +1 -1
- package/lib/module/web/browser/parseSearchResponse.js +3 -4
- package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
- package/lib/module/web/browser/sections.js +1 -1
- package/lib/module/web/util/BrowserPathHelper.js +1 -3
- package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
- package/lib/typescript/src/features/battery.d.ts +17 -12
- package/lib/typescript/src/features/battery.d.ts.map +1 -1
- package/lib/typescript/src/features/browser.d.ts +64 -24
- package/lib/typescript/src/features/browser.d.ts.map +1 -1
- package/lib/typescript/src/features/carConnection.d.ts +3 -4
- package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
- package/lib/typescript/src/features/equalizer.d.ts +9 -5
- package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
- package/lib/typescript/src/features/errors.d.ts +37 -22
- package/lib/typescript/src/features/errors.d.ts.map +1 -1
- package/lib/typescript/src/features/favorites.d.ts +15 -13
- package/lib/typescript/src/features/favorites.d.ts.map +1 -1
- package/lib/typescript/src/features/gate.d.ts +14 -8
- package/lib/typescript/src/features/gate.d.ts.map +1 -1
- package/lib/typescript/src/features/metadata.d.ts +37 -17
- package/lib/typescript/src/features/metadata.d.ts.map +1 -1
- package/lib/typescript/src/features/network.d.ts +5 -1
- package/lib/typescript/src/features/network.d.ts.map +1 -1
- package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
- package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
- package/lib/typescript/src/features/output.d.ts +8 -4
- package/lib/typescript/src/features/output.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/controls.d.ts +10 -5
- package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
- package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/playing.d.ts +16 -3
- package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/progress.d.ts +11 -5
- package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/state.d.ts +8 -3
- package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
- package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
- package/lib/typescript/src/features/playback/volume.d.ts +6 -5
- package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
- package/lib/typescript/src/features/player/options.d.ts +52 -37
- package/lib/typescript/src/features/player/options.d.ts.map +1 -1
- package/lib/typescript/src/features/player/setup.d.ts +65 -60
- package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
- package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/queue.d.ts +48 -20
- package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
- package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
- package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
- package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
- package/lib/typescript/src/features/remoteControls.d.ts +58 -25
- package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
- package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
- package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
- package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
- package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
- package/lib/typescript/src/types/browser.d.ts +181 -144
- package/lib/typescript/src/types/browser.d.ts.map +1 -1
- package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
- package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
- package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
- package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
- package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
- package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
- package/lib/typescript/src/utils/useDebug.d.ts +16 -3
- package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/CLAUDE.md +7 -2
- package/src/docs-floors.test.ts +71 -0
- package/src/features/battery.ts +17 -13
- package/src/features/browser-config.ts +1 -1
- package/src/features/browser.ts +65 -24
- package/src/features/carConnection.ts +3 -4
- package/src/features/equalizer.ts +9 -5
- package/src/features/errors.ts +37 -22
- package/src/features/favorites.ts +15 -13
- package/src/features/gate.ts +14 -8
- package/src/features/metadata.ts +37 -17
- package/src/features/network.ts +5 -1
- package/src/features/nowPlaying.ts +28 -14
- package/src/features/output.ts +8 -4
- package/src/features/playback/controls.ts +10 -5
- package/src/features/playback/playWhenReady.ts +6 -5
- package/src/features/playback/playing.ts +16 -3
- package/src/features/playback/progress.ts +11 -5
- package/src/features/playback/state.ts +8 -3
- package/src/features/playback/trackPlaybackTime.ts +9 -2
- package/src/features/playback/volume.ts +6 -5
- package/src/features/player/options.ts +54 -43
- package/src/features/player/setup.ts +67 -61
- package/src/features/queue/activeTrack.ts +0 -1
- package/src/features/queue/queue.ts +48 -20
- package/src/features/queue/repeatMode.ts +1 -1
- package/src/features/queue/shuffle.ts +0 -1
- package/src/features/remoteControls.ts +59 -35
- package/src/features/sleepTimer.ts +15 -7
- package/src/types/browser-nodes.ts +54 -57
- package/src/types/browser.ts +183 -146
- package/src/utils/LazyNativeEmitter.ts +6 -9
- package/src/utils/NativeUpdatedValue.ts +13 -12
- package/src/utils/getTrackIdentity.ts +6 -4
- package/src/utils/useDebug.ts +16 -3
- package/src/web/NativeAudioBrowser.ts +2 -4
- package/src/web/browser/parseSearchResponse.ts +3 -4
- package/src/web/browser/sections.ts +1 -1
- package/src/web/util/BrowserPathHelper.ts +1 -3
- package/website/guide/android-auto.md +25 -13
- package/website/guide/android-certificates.md +199 -120
- package/website/guide/artwork.md +93 -48
- package/website/guide/audio-output.md +86 -68
- package/website/guide/automotive.md +15 -10
- package/website/guide/basic-usage.md +5 -2
- package/website/guide/battery.md +50 -23
- package/website/guide/browser.md +155 -68
- package/website/guide/carplay.md +132 -49
- package/website/guide/configuration.md +85 -49
- package/website/guide/equalizer.md +36 -32
- package/website/guide/errors.md +106 -64
- package/website/guide/favorites.md +41 -31
- package/website/guide/gate.md +24 -10
- package/website/guide/getting-started.md +55 -2
- package/website/guide/hooks.md +53 -47
- package/website/guide/live-streams.md +80 -49
- package/website/guide/metadata.md +87 -53
- package/website/guide/migrating-from-track-player.md +94 -49
- package/website/guide/native-callback-fetch.md +46 -36
- package/website/guide/network.md +36 -20
- package/website/guide/now-playing.md +72 -44
- package/website/guide/playback.md +112 -35
- package/website/guide/queue.md +77 -43
- package/website/guide/remote-controls.md +87 -29
- package/website/guide/search.md +37 -22
- package/website/guide/sleep-timer.md +35 -14
- package/website/guide/track.md +59 -35
package/website/guide/carplay.md
CHANGED
|
@@ -13,7 +13,9 @@ CarPlay integration for audio apps works through two systems:
|
|
|
13
13
|
|
|
14
14
|
On CarPlay's audio interface the search button always triggers Siri — audio apps don't use `CPSearchTemplate` (that's a navigation-app API).
|
|
15
15
|
|
|
16
|
-
The two systems are independent, but **both** require the [React Native host setup](#react-native-host-uiscene-headless) (UIScene lifecycle + headless RN boot)
|
|
16
|
+
The two systems are independent, but **both** require the [React Native host setup](#react-native-host-uiscene-headless) (UIScene lifecycle + headless RN boot). Every CarPlay app needs it, even browse-only. Siri then adds its own entitlement, Info.plist keys, and intent handler on top.
|
|
17
|
+
|
|
18
|
+
The **Now Playing Buttons**, **Playing Indicator**, **Loading States** and **Album Line Navigation** sections are optional polish. Skip them to get a minimal integration working.
|
|
17
19
|
|
|
18
20
|
::: info Before you start
|
|
19
21
|
This page assumes you've installed the library and have the player running: add `react-native-audio-browser`, run `pod install` in `ios/`, and call `setupPlayer()` + `configureBrowser()` at startup. See [Getting Started](/guide/getting-started) and [Basic Usage](/guide/basic-usage) first.
|
|
@@ -68,16 +70,27 @@ Your scene manifest needs **two** scene configurations: the CarPlay template sce
|
|
|
68
70
|
</dict>
|
|
69
71
|
```
|
|
70
72
|
|
|
71
|
-
The two `UISceneDelegateClassName` strings name the
|
|
73
|
+
The two `UISceneDelegateClassName` strings name the delegate for each scene:
|
|
74
|
+
|
|
75
|
+
- `RNABCarPlaySceneDelegate` ships with the library. You never implement it; it links in once the `AudioBrowser` pod is installed.
|
|
76
|
+
- `PhoneSceneDelegate` is your own, written in the host setup below.
|
|
77
|
+
|
|
78
|
+
These manifest strings are only a fallback: once you add `configurationForConnecting` (next section), your code picks each scene's delegate. Until you finish the host setup, `PhoneSceneDelegate` does not resolve yet, and that is expected.
|
|
72
79
|
|
|
73
80
|
## React Native host (UIScene + headless)
|
|
74
81
|
|
|
75
|
-
This section is **required for any CarPlay integration
|
|
82
|
+
This section is **required for any CarPlay integration**, browse-only or Siri. Set it up once; both the browse templates and Siri depend on it.
|
|
83
|
+
|
|
84
|
+
CarPlay connects through scenes and can launch your app in the background with no phone window. So React Native has to start both on the foreground path (your phone scene) and headless (in a hidden window).
|
|
76
85
|
|
|
77
86
|
::: warning Two prerequisites
|
|
78
|
-
**UIScene lifecycle** — CarPlay requires a `UIWindowSceneDelegate` for the phone window.
|
|
87
|
+
**UIScene lifecycle** — CarPlay requires a `UIWindowSceneDelegate` for the phone window. If your app still sets up its window directly in `AppDelegate`, migrate to scenes first (the sections below build all the pieces).
|
|
88
|
+
|
|
89
|
+
**New Architecture host, Swift** — these snippets assume a Swift `AppDelegate` built on `RCTReactNativeFactory` and `RCTDefaultReactNativeFactoryDelegate`, which React Native ships from **0.78**.
|
|
90
|
+
|
|
91
|
+
On React Native versions before 0.78 (see [Getting Started](/guide/getting-started#installation) for the minimum), the template's `AppDelegate` subclasses `RCTAppDelegate` instead, so adapt the same pieces (scene routing, the headless helper, the started flag) to that host.
|
|
79
92
|
|
|
80
|
-
|
|
93
|
+
If yours is still Objective-C (`.mm`), migrating it to Swift first is simpler than translating this wiring by hand. Scaffold a throwaway app (`npx @react-native-community/cli init Tmp`) and use its `AppDelegate.swift` as a reference. ObjC works too (the bridging header is then unnecessary, see [Siri step 3](#_3-bridging-header-swift-appdelegate-only)) but isn't shown here.
|
|
81
94
|
:::
|
|
82
95
|
|
|
83
96
|
### The factory
|
|
@@ -132,11 +145,11 @@ class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
|
|
|
132
145
|
|
|
133
146
|
Two things call this helper, which is why it's required even for **browse-only** apps:
|
|
134
147
|
|
|
135
|
-
- The library's `RNABCarPlaySceneDelegate` calls `startReactNativeHeadless` on your `AppDelegate`
|
|
148
|
+
- The library's `RNABCarPlaySceneDelegate` calls `startReactNativeHeadless` on your `AppDelegate` every time CarPlay connects. So a browse-only CarPlay launch boots RN automatically. When the phone scene already started RN, the helper's guard makes the call a no-op.
|
|
136
149
|
- Your Siri intent handler calls it (step 4) for a background intent launch.
|
|
137
150
|
|
|
138
|
-
::: warning
|
|
139
|
-
The library finds this method **by selector
|
|
151
|
+
::: warning Declare it `@objc func startReactNativeHeadless()`
|
|
152
|
+
The library finds this method **by Objective-C selector**. It must be named exactly `startReactNativeHeadless`, take no arguments, and be marked `@objc`: Swift does not expose a plain method to the Objective-C runtime. Otherwise the library's CarPlay delegate can't boot RN and browse screens hang empty.
|
|
140
153
|
:::
|
|
141
154
|
|
|
142
155
|
```swift
|
|
@@ -147,7 +160,7 @@ private var headlessWindow: UIWindow?
|
|
|
147
160
|
/// Boots React Native into a hidden window when no UI scene exists yet.
|
|
148
161
|
/// Called by the library's CarPlay delegate (browse) and your Siri handler.
|
|
149
162
|
/// Safe to call repeatedly — it starts RN at most once.
|
|
150
|
-
func startReactNativeHeadless() {
|
|
163
|
+
@objc func startReactNativeHeadless() {
|
|
151
164
|
guard !reactNativeStarted else { return }
|
|
152
165
|
reactNativeStarted = true
|
|
153
166
|
|
|
@@ -167,9 +180,9 @@ func startReactNativeHeadless() {
|
|
|
167
180
|
)
|
|
168
181
|
}
|
|
169
182
|
|
|
170
|
-
/// Called by the phone scene
|
|
171
|
-
/// headless helper
|
|
172
|
-
/// `reactNativeStarted
|
|
183
|
+
/// Called by the phone scene when it starts RN on the foreground path, so the
|
|
184
|
+
/// headless helper doesn't start it again. Only the headless helper checks
|
|
185
|
+
/// `reactNativeStarted`: the phone scene always starts RN in its own window.
|
|
173
186
|
func markReactNativeStarted() {
|
|
174
187
|
reactNativeStarted = true
|
|
175
188
|
}
|
|
@@ -208,7 +221,13 @@ class PhoneSceneDelegate: UIResponder, UIWindowSceneDelegate {
|
|
|
208
221
|
}
|
|
209
222
|
```
|
|
210
223
|
|
|
211
|
-
|
|
224
|
+
::: info After a headless launch
|
|
225
|
+
The phone scene starts RN even when CarPlay or Siri already started it headless. The factory reuses its React host, so JS keeps running in the same runtime.
|
|
226
|
+
|
|
227
|
+
But your root component mounts a second time, in the phone window, while the headless one stays mounted in the hidden window. Keep app-wide side effects (player setup, `configureBrowser`) idempotent, or put them outside the root component.
|
|
228
|
+
:::
|
|
229
|
+
|
|
230
|
+
See the example app's [`AppDelegate.swift`](https://github.com/radio-garden/react-native-audio-browser/blob/next/apps/example-native/ios/AudioBrowserExample/AppDelegate.swift) and [`PhoneSceneDelegate.swift`](https://github.com/radio-garden/react-native-audio-browser/blob/next/apps/example-native/ios/AudioBrowserExample/PhoneSceneDelegate.swift) for the complete, copy-pasteable versions.
|
|
212
231
|
|
|
213
232
|
### Routing scene connections
|
|
214
233
|
|
|
@@ -243,7 +262,9 @@ One coupling that **is** load-bearing: the `name:` you pass to `UISceneConfigura
|
|
|
243
262
|
|
|
244
263
|
### The assembled `AppDelegate`
|
|
245
264
|
|
|
246
|
-
The fragments above all live on one `AppDelegate`. Here is the whole class in one piece
|
|
265
|
+
The fragments above all live on one `AppDelegate`. Here is the whole class in one piece, to copy.
|
|
266
|
+
|
|
267
|
+
It **replaces** the `@main class AppDelegate` your RN template generated in `ios/<app>/AppDelegate.swift` (you keep one `@main`; don't add a second). The Siri `handlerFor` method at the end is needed only if you add [Siri Voice Search](#siri-voice-search):
|
|
247
268
|
|
|
248
269
|
```swift
|
|
249
270
|
import UIKit
|
|
@@ -294,7 +315,8 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
|
|
|
294
315
|
}
|
|
295
316
|
|
|
296
317
|
// Boots RN into a hidden window when there's no UI scene (background launch).
|
|
297
|
-
|
|
318
|
+
// `@objc` so the library's CarPlay delegate can find it by selector.
|
|
319
|
+
@objc func startReactNativeHeadless() {
|
|
298
320
|
guard !reactNativeStarted else { return }
|
|
299
321
|
reactNativeStarted = true
|
|
300
322
|
headlessWindow = UIWindow(frame: CGRect(x: 0, y: 0, width: 1, height: 1))
|
|
@@ -339,24 +361,29 @@ class ReactNativeDelegate: RCTDefaultReactNativeFactoryDelegate {
|
|
|
339
361
|
This is the complete `AppDelegate.swift` (the `@main class AppDelegate` plus its `ReactNativeDelegate` in the same file). `PhoneSceneDelegate` lives in its **own** `PhoneSceneDelegate.swift` (shown above). Those two files are the complete native side.
|
|
340
362
|
|
|
341
363
|
::: warning Don't blindly overwrite an AppDelegate you've customized
|
|
342
|
-
This block is the minimal shape. If your existing `AppDelegate` / `ReactNativeDelegate` already has extra overrides
|
|
364
|
+
This block is the minimal shape. If your existing `AppDelegate` / `ReactNativeDelegate` already has extra overrides (bundle customization, linking setup, push/deep-link handlers, `customize(rootView:)`, extra modules), **keep them**.
|
|
365
|
+
|
|
366
|
+
Merge the CarPlay additions into your file rather than replacing it wholesale: the factory split, `configurationForConnecting`, the headless helper, `markReactNativeStarted`, and the Siri `handlerFor`.
|
|
343
367
|
:::
|
|
344
368
|
|
|
345
369
|
### Where to call `configureBrowser`
|
|
346
370
|
|
|
347
|
-
|
|
371
|
+
Call `configureBrowser` (and `setupPlayer`) as a **top-level side-effect in `index.js`**, next to `AppRegistry.registerComponent`. It then runs when the JS bundle loads, mounted UI or not.
|
|
348
372
|
|
|
349
|
-
|
|
373
|
+
The headless helper mounts your root component in the hidden window, and the phone scene mounts it again later. So a call in a component's `useEffect` runs once per window, and only after the first render. That's late for Siri, whose handler waits only briefly for setup (see [step 4](#_4-appdelegate-intent-handler)). A top-level call in `index.js` runs once, as soon as the bundle loads.
|
|
374
|
+
|
|
375
|
+
`configureBrowser` **replaces** the whole config each time; it doesn't merge. So build one object with everything together: tabs, routes, and (for Siri) search. The snippets further down show one key at a time for brevity.
|
|
350
376
|
|
|
351
377
|
```ts
|
|
352
378
|
const browserConfig = {
|
|
353
|
-
// Tabs along the top of the CarPlay browser (
|
|
354
|
-
//
|
|
379
|
+
// Tabs along the top of the CarPlay browser (see the tab limit in
|
|
380
|
+
// /guide/browser#tabs-and-the-initial-path).
|
|
355
381
|
tabs: [{ title: 'Home', path: '/' }],
|
|
356
382
|
|
|
357
383
|
// routes: path → BrowserSource (static page, callback, or HTTP).
|
|
358
384
|
routes: {
|
|
359
385
|
'/': async () => ({
|
|
386
|
+
path: '/',
|
|
360
387
|
title: 'Home',
|
|
361
388
|
children: [{ title: 'Crunchy Greens FM', src: 'https://...' }]
|
|
362
389
|
})
|
|
@@ -397,7 +424,7 @@ Siri voice search builds on the [React Native host setup](#react-native-host-uis
|
|
|
397
424
|
- **Steps 1–4** — Siri entitlement, Info.plist keys, bridging header, intent handler
|
|
398
425
|
|
|
399
426
|
::: warning Step 0 (required) — a configured `search` source
|
|
400
|
-
Siri voice search resolves spoken queries through the **same [`search`](/guide/search) source as your in-app search**.
|
|
427
|
+
Siri voice search resolves spoken queries through the **same [`search`](/guide/search) source as your in-app search**. Without one, "play jazz" returns **nothing**, even with steps 1–4 wired up. Add `search` to the one config you pass to [`configureBrowser`](#where-to-call-configurebrowser) at startup:
|
|
401
428
|
|
|
402
429
|
```ts
|
|
403
430
|
configureBrowser({
|
|
@@ -405,22 +432,25 @@ configureBrowser({
|
|
|
405
432
|
search: {
|
|
406
433
|
// GET https://api.example.com/search?q=jazz — the library appends
|
|
407
434
|
// `q` plus structured voice params (`mode`, `genre`, `artist`,
|
|
408
|
-
// `album`, `reference`) and expects a
|
|
409
|
-
//
|
|
410
|
-
//
|
|
435
|
+
// `album`, `reference`) and expects a bare Track[] back (a JSON
|
|
436
|
+
// array, not a page object), where each playable Track needs at
|
|
437
|
+
// least `title` + `src`.
|
|
411
438
|
baseUrl: 'https://api.example.com/search'
|
|
412
439
|
}
|
|
413
440
|
})
|
|
414
441
|
```
|
|
415
442
|
|
|
416
|
-
|
|
443
|
+
The browse templates work without `search`; Siri does not. See [Search](/guide/search#configuring-search) for:
|
|
417
444
|
|
|
418
|
-
|
|
445
|
+
- the full `SearchParams` (genre / artist / album / `mode` / `reference`)
|
|
446
|
+
- the callback form, which returns [`Track`](/api/types/browser-nodes/#track)`[]` itself and receives the spoken text as `query` rather than `q`
|
|
447
|
+
- `transform`, for rewriting requests
|
|
419
448
|
|
|
420
|
-
See [Search](/guide/search) for the full `SearchParams` (genre / artist / album / `mode` / `reference`), the callback form (return [`Track`](/api/types/browser-nodes/#track)`[]` yourself), and `transform` for rewriting requests. This is required for Siri; the browse templates work without it.
|
|
421
449
|
:::
|
|
422
450
|
|
|
423
|
-
CarPlay's tab bar already has a **search button that launches Siri
|
|
451
|
+
CarPlay's tab bar already has a **search button that launches Siri**, which works once the steps below are wired up.
|
|
452
|
+
|
|
453
|
+
The library can also show an **"Ask Siri to Play Audio" cell inside a list** as an extra entry point. This is optional polish, not what enables Siri search. To add it, set [`carPlaySiriListButton`](/api/types/browser/#carplaysirilistbuttonposition) on the resolved content your route source returns:
|
|
424
454
|
|
|
425
455
|
```ts
|
|
426
456
|
configureBrowser({
|
|
@@ -429,6 +459,7 @@ configureBrowser({
|
|
|
429
459
|
// Basic Usage and the BrowserSource type: /api/types/browser/#browsersource
|
|
430
460
|
routes: {
|
|
431
461
|
'/': async () => ({
|
|
462
|
+
path: '/',
|
|
432
463
|
title: 'Home',
|
|
433
464
|
carPlaySiriListButton: 'top',
|
|
434
465
|
children: [{ title: 'Crunchy Greens FM', src: 'https://...' }]
|
|
@@ -439,16 +470,16 @@ configureBrowser({
|
|
|
439
470
|
|
|
440
471
|
(Tabs themselves come from your separate [`tabs`](/api/types/browser/#tabs) config, not from this route — the `'/'` route here is just where the button is attached. See [Basic Usage](/guide/basic-usage) for how `tabs` and `routes` fit together.)
|
|
441
472
|
|
|
442
|
-
The `carPlaySiriListButton` property accepts `'top'` or `'bottom'` to control where the system assistant cell appears. It only affects CarPlay
|
|
443
|
-
|
|
444
|
-
::: tip
|
|
445
|
-
The button just launches Siri — it does **nothing** until the entitlement, Info.plist keys, and intent handler in the steps below are in place. Wire those up first, or tapping it will appear to do nothing.
|
|
446
|
-
:::
|
|
473
|
+
The `carPlaySiriListButton` property accepts `'top'` or `'bottom'` to control where the system assistant cell appears. It only affects CarPlay, not the phone UI.
|
|
447
474
|
|
|
448
475
|
To complete the setup, your app needs the Siri entitlement, a couple of Info.plist keys, a bridging header, and a one-line handler in your AppDelegate. Media intents are handled in-app: Siri delivers the `INPlayMediaIntent` straight to your `AppDelegate`.
|
|
449
476
|
|
|
450
477
|
::: info iOS version
|
|
451
|
-
The
|
|
478
|
+
The version numbers on this page are capability notes within the library's [iOS floor](/guide/getting-started#installation):
|
|
479
|
+
|
|
480
|
+
- The in-app handler API (`application(_:handlerFor:)`) exists from iOS 14, so you never need to gate on it.
|
|
481
|
+
- The automatic CarPlay loading spinner needs iOS 18.4+.
|
|
482
|
+
|
|
452
483
|
:::
|
|
453
484
|
|
|
454
485
|
### 1. Siri entitlement
|
|
@@ -499,7 +530,7 @@ Add Siri usage description and supported media categories to your app's Info.pli
|
|
|
499
530
|
- **`INUpdateMediaAffinityIntent`** — "like" / "dislike" the current track.
|
|
500
531
|
- **`INAddMediaIntent`** — add the current track to favorites.
|
|
501
532
|
|
|
502
|
-
Register only the ones you want; `INPlayMediaIntent` alone is enough for voice search. The [`INSupportedMediaCategories`](https://developer.apple.com/documentation/
|
|
533
|
+
Register only the ones you want; `INPlayMediaIntent` alone is enough for voice search. The [`INSupportedMediaCategories`](https://developer.apple.com/documentation/bundleresources/information-property-list/insupportedmediacategories) values tell Siri which spoken requests to route to your app — if they don't cover your content, Siri may hand the request to a **different app**, so list every category you actually support.
|
|
503
534
|
|
|
504
535
|
### 3. Bridging Header (Swift AppDelegate only)
|
|
505
536
|
|
|
@@ -535,13 +566,21 @@ func application(
|
|
|
535
566
|
}
|
|
536
567
|
```
|
|
537
568
|
|
|
538
|
-
`RNABAudioBrowser.handler(for:)` is the library's **only** intent entry point. It returns an opaque handler object for intents it supports (`INPlayMediaIntent`, `INUpdateMediaAffinityIntent`, `INAddMediaIntent`) and `nil` for anything else
|
|
569
|
+
`RNABAudioBrowser.handler(for:)` is the library's **only** intent entry point, with no separate registration or setup call. It returns an opaque handler object for the intents it supports (`INPlayMediaIntent`, `INUpdateMediaAffinityIntent`, `INAddMediaIntent`) and `nil` for anything else.
|
|
570
|
+
|
|
571
|
+
The library resolves the spoken query through your configured [`search`](/guide/search) source (the same one your in-app search uses — it is **not** a browse route), queues the results, and starts playback automatically.
|
|
572
|
+
|
|
573
|
+
::: tip The handler waits only briefly for setup
|
|
574
|
+
On a cold launch, the handler waits up to about **8 seconds** for your JS to run `setupPlayer()` and `configureBrowser()`, then fails the intent. So call both at the top level of `index.js`, before any slow async work (see [Where to call `configureBrowser`](#where-to-call-configurebrowser)).
|
|
539
575
|
|
|
540
|
-
|
|
541
|
-
|
|
576
|
+
That limit covers only the wait for setup. Your Gate's resolver and your `search` source run after it with no time limit of their own, so keep them quick: Siri gives up on a slow request.
|
|
577
|
+
|
|
578
|
+
If you use a [Gate](/guide/gate), a paywall or region check, it can refuse the search. It blocks search and browsing from the car, not playback, so "resume" still plays.
|
|
542
579
|
:::
|
|
543
580
|
|
|
544
|
-
> **Why a handler object, not `application(_:handle:completionHandler:)`?** The latter is not a real `UIApplicationDelegate` method, so iOS never calls it. With no in-app handler registered, the system falls back to a `UISIntentForwardingAction`, which crashes in `-[INHandleIntentForwardingActionResponse isSuccess]`.
|
|
581
|
+
> **Why a handler object, not `application(_:handle:completionHandler:)`?** The latter is not a real `UIApplicationDelegate` method, so iOS never calls it. With no in-app handler registered, the system falls back to a `UISIntentForwardingAction`, which crashes in `-[INHandleIntentForwardingActionResponse isSuccess]`.
|
|
582
|
+
>
|
|
583
|
+
> Returning a handler from `application(_:handlerFor:)` keeps iOS on the in-app path. **No separate Intents Extension is required**; everything runs in-app.
|
|
545
584
|
|
|
546
585
|
### How It Works
|
|
547
586
|
|
|
@@ -552,11 +591,44 @@ You don't need to race `configureBrowser` against the intent. The handler **wait
|
|
|
552
591
|
5. The library resolves the request and starts playback — **resuming** the last session when the user just said your app's name, otherwise **searching** your content (genre/artist/album/etc. are forwarded as structured search params)
|
|
553
592
|
6. CarPlay's Now Playing screen updates automatically
|
|
554
593
|
|
|
555
|
-
##
|
|
594
|
+
## Now Playing Buttons
|
|
556
595
|
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
596
|
+
The Now Playing screen always has CarPlay's transport controls. More buttons, one of each kind in the table below, go in the row beneath them: list them in `ios.carPlayNowPlayingButtons`, left to right in the order you want them:
|
|
597
|
+
|
|
598
|
+
```ts
|
|
599
|
+
await setupPlayer({
|
|
600
|
+
capabilities: { favorite: true },
|
|
601
|
+
ios: {
|
|
602
|
+
carPlayNowPlayingButtons: ['shuffle', 'repeat', 'favorite', 'playback-rate']
|
|
603
|
+
}
|
|
604
|
+
})
|
|
605
|
+
```
|
|
606
|
+
|
|
607
|
+
You can also change them later with `updateOptions({ ios: { carPlayNowPlayingButtons: [...] } })`. The default is `[]`, which means no extra buttons.
|
|
608
|
+
|
|
609
|
+
| Button | What a tap does |
|
|
610
|
+
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
611
|
+
| `'shuffle'` | Turns shuffle on or off. |
|
|
612
|
+
| `'repeat'` | Cycles the repeat mode: off → track → queue → off. |
|
|
613
|
+
| `'favorite'` | Toggles the playing track's favorite state; the heart is filled while it is a favorite. See [Favorites](/guide/favorites). |
|
|
614
|
+
| `'playback-rate'` | Steps to the next rate in `ios.playbackRates`, wrapping from the last back to the first. With `playbackRates: []` the tap does nothing. |
|
|
615
|
+
|
|
616
|
+
- **Each button is drawn once.** A button listed twice keeps its first position.
|
|
617
|
+
- **More than five entries log a warning.** Five is CarPlay's limit for the row; the count includes repeats.
|
|
618
|
+
- **A [gate](/guide/gate) hides them.** While a gate is active the row is empty. The transport controls stay.
|
|
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.
|
|
621
|
+
|
|
622
|
+
## Playing Indicator
|
|
623
|
+
|
|
624
|
+
CarPlay marks the playing item in browse lists with a now-playing indicator. `ios.carPlayPlayingIndicatorLocation` chooses where it draws:
|
|
625
|
+
|
|
626
|
+
- `'leading'` (default): in the artwork slot, in place of the row's artwork while it plays, as Apple Music does.
|
|
627
|
+
- `'trailing'`: at the end of the row, so the artwork stays visible.
|
|
628
|
+
|
|
629
|
+
If you change it with `updateOptions`, rows already on screen update too.
|
|
630
|
+
|
|
631
|
+
## Loading States
|
|
560
632
|
|
|
561
633
|
Browse screens show a loading state while their content resolves — pushed destinations, tabs loading lazily, and the startup screen while tabs are queried. On iOS 18.4+ the system loading spinner is shown automatically. Older iOS versions have no spinner API; those screens stay blank unless you supply a [`carPlayLoadingTitle`](/api/types/browser/#carplayloadingtitle):
|
|
562
634
|
|
|
@@ -571,7 +643,12 @@ The title renders as the list's centered empty state and disappears as soon as c
|
|
|
571
643
|
|
|
572
644
|
## Album Line Navigation
|
|
573
645
|
|
|
574
|
-
The album line on the Now Playing screen can navigate into the browse tree.
|
|
646
|
+
The album line on the Now Playing screen can navigate into the browse tree. It becomes tappable when the active track has both:
|
|
647
|
+
|
|
648
|
+
- an **`album`** string, which CarPlay builds the tappable line from (see the warning below)
|
|
649
|
+
- an **`albumPath`**: a `path` in your [`routes`](/guide/basic-usage), so the destination must exist there
|
|
650
|
+
|
|
651
|
+
Tapping the line pushes that path:
|
|
575
652
|
|
|
576
653
|
```ts
|
|
577
654
|
{
|
|
@@ -598,12 +675,16 @@ configureBrowser({
|
|
|
598
675
|
Return a browse path to enable the album line for that track, or `undefined` to leave it untappable.
|
|
599
676
|
|
|
600
677
|
::: warning Album metadata required
|
|
601
|
-
CarPlay renders the tappable album/artist button as a **separate line built from the track's `album
|
|
678
|
+
CarPlay renders the tappable album/artist button as a **separate line built from the track's `album`**: the third metadata line, with a chevron. A track without an `album` gives CarPlay no string to turn into a button, and the artist line alone is never tappable.
|
|
679
|
+
|
|
680
|
+
Set `album` on any track that should offer album-line navigation. See [Now Playing](/guide/now-playing) for the full field-by-surface rendering matrix.
|
|
602
681
|
:::
|
|
603
682
|
|
|
604
683
|
## Template Depth
|
|
605
684
|
|
|
606
|
-
CarPlay limits an audio app's template stack to **five templates, the tab bar included** (CarPlay App Programming Guide
|
|
685
|
+
CarPlay limits an audio app's template stack to **five templates, the tab bar included** (see Apple's [CarPlay App Programming Guide](https://developer.apple.com/carplay/)), so the stack is full four pushes in. Now Playing and Up Next each take a slot like any list.
|
|
686
|
+
|
|
687
|
+
A browse tree with a fixed shape (tabs → show → episodes) never gets there; one that can be drilled without end — a place, a place near it, a place near that — does.
|
|
607
688
|
|
|
608
689
|
At the limit, the library replaces the **top** page with the new one, so a push always lands:
|
|
609
690
|
|
|
@@ -633,7 +714,9 @@ An `error` line in that category means the pop or the push failed; it names the
|
|
|
633
714
|
|
|
634
715
|
## Testing
|
|
635
716
|
|
|
636
|
-
Test your app in the `CarPlay Simulator.app`, which is part of the [Additional Tools for Xcode](https://developer.apple.com/download/all/?q=additional%20tools%20for%20xcode). Siri voice search works there, so you can exercise the full intent flow without a car.
|
|
717
|
+
Test your app in the `CarPlay Simulator.app`, which is part of the [Additional Tools for Xcode](https://developer.apple.com/download/all/?q=additional%20tools%20for%20xcode). Siri voice search works there, so you can exercise the full intent flow without a car.
|
|
718
|
+
|
|
719
|
+
CarPlay support on the iOS Simulator can be a little flaky. If something looks broken, retry, or check on a physical device.
|
|
637
720
|
|
|
638
721
|
### Troubleshooting
|
|
639
722
|
|
|
@@ -641,10 +724,10 @@ Test your app in the `CarPlay Simulator.app`, which is part of the [Additional T
|
|
|
641
724
|
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
|
642
725
|
| Siri mic opens but returns nothing | No [`search` source](#siri-voice-search) configured (Step 0). |
|
|
643
726
|
| The "Ask Siri" cell does nothing | Siri entitlement / Info.plist keys / intent handler not wired (steps 1–4). |
|
|
644
|
-
| CarPlay browse screens hang empty | `startReactNativeHeadless` missing or
|
|
727
|
+
| CarPlay browse screens hang empty | `startReactNativeHeadless` missing, misnamed or missing `@objc`: the library calls it by selector. |
|
|
645
728
|
| Build error: _module 'AudioBrowser' not found_ | `pod install` hasn't linked the `AudioBrowser` pod. |
|
|
646
729
|
| Crash: _no UISceneConfiguration named …_ | The `name:` in `configurationForConnecting` doesn't match `UISceneConfigurationName` in the manifest. |
|
|
647
730
|
|
|
648
731
|
## Reference
|
|
649
732
|
|
|
650
|
-
See the [example app](https://github.com/radio-garden/react-native-audio-browser/tree/
|
|
733
|
+
See the [example app](https://github.com/radio-garden/react-native-audio-browser/tree/next/apps/example-native/ios/AudioBrowserExample) for a complete working implementation.
|
|
@@ -11,8 +11,8 @@ Everything about how the player behaves is set through three functions:
|
|
|
11
11
|
- [`updateOptions(options)`](/api/features/player/#updateoptions) — change a
|
|
12
12
|
subset of options later, at runtime.
|
|
13
13
|
- [`getOptions()`](/api/features/player/#getoptions) /
|
|
14
|
-
[`useOptions()`](/api/features/player/#useoptions) — read the current
|
|
15
|
-
|
|
14
|
+
[`useOptions()`](/api/features/player/#useoptions) — read the current
|
|
15
|
+
options.
|
|
16
16
|
|
|
17
17
|
This page maps the whole options surface and links to the feature guide that
|
|
18
18
|
covers each area in depth.
|
|
@@ -35,10 +35,21 @@ await setupPlayer({
|
|
|
35
35
|
})
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
Calling `setupPlayer` again
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
38
|
+
Calling `setupPlayer` again is how you change a
|
|
39
|
+
[setup-only option](#setup-only-vs-updatable) after launch. The runtime options
|
|
40
|
+
(capabilities, intervals, the updatable `android` / `ios` fields) carry over on
|
|
41
|
+
both platforms. The setup-only fields behave differently on each:
|
|
42
|
+
|
|
43
|
+
- **Android** reconfigures in place. The fields you pass are merged over the
|
|
44
|
+
previous ones, and the audio engine is only rebuilt when a construction-bound
|
|
45
|
+
field (buffers, wake mode, …) changed. Two fields are exceptions. Left out,
|
|
46
|
+
`remoteOutputs` turns the remote outputs off again, and `nowPlaying` turns
|
|
47
|
+
the default mapping back on. A `nowPlaying` formatter stays until another
|
|
48
|
+
function replaces it: passing `true` or leaving it out does not drop it.
|
|
49
|
+
- **iOS** replaces the player, built from that call's options alone. The queue
|
|
50
|
+
is cleared, and a setup-only field you leave out (`ios.category`,
|
|
51
|
+
`ios.buffer`, `retry`, …) goes back to its default, so pass the full `ios` and
|
|
52
|
+
`retry` set each time.
|
|
42
53
|
|
|
43
54
|
## `updateOptions`
|
|
44
55
|
|
|
@@ -53,27 +64,28 @@ updateOptions({ progressUpdateEventInterval: null }) // disable progress events
|
|
|
53
64
|
updateOptions({ ios: { carPlayNowPlayingButtons: ['repeat'] } })
|
|
54
65
|
```
|
|
55
66
|
|
|
56
|
-
`null`
|
|
67
|
+
`null` means something on two fields:
|
|
57
68
|
`progressUpdateEventInterval: null` disables progress events, and
|
|
58
|
-
`android.remoteButtonLayout: null`
|
|
59
|
-
capabilities
|
|
69
|
+
`android.remoteButtonLayout: null` goes back to the layout derived from
|
|
70
|
+
capabilities. Elsewhere, omit a field to leave it unchanged.
|
|
60
71
|
|
|
61
72
|
## Setup-only vs updatable
|
|
62
73
|
|
|
63
74
|
`updateOptions` can change only a subset. The rest are set in `setupPlayer`
|
|
64
|
-
(call it again to change them later
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
75
|
+
(call it again to change them later; on iOS that call also clears the queue and
|
|
76
|
+
resets any setup-only field you omit, see [`setupPlayer`](#setupplayer)).
|
|
77
|
+
|
|
78
|
+
| Option | `setupPlayer` | `updateOptions` |
|
|
79
|
+
| ------------------------------------------------------------------------------------------------------------ | :-----------: | :-------------: |
|
|
80
|
+
| `capabilities` | ✓ | ✓ |
|
|
81
|
+
| `forwardJumpInterval` / `backwardJumpInterval` | ✓ | ✓ |
|
|
82
|
+
| `progressUpdateEventInterval` | ✓ | ✓ |
|
|
83
|
+
| `android.appKilledPlaybackBehavior` / `skipSilence` / `remoteButtonLayout` | ✓ | ✓ |
|
|
84
|
+
| `ios.playbackRates` / `carPlayUpNextButton` / `carPlayNowPlayingButtons` / `carPlayPlayingIndicatorLocation` | ✓ | ✓ |
|
|
85
|
+
| `nowPlaying` (metadata formatter) | ✓ | — |
|
|
86
|
+
| `playWhenReady`, `repeatMode` (initial values) | ✓ | — |
|
|
87
|
+
| `retry`, `keepSessionAliveOnError`, `remoteOutputs` | ✓ | — |
|
|
88
|
+
| `android` / `ios` audio engine & session (`audioContentType`, `wakeMode`, `category`, …) | ✓ | — |
|
|
77
89
|
|
|
78
90
|
`remoteOutputs` (Android) turns on the outputs of the system Output Switcher
|
|
79
91
|
beyond the phone's own: `{}` lists media route providers' speakers, and
|
|
@@ -81,6 +93,12 @@ beyond the phone's own: `{}` lists media route providers' speakers, and
|
|
|
81
93
|
a `setupPlayer` call, they are off; see
|
|
82
94
|
[Remote outputs](/guide/audio-output#remote-outputs-android).
|
|
83
95
|
|
|
96
|
+
`retry` retries load errors automatically, and is off by default; see
|
|
97
|
+
[Automatic retry](/guide/errors#automatic-retry). `keepSessionAliveOnError`
|
|
98
|
+
(Android, default `true`) keeps the media session and its transport controls
|
|
99
|
+
through a terminal playback error, so Android Auto keeps next and previous on a
|
|
100
|
+
dead stream.
|
|
101
|
+
|
|
84
102
|
`playWhenReady` and `repeatMode` set the _initial_ state; change them at runtime
|
|
85
103
|
with [`setPlayWhenReady`](/guide/playback#play-when-ready) /
|
|
86
104
|
[`setRepeatMode`](/guide/queue#repeat-and-shuffle), not `updateOptions`.
|
|
@@ -111,11 +129,11 @@ updateOptions({
|
|
|
111
129
|
|
|
112
130
|
## Controls & progress
|
|
113
131
|
|
|
114
|
-
| Option | Default | What
|
|
115
|
-
| ----------------------------- | ------- |
|
|
116
|
-
| `forwardJumpInterval` | `15` | Seconds for the jump-forward control.
|
|
117
|
-
| `backwardJumpInterval` | `15` | Seconds for the jump-backward control.
|
|
118
|
-
| `progressUpdateEventInterval` | `null` | Seconds between progress events; `null` disables them — see [Playback → Progress](/guide/playback#progress).
|
|
132
|
+
| Option | Default | What |
|
|
133
|
+
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
134
|
+
| `forwardJumpInterval` | `15` | Seconds for the jump-forward control. With no handler, Android seeks by Media3's fixed increment instead; see [Remote Controls](/guide/remote-controls#overriding-a-control). |
|
|
135
|
+
| `backwardJumpInterval` | `15` | Seconds for the jump-backward control. With no handler, Android seeks by Media3's fixed increment instead; see [Remote Controls](/guide/remote-controls#overriding-a-control). |
|
|
136
|
+
| `progressUpdateEventInterval` | `null` | Seconds between progress events; `null` disables them — see [Playback → Progress](/guide/playback#progress). |
|
|
119
137
|
|
|
120
138
|
## Now Playing
|
|
121
139
|
|
|
@@ -130,30 +148,48 @@ It's **setup-only** (a function can't cross `updateOptions`). See
|
|
|
130
148
|
|
|
131
149
|
## Android options (`android`)
|
|
132
150
|
|
|
133
|
-
| Option | Default
|
|
134
|
-
| --------------------------- |
|
|
135
|
-
| `appKilledPlaybackBehavior` | `'
|
|
136
|
-
| `skipSilence` | `false`
|
|
137
|
-
| `remoteButtonLayout` | `null`
|
|
138
|
-
| `audioContentType` | `'music'`
|
|
139
|
-
| `wakeMode` | `'none'`
|
|
151
|
+
| Option | Default | What |
|
|
152
|
+
| --------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
153
|
+
| `appKilledPlaybackBehavior` | `'stop-playback-and-remove-notification'` | What happens when the app is swiped away (`continue-playback` / `pause-playback` / `stop-playback-and-remove-notification`). |
|
|
154
|
+
| `skipSilence` | `false` | Skip silent segments during playback. |
|
|
155
|
+
| `remoteButtonLayout` | `null` | Explicit button placement (`back` / `forward` / `overflow`); `null` derives it from capabilities — see [Button layout](/guide/remote-controls#button-layout-android). |
|
|
156
|
+
| `audioContentType` | `'music'` | Audio attributes content type (setup-only). |
|
|
157
|
+
| `wakeMode` | `'none'` | CPU/network wake lock during playback (setup-only). |
|
|
158
|
+
| `handleAudioBecomingNoisy` | `true` | Pause when the audio becomes noisy, such as when headphones are unplugged (setup-only). |
|
|
159
|
+
| `maxBuffer` | `50000` | Milliseconds of media the player loads ahead (setup-only). |
|
|
160
|
+
| `minBuffer` | `50000` | Accepted but has no effect; the player always loads up to `maxBuffer` (setup-only). |
|
|
161
|
+
| `playBuffer` | `1000` | Milliseconds that must be buffered to start or resume after a user action such as a seek (setup-only). |
|
|
162
|
+
| `rebufferBuffer` | `null` | Milliseconds that must be buffered to resume after a rebuffer; `null` adapts it to how fast the buffer drained (setup-only). |
|
|
163
|
+
| `backBuffer` | `0` | Milliseconds kept behind the playhead (setup-only). |
|
|
164
|
+
| `maxCacheSize` | `0` | Cache size in MB (setup-only). |
|
|
165
|
+
| `audioOffload` | `false` | Decode on dedicated hardware to save power (setup-only). |
|
|
140
166
|
|
|
141
167
|
## iOS options (`ios`)
|
|
142
168
|
|
|
143
|
-
| Option
|
|
144
|
-
|
|
|
145
|
-
| `playbackRates`
|
|
146
|
-
| `carPlayUpNextButton`
|
|
147
|
-
| `carPlayNowPlayingButtons`
|
|
148
|
-
| `
|
|
169
|
+
| Option | Default | What |
|
|
170
|
+
| --------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
171
|
+
| `playbackRates` | `[0.5, 1.0, 1.5, 2.0]` | Rates offered by the rate control. |
|
|
172
|
+
| `carPlayUpNextButton` | `true` | Show the "Up Next" button on CarPlay (auto-hidden when the queue has one track). |
|
|
173
|
+
| `carPlayNowPlayingButtons` | `[]` | Buttons on the CarPlay now-playing screen, left to right, at most one of each kind: see [CarPlay](/guide/carplay#now-playing-buttons). |
|
|
174
|
+
| `carPlayPlayingIndicatorLocation` | `'leading'` | Where the now-playing indicator draws on CarPlay list rows: `'leading'` in the artwork slot, `'trailing'` at the end of the row — see [CarPlay](/guide/carplay#playing-indicator). |
|
|
175
|
+
| `category` | `'playback'` | iOS audio session category (setup-only). |
|
|
176
|
+
| `categoryMode` | `'default'` | Audio session mode (setup-only). |
|
|
177
|
+
| `categoryOptions` | `[]` | Audio session category options (setup-only). |
|
|
178
|
+
| `categoryPolicy` | `'default'` | Audio session route-sharing policy (setup-only). |
|
|
179
|
+
| `buffer` | `0` | Preferred forward buffer in milliseconds; `0` lets AVPlayer choose (setup-only). |
|
|
149
180
|
|
|
150
181
|
## Reading the current options
|
|
151
182
|
|
|
152
|
-
[`getOptions()`](/api/features/player/#getoptions) returns the
|
|
183
|
+
[`getOptions()`](/api/features/player/#getoptions) returns the current
|
|
153
184
|
[`Options`](/api/features/player/#options) (capabilities, intervals,
|
|
154
185
|
`progressUpdateEventInterval`, and the `android` / `ios` blocks for the current
|
|
155
|
-
platform).
|
|
156
|
-
|
|
186
|
+
platform). `capabilities` holds only the capabilities you set, plus
|
|
187
|
+
`jumpForward` / `jumpBackward: false` on Android and iOS. A missing entry means
|
|
188
|
+
its default from the [Capabilities](#capabilities) table, so test
|
|
189
|
+
`capabilities.play !== false` rather than `capabilities.play === true`.
|
|
190
|
+
|
|
191
|
+
[`useOptions()`](/api/features/player/#useoptions) is the reactive hook;
|
|
192
|
+
[`onOptionsChanged`](/api/features/player/#onoptionschanged) is the
|
|
157
193
|
subscription.
|
|
158
194
|
|
|
159
195
|
```tsx
|
|
@@ -171,9 +207,9 @@ own getters/hooks, e.g. [`useRepeatMode`](/guide/queue#repeat-and-shuffle)).
|
|
|
171
207
|
|
|
172
208
|
## API summary
|
|
173
209
|
|
|
174
|
-
| API | Purpose
|
|
175
|
-
| ------------------------------- |
|
|
176
|
-
| `setupPlayer(options?)` | Initialize (and reconfigure) the player; `async`, once at startup.
|
|
177
|
-
| `updateOptions(options)` | Change runtime options later
|
|
178
|
-
| `getOptions()` / `useOptions()` | Read the
|
|
179
|
-
| `onOptionsChanged` | Subscribe to options changes outside React.
|
|
210
|
+
| API | Purpose |
|
|
211
|
+
| ------------------------------- | ------------------------------------------------------------------ |
|
|
212
|
+
| `setupPlayer(options?)` | Initialize (and reconfigure) the player; `async`, once at startup. |
|
|
213
|
+
| `updateOptions(options)` | Change runtime options later, merged over the current ones. |
|
|
214
|
+
| `getOptions()` / `useOptions()` | Read the current runtime options. |
|
|
215
|
+
| `onOptionsChanged` | Subscribe to options changes outside React. |
|