react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.20

package/website/guide/migrating-from-track-player.md

@@ -0,0 +1,244 @@
+---
+description: 'Porting from react-native-track-player v4: what carries over unchanged, what was renamed or reshaped, and what is new.'
+---
+
+# Migrating from react-native-track-player
+
+If you're coming from [react-native-track-player](https://github.com/doublesymmetry/react-native-track-player/tree/v4)
+(RNTP) v4, most of your playback and queue code ports over almost unchanged — the
+function names and semantics were deliberately kept familiar. This page maps the
+parts that _do_ change.
+
+`react-native-audio-browser` started as a fork of RNTP v4, and we wrote much of
+that original code. We've since rethought and rewritten it almost entirely. The
+API stays familiar by lineage, not coincidence, but almost everything underneath
+is new. RNTP has itself moved to a commercial license; `react-native-audio-browser`
+stays MIT.
+
+## What ports over unchanged
+
+These are the same calls with the same meaning — `import` them from
+`react-native-audio-browser` instead of `react-native-track-player`:
+
+[`setupPlayer`](/api/features/player/#setupplayer), [`updateOptions`](/api/features/player/#updateoptions),
+[`add`](/api/features/queue/#add), [`remove`](/api/features/queue/#remove), [`move`](/api/features/queue/#move),
+[`skip`](/api/features/queue/#skip), [`skipToNext`](/api/features/queue/#skiptonext),
+[`skipToPrevious`](/api/features/queue/#skiptoprevious), [`setQueue`](/api/features/queue/#setqueue),
+[`getQueue`](/api/features/queue/#getqueue), [`getTrack`](/api/features/queue/#gettrack),
+[`removeUpcomingTracks`](/api/features/queue/#removeupcomingtracks), [`load`](/api/features/queue/#load),
+[`reset`](/api/features/playback/#reset), [`retry`](/api/features/playback/#retry),
+[`play`](/api/features/playback/#play), [`pause`](/api/features/playback/#pause),
+[`stop`](/api/features/playback/#stop), [`seekTo`](/api/features/playback/#seekto),
+[`seekBy`](/api/features/playback/#seekby), [`setRate`](/api/features/playback/#setrate),
+[`getRate`](/api/features/playback/#getrate), [`setVolume`](/api/features/playback/#setvolume),
+[`getVolume`](/api/features/playback/#getvolume), [`setRepeatMode`](/api/features/queue/#setrepeatmode),
+[`getRepeatMode`](/api/features/queue/#getrepeatmode), [`setPlayWhenReady`](/api/features/playback/#setplaywhenready),
+[`getPlayWhenReady`](/api/features/playback/#getplaywhenready), [`getActiveTrack`](/api/features/queue/#getactivetrack),
+[`getActiveTrackIndex`](/api/features/queue/#getactivetrackindex).
+
+The differences below are what to watch for.
+
+## Getters are synchronous — and there are hooks
+
+RNTP getters return Promises; audio-browser getters return the value
+**synchronously**, and most have a reactive **hook**. Drop the `await` (awaiting a
+non-Promise still works, so this isn't urgent), and prefer the hook in React.
+
+| RNTP v4                                   | audio-browser                                                                                                                      |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `await getPosition()`                     | [`getProgress().position`](/api/features/playback/#position)                                                                       |
+| `await getDuration()`                     | [`getProgress().duration`](/api/features/playback/#duration)                                                                       |
+| `await getBufferedPosition()`             | [`getProgress().buffered`](/api/features/playback/#buffered)                                                                       |
+| `await getProgress()`                     | [`getProgress()`](/api/features/playback/#getprogress) (sync) / [`usePolledProgress()`](/api/features/playback/#usepolledprogress) |
+| `await getState()` / `getPlaybackState()` | [`getPlayback().state`](/api/features/playback/#state) / [`usePlayback()`](/api/features/playback/#useplayback)                    |
+| `await getActiveTrack()`                  | [`getActiveTrack()`](/api/features/queue/#getactivetrack) / [`useActiveTrack()`](/api/features/queue/#useactivetrack)              |
+| `await getQueue()`                        | [`getQueue()`](/api/features/queue/#getqueue) / [`useQueue()`](/api/features/queue/#usequeue)                                      |
+| `await getRepeatMode()`                   | [`getRepeatMode()`](/api/features/queue/#getrepeatmode) / [`useRepeatMode()`](/api/features/queue/#userepeatmode)                  |
+
+Two hook gotchas:
+
+- **`useProgress` changed meaning.** RNTP's `useProgress(interval)` is polling;
+  its drop-in is [`usePolledProgress(intervalMs)`](/api/features/playback/#usepolledprogress).
+  audio-browser _also_ has a [`useProgress()`](/api/features/playback/#useprogress), but it's **event-based and takes no
+  interval** (and needs `progressUpdateEventInterval` enabled) — so copying
+  `useProgress(2000)` over compiles but silently ignores the arg. Use
+  `usePolledProgress` if you relied on the polling interval.
+- **`useIsPlaying()` → [`usePlayingState()`](/api/features/playback/#useplayingstate)**,
+  but the field is renamed: RNTP's `{ playing, bufferingDuringPlay }` becomes
+  `{ playing, buffering }`.
+
+## Events: per-event `on*` / `use*`, no `Event` enum
+
+RNTP centralizes events behind the `Event` enum with `addEventListener` /
+`useTrackPlayerEvents`. audio-browser exposes one emitter (and usually a hook)
+per event, and `addListener` returns an **unsubscribe function** (not a
+subscription with `.remove()`):
+
+```ts
+// RNTP
+import TrackPlayer, { Event } from 'react-native-track-player'
+const sub = TrackPlayer.addEventListener(
+  Event.PlaybackActiveTrackChanged,
+  (e) => {}
+)
+sub.remove()
+
+// audio-browser
+import { onActiveTrackChanged } from 'react-native-audio-browser'
+const unsubscribe = onActiveTrackChanged.addListener((e) => {})
+unsubscribe()
+```
+
+| RNTP `Event.*`                   | audio-browser                                                                                                                                                                                                                    |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PlaybackActiveTrackChanged`     | [`onActiveTrackChanged`](/api/features/queue/#onactivetrackchanged) / [`useActiveTrack()`](/api/features/queue/#useactivetrack)                                                                                                  |
+| `PlaybackState`                  | [`onPlaybackChanged`](/api/features/playback/#onplaybackchanged) / [`usePlayback()`](/api/features/playback/#useplayback)                                                                                                        |
+| `PlaybackProgressUpdated`        | [`onProgressUpdated`](/api/features/playback/#onprogressupdated) / [`useProgress()`](/api/features/playback/#useprogress)                                                                                                        |
+| `PlaybackQueueEnded`             | [`onQueueEnded`](/api/features/queue/#onqueueended)                                                                                                                                                                              |
+| `PlaybackError` / `PlayerError`  | [`onPlaybackError`](/api/features/errors/#onplaybackerror) / [`usePlaybackError()`](/api/features/errors/#useplaybackerror)                                                                                                      |
+| `PlaybackPlayWhenReadyChanged`   | [`onPlayWhenReadyChanged`](/api/features/playback/#onplaywhenreadychanged) / [`usePlayWhenReady()`](/api/features/playback/#useplaywhenready)                                                                                    |
+| `Remote*` (Play, Pause, Next, …) | `handleRemote*` to override, `onRemote*` to observe — see [Remote Controls](/guide/remote-controls)                                                                                                                              |
+| `Metadata*Received`              | [`onTimedMetadata`](/api/features/metadata/#ontimedmetadata) / [`onChapterMetadata`](/api/features/metadata/#onchaptermetadata) / [`onTrackMetadata`](/api/features/metadata/#ontrackmetadata) — see [Metadata](/guide/metadata) |
+
+## Delete the playback service
+
+RNTP requires `registerPlaybackService(() => require('./service'))` and a service
+file that wires `Event.RemotePlay → TrackPlayer.play()`, etc. **audio-browser has
+no playback service** — the library wires the native side itself, and remote
+controls drive the player by default. Delete the service file and the
+registration call. To customize a remote control, set a
+[`handleRemote*`](/guide/remote-controls) override (pass `undefined` to restore
+the default); to just observe, use `onRemote*`:
+
+```ts
+import { handleRemoteNext, skipToNext } from 'react-native-audio-browser'
+
+// Override "next" (call the default action yourself if you still want it):
+handleRemoteNext(() => skipToNext())
+handleRemoteNext(undefined) // restore the default
+```
+
+## `capabilities`: an object, not an array
+
+```ts
+// RNTP
+import { Capability } from 'react-native-track-player'
+await TrackPlayer.updateOptions({
+  capabilities: [Capability.Play, Capability.Pause, Capability.SkipToNext]
+})
+
+// audio-browser — most are ON by default; specify only what differs
+updateOptions({ capabilities: { skipToPrevious: false } })
+```
+
+Pass `capabilities` to **either** [`setupPlayer`](/api/features/player/#setupplayer)
+(initial) or [`updateOptions`](/api/features/player/#updateoptions) (later) — both
+accept it. See
+[Configuration → Capabilities](/guide/configuration#capabilities) for the
+defaults (everything on except `jumpForward`, `jumpBackward`, `favorite`).
+`Capability.Like` / `RatingType` map to the [`favorite`](/guide/favorites)
+capability.
+
+## Enums become string literals
+
+audio-browser has no enum objects — use the string values directly:
+
+| RNTP                                 | audio-browser                                 |
+| ------------------------------------ | --------------------------------------------- |
+| `State.Playing`, `State.Paused`, …   | `'playing'`, `'paused'`, … (same strings)     |
+| `RepeatMode.Off` / `Track` / `Queue` | `'off'` / `'track'` / `'queue'`               |
+| `Capability.Play` (in an array)      | `{ play: true }` (in the capabilities object) |
+
+`State`'s string values are identical, so `state === 'playing'` checks port
+directly — you just drop the enum import.
+
+## `Track`: `url` → `src`
+
+The playable URL field is renamed. In audio-browser, the **playable source**
+is [`src`](/api/types/browser-nodes/#src); a track's **browse address** (for the
+[browse tree](/guide/browser)) is a separate field, `path`:
+
+```ts
+// RNTP
+{
+  url: ('https://cdn.example.com/song.mp3', title, artist, artwork)
+}
+
+// audio-browser
+{
+  src: ('https://cdn.example.com/song.mp3', title, artist, artwork)
+}
+```
+
+Other field changes: `isLiveStream` → [`live`](/api/types/browser-nodes/#live); per-track `headers`
+move to a [media request config](/guide/browser); `rating` → favorites (see
+above). `title` / `artist` / `album` / `artwork` / `duration` are unchanged.
+
+## Now-playing metadata
+
+```ts
+// RNTP
+TrackPlayer.updateNowPlayingMetadata({ title, artist })
+TrackPlayer.clearNowPlayingMetadata()
+
+// audio-browser
+import { updateNowPlaying } from 'react-native-audio-browser'
+updateNowPlaying({ title, artist })
+updateNowPlaying(null) // clear
+```
+
+For live streams, prefer the [Now Playing formatter](/guide/now-playing) over
+imperative updates — it re-derives the lock-screen lines on every metadata /
+state change.
+
+## Setup, before and after
+
+```ts
+// RNTP — index.js + startup
+TrackPlayer.registerPlaybackService(() => require('./service'))
+await TrackPlayer.setupPlayer()
+await TrackPlayer.updateOptions({
+  capabilities: [Capability.Play, Capability.Pause, Capability.SkipToNext],
+  progressUpdateEventInterval: 2
+})
+```
+
+```ts
+// audio-browser — one declarative call, no service
+import { setupPlayer } from 'react-native-audio-browser'
+
+await setupPlayer({
+  progressUpdateEventInterval: 2
+  // capabilities are on by default; nothing to register
+})
+```
+
+See [Configuration](/guide/configuration) for the full options surface and what's
+setup-only vs runtime-updatable.
+
+## What you gain
+
+audio-browser adds capabilities RNTP doesn't have — worth adopting once you've
+ported:
+
+- A [**browse tree**](/guide/browser) that powers native **CarPlay** and
+  **Android Auto** menus (and voice [search](/guide/search)) — see the
+  [Automotive overview](/guide/automotive).
+- A [**now-playing formatter**](/guide/now-playing) for live-stream metadata and
+  transient status lines.
+- [**Content gating**](/guide/gate), a [**sleep timer**](/guide/sleep-timer),
+  an [**equalizer**](/guide/equalizer), and [**favorites**](/guide/favorites).
+
+## Quick reference
+
+| Area            | RNTP v4                                                | audio-browser                                                                      |
+| --------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| Getters         | `await TrackPlayer.getX()`                             | `getX()` (sync) or `useX()`                                                        |
+| Events          | `Event` + `addEventListener` / `useTrackPlayerEvents`  | per-event `onX` / `useX`                                                           |
+| Unsubscribe     | `subscription.remove()`                                | the function `addListener` returns                                                 |
+| Remote handling | a registered playback **service**                      | default behavior + `handleRemote*`                                                 |
+| Capabilities    | `Capability[]`                                         | `capabilities` object of booleans                                                  |
+| Enums           | `State.*`, `RepeatMode.*`                              | string literals (`'playing'`, `'queue'`)                                           |
+| Playable URL    | `track.url`                                            | [`track.src`](/api/types/browser-nodes/#src)                                       |
+| Live flag       | `track.isLiveStream`                                   | [`track.live`](/api/types/browser-nodes/#live)                                     |
+| Now playing     | `updateNowPlayingMetadata` / `clearNowPlayingMetadata` | [`updateNowPlaying`](/api/features/nowPlaying/#updatenowplaying)`(update \| null)` |

package/website/guide/native-callback-fetch.md

@@ -0,0 +1,127 @@
+---
+description: "Why React Native's fetch hangs inside browse resolvers, search sources, and request transforms when the device is asleep, and what to use instead."
+---
+
+# Networking in native callbacks (don't use `fetch`)
+
+**If a browse route resolver, search source, or request `transform` does its own
+networking with React Native's built-in `fetch` — and it works in your app but
+_hangs_ when the device is asleep (browsing on CarPlay or Android Auto with the
+screen off, or answering a voice intent) — you are in the right place.** The
+browse screen goes blank because the request never resolves. The fix is to fetch
+with
+[`react-native-nitro-fetch`](https://github.com/margelo/react-native-nitro-fetch),
+or to let the library do the request natively.
+
+## The problem
+
+The library invokes the async callbacks you provide **from native code**,
+whenever the system asks for content — including while your app is asleep:
+
+- browse **route resolvers** (`configureBrowser({ routes })`),
+- the **search source** (`configureBrowser({ search })`),
+- request **`transform`** callbacks.
+
+A locked iPhone browsing your library on CarPlay, or a "play jazz" voice command
+with the screen dark, runs these callbacks with the app backgrounded. The first
+native call into JS runs fine — but the moment your callback `await`s a `fetch`,
+it hangs until the phone wakes.
+
+### Why `fetch` hangs while asleep
+
+React Native's `fetch` is the [`whatwg-fetch`](https://github.com/JakeChampion/fetch)
+polyfill, and it resolves its promise with a **zero-delay timer**, not a
+microtask:
+
+```js
+// inside whatwg-fetch
+setTimeout(function () {
+  resolve(new Response(body, options))
+}, 0)
+```
+
+When the device is asleep, React Native's timer module is paused — on iOS,
+`RCTTiming` pauses the `CADisplayLink` that drives JS timers — so `setTimeout`
+callbacks don't fire. Native networking (`RCTNetworking`) **does** perform the
+request and receive the response, but the `setTimeout(0)` that would hand it back
+to your `await` never runs. The promise sits unresolved until the screen wakes,
+and your browse list spins or shows blank. Android suspends JS timers the same
+way while the app is backgrounded behind Android Auto, so the symptom and the fix
+are identical there.
+
+This isn't specific to this library — it affects any `fetch` on a sleeping
+device, and upgrading doesn't help: current React Native still ships
+`whatwg-fetch`.
+
+## The fix: `react-native-nitro-fetch`
+
+[`react-native-nitro-fetch`](https://github.com/margelo/react-native-nitro-fetch)
+is a drop-in `fetch` replacement that runs the request on a native thread
+(`URLSession` on iOS, Cronet on Android) and resolves through **Nitro's
+microtask queue** — no `setTimeout`, no `whatwg-fetch`, no `RCTTiming`
+dependency. So it completes even when the callback runs while the device is
+asleep. Since this library is already a Nitro module, it's a natural fit.
+
+```bash
+npm install react-native-nitro-fetch react-native-nitro-modules
+```
+
+You already have `react-native-nitro-modules` (it's a peer dependency of this
+library); you'll need a native rebuild (`pod install` + rebuild) after
+installing.
+
+Then add one import at the top of any module with a native-invoked callback — it
+shadows the global `fetch`, so the call sites don't change:
+
+```ts
+import { configureBrowser } from 'react-native-audio-browser'
+import { fetch } from 'react-native-nitro-fetch'
+
+configureBrowser({
+  tabs: [{ title: 'Browse', path: '/browse' }],
+  routes: {
+    '/browse': async ({ path }) => {
+      const res = await fetch('https://api.example.com/browse')
+      const { children } = await res.json()
+      return { path: path, title: 'Browse', children }
+    }
+  }
+})
+```
+
+Use the same import in your search source and request `transform`s.
+
+## Even simpler: let the library fetch natively
+
+If a route just maps a path to an HTTP request, you don't have to write a JS
+callback at all. Give the browse source a `baseUrl` and the **library performs
+the request natively** for each navigated path — no JS networking, nothing to
+stall:
+
+```ts
+configureBrowser({
+  // Each browse path is fetched over HTTP on the native side.
+  browse: { baseUrl: 'https://api.example.com' },
+  tabs: [{ title: 'Browse', path: '/browse' }]
+})
+```
+
+The navigated path is appended to `baseUrl`; to remap or shape the request, use a
+[`transform`](/guide/browser) (still native). The search source accepts the same
+request-config form, so it can be served natively too. Reach for
+`react-native-nitro-fetch` only when you need logic a request config can't
+express (combining sources, reading local storage, custom shaping).
+
+## When it's safe to use plain `fetch`
+
+This only affects code the library invokes from native while the app is asleep.
+Networking driven by **your own app UI in the foreground** — a screen the user is
+looking at — runs on the normal JS loop and is unaffected; plain `fetch` is fine
+there. Rule of thumb: if the OS can run the code with the screen off, don't
+depend on `fetch`.
+
+## Further reading
+
+- [`react-native-nitro-fetch`](https://github.com/margelo/react-native-nitro-fetch)
+- [JS timers don't fire when the app is backgrounded (RN #38711)](https://github.com/facebook/react-native/issues/38711)
+- [Timers & fetch freeze behind a native activity (RN #54534)](https://github.com/facebook/react-native/issues/54534)

package/website/guide/network.md

@@ -0,0 +1,86 @@
+---
+description: 'Track the device''s validated internet connectivity with useOnline, getOnline, and onOnlineChanged, and what "online" means on each platform.'
+---
+
+# Network
+
+The library tracks the device's internet connectivity with a native monitor and
+exposes it three ways:
+
+- [`useOnline()`](/api/features/network/#useonline) — a reactive hook for your UI.
+- [`getOnline()`](/api/features/network/#getonline) — a one-off snapshot.
+- [`onOnlineChanged`](/api/features/network/#ononlinechanged) — subscribe to
+  changes outside React.
+
+All three report the same boolean: `true` when the device has a working internet
+connection. **"Online" means _validated_ internet, not just "connected to a
+network".** Android is strict here — it requires the OS to confirm the network
+actually reaches the internet, so Wi-Fi with no real connectivity reads as
+`false`. iOS derives the signal from the system path monitor (`NWPathMonitor`),
+which is slightly more permissive about such captive networks.
+
+The UI snippet imports `Text` from `react-native`; everything else is from
+`react-native-audio-browser`.
+
+## In your UI
+
+`useOnline` re-renders when connectivity flips — enough for an offline banner:
+
+```tsx
+import { Text } from 'react-native'
+import { useOnline } from 'react-native-audio-browser'
+
+function OfflineBanner() {
+  const online = useOnline()
+  if (online) return null
+  return <Text>You're offline</Text>
+}
+```
+
+## Outside React
+
+Read a snapshot with `getOnline()`, or subscribe with `onOnlineChanged`
+(`addListener` returns an unsubscribe function):
+
+```ts
+import { getOnline, onOnlineChanged } from 'react-native-audio-browser'
+
+getOnline() // → true | false
+
+const unsubscribe = onOnlineChanged.addListener((online) => {
+  if (online) refetchSomething()
+})
+
+// later:
+unsubscribe()
+```
+
+## You may not need this
+
+The player already reacts to connectivity on its own, so you usually don't wire
+these up for playback:
+
+- When the connection drops mid-stream, the now-playing formatter receives
+  `stalled: 'offline'` (vs `'buffering'` when online) — see
+  [Now Playing → the formatter](/guide/now-playing#the-formatter-derived-continuous).
+- When the connection returns while the stream sits **stalled** (state
+  `'buffering'` with play intent), the player re-establishes it automatically —
+  you don't need to listen for reconnect and re-`play()`. If the drop instead
+  surfaced as a playback **error**, recovery belongs to
+  [automatic retry](/guide/errors#automatic-retry) (`setupPlayer({ retry })`,
+  off by default); once retry gives up — or without it — the player stays in
+  `'error'` until the listener (or your code) calls `retry()` / `play()`.
+
+Reach for `useOnline` / `onOnlineChanged` for **your own** UI and data — an
+offline banner, disabling a control, refetching a list on reconnect.
+
+## API summary
+
+| API               | Purpose                                                               |
+| ----------------- | --------------------------------------------------------------------- |
+| `useOnline()`     | Reactive `boolean`; re-renders on connectivity change.                |
+| `getOnline()`     | One-off snapshot `boolean`.                                           |
+| `onOnlineChanged` | Subscribe outside React; `addListener(cb)` returns an unsubscribe fn. |
+
+`true` = validated internet connection; `false` = offline (including a network
+with no real internet on Android).

package/website/guide/now-playing.md

@@ -0,0 +1,175 @@
+---
+description: 'What the system surfaces show: which metadata field lands where, the four layers that decide its value at any moment, and reading the result back in your own UI.'
+---
+
+# Now Playing
+
+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. The library publishes one metadata dictionary and the _operating system_ renders it — each surface picks different fields, composes them differently, and ignores the rest. The same published metadata is also readable inside your own app — see [Reading now-playing in your own UI](#reading-now-playing-in-your-own-ui).
+
+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.
+
+## Which field shows where
+
+Apple and Google document very little of this; the table below reflects observed behavior.
+
+| Field     | iOS lock screen / Control Center                                       | CarPlay Now Playing                                                | Android notification | Android Auto Now Playing | Bluetooth (AVRCP)       |
+| --------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------- | ------------------------ | ----------------------- |
+| `title`   | Primary line                                                           | Primary line                                                       | Primary line         | Primary line             | Title                   |
+| `artist`  | **Secondary line (sole source — `album` is never used as a fallback)** | Second line                                                        | Secondary line       | Secondary line           | Artist                  |
+| `album`   | Not shown                                                              | **Third line — also the tappable album/artist button (see below)** | Not shown            | Rarely shown             | Album (some head units) |
+| `artwork` | Shown                                                                  | Shown                                                              | Shown                | Shown                    | —                       |
+| `live`    | "LIVE" indicator replaces the time scrubber                            | "LIVE" indicator                                                   | —                    | —                        | —                       |
+
+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.
+
+`artwork` is the URL you _set_ on a track. (`Track.artworkSource` is a separate, output-only `ImageSource` the library populates for you to render in your own `<Image>` — it isn't published to surfaces.) Note that artwork isn't one of the overridable text fields: the formatter, override, and flash layers below carry only `title` / `artist` / `album`. Now-playing artwork comes from the track's `artwork`, optionally resolved through the [`nowPlayingArtwork`](#now-playing-artwork) config.
+
+## The four metadata layers
+
+What actually renders is decided by a fixed priority order. Each layer only overrides the fields it sets — anything it leaves `undefined` falls through to the layer below:
+
+| Priority     | Layer            | API                                    | Lifetime                             |
+| ------------ | ---------------- | -------------------------------------- | ------------------------------------ |
+| 1 (highest)  | **Flash**        | `flashNowPlaying(update, durationMs)`  | `durationMs`, on a native timer      |
+| 2            | **Formatter**    | `setupPlayer({ nowPlaying })`          | as long as it's configured           |
+| 3            | **Override**     | `updateNowPlaying(update)`             | until cleared or the track changes   |
+| 4 (baseline) | **Track fields** | `Track.title` / `artist` / `album` / … | the track's time as the active track |
+
+### Track fields — the baseline
+
+With nothing else configured, the active track's own fields are published as-is. For on-demand content this is usually all you need.
+
+### The formatter — derived, continuous
+
+The [`nowPlaying`](/api/features/player/#formatnowplayingcallback) formatter hands you the now-playing text lines outright, re-invoked whenever they could change: on track change, on every timed-metadata update, on every playback transition (play / pause, a stall starting or recovering, an error), and on connectivity changes. 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:
+
+```ts
+setupPlayer({
+  nowPlaying: ({ timedMetadata, playWhenReady, stalled, error }) => {
+    // `yourErrorLine` is your own kind→copy mapping — branch on `error.kind`,
+    // never `error.message`, which is developer English and never localized.
+    // This line is read by listeners, on the lock screen and in the car.
+    // See [Playback errors](/guide/errors#playback-errors).
+    if (error) return { artist: yourErrorLine(error.kind) }
+    if (stalled) {
+      return {
+        artist: stalled === 'offline' ? 'No connection' : 'Reconnecting…'
+      }
+    }
+    // The live song, only while actually playing — a paused stream's last
+    // song is stale, so fall back to the track default (return undefined).
+    if (!playWhenReady || !timedMetadata?.title) return
+    return { artist: timedMetadata.title }
+  }
+})
+```
+
+The callback receives a single [`FormatNowPlayingParams`](/api/features/player/#formatnowplayingparams) object:
+
+| Field           | Type             | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `track`         | `Track`          | The currently playing track.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `timedMetadata` | `TimedMetadata?` | The ICY / ID3 "now playing song", if any.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `playWhenReady` | `boolean`        | Play/pause intent — stays `true` through buffers, so the song line won't flicker.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `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.                                                                                                                                                                                                                                                                                                  |
+| `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). While [automatic retry](/guide/errors#automatic-retry) is still working, this carries the advisory error (`error.retrying === true`) — the formatter re-runs when it arrives, changes, and clears, so you can show provisional copy ("… — retrying") that hardens into the final line when the player gives up. |
+
+It returns a [`NowPlayingUpdate`](/api/features/metadata/#nowplayingupdate) (`{ title?, artist?, album? }`) or `undefined`. The callback is synchronous and should stay cheap — it's a pure formatting function, no I/O. 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.
+
+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).)
+
+### The override — imperative, sticky
+
+[`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.
+
+**If a formatter is configured, it outranks the override** — the formatter's result is applied on top, falling back per-field to `override ?? track`. Mixing the two is rarely what you want: with a formatter in place, feed it state instead of calling `updateNowPlaying` around it. (The override predates the formatter; the formatter is the newer, preferred layer for anything derived from playback state.)
+
+### The flash — transient, top priority
+
+[`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. 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:
+
+```ts
+// A radio product with an hourly skip allowance:
+handleRemoteNext(() => {
+  if (skipsRemaining() > 0) {
+    skipToNext()
+  } else {
+    flashNowPlaying({ artist: 'Skip limit reached' }, 3000)
+  }
+})
+```
+
+Three properties make it a dedicated layer rather than sugar over `updateNowPlaying`:
+
+- **It outranks the formatter.** While a flash is active the formatter pass is skipped entirely, so a live station's next metadata tick can't overwrite the message mid-window.
+- **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.
+- **A track change clears it early.** A flash is feedback about a moment; it never carries over to a new track.
+
+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.
+
+## Reading now-playing in your own UI
+
+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:
+
+```tsx
+import { Text } from 'react-native'
+import { useNowPlaying } from 'react-native-audio-browser'
+
+function MiniPlayer() {
+  const nowPlaying = useNowPlaying()
+  if (!nowPlaying) return null
+  return (
+    <Text>
+      {nowPlaying.title} — {nowPlaying.artist}
+    </Text>
+  )
+}
+```
+
+`useNowPlaying` returns the resolved [`NowPlayingMetadata`](/api/features/metadata/#nowplayingmetadata) — the same dictionary the system surfaces see, _after_ the four layers are applied — or `undefined` when nothing is playing. It carries `title` / `artist` / `album` / `artwork` (and `elapsedTime`). For the live scrubber position, pair it with [`useProgress`](/guide/playback#progress).
+
+Outside React, [`getNowPlaying()`](/api/features/nowPlaying/#getnowplaying) reads a snapshot and [`onNowPlayingChanged`](/api/features/nowPlaying/#onnowplayingchanged) subscribes to changes (it fires when the override changes or the track changes).
+
+To render artwork, don't use this `artwork` field directly — it's a raw URL string. Use the active track's ready-to-use `artworkSource` instead (`<Image source={track.artworkSource} />`) — see [Track](/guide/track).
+
+## Gotchas worth knowing
+
+**CarPlay's tappable line renders from `album`.** When a track has an `albumPath` (or `resolveAlbumPath` returns a path), the _album line_ becomes tappable — rendered as a third metadata line with a chevron, navigating the browse stack. A track without an `album` has no such line, so there is nothing to render or tap even though a destination exists. See the [CarPlay guide](/guide/carplay#album-line-navigation).
+
+**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.
+
+**`artist` and `album` render as adjacent lines on CarPlay.** Giving both the same string displays it twice. If both fields must carry related context (a live stream's location, say), differentiate the copy — the album line reads well as an action since it can be tappable.
+
+**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.
+
+**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.
+
+**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.
+
+## Now-playing artwork
+
+Artwork is the one surface field the text layers (formatter / override / flash) can't touch — they carry only `title` / `artist` / `album`. The now-playing image comes from the active track's `artwork`.
+
+By default that's the same image as the track's browse-list thumbnail. To resolve it differently — a larger, lock-screen-quality image without bloating list thumbnails — set the `nowPlayingArtwork` config kind, which builds the now-playing image from its own request (e.g. `{ path: '/artwork/{id}' }`):
+
+```ts
+configureBrowser({
+  nowPlayingArtwork: { path: '/artwork/{id}' }
+  // ...tabs, routes
+})
+```
+
+See [`BrowserConfiguration.nowPlayingArtwork`](/api/types/browser/#browserconfiguration).
+
+## API summary
+
+| API                                       | Purpose                                                      |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `setupPlayer({ nowPlaying })`             | Configure the formatter — derived lines from playback state. |
+| `updateNowPlaying(update \| null)`        | Imperatively override fields; `null` clears.                 |
+| `flashNowPlaying(update, durationMs)`     | Transient, top-priority swap (refused-command feedback).     |
+| `clearNowPlayingFlash()`                  | Cancel an active flash early.                                |
+| `useNowPlaying()` / `getNowPlaying()`     | Read the resolved metadata in your own UI.                   |
+| `onNowPlayingChanged`                     | Subscribe to metadata changes outside React.                 |
+| `onTimedMetadata`                         | Subscribe to ICY / ID3 stream metadata directly.             |
+| `configureBrowser({ nowPlayingArtwork })` | Resolve now-playing artwork from its own request.            |