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/network.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: 'Track the device''s
|
|
2
|
+
description: 'Track the device''s internet connectivity with useOnline, getOnline, and onOnlineChanged, and what "online" means on each platform.'
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Network
|
|
6
6
|
|
|
7
|
-
The library tracks the device's internet connectivity with a
|
|
7
|
+
The library tracks the device's internet connectivity with a platform monitor and
|
|
8
8
|
exposes it three ways:
|
|
9
9
|
|
|
10
10
|
- [`useOnline()`](/api/features/network/#useonline) — a reactive hook for your UI.
|
|
@@ -12,15 +12,26 @@ exposes it three ways:
|
|
|
12
12
|
- [`onOnlineChanged`](/api/features/network/#ononlinechanged) — subscribe to
|
|
13
13
|
changes outside React.
|
|
14
14
|
|
|
15
|
-
All three report the same boolean
|
|
16
|
-
connection. **"Online" means _validated_ internet, not just "connected to a
|
|
17
|
-
network".** Android is strict here — it requires the OS to confirm the network
|
|
18
|
-
actually reaches the internet, so Wi-Fi with no real connectivity reads as
|
|
19
|
-
`false`. iOS derives the signal from the system path monitor (`NWPathMonitor`),
|
|
20
|
-
which is slightly more permissive about such captive networks.
|
|
15
|
+
All three report the same boolean, but each platform decides it differently:
|
|
21
16
|
|
|
22
|
-
|
|
23
|
-
|
|
17
|
+
- **Android** asks the OS whether the default network is _validated_: it must
|
|
18
|
+
actually reach the internet, so Wi-Fi with no internet behind it reads
|
|
19
|
+
`false`.
|
|
20
|
+
- **iOS** reads the system path monitor (`NWPathMonitor`), which reports
|
|
21
|
+
whether a usable network path exists. It does not check that the internet is
|
|
22
|
+
reachable, so a captive or dead Wi-Fi can read `true`.
|
|
23
|
+
- **Web** reads `navigator.onLine` and the window's `online` and `offline`
|
|
24
|
+
events, which only say whether a network interface is up.
|
|
25
|
+
|
|
26
|
+
::: warning Android: only after setupPlayer()
|
|
27
|
+
On Android the connectivity monitor belongs to the player, so it runs only once
|
|
28
|
+
`setupPlayer()` has connected the player service.
|
|
29
|
+
|
|
30
|
+
Before that, and while the service restarts, `getOnline()` and `useOnline()`
|
|
31
|
+
read `true` even when the device is offline, and `onOnlineChanged` doesn't
|
|
32
|
+
fire. Once the service connects, `onOnlineChanged` fires with the current
|
|
33
|
+
state. iOS and web report the real state from the start.
|
|
34
|
+
:::
|
|
24
35
|
|
|
25
36
|
## In your UI
|
|
26
37
|
|
|
@@ -63,13 +74,18 @@ these up for playback:
|
|
|
63
74
|
- When the connection drops mid-stream, the now-playing formatter receives
|
|
64
75
|
`stalled: 'offline'` (vs `'buffering'` when online) — see
|
|
65
76
|
[Now Playing → the formatter](/guide/now-playing#the-formatter-derived-continuous).
|
|
66
|
-
-
|
|
67
|
-
`'buffering'` with play intent), the player re-establishes it automatically
|
|
68
|
-
you don't need to listen for reconnect and re-`play()`.
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
77
|
+
- On iOS, when the connection returns while the stream sits **stalled** (state
|
|
78
|
+
`'buffering'` with play intent), the player re-establishes it automatically:
|
|
79
|
+
you don't need to listen for reconnect and re-`play()`.
|
|
80
|
+
|
|
81
|
+
On Android, most drops surface as a playback **error** instead, and the
|
|
82
|
+
reconnect when connectivity returns only runs with
|
|
83
|
+
[automatic retry](/guide/errors#automatic-retry)
|
|
84
|
+
(`setupPlayer({ retry })`, off by default) enabled. See
|
|
85
|
+
[Live streams → Dropouts](/guide/live-streams#dropouts-stalls-and-retry).
|
|
86
|
+
|
|
87
|
+
Once retry gives up, or without it, the player stays in `'error'` until the
|
|
88
|
+
listener (or your code) calls `retry()` or `play()`.
|
|
73
89
|
|
|
74
90
|
Reach for `useOnline` / `onOnlineChanged` for **your own** UI and data — an
|
|
75
91
|
offline banner, disabling a control, refetching a list on reconnect.
|
|
@@ -79,8 +95,8 @@ offline banner, disabling a control, refetching a list on reconnect.
|
|
|
79
95
|
| API | Purpose |
|
|
80
96
|
| ----------------- | --------------------------------------------------------------------- |
|
|
81
97
|
| `useOnline()` | Reactive `boolean`; re-renders on connectivity change. |
|
|
82
|
-
| `getOnline()` | One-off snapshot `boolean
|
|
98
|
+
| `getOnline()` | One-off snapshot `boolean` (`true` on Android before setup). |
|
|
83
99
|
| `onOnlineChanged` | Subscribe outside React; `addListener(cb)` returns an unsubscribe fn. |
|
|
84
100
|
|
|
85
|
-
`true` =
|
|
86
|
-
with no
|
|
101
|
+
`true` = online by the platform's definition above; `false` = offline
|
|
102
|
+
(including a network with no internet behind it on Android).
|
|
@@ -4,7 +4,9 @@ description: 'What the system surfaces show: which metadata field lands where, t
|
|
|
4
4
|
|
|
5
5
|
# Now Playing
|
|
6
6
|
|
|
7
|
-
The now-playing surface is everything that displays the current track on the _system's_ surfaces: the iOS lock screen and Control Center, the Android notification, CarPlay and Android Auto's Now Playing screens, and Bluetooth head units.
|
|
7
|
+
The now-playing surface is everything that displays the current track on the _system's_ surfaces: the iOS lock screen and Control Center, the Android notification, CarPlay and Android Auto's Now Playing screens, and Bluetooth head units.
|
|
8
|
+
|
|
9
|
+
The library publishes one metadata dictionary and the _operating system_ renders it. Each surface picks different fields, composes them differently, and ignores the rest. Your own app can read the same metadata: see [Reading now-playing in your own UI](#reading-now-playing-in-your-own-ui).
|
|
8
10
|
|
|
9
11
|
This guide covers: **which fields land where** (the static matrix), **the four layers that decide what those fields contain at any moment** (the dynamic model), and **reading the result back** in your own UI.
|
|
10
12
|
|
|
@@ -22,32 +24,40 @@ Apple and Google document very little of this; the table below reflects observed
|
|
|
22
24
|
|
|
23
25
|
The time scrubber (elapsed, duration, playback rate) is not driven by track fields at all — every surface derives it from the player itself. `Track.duration` is informational metadata for your app (echoed back through now-playing events); it does not affect the scrubber.
|
|
24
26
|
|
|
25
|
-
`artwork` is the URL you _set_ on a track.
|
|
27
|
+
`artwork` is the URL you _set_ on a track. On iOS and Android, surfaces show the resolved image, not the raw URL. On web, the Media Session gets the raw URL. The layers below cannot change it: see [Now-playing artwork](#now-playing-artwork).
|
|
26
28
|
|
|
27
29
|
## The four metadata layers
|
|
28
30
|
|
|
29
|
-
What actually renders is decided by a fixed priority order. Each layer only overrides the fields it sets
|
|
31
|
+
What actually renders is decided by a fixed priority order. Each layer only overrides the fields it sets. A field it leaves `undefined` falls through to the layer below, except under a flash (see [the flash](#the-flash-transient-top-priority)):
|
|
30
32
|
|
|
31
|
-
| Priority | Layer | API | Lifetime
|
|
32
|
-
| ------------ | ---------------- | -------------------------------------- |
|
|
33
|
-
| 1 (highest) | **Flash** | `flashNowPlaying(update, durationMs)` | `durationMs`, on a native timer
|
|
34
|
-
| 2 | **Formatter** | `setupPlayer({ nowPlaying })` | as long as it's configured
|
|
35
|
-
| 3 | **Override** | `updateNowPlaying(update)` | until cleared or the track changes
|
|
36
|
-
| 4 (baseline) | **Track fields** | `Track.title` / `artist` / `album` / … | the track's time as the active track
|
|
33
|
+
| Priority | Layer | API | Lifetime |
|
|
34
|
+
| ------------ | ---------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
35
|
+
| 1 (highest) | **Flash** | `flashNowPlaying(update, durationMs)` | `durationMs`, on a native timer (web: see [the flash](#the-flash-transient-top-priority)) |
|
|
36
|
+
| 2 | **Formatter** | `setupPlayer({ nowPlaying })` | as long as it's configured |
|
|
37
|
+
| 3 | **Override** | `updateNowPlaying(update)` | until cleared or the track changes |
|
|
38
|
+
| 4 (baseline) | **Track fields** | `Track.title` / `artist` / `album` / … | the track's time as the active track |
|
|
37
39
|
|
|
38
|
-
### Track fields
|
|
40
|
+
### Track fields: the baseline
|
|
39
41
|
|
|
40
42
|
With nothing else configured, the active track's own fields are published as-is. For on-demand content this is usually all you need.
|
|
41
43
|
|
|
42
|
-
### The formatter
|
|
44
|
+
### The formatter: derived, continuous
|
|
45
|
+
|
|
46
|
+
The [`nowPlaying`](/api/features/player/#formatnowplayingcallback) formatter hands you the now-playing text lines outright. The library calls it again whenever the lines could change:
|
|
47
|
+
|
|
48
|
+
- on a track change
|
|
49
|
+
- on every timed-metadata update
|
|
50
|
+
- on every playback transition: play / pause, a stall starting or recovering, an error
|
|
51
|
+
- on connectivity changes
|
|
43
52
|
|
|
44
|
-
|
|
53
|
+
It's the right layer for anything _derived from playback state_: the live song from ICY/ID3 metadata, a "Reconnecting…" line during a stall, an error message:
|
|
45
54
|
|
|
46
55
|
```ts
|
|
47
56
|
setupPlayer({
|
|
48
57
|
nowPlaying: ({ timedMetadata, playWhenReady, stalled, error }) => {
|
|
49
|
-
// `yourErrorLine` is your own kind→copy mapping
|
|
50
|
-
// never `error.message`, which is developer English
|
|
58
|
+
// `yourErrorLine` is your own kind→copy mapping. Branch on
|
|
59
|
+
// `error.kind`, never `error.message`, which is developer English
|
|
60
|
+
// and never localized.
|
|
51
61
|
// This line is read by listeners, on the lock screen and in the car.
|
|
52
62
|
// See [Playback errors](/guide/errors#playback-errors).
|
|
53
63
|
if (error) return { artist: yourErrorLine(error.kind) }
|
|
@@ -66,27 +76,33 @@ setupPlayer({
|
|
|
66
76
|
|
|
67
77
|
The callback receives a single [`FormatNowPlayingParams`](/api/features/player/#formatnowplayingparams) object:
|
|
68
78
|
|
|
69
|
-
| Field | Type | Meaning
|
|
70
|
-
| --------------- | ---------------- |
|
|
71
|
-
| `track` | `Track` | The currently playing track.
|
|
72
|
-
| `timedMetadata` | `TimedMetadata?` | The ICY / ID3 "now playing song", if any.
|
|
73
|
-
| `playWhenReady` | `boolean` | Play/pause intent — stays `true` through buffers, so the song line won't flicker.
|
|
74
|
-
| `stalled` | `StallReason?` | Truthy only during a mid-stream stall: `'buffering'` (rebuffering while online) or `'offline'` (no connectivity). Use `if (stalled)`, compare `=== 'offline'` for the reason.
|
|
75
|
-
| `error` | `PlaybackError?` | The current playback error, if playback failed. Switch on `error.kind` to pick your own localized line
|
|
79
|
+
| Field | Type | Meaning |
|
|
80
|
+
| --------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
|
+
| `track` | `Track` | The currently playing track. |
|
|
82
|
+
| `timedMetadata` | `TimedMetadata?` | The ICY / ID3 "now playing song", if any. On iOS, also a file's own tags when the file has no chapters. |
|
|
83
|
+
| `playWhenReady` | `boolean` | Play/pause intent — stays `true` through buffers, so the song line won't flicker. |
|
|
84
|
+
| `stalled` | `StallReason?` | Truthy only during a mid-stream stall: `'buffering'` (rebuffering while online) or `'offline'` (no connectivity). Use `if (stalled)`, compare `=== 'offline'` for the reason. |
|
|
85
|
+
| `error` | `PlaybackError?` | The current playback error, if playback failed. Switch on `error.kind` to pick your own localized line: see [Playback errors](/guide/errors#playback-errors). |
|
|
76
86
|
|
|
77
|
-
|
|
87
|
+
While [automatic retry](/guide/errors#automatic-retry) is still working, `error` carries the advisory error (`error.retrying === true`). The formatter runs again when that error arrives, changes and clears. So you can show provisional copy ("Retrying…") that becomes the final line when the player gives up.
|
|
88
|
+
|
|
89
|
+
It returns a [`NowPlayingUpdate`](/api/features/metadata/#nowplayingupdate) (`{ title?, artist?, album? }`) or `undefined`. The callback is synchronous and should stay cheap: a pure formatting function, no I/O.
|
|
90
|
+
|
|
91
|
+
Each returned field falls back **independently** to the track's value when omitted. Returning `undefined` (or `{}`) uses the track default entirely. Identical results across a rapid burst of transitions are de-duplicated natively, so they won't flicker the surface.
|
|
78
92
|
|
|
79
93
|
Timed metadata is never auto-applied: the library surfaces ICY (Shoutcast/Icecast) and in-band ID3 (HLS) frames to your code, and the formatter is where you decide what reaches the now-playing line. (To consume those frames outside the formatter, subscribe to [`onTimedMetadata`](/api/features/metadata/#ontimedmetadata).)
|
|
80
94
|
|
|
81
|
-
### The override
|
|
95
|
+
### The override: imperative, sticky
|
|
82
96
|
|
|
83
97
|
[`updateNowPlaying({ artist: '…' })`](/api/features/nowPlaying/#updatenowplaying) pins fields until you pass `null` or the track changes. It's the layer to reach for when you _don't_ configure a formatter.
|
|
84
98
|
|
|
85
|
-
**If a formatter is configured, it outranks the override
|
|
99
|
+
**If a formatter is configured, it outranks the override.** The formatter's result is applied on top, falling back per-field to `override ?? track`. With a formatter in place, feed it state instead of calling `updateNowPlaying` around it. Prefer the formatter for anything derived from playback state.
|
|
100
|
+
|
|
101
|
+
### The flash: transient, top priority
|
|
86
102
|
|
|
87
|
-
|
|
103
|
+
[`flashNowPlaying(update, durationMs)`](/api/features/nowPlaying/#flashnowplaying) is the toast of the now-playing world: it briefly replaces the fields it sets, then reverts to whatever the lower layers say.
|
|
88
104
|
|
|
89
|
-
|
|
105
|
+
External surfaces have no notification primitive, so a transient metadata swap is the only way to give feedback there. The canonical use is answering a refused remote command:
|
|
90
106
|
|
|
91
107
|
```ts
|
|
92
108
|
// A radio product with an hourly skip allowance:
|
|
@@ -101,12 +117,20 @@ handleRemoteNext(() => {
|
|
|
101
117
|
|
|
102
118
|
Three properties make it a dedicated layer rather than sugar over `updateNowPlaying`:
|
|
103
119
|
|
|
104
|
-
- **It outranks the formatter.** While a flash is active the formatter pass is skipped
|
|
120
|
+
- **It outranks the formatter.** While a flash is active the formatter pass is skipped, so a live station's next metadata tick can't overwrite the message mid-window. Fields the flash leaves unset come from the override or the track, not from the formatter. Set every line you want to keep.
|
|
105
121
|
- **The revert runs on a native timer.** A JS `setTimeout` pauses with a backgrounded host on Android — and remote commands from the lock screen arrive exactly when the host is backgrounded. The native timer fires regardless.
|
|
106
122
|
- **A track change clears it early.** A flash is feedback about a moment; it never carries over to a new track.
|
|
107
123
|
|
|
108
124
|
Repeated calls restart the window. [`clearNowPlayingFlash()`](/api/features/nowPlaying/#clearnowplayingflash) cancels one imperatively — for example when the condition the flash complained about resolves mid-window.
|
|
109
125
|
|
|
126
|
+
::: warning Web and `nowPlaying: false`
|
|
127
|
+
The three properties above hold on iOS and Android. On web, a flash is an `updateNowPlaying` override with a JS timer. It replaces any override you set, and the revert (or `clearNowPlayingFlash()`) clears the override instead of restoring it.
|
|
128
|
+
|
|
129
|
+
A track change doesn't cancel the timer, so a pending revert also clears an override you set for the next track.
|
|
130
|
+
|
|
131
|
+
With `nowPlaying: false`, Android ignores the flash, while iOS still shows it.
|
|
132
|
+
:::
|
|
133
|
+
|
|
110
134
|
## Reading now-playing in your own UI
|
|
111
135
|
|
|
112
136
|
The metadata you publish is also what your own app should render — a mini-player, a full-screen "now playing" view — so the in-app UI matches the lock screen exactly, formatter and all. Use the [`useNowPlaying`](/api/features/nowPlaying/#usenowplaying) hook:
|
|
@@ -126,15 +150,19 @@ function MiniPlayer() {
|
|
|
126
150
|
}
|
|
127
151
|
```
|
|
128
152
|
|
|
129
|
-
`useNowPlaying` returns the resolved [`NowPlayingMetadata`](/api/features/metadata/#nowplayingmetadata)
|
|
153
|
+
`useNowPlaying` returns the resolved [`NowPlayingMetadata`](/api/features/metadata/#nowplayingmetadata): the same dictionary the system surfaces see, _after_ the four layers are applied. The exception is `nowPlaying: false` on iOS and Android: the hook still reports an `updateNowPlaying` override the surface ignores (on Android, a flash too). It returns `undefined` when there is no active track. It carries `title` / `artist` / `album` / `artwork`.
|
|
130
154
|
|
|
131
|
-
|
|
155
|
+
It also carries `elapsedTime`, but only on iOS, and it is not a live position. For the scrubber position, use [`useProgress`](/guide/playback#progress).
|
|
132
156
|
|
|
133
|
-
|
|
157
|
+
Outside React, [`getNowPlaying()`](/api/features/nowPlaying/#getnowplaying) reads a snapshot. [`onNowPlayingChanged`](/api/features/nowPlaying/#onnowplayingchanged) fires whenever the published lines change: a new track, a formatter result, an override, or a flash starting or ending.
|
|
158
|
+
|
|
159
|
+
To render artwork, don't use this `artwork` field: it is a plain URL string, and on Android and web it is the track's `artwork` before your artwork config resolves it. Use the active track's `artworkSource` (`<Image source={track.artworkSource} />`). See [Track](/guide/track).
|
|
134
160
|
|
|
135
161
|
## Gotchas worth knowing
|
|
136
162
|
|
|
137
|
-
**CarPlay's tappable line renders from `album`.** When a track has an `albumPath` (or `resolveAlbumPath` returns a path), the _album line_ becomes tappable
|
|
163
|
+
**CarPlay's tappable line renders from `album`.** When a track has an `albumPath` (or `resolveAlbumPath` returns a path), the _album line_ becomes tappable. It renders as a third metadata line with a chevron and navigates the browse stack.
|
|
164
|
+
|
|
165
|
+
A track without an `album` has no such line, so there is nothing to tap even though a destination exists. See the [CarPlay guide](/guide/carplay#album-line-navigation).
|
|
138
166
|
|
|
139
167
|
**The iOS lock screen never shows `album`.** Its secondary line comes from `artist` alone. If you move information from `artist` to `album` (for example to feed the CarPlay button line), it disappears from the lock screen.
|
|
140
168
|
|
|
@@ -142,15 +170,15 @@ To render artwork, don't use this `artwork` field directly — it's a raw URL st
|
|
|
142
170
|
|
|
143
171
|
**One metadata dictionary feeds every surface.** There is no per-surface metadata: whatever you publish appears (or doesn't) everywhere simultaneously, per the table above. You cannot hide a field from one surface without hiding it from all of them.
|
|
144
172
|
|
|
145
|
-
**A formatter quietly disables `updateNowPlaying` for the fields it returns.** See [the override](#the-override
|
|
173
|
+
**A formatter quietly disables `updateNowPlaying` for the fields it returns.** See [the override](#the-override-imperative-sticky): the formatter's result wins per-field. If a line you set imperatively keeps reverting, a formatter is overwriting it; either move that logic into the formatter or use `flashNowPlaying` if it was meant to be transient.
|
|
146
174
|
|
|
147
175
|
**Browse lists are separate.** `subtitle` drives browse-list rows (CarPlay list detail text, Android Auto list subtitle) and is never shown on now-playing surfaces; `artist` drives now-playing and is never shown in browse lists. Neither falls back to the other.
|
|
148
176
|
|
|
149
177
|
## Now-playing artwork
|
|
150
178
|
|
|
151
|
-
Artwork is the one surface field the text layers (formatter / override / flash) can't touch
|
|
179
|
+
Artwork is the one surface field the text layers (formatter / override / flash) can't touch: they carry only `title` / `artist` / `album`. On iOS and Android, surfaces show the active track's resolved artwork, `artworkSource`. That is the track's `artwork` after your [artwork configuration](/guide/browser#media-and-artwork) transforms it. On web, the Media Session gets the track's raw `artwork` URL (the `dark` one of a pair), which neither artwork config touches.
|
|
152
180
|
|
|
153
|
-
By default that's the same image as the track's browse-list thumbnail. To resolve it differently
|
|
181
|
+
By default that's the same image as the track's browse-list thumbnail. To resolve it differently, set the `nowPlayingArtwork` config kind. It builds the now-playing image from its own request (e.g. `{ path: '/artwork/{id}' }`), for example a larger, lock-screen-quality image that does not bloat list thumbnails:
|
|
154
182
|
|
|
155
183
|
```ts
|
|
156
184
|
configureBrowser({
|
|
@@ -163,13 +191,13 @@ See [`BrowserConfiguration.nowPlayingArtwork`](/api/types/browser/#browserconfig
|
|
|
163
191
|
|
|
164
192
|
## API summary
|
|
165
193
|
|
|
166
|
-
| API | Purpose
|
|
167
|
-
| ----------------------------------------- |
|
|
168
|
-
| `setupPlayer({ nowPlaying })` | Configure the formatter
|
|
169
|
-
| `updateNowPlaying(update \| null)` | Imperatively override fields; `null` clears.
|
|
170
|
-
| `flashNowPlaying(update, durationMs)` | Transient, top-priority swap (refused-command feedback).
|
|
171
|
-
| `clearNowPlayingFlash()` | Cancel an active flash early.
|
|
172
|
-
| `useNowPlaying()` / `getNowPlaying()` | Read the resolved metadata in your own UI.
|
|
173
|
-
| `onNowPlayingChanged` | Subscribe to metadata changes outside React.
|
|
174
|
-
| `onTimedMetadata` | Subscribe to ICY / ID3 stream metadata directly.
|
|
175
|
-
| `configureBrowser({ nowPlayingArtwork })` | Resolve now-playing artwork from its own request.
|
|
194
|
+
| API | Purpose |
|
|
195
|
+
| ----------------------------------------- | ----------------------------------------------------------- |
|
|
196
|
+
| `setupPlayer({ nowPlaying })` | Configure the formatter: derived lines from playback state. |
|
|
197
|
+
| `updateNowPlaying(update \| null)` | Imperatively override fields; `null` clears. |
|
|
198
|
+
| `flashNowPlaying(update, durationMs)` | Transient, top-priority swap (refused-command feedback). |
|
|
199
|
+
| `clearNowPlayingFlash()` | Cancel an active flash early. |
|
|
200
|
+
| `useNowPlaying()` / `getNowPlaying()` | Read the resolved metadata in your own UI. |
|
|
201
|
+
| `onNowPlayingChanged` | Subscribe to metadata changes outside React. |
|
|
202
|
+
| `onTimedMetadata` | Subscribe to ICY / ID3 stream metadata directly. |
|
|
203
|
+
| `configureBrowser({ nowPlayingArtwork })` | Resolve now-playing artwork from its own request. |
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: 'Control the active track — play, pause, stop, seek, playback state, progress, rate, and volume —
|
|
2
|
+
description: 'Control the active track — play, pause, stop, seek, playback state, progress, rate, and volume — and how playback handles the background, interruptions, and audio focus.'
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Playback
|
|
@@ -7,14 +7,25 @@ description: 'Control the active track — play, pause, stop, seek, playback sta
|
|
|
7
7
|
This guide covers **controlling the active track** — transport (play / pause /
|
|
8
8
|
stop), seeking, playback state, progress, rate, and volume. It's the toolkit for
|
|
9
9
|
building your own player UI.
|
|
10
|
+
[A later section](#background-audio-interruptions-and-audio-focus) covers what
|
|
11
|
+
the library handles for you: background audio, interruptions, and audio focus.
|
|
10
12
|
|
|
11
13
|
Playback acts on whatever the **active track** is. _Which_ track that is — and
|
|
12
|
-
moving between tracks with next/previous — belongs to the
|
|
14
|
+
moving between tracks with next/previous — belongs to the
|
|
15
|
+
[queue](/guide/queue#moving-between-tracks);
|
|
13
16
|
this page is about playing the one that's already active. The system surfaces
|
|
14
17
|
(lock screen, notification, car) are covered in [Now Playing](/guide/now-playing).
|
|
15
18
|
|
|
16
|
-
> All functions here are synchronous
|
|
17
|
-
>
|
|
19
|
+
> All functions here are synchronous. Called with no track loaded, they don't
|
|
20
|
+
> throw: `pause`, `stop` and the seek calls do nothing, and `setPlayWhenReady`,
|
|
21
|
+
> `setRate` and `setVolume` keep their value for the next track. `play()` and
|
|
22
|
+
> `togglePlayback()` raise the play intent as `setPlayWhenReady(true)` does, so
|
|
23
|
+
> the next track loaded starts playing (on web, Chrome keeps that intent and
|
|
24
|
+
> Firefox drops it). On iOS and Android, play, pause, stop, seek, rate and
|
|
25
|
+
> volume calls made before `setupPlayer` has resolved are dropped; on web they
|
|
26
|
+
> throw `SetupNotCalledError`. On every platform `setPlayWhenReady` is kept and
|
|
27
|
+
> applied at setup. Two have argument rules: `setRate` and
|
|
28
|
+
> `trackPlaybackTime`, both covered below.
|
|
18
29
|
|
|
19
30
|
The UI snippets below import `useState` from `react`, `Text` / `Button` /
|
|
20
31
|
`Switch` from `react-native`, and `Slider` from
|
|
@@ -29,12 +40,15 @@ import { play, pause, togglePlayback, stop } from 'react-native-audio-browser'
|
|
|
29
40
|
play() // play or resume the active track
|
|
30
41
|
pause() // pause, keeping position
|
|
31
42
|
togglePlayback() // flip between play and pause
|
|
32
|
-
stop() // stop
|
|
43
|
+
stop() // stop; the track stays loaded
|
|
33
44
|
```
|
|
34
45
|
|
|
35
|
-
`stop` keeps the track loaded
|
|
36
|
-
|
|
37
|
-
|
|
46
|
+
`stop` keeps the track loaded, and what `play()` does afterwards depends on the
|
|
47
|
+
platform. On iOS, `stop` rewinds a non-live track to the start, so `play()`
|
|
48
|
+
plays it from the beginning. On Android and web the position is kept, so
|
|
49
|
+
`play()` resumes where it stopped.
|
|
50
|
+
|
|
51
|
+
`stop` is not the same as `reset`, which stops playback **and clears the queue**:
|
|
38
52
|
|
|
39
53
|
```ts
|
|
40
54
|
import { reset } from 'react-native-audio-browser'
|
|
@@ -42,11 +56,11 @@ import { reset } from 'react-native-audio-browser'
|
|
|
42
56
|
reset() // tear down: stop + empty the queue
|
|
43
57
|
```
|
|
44
58
|
|
|
45
|
-
| | Position
|
|
46
|
-
| --------- |
|
|
47
|
-
| `pause()` | kept
|
|
48
|
-
| `stop()` | reset to start | yes | kept |
|
|
49
|
-
| `reset()` | —
|
|
59
|
+
| | Position | Track stays loaded | Queue |
|
|
60
|
+
| --------- | ---------------------------------------------- | ------------------ | ------- |
|
|
61
|
+
| `pause()` | kept | yes | kept |
|
|
62
|
+
| `stop()` | reset to start on iOS; kept on Android and web | yes | kept |
|
|
63
|
+
| `reset()` | — | no | cleared |
|
|
50
64
|
|
|
51
65
|
## Seeking
|
|
52
66
|
|
|
@@ -70,7 +84,7 @@ seekToLiveEdge()
|
|
|
70
84
|
```
|
|
71
85
|
|
|
72
86
|
Moving between tracks (next / previous / skip) is part of the
|
|
73
|
-
[queue](/guide/
|
|
87
|
+
[queue](/guide/queue#moving-between-tracks), not seeking.
|
|
74
88
|
|
|
75
89
|
## Playback state
|
|
76
90
|
|
|
@@ -101,8 +115,13 @@ function PlayerStatus() {
|
|
|
101
115
|
}
|
|
102
116
|
```
|
|
103
117
|
|
|
104
|
-
`retry()`
|
|
105
|
-
|
|
118
|
+
`retry()` is meant for the `'error'` state, where it re-attempts the current
|
|
119
|
+
item. It isn't gated on that state.
|
|
120
|
+
|
|
121
|
+
On iOS it reloads the current item in any state, even while playing. On Android
|
|
122
|
+
and web it reloads whenever the player is stopped or failed, without raising the
|
|
123
|
+
play intent, so after `stop()` it loads the track but doesn't play it. See [Errors](/guide/errors#manual-retry) for the
|
|
124
|
+
error shape and handling.
|
|
106
125
|
|
|
107
126
|
### Just playing or buffering?
|
|
108
127
|
|
|
@@ -128,13 +147,18 @@ function PlayPauseButton() {
|
|
|
128
147
|
### Play-when-ready
|
|
129
148
|
|
|
130
149
|
`playWhenReady` is the **intent** to play, separate from whether audio is
|
|
131
|
-
actually coming out yet (it may still be loading or buffering). Setting it
|
|
132
|
-
|
|
150
|
+
actually coming out yet (it may still be loading or buffering). Setting it does
|
|
151
|
+
what `play()` / `pause()` do, with two exceptions. Before `setupPlayer`
|
|
152
|
+
resolves, `setPlayWhenReady` is kept and applied at setup, while `play()` is
|
|
153
|
+
dropped on iOS and Android and throws on web.
|
|
154
|
+
|
|
155
|
+
On Android, `setPlayWhenReady(true)` doesn't restart a stopped or failed player;
|
|
156
|
+
`play()` or `retry()` does:
|
|
133
157
|
|
|
134
158
|
```tsx
|
|
135
159
|
import { setPlayWhenReady, usePlayWhenReady } from 'react-native-audio-browser'
|
|
136
160
|
|
|
137
|
-
setPlayWhenReady(true) //
|
|
161
|
+
setPlayWhenReady(true) // raise the intent to play
|
|
138
162
|
|
|
139
163
|
function PlayToggle() {
|
|
140
164
|
const wantsToPlay = usePlayWhenReady()
|
|
@@ -147,9 +171,13 @@ function PlayToggle() {
|
|
|
147
171
|
}
|
|
148
172
|
```
|
|
149
173
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
174
|
+
`usePlayWhenReady` is the raw intent: it stays `true` after an error.
|
|
175
|
+
`usePlayingState().playing` is that intent only while a
|
|
176
|
+
track can play, so it goes `false` in the `'error'`, `'ended'`, `'none'` and
|
|
177
|
+
`'stopped'` states.
|
|
178
|
+
|
|
179
|
+
Both flip the instant the user taps. Neither says whether
|
|
180
|
+
sound is coming out yet; `buffering` does.
|
|
153
181
|
|
|
154
182
|
## Progress
|
|
155
183
|
|
|
@@ -212,7 +240,9 @@ getRate() // → current rate
|
|
|
212
240
|
```
|
|
213
241
|
|
|
214
242
|
Rate is a speed multiplier, not a transport control: it's independent of
|
|
215
|
-
play/pause, and setting it while paused doesn't start playback.
|
|
243
|
+
play/pause, and setting it while paused doesn't start playback.
|
|
244
|
+
|
|
245
|
+
Pass a value
|
|
216
246
|
greater than zero — the platforms disagree on what a non-positive rate does
|
|
217
247
|
(iOS ignores it, Android throws, web stalls the audio element), so treat it as
|
|
218
248
|
unsupported rather than as a way to pause.
|
|
@@ -277,7 +307,8 @@ function SystemVolumeLabel() {
|
|
|
277
307
|
|
|
278
308
|
`setSystemVolume` is a **no-op on iOS** — Apple provides no public API to set
|
|
279
309
|
the system volume (use the player volume there instead). Reading it and
|
|
280
|
-
`useSystemVolume` work on
|
|
310
|
+
`useSystemVolume` work on iOS and Android. On web, `setSystemVolume` does
|
|
311
|
+
nothing, and `getSystemVolume` and `useSystemVolume` always return `1`.
|
|
281
312
|
|
|
282
313
|
## Measuring listening time
|
|
283
314
|
|
|
@@ -300,29 +331,75 @@ const cancel = trackPlaybackTime(({ total, sinceLast, track }) => {
|
|
|
300
331
|
cancel()
|
|
301
332
|
```
|
|
302
333
|
|
|
303
|
-
`period` must be `>= 1` (it throws otherwise).
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
334
|
+
`period` must be `>= 1` (it throws otherwise). On Android, subscribe after
|
|
335
|
+
`setupPlayer` has resolved. A subscription made earlier never fires, even once
|
|
336
|
+
the player is up, and neither does one that was active while the playback
|
|
337
|
+
service restarted. To get ticks again, cancel every subscription and subscribe
|
|
338
|
+
once more.
|
|
339
|
+
|
|
340
|
+
`total` counts from when you subscribed, across every track that plays: it
|
|
341
|
+
keeps climbing through track changes. To measure per track, cancel and
|
|
342
|
+
re-subscribe whenever the [active track changes](/guide/queue#the-active-track). It's a coarse,
|
|
343
|
+
~1-second-resolution signal, not a precise timer.
|
|
344
|
+
|
|
345
|
+
`track` is the active track as of the latest track change since the first
|
|
346
|
+
`trackPlaybackTime` subscription. If the first subscription starts while a track
|
|
347
|
+
is already playing, it is `undefined` until the next track change.
|
|
348
|
+
|
|
349
|
+
## Background audio, interruptions and audio focus
|
|
350
|
+
|
|
351
|
+
Playback carries on with your app in the background and the screen locked:
|
|
352
|
+
|
|
353
|
+
- **iOS** needs the `audio` background mode in your app's `Info.plist` (see
|
|
354
|
+
[Getting Started](/guide/getting-started#installation)). The audio session
|
|
355
|
+
category defaults to `'playback'`; `ios.category`, `categoryMode`,
|
|
356
|
+
`categoryOptions` and `categoryPolicy` change it at setup
|
|
357
|
+
([iOS options](/guide/configuration#ios-options-ios)).
|
|
358
|
+
- **Android** plays from the library's foreground media service, which its
|
|
359
|
+
merged manifest declares. What happens when the app is swiped away is set by
|
|
360
|
+
`android.appKilledPlaybackBehavior`
|
|
361
|
+
([Android options](/guide/configuration#android-options-android)).
|
|
362
|
+
|
|
363
|
+
On iOS, the library activates the audio session when playback starts (on
|
|
364
|
+
`play()`, not at setup), so launching your app doesn't stop other apps' audio. It releases the
|
|
365
|
+
session about 3 seconds after playback stops, so their audio can come back.
|
|
366
|
+
|
|
367
|
+
**Interruptions** (a phone call, an alarm, another app starting audio) are
|
|
368
|
+
handled natively, with nothing to wire up:
|
|
369
|
+
|
|
370
|
+
- On **iOS**, an interruption pauses playback. When it ends, playback resumes
|
|
371
|
+
if iOS says it should and the player was playing when it began; otherwise it
|
|
372
|
+
stays paused.
|
|
373
|
+
- On **Android**, the player holds audio focus. It pauses while another app
|
|
374
|
+
holds focus briefly and resumes when focus returns. It pauses when another
|
|
375
|
+
app takes focus for good. It lowers its volume under a short sound such as a
|
|
376
|
+
notification, or pauses instead with `android.audioContentType: 'speech'`.
|
|
377
|
+
|
|
378
|
+
When the output disappears (headphones unplugged, a Bluetooth speaker switched
|
|
379
|
+
off), playback pauses; see
|
|
380
|
+
[Audio Output](/guide/audio-output#you-may-not-need-this-for-unplug-handling).
|
|
381
|
+
On Android, `android.handleAudioBecomingNoisy: false` turns that off.
|
|
309
382
|
|
|
310
383
|
## API summary
|
|
311
384
|
|
|
312
385
|
| API | Purpose |
|
|
313
386
|
| ----------------------------------------------- | ----------------------------------------------------------------------- |
|
|
314
387
|
| `play()` / `pause()` / `togglePlayback()` | Start, pause, or flip playback. |
|
|
315
|
-
| `stop()` | Stop
|
|
388
|
+
| `stop()` | Stop; track stays loaded (position resets to the start on iOS only). |
|
|
316
389
|
| `reset()` | Stop **and** clear the queue. |
|
|
317
390
|
| `seekTo(seconds)` / `seekBy(offset)` | Seek to an absolute / relative position. |
|
|
318
391
|
| `seekToLiveEdge()` | Jump to the live edge (no-op if not live). |
|
|
319
392
|
| `usePlayback()` / `getPlayback()` | Full `{ state, error }`; subscribe via `onPlaybackChanged`. |
|
|
320
|
-
| `retry()` | Re-attempt the current item
|
|
321
|
-
| `usePlayingState()`
|
|
393
|
+
| `retry()` | Re-attempt the current item; meant for the `'error'` state. |
|
|
394
|
+
| `usePlayingState()` / `getPlayingState()` | `{ playing, buffering }` booleans for a play/pause button. |
|
|
395
|
+
| `onPlayingState` | Subscribe to `{ playing, buffering }` changes. |
|
|
322
396
|
| `setPlayWhenReady(bool)` / `usePlayWhenReady()` | Play/pause _intent_, independent of buffering. |
|
|
397
|
+
| `getPlayWhenReady()` / `onPlayWhenReadyChanged` | Read or subscribe to the play/pause intent. |
|
|
323
398
|
| `usePolledProgress(intervalMs?)` | `{ position, duration, buffered }` via polling (ms) — works by default. |
|
|
324
|
-
| `useProgress()` / `
|
|
399
|
+
| `useProgress()` / `onProgressUpdated` | Progress via events (enable `progressUpdateEventInterval` first). |
|
|
400
|
+
| `getProgress()` | One-off progress snapshot; always works. |
|
|
325
401
|
| `getRate()` / `setRate(rate)` | Playback speed multiplier (`1` = normal). |
|
|
326
402
|
| `getVolume()` / `setVolume(0..1)` | This player's volume. |
|
|
327
|
-
| `getSystemVolume()` / `useSystemVolume()` | Device media volume (`setSystemVolume`
|
|
403
|
+
| `getSystemVolume()` / `useSystemVolume()` | Device media volume (`setSystemVolume` does nothing on iOS or web). |
|
|
404
|
+
| `onSystemVolumeChanged` | Subscribe to device media volume changes. |
|
|
328
405
|
| `trackPlaybackTime(cb, period)` | Heartbeat every `period` seconds of real playback. |
|