react-native-audio-browser 0.2.0-next.12 → 0.2.0-next.13

package/website/guide/hooks.md

@@ -0,0 +1,238 @@
+---
+description: 'The React hooks that keep your UI in sync with playback, the queue, the browse tree, and the device — including changes driven from outside your app.'
+---
+
+# Hooks
+
+The library exposes its state as **React hooks** — call one in a component and it returns the current value and re-renders whenever that value changes. They keep your in-app UI in sync with playback, the queue, the browse tree, and the device, including changes driven from _outside_ your app (the lock screen, CarPlay, Android Auto, Bluetooth).
+
+```tsx
+import { useActiveTrack, usePlayingState } from 'react-native-audio-browser'
+
+function NowPlaying() {
+  const track = useActiveTrack()
+  const { playing } = usePlayingState()
+  return (
+    <Text>
+      {playing ? 'Playing' : 'Paused'}: {track?.title}
+    </Text>
+  )
+}
+```
+
+## The getter / hook / event trio
+
+Most state comes in three forms, so you can read it whichever way fits:
+
+| Form       | Shape    | Use it                                                       |
+| ---------- | -------- | ------------------------------------------------------------ |
+| **Hook**   | `useX()` | inside a component — re-renders on change                    |
+| **Getter** | `getX()` | a one-off synchronous read, anywhere                         |
+| **Event**  | `on…`    | `onX.addListener(cb)` outside React — returns an unsubscribe |
+
+Most events are named `on<Thing>Changed`, but several aren't — `onProgressUpdated`, `onPlayingState`, `onPlaybackError`, `onNavigationError`. The exact event for each hook is in the [reference table](#all-hooks-at-a-glance), so don't guess the name.
+
+```ts
+import { getPlayback, onPlaybackChanged } from 'react-native-audio-browser'
+
+const now = getPlayback() // read once
+const stop = onPlaybackChanged.addListener((p) => console.log(p.state)) // subscribe
+// stop() to unsubscribe
+```
+
+Every hook, getter, and event is a named export from `react-native-audio-browser`. Hooks read a cached value synchronously on first render (no flash of empty state) and then subscribe for you. Mutating state is separate — `setX()` / action functions (`play`, `setQueue`, `setShuffle`, `setRepeatMode`, `setPlayWhenReady`, …) — covered in [Basic Usage](/guide/basic-usage).
+
+## Playback
+
+The transport state — what the player is doing right now.
+
+```tsx
+import {
+  usePlayback,
+  usePlayingState,
+  useProgress
+} from 'react-native-audio-browser'
+
+function Transport() {
+  const { state } = usePlayback() // e.g. 'playing' | 'paused' (full list below)
+  const { playing, buffering } = usePlayingState()
+  const { position, duration, buffered } = useProgress() // seconds
+  return <Scrubber position={position} duration={duration} />
+}
+```
+
+- [**`usePlayback()`**](/api/features/playback/#useplayback) → `{ state, error? }`. `state` is one of `none`, `ready`, `loading`, `buffering`, `playing`, `paused`, `stopped`, `ended`, `error`.
+- [**`usePlayingState()`**](/api/features/playback/#useplayingstate) → `{ playing, buffering }`. A lighter hook when you only need the booleans.
+- [**`useProgress()`**](/api/features/playback/#useprogress) → [`Progress`](/api/features/playback/#progress) (`{ position, duration, buffered }`) in seconds. Event-driven, but **off by default**: `progressUpdateEventInterval` is `null` until you set it (in seconds) via `updateOptions({ progressUpdateEventInterval: 0.5 })` — otherwise the value never ticks.
+- [**`usePolledProgress(updateInterval = 1000)`**](/api/features/playback/#usepolledprogress) → same [`Progress`](/api/features/playback/#progress), but polled on its own timer (milliseconds) instead of event-driven, so it works without `progressUpdateEventInterval`. Good for a smooth scrubber; it pauses while the app is backgrounded.
+- [**`usePlayWhenReady()`**](/api/features/playback/#useplaywhenready) → `boolean`: whether the player will start as soon as content is ready.
+- [**`useSystemVolume()`**](/api/features/playback/#usesystemvolume) → `number` 0–1, the device volume (read-only on iOS).
+
+::: tip `useProgress` vs `usePolledProgress`
+`useProgress` emits at the global `progressUpdateEventInterval` (and stays still until you set it); `usePolledProgress` ignores that and ticks on its own timer. For a scrubber, `usePolledProgress` is usually the simpler choice.
+:::
+
+## Queue and active track
+
+```tsx
+import {
+  useActiveTrack,
+  useQueue,
+  useRepeatMode,
+  useShuffle
+} from 'react-native-audio-browser'
+
+function QueueScreen() {
+  const active = useActiveTrack() // Track | undefined
+  const queue = useQueue() // Track[]
+  const repeat = useRepeatMode() // 'off' | 'track' | 'queue'
+  const shuffle = useShuffle() // boolean
+  return <List data={queue} highlight={active?.id} />
+}
+```
+
+[`useActiveTrack`](/api/features/queue/#useactivetrack) updates even when the track changes from an external control (car next/previous), so matching on the track's identity keeps your UI correct. Note `Track.id` is **optional** (and may be undefined for a browse item the user picked in the car without you queuing it) — fall back to `src` / `path` if you rely on `id`. See [Track](/guide/track) for the Track shape.
+
+## Now playing
+
+[**`useNowPlaying()`**](/api/features/nowPlaying/#usenowplaying) → [`NowPlayingMetadata`](/api/features/metadata/#nowplayingmetadata)` | undefined` — the metadata shown on the lock screen and car surfaces. It reflects any override you set via `updateNowPlaying()` (e.g. the current song on a live stream), falling back to the active track otherwise. See [Now Playing](/guide/now-playing).
+
+```tsx
+const meta = useNowPlaying()
+// { title?, artist?, album?, artwork?, genre?, duration?,
+//   description?, mediaId?, elapsedTime? }
+```
+
+## Browsing
+
+Mirror the browse tree your app draws — the same state CarPlay and Android Auto render.
+
+- [**`useTabs()`**](/api/features/browser/#usetabs) → [`Track`](/api/types/browser-nodes/#track)`[] | undefined` — the top-level tabs.
+- [**`usePath()`**](/api/features/browser/#usepath) → `string | undefined` — the current browse path.
+- [**`useContent()`**](/api/features/browser/#usecontent) → [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack)` | undefined` — the resolved page (`content?.sections` to render — each a titled, styled group of tracks).
+
+```tsx
+import { useContent, navigate } from 'react-native-audio-browser'
+
+function Browse() {
+  const page = useContent()
+  // each section: { title?, style?, path?, children: Track[] }
+  return (
+    <List
+      sections={page?.sections ?? []}
+      onSelect={(track) => navigate(track)}
+    />
+  )
+}
+```
+
+See [Browser](/guide/browser) for how navigation and content resolution work.
+
+## Sleep timer
+
+- [**`useSleepTimerActive()`**](/api/features/sleepTimer/#usesleeptimeractive) → `boolean` — lightweight "is a timer set?" check.
+- [**`useSleepTimer(params?)`**](/api/features/sleepTimer/#usesleeptimer) → the live [`SleepTimerState`](/api/features/sleepTimer/#sleeptimerstate), or `undefined` when none is set:
+  - `{ time, secondsLeft }` for a countdown timer (`time` is the epoch-ms fire time), or
+  - `{ sleepWhenPlayedToEnd: true }` for an end-of-track timer.
+
+```tsx
+const timer = useSleepTimer({ updateInterval: 1000 })
+// timer && 'secondsLeft' in timer → show timer.secondsLeft
+```
+
+`params` takes `updateInterval` (countdown tick rate, default 1000ms) and `inactive` (set `true` while backgrounded to pause ticking). `secondsLeft` does not advance in the background.
+
+## Device and environment
+
+| Hook                                                                | Returns                                                 | Notes                                             |
+| ------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------- |
+| [`useOnline()`](/api/features/network/#useonline)                   | `boolean`                                               | network connectivity                              |
+| [`useCarConnected()`](/api/features/carConnection/#usecarconnected) | `boolean`                                               | CarPlay / Android Auto connected (`false` on web) |
+| [`useSystemVolume()`](/api/features/playback/#usesystemvolume)      | `number`                                                | device volume 0–1                                 |
+| [`useOutput()`](/api/features/output/#useoutput)                    | [`Output`](/api/features/output/#output)` \| undefined` | current audio output (iOS + Android)              |
+
+```tsx
+const output = useOutput() // { type, name, external } | undefined
+// e.g. output?.type === 'bluetooth', output?.external === true
+```
+
+`useOutput` updates as routes change (AirPods connect, a Bluetooth speaker is selected, etc.); it's `undefined` when unknown, and Android reports coarser `type`s. See [Audio Output](/guide/audio-output).
+
+## Errors
+
+- [**`usePlaybackError()`**](/api/features/errors/#useplaybackerror) → [`PlaybackError`](/api/features/errors/#playbackerror)` | undefined` — playback failures, with a normalized `kind` (`offline`, `unreachable`, `not-found`, `rejected`, `unplayable`, `stalled`, …) to branch on, plus a platform-specific `code` and optional `statusCode` for telemetry. Never show its `message` — see [Errors](/guide/errors#playback-errors).
+- [**`useNavigationError()`**](/api/features/errors/#usenavigationerror) → [`NavigationError`](/api/features/errors/#navigationerror)` | undefined` — a browse/search failure, with a typed `code` (`network-error`, `http-error`, `timeout`, `empty-content`, …) and optional `statusCode`.
+- [**`useFormattedNavigationError()`**](/api/features/errors/#useformattednavigationerror) → `{ title, message } | undefined` — the same error run through your `formatNavigationError` config (the copy CarPlay and Android Auto show), ready to display.
+
+```tsx
+const error = useFormattedNavigationError()
+return error ? <Banner title={error.title} body={error.message} /> : null
+```
+
+## Player options
+
+[**`useOptions()`**](/api/features/player/#useoptions) → the current [`Options`](/api/features/player/#options) (jump intervals, `capabilities`, and the `android` / `ios` blocks). Mutate with `updateOptions(partial)`.
+
+```tsx
+const { forwardJumpInterval, capabilities } = useOptions()
+```
+
+## Android-only hooks
+
+**Battery** (Android background-restriction state — all `false`/`unrestricted` on iOS):
+
+- [**`useBatteryWarning()`**](/api/features/battery/#usebatterywarning) → `{ pending, status, dismiss, openSettings }` — the meta-hook for a complete warning UI; `dismiss()` and `openSettings()` are ready-to-wire actions.
+- [**`useBatteryWarningPending()`**](/api/features/battery/#usebatterywarningpending) → `boolean` and [**`useBatteryOptimizationStatus()`**](/api/features/battery/#usebatteryoptimizationstatus) → `'unrestricted' | 'optimized' | 'restricted'` are the individual pieces.
+
+```tsx
+const { pending, status, dismiss, openSettings } = useBatteryWarning()
+```
+
+**Equalizer**: [**`useEqualizerSettings()`**](/api/features/equalizer/#useequalizersettings) → [`EqualizerSettings`](/api/features/equalizer/#equalizersettings)` | undefined` (`bandLevels`, `presets`, `enabled`, …); `undefined` on iOS. Drive it with `setEqualizerEnabled` / `setEqualizerPreset` / `setEqualizerLevels`.
+
+## Debugging
+
+**`useDebug(options?)`** → `{ state, logs, clear }` — a live snapshot of all player state plus a change log (last 100 entries). It's a development aid; `options.enabled` defaults to `__DEV__`.
+
+```tsx
+const { state, logs, clear } = useDebug({ metadata: true })
+```
+
+## All hooks at a glance
+
+The **Event** column is the emitter name for the getter/event form — handy because the names aren't fully uniform.
+
+The **Hook** name links to its full API entry; the **Returns** type links to its definition where it has one.
+
+| Hook                                                                                  | Returns                                                                          | Event                                | Platform            |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------ | ------------------- |
+| [`usePlayback`](/api/features/playback/#useplayback)                                  | `{ state, error? }`                                                              | `onPlaybackChanged`                  | all                 |
+| [`usePlayingState`](/api/features/playback/#useplayingstate)                          | `{ playing, buffering }`                                                         | `onPlayingState`                     | all                 |
+| [`useProgress`](/api/features/playback/#useprogress)                                  | `{ position, duration, buffered }`                                               | `onProgressUpdated`                  | all                 |
+| [`usePolledProgress`](/api/features/playback/#usepolledprogress)                      | `{ position, duration, buffered }`                                               | _(polled)_                           | all                 |
+| [`usePlayWhenReady`](/api/features/playback/#useplaywhenready)                        | `boolean`                                                                        | `onPlayWhenReadyChanged`             | all                 |
+| [`useSystemVolume`](/api/features/playback/#usesystemvolume)                          | `number`                                                                         | `onSystemVolumeChanged`              | all (read-only iOS) |
+| [`useActiveTrack`](/api/features/queue/#useactivetrack)                               | [`Track`](/api/types/browser-nodes/#track)` \| undefined`                        | `onActiveTrackChanged`               | all                 |
+| [`useQueue`](/api/features/queue/#usequeue)                                           | [`Track`](/api/types/browser-nodes/#track)`[]`                                   | `onQueueChanged`                     | all                 |
+| [`useRepeatMode`](/api/features/queue/#userepeatmode)                                 | [`RepeatMode`](/api/features/queue/#repeatmode)                                  | `onRepeatModeChanged`                | all                 |
+| [`useShuffle`](/api/features/queue/#useshuffle)                                       | `boolean`                                                                        | `onShuffleChanged`                   | all                 |
+| [`useNowPlaying`](/api/features/nowPlaying/#usenowplaying)                            | `NowPlayingMetadata \| undefined`                                                | `onNowPlayingChanged`                | all                 |
+| [`useTabs`](/api/features/browser/#usetabs)                                           | [`Track`](/api/types/browser-nodes/#track)`[] \| undefined`                      | `onTabsChanged`                      | all                 |
+| [`usePath`](/api/features/browser/#usepath)                                           | `string \| undefined`                                                            | `onPathChanged`                      | all                 |
+| [`useContent`](/api/features/browser/#usecontent)                                     | [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack)` \| undefined`        | `onContentChanged`                   | all                 |
+| [`useSleepTimerActive`](/api/features/sleepTimer/#usesleeptimeractive)                | `boolean`                                                                        | `onSleepTimerChanged`                | all                 |
+| [`useSleepTimer`](/api/features/sleepTimer/#usesleeptimer)                            | [`SleepTimerState`](/api/features/sleepTimer/#sleeptimerstate)` \| undefined`    | `onSleepTimerChanged`                | all                 |
+| [`useOnline`](/api/features/network/#useonline)                                       | `boolean`                                                                        | `onOnlineChanged`                    | all                 |
+| [`useCarConnected`](/api/features/carConnection/#usecarconnected)                     | `boolean`                                                                        | `onCarConnectedChanged`              | all (`false` web)   |
+| [`useOutput`](/api/features/output/#useoutput)                                        | [`Output`](/api/features/output/#output)` \| undefined`                          | `onOutputChanged`                    | iOS, Android        |
+| [`usePlaybackError`](/api/features/errors/#useplaybackerror)                          | [`PlaybackError`](/api/features/errors/#playbackerror)` \| undefined`            | `onPlaybackError`                    | all                 |
+| [`useNavigationError`](/api/features/errors/#usenavigationerror)                      | [`NavigationError`](/api/features/errors/#navigationerror)` \| undefined`        | `onNavigationError`                  | all                 |
+| [`useFormattedNavigationError`](/api/features/errors/#useformattednavigationerror)    | `{ title, message } \| undefined`                                                | `onFormattedNavigationError`         | all                 |
+| [`useOptions`](/api/features/player/#useoptions)                                      | [`Options`](/api/features/player/#options)                                       | `onOptionsChanged`                   | all                 |
+| [`useBatteryWarning`](/api/features/battery/#usebatterywarning)                       | `{ pending, status, dismiss, openSettings }`                                     | _(composite)_                        | Android             |
+| [`useBatteryWarningPending`](/api/features/battery/#usebatterywarningpending)         | `boolean`                                                                        | `onBatteryWarningPendingChanged`     | Android             |
+| [`useBatteryOptimizationStatus`](/api/features/battery/#usebatteryoptimizationstatus) | [`BatteryOptimizationStatus`](/api/features/battery/#batteryoptimizationstatus)  | `onBatteryOptimizationStatusChanged` | Android             |
+| [`useEqualizerSettings`](/api/features/equalizer/#useequalizersettings)               | [`EqualizerSettings`](/api/features/equalizer/#equalizersettings)` \| undefined` | `onEqualizerChanged`                 | Android             |
+| `useDebug`                                                                            | `{ state, logs, clear }`                                                         | _(composite)_                        | all                 |
+
+For the exact return types, see the [API reference](/api/).

package/website/guide/live-streams.md

@@ -0,0 +1,125 @@
+---
+description: 'The map for live audio: stream formats, missing durations, dropped connections, expiring URLs, and song titles carried in-band.'
+---
+
+# Live Streams
+
+Live audio is what most of this player's edge cases are about: streams that
+have no duration, drop in tunnels, expire their URLs, and carry their song
+titles in-band. The pieces live in their own guides — this page is the map,
+with just enough of each to know which link you need.
+
+## Stream formats
+
+Point [`src`](/api/types/browser-nodes/#track) at the stream URL — there is
+no format field; each platform's player detects the container:
+
+- **HLS** (`.m3u8`) — both platforms. In-band ID3 timed metadata is read —
+  see [Metadata](/guide/metadata#timed-metadata-the-live-song).
+- **ICY / Icecast / Shoutcast** — plain HTTP radio, both platforms. The ICY
+  `StreamTitle` arrives as timed metadata, filling only `title` — it reaches
+  the lock screen once your
+  [now-playing formatter](/guide/now-playing#the-formatter-derived-continuous)
+  applies it, never automatically (see
+  [Metadata](/guide/metadata#timed-metadata-the-live-song)).
+- **Progressive HTTP** — ordinary MP3/AAC/… files and endless streams, both
+  platforms.
+- **DASH / SmoothStreaming** — Android only (bundled Media3 modules); iOS's
+  AVPlayer doesn't support them.
+
+Mark the track itself with [`live: true`](/api/types/browser-nodes/#track):
+it shows the live indicator on iOS now-playing and arms
+[`seekToLiveEdge()`](#the-live-edge) — declare it on every live track.
+To hear it, put the track in the queue (or serve it from a
+[browse tree](/guide/basic-usage)) after
+[`setupPlayer()`](/guide/basic-usage#set-up-the-player) has run:
+
+```ts
+import { play, setQueue } from 'react-native-audio-browser'
+
+setQueue([
+  {
+    src: 'https://stream.example.com/main.mp3',
+    title: 'Beacon FM',
+    live: true
+  }
+])
+play()
+```
+
+## Dropouts: stalls and retry
+
+A connection drop mid-stream surfaces one of two ways, with different owners:
+
+- **A stall** (how most iOS drops surface) — the player holds `'buffering'`
+  with play intent, and re-establishes the stream by itself when
+  connectivity returns. No wiring needed — see
+  [Network → You may not need this](/guide/network#you-may-not-need-this).
+  While stalled offline, the [now-playing formatter](/guide/now-playing#the-formatter-derived-continuous)
+  receives `stalled: 'offline'` (vs `'buffering'` when online) so the lock
+  screen can say why.
+- **A playback error** (how most Android drops surface) — recovery belongs
+  to [automatic retry](/guide/errors#automatic-retry)
+  (`setupPlayer({ retry })`, off by default). Two duration budgets, chosen
+  by whether this load has ever produced audio: **12 s** for a stream that
+  never played (counting only online time — a station tapped in a tunnel
+  still gets its chance when the network returns), **2 min** once playback
+  proved the stream works. The 2 min budget is a wall clock that _includes_
+  offline time, deliberately — see
+  [the budgets](/guide/errors#two-duration-budgets). Budgets exhausted →
+  state `'error'`, where [`retry()`](/guide/errors#manual-retry) and your
+  error UI take over.
+
+Android's reconnect-on-restore only arms through the retry machinery, so
+the platform whose drops become errors is also the one that won't heal
+without it. **If surviving tunnels matters to you, enable `retry`.** (The
+web implementation has no automatic retry at all, and no ICY metadata —
+every web error is terminal.)
+
+## Fresh URLs on every reconnect
+
+If your stream URLs are signed or short-lived, build them in
+[`media.resolve`](/guide/browser#media-and-artwork) — the per-track layer of
+the stream request. Every recovery path re-runs it rather than replaying the
+cached URL: automatic retry, network restore, play-from-`'error'`. A URL
+that expired during the outage is re-signed instead of re-failing.
+
+```ts
+import { configureBrowser } from 'react-native-audio-browser'
+
+// Merge `media` into your one configureBrowser call — it replaces the
+// whole config, so a media-only call would drop your tabs and routes.
+configureBrowser({
+  media: {
+    resolve: async (track) => ({
+      path: `/stream/${track.id}`,
+      // sign() is yours — however your backend mints stream tokens
+      query: { token: await sign(track.id) }
+    })
+  }
+})
+```
+
+A relative `path` is joined to your configured `baseUrl` — see
+[Shaping requests](/guide/browser#shaping-requests) for the layering.
+
+## The live edge
+
+[`seekToLiveEdge()`](/api/features/playback/#seektoliveedge) jumps a live
+track back to the newest available audio — a no-op unless the current track
+declares `live: true`. On a stream with a seekable live window (HLS with a
+sliding window) it seeks to the window's edge; on a non-seekable one
+(typical ICY radio) it reconnects instead — a fresh connection _is_ the
+live edge, and an expired URL re-resolves through `media.resolve`. General
+seeking is in [Playback](/guide/playback).
+
+## API summary
+
+| API                                                          | Purpose                                                           |
+| ------------------------------------------------------------ | ----------------------------------------------------------------- |
+| [`Track.live`](/api/types/browser-nodes/#track)              | Declare a live track: iOS live indicator, arms the live edge.     |
+| [`seekToLiveEdge()`](/api/features/playback/#seektoliveedge) | Jump to the newest audio (no-op for non-live tracks).             |
+| [`setupPlayer({ retry })`](/guide/errors#automatic-retry)    | Automatic retry: 12 s first-connect / 2 min recovery budgets.     |
+| [`retry()`](/guide/errors#manual-retry)                      | Restart from `'error'` with fresh budgets.                        |
+| [`media.resolve`](/guide/browser#media-and-artwork)          | Build each (re)load's stream request — signed / short-lived URLs. |
+| [`useOnline()`](/guide/network)                              | Connectivity for your own UI; playback reacts on its own.         |

package/website/guide/metadata.md

@@ -0,0 +1,239 @@
+---
+description: 'Read the metadata coming out of the media as it plays: the live ICY or HLS song, the static tags baked into a file, and chapter markers.'
+---
+
+# Metadata
+
+As a track plays, the player surfaces metadata it reads _from the media_ — the
+live "now playing song" of a radio stream, the tags embedded in an audio file,
+and chapter markers. These arrive as three independent event streams:
+
+- [`onTimedMetadata`](/api/features/metadata/#ontimedmetadata) — the live song
+  from a stream (ICY radio or HLS in-band ID3), changing as the broadcast does.
+- [`onTrackMetadata`](/api/features/metadata/#ontrackmetadata) — the static tags
+  baked into a media file, read when it loads.
+- [`onChapterMetadata`](/api/features/metadata/#onchaptermetadata) — chapter
+  markers with time ranges, for podcasts and audiobooks.
+
+These are **read-only signals coming _in_** from the media — they don't change
+what's displayed anywhere. It's up to you to do something with them: feed the
+[Now Playing](/guide/now-playing) surfaces, render your own UI, or build a
+chapter list. (Each is subscription-only — there's no getter or hook; you
+subscribe and keep the latest value yourself, as shown below.)
+
+The UI snippets below import `useEffect` / `useState` from `react`, and `Text` /
+`Button` / `Image` / `FlatList` from `react-native`; those import lines are
+omitted for brevity. Everything else comes from `react-native-audio-browser`.
+
+## Subscribing
+
+Every metadata event follows the same shape: `addListener` registers a callback
+and returns a cleanup function that unsubscribes.
+
+```ts
+import { onTimedMetadata } from 'react-native-audio-browser'
+
+const unsubscribe = onTimedMetadata.addListener((metadata) => {
+  console.log('now playing:', metadata.title)
+})
+
+// later:
+unsubscribe()
+```
+
+Because the cleanup function is exactly what React's `useEffect` wants returned,
+turning any of these into reactive state is a one-liner — see
+[Holding metadata in state](#holding-metadata-in-state).
+
+## Timed metadata — the live song
+
+[`onTimedMetadata`](/api/features/metadata/#ontimedmetadata) delivers the
+"now playing song" announced by a live stream. Two formats arrive through this
+one event:
+
+- **ICY** metadata — Shoutcast / Icecast HTTP radio.
+- **In-band ID3** timed metadata — how **HLS** live streams (and some others)
+  carry the current song.
+
+It fires each time the stream announces a new song, so the value changes
+throughout a single track.
+
+[`TimedMetadata`](/api/features/metadata/#timedmetadata) — every field optional:
+
+| Field    | Meaning                                          |
+| -------- | ------------------------------------------------ |
+| `title`  | The song title (often "Artist - Song" in ICY).   |
+| `artist` | The artist, when the stream sends it separately. |
+| `album`  | The album, when present.                         |
+| `date`   | A date string, when present.                     |
+| `genre`  | The genre, when present.                         |
+
+::: warning ICY sends only a title
+Shoutcast / Icecast (ICY) radio populates **only `title`** — typically a combined
+`"Artist - Song"` string. `artist`, `album`, `date`, and `genre` stay `undefined`
+for ICY; they're filled only by ID3 / HLS / file metadata. For a radio app,
+parse `title` yourself rather than binding `metadata.artist`.
+:::
+
+This is the signal behind a live station's "now playing" line. To show it on the
+lock screen / car, you usually don't subscribe here directly — you read it inside
+the Now Playing formatter, which is re-invoked on every timed-metadata update.
+See [Now Playing → the formatter](/guide/now-playing#the-formatter-derived-continuous).
+Subscribe to `onTimedMetadata` when you want the live song for _your own_ UI.
+
+## Track metadata — the file's tags
+
+[`onTrackMetadata`](/api/features/metadata/#ontrackmetadata) delivers the static
+metadata baked into a media file — ID3 tags on an MP3, the metadata atoms in an
+MP4/M4A — read when the player loads the asset. Use it for on-demand content
+(podcast episodes, audiobooks, downloaded files) whose tags you didn't set
+yourself.
+
+[`TrackMetadata`](/api/features/metadata/#trackmetadata) is richer than the
+timed shape. **Every field is an optional `string`:**
+
+| Field          | Meaning                          |
+| -------------- | -------------------------------- |
+| `title`        | Track title.                     |
+| `artist`       | Track artist.                    |
+| `albumTitle`   | Album name.                      |
+| `subtitle`     | Secondary line.                  |
+| `description`  | Long description / show notes.   |
+| `artworkUri`   | Artwork URL.                     |
+| `trackNumber`  | Track number within the album.   |
+| `composer`     | Composer credit.                 |
+| `conductor`    | Conductor credit.                |
+| `genre`        | Genre.                           |
+| `compilation`  | Compilation name.                |
+| `station`      | Station/channel name.            |
+| `mediaType`    | Media type string.               |
+| `creationDate` | Full creation date.              |
+| `creationYear` | Creation year.                   |
+| `url`          | A URL associated with the track. |
+
+```tsx
+import { onTrackMetadata, type TrackMetadata } from 'react-native-audio-browser'
+
+function FileInfo() {
+  const [meta, setMeta] = useState<TrackMetadata>()
+  useEffect(() => onTrackMetadata.addListener(setMeta), [])
+  if (!meta) return null
+  return (
+    <>
+      {meta.artworkUri && <Image source={{ uri: meta.artworkUri }} />}
+      <Text>
+        {meta.title} — {meta.artist}
+      </Text>
+      <Text>{meta.description}</Text>
+    </>
+  )
+}
+```
+
+::: tip Mind the field names
+Two traps when moving between the streams:
+
+- **title vs title:** `TimedMetadata.title` is the _song_ (changes during a live
+  stream); `TrackMetadata.title` is the _file's_ title (static, read once).
+- **album vs albumTitle:** timed metadata uses `album`; track metadata uses
+  `albumTitle`. And `TimedMetadata` has no artwork field — only `TrackMetadata`
+  carries `artworkUri`.
+  :::
+
+## Chapter metadata — podcast & audiobook chapters
+
+[`onChapterMetadata`](/api/features/metadata/#onchaptermetadata) delivers the
+full list of chapters for the current track as a
+[`ChapterMetadata[]`](/api/features/metadata/#chaptermetadata):
+
+| Field       | Type      | Meaning                                        |
+| ----------- | --------- | ---------------------------------------------- |
+| `startTime` | `number`  | Chapter start, in **seconds**.                 |
+| `endTime`   | `number`  | Chapter end, in **seconds**.                   |
+| `title`     | `string?` | Chapter title, if present.                     |
+| `url`       | `string?` | A URL associated with the chapter, if present. |
+
+Because `startTime` is in seconds, it drops straight into
+[`seekTo`](/guide/playback#seeking) to make a tappable chapter list:
+
+```tsx
+import {
+  onChapterMetadata,
+  seekTo,
+  type ChapterMetadata
+} from 'react-native-audio-browser'
+
+function ChapterList() {
+  const [chapters, setChapters] = useState<ChapterMetadata[]>([])
+  useEffect(() => onChapterMetadata.addListener(setChapters), [])
+
+  return (
+    <FlatList
+      data={chapters}
+      keyExtractor={(chapter) => String(chapter.startTime)}
+      renderItem={({ item }) => (
+        <Button
+          title={item.title ?? 'Chapter'}
+          onPress={() => seekTo(item.startTime)}
+        />
+      )}
+    />
+  )
+}
+```
+
+## Which metadata is which
+
+|             | `onTimedMetadata`       | `onTrackMetadata`      | `onChapterMetadata`         |
+| ----------- | ----------------------- | ---------------------- | --------------------------- |
+| Source      | Live stream (ICY / ID3) | Tags in the media file | Chapter markers in the file |
+| Changes     | Throughout the track    | Once, on load          | Once, on load               |
+| Shape       | One `TimedMetadata`     | One `TrackMetadata`    | A `ChapterMetadata[]`       |
+| Typical use | Live "now playing" song | Podcast/file info      | Chapter navigation          |
+| Platform    | iOS, Android            | iOS, Android           | iOS, Android                |
+
+::: warning Not available on web
+All three are iOS and Android only. On web they are subscribable but never
+fire, so a listener sees nothing and
+[`FormatNowPlayingParams.timedMetadata`](/api/features/player/#formatnowplayingparams)
+stays `undefined`.
+
+ICY is the hard case: the browser strips the interleaved metadata before the
+player can reach it, and no API exposes it. In-band ID3 from HLS _is_ reachable
+through the web player and simply isn't wired up yet — that part is tracked in
+[#118](https://github.com/radio-garden/react-native-audio-browser/issues/118).
+:::
+
+## Holding metadata in state
+
+None of these come with a built-in hook, but each `addListener` returns the
+cleanup function `useEffect` expects, so a reusable hook is a few lines:
+
+```tsx
+import { onTimedMetadata, type TimedMetadata } from 'react-native-audio-browser'
+
+// Returns TimedMetadata | undefined (undefined until the first event).
+function useTimedMetadata(): TimedMetadata | undefined {
+  const [metadata, setMetadata] = useState<TimedMetadata>()
+  useEffect(() => onTimedMetadata.addListener(setMetadata), [])
+  return metadata
+}
+
+function NowPlayingSong() {
+  const song = useTimedMetadata()
+  return <Text>{song?.title ?? 'Unknown'}</Text>
+}
+```
+
+The same pattern works for `onTrackMetadata` and `onChapterMetadata` — swap the
+event and the state type.
+
+## API summary
+
+| API                 | Delivers                                                 |
+| ------------------- | -------------------------------------------------------- |
+| `onTimedMetadata`   | Live `TimedMetadata` (the streaming "now playing" song). |
+| `onTrackMetadata`   | Static `TrackMetadata` (the media file's embedded tags). |
+| `onChapterMetadata` | `ChapterMetadata[]` (chapter markers, times in seconds). |
+
+All three are subscriptions: `addListener(cb)` returns an unsubscribe function.