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

package/website/guide/artwork.md

@@ -0,0 +1,255 @@
+---
+description: 'Set Track.artwork once and render it everywhere: the fetch and transform pipeline, per-surface sizing, SF Symbols, tinting, light/dark pairs, Android vector icons, and SVG.'
+---
+
+# Artwork
+
+**Artwork** is the image shown for a track — the thumbnail in a browse list, the cover on the lock screen, the icon on a CarPlay row. You set one field, `artwork`, on a [`Track`](/guide/track); the library resolves and transforms it per surface and per requested size, and hands the ready-to-render result back on `artworkSource`.
+
+This guide covers the mental model (the two configs and the output field), **which artwork renders where**, the **transform pipeline** that turns your URL into a sized request, and the platform-specific bits: SF Symbols on iOS, tinting, light/dark artwork, Android vector icons, and SVG.
+
+## Mental model
+
+Three names do all the work:
+
+| Name                                   | What it is                                                                                                                     | You                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| `Track.artwork`                        | The image **you set** — an `https` URL, an `sf:` symbol (iOS), a platform URI, or a `{ light, dark }` pair.                    | set it                                                |
+| `artwork` / `nowPlayingArtwork` config | How the library **fetches** that image (base URL, headers, signing, sizing).                                                   | configure once (override per route / for now-playing) |
+| `Track.artworkSource`                  | The resolved, ready-to-render [`ImageSource`](/api/types/browser-nodes/#imagesource) (URL + headers) the library **produces**. | read it                                               |
+
+`artwork` is the only field you set per track. `artworkSource` is **output-only** — the library populates it; never set it yourself.
+
+```tsx
+import { useActiveTrack } from 'react-native-audio-browser'
+import { Image } from 'react-native'
+
+function Cover() {
+  const track = useActiveTrack()
+  // artworkSource is the transformed result, shaped for <Image>
+  return <Image source={track?.artworkSource} />
+}
+```
+
+## Which artwork renders where
+
+The library publishes art to several surfaces; each gets its image from a field/config and (where the surface knows its display size) a size hint:
+
+| Surface                                         | Image from                                    | Size hint | Tinting                                                                        |
+| ----------------------------------------------- | --------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
+| **Browse rows / tabs** (CarPlay / Android Auto) | `artwork` (per-route override allowed)        | no        | CarPlay: `style: { artworkRendering: 'stencil' }`, or a `{ light, dark }` pair |
+| **In-app `<Image>`**                            | `artworkSource` (output)                      | no        | your UI                                                                        |
+| **iOS lock screen / Control Center**            | `nowPlayingArtwork` → falls back to `artwork` | yes       | —                                                                              |
+| **CarPlay Now Playing**                         | `nowPlayingArtwork` → `artwork`               | yes       | —                                                                              |
+| **Android notification / Android Auto**         | `nowPlayingArtwork` → `artwork`               | yes       | — (Android Auto is dark-only)                                                  |
+| **CarPlay tile sections** (`display: 'grid'`)   | `artwork` (each tile is a Track)              | yes       | CarPlay: `style: { artworkRendering: 'stencil' }`, or a `{ light, dark }` pair |
+
+**Size hint** = the surface tells the library the pixels it needs, delivered as an [`ImageContext`](/api/types/browser/#imagecontext) to your `transform` / `imageQueryParams`. Browse-time resolution has none.
+
+Two things to take from the table:
+
+- **One image by default.** With only `artwork` set, the same source feeds browse rows _and_ every now-playing surface. Set `nowPlayingArtwork` only when the now-playing image should differ (a larger, lock-screen-quality cover without bloating list thumbnails).
+- **Size hints exist only where the surface knows its size.** Browse-time resolution has no size, so `imageQueryParams` and `context` (below) do nothing there; they kick in at load time on CarPlay / Android Auto / now-playing.
+- **Tinting is for browse icons only.** `artworkRendering: 'stencil'` is applied when CarPlay renders browse content — list rows, tabs, and tiles — not to now-playing cover art.
+
+## The transform pipeline
+
+`artwork` is an [`ArtworkRequestConfig`](/api/types/browser/#artworkrequestconfig). When the library needs a track's image, it builds the request in layers, each overriding the last:
+
+1. **`request`** — shared base config (user agent, common headers).
+2. **`artwork`** — the static image config (`baseUrl`, `headers`, …).
+3. **`resolve(track)` / `resolveSync(track)`** — per-track overrides built from the track's metadata.
+4. **`imageQueryParams`** — appends the surface's requested size (when it reports one).
+5. **`transform({ request, context })` / `transformSync`** — final tweak, with the requested size in `context`.
+
+To build a per-track URL, use `resolve` (the track is the argument). The `{id}` token is **not** a general feature — only `nowPlayingArtwork` templates it (see below); static values in `artwork` are sent verbatim.
+
+A typical CDN setup never needs more than `baseUrl` plus `imageQueryParams`:
+
+```ts
+import { configureBrowser } from 'react-native-audio-browser'
+
+configureBrowser({
+  // ...the rest of your config (tabs, routes, …)
+  artwork: {
+    baseUrl: 'https://images.example.com',
+    // tell the library which query params carry the requested size
+    imageQueryParams: { width: 'w', height: 'h' }
+  }
+})
+```
+
+With [`imageQueryParams`](/api/types/browser/#imagequeryparams) the requested size from CarPlay / Android Auto is appended automatically — `?w=200&h=200` — so each surface gets right-sized art. Omit `height` to send width only. This only fires on surfaces that report a size; browse rows (no size hint) get the URL without these params.
+
+For anything `imageQueryParams` can't express — per-track paths, signed URLs — use `resolve` and `transform` (or their sync variants):
+
+```ts
+import { configureBrowser } from 'react-native-audio-browser'
+import HmacSHA256 from 'crypto-js/hmac-sha256' // add: yarn add crypto-js
+
+const CDN_KEY = process.env.CDN_KEY ?? '' // your CDN signing key
+
+// sign the path locally with your key — a pure, sync function
+const signUrl = (path: string) => HmacSHA256(path, CDN_KEY).toString()
+
+configureBrowser({
+  artwork: {
+    baseUrl: 'https://images.example.com',
+    // build the path from the track (sync — no await needed)
+    resolveSync: (track) => ({ path: `/covers/${track.id}.jpg` }),
+    // then sign it + size it. both are sync, so no Promise is
+    // allocated per image
+    transformSync: ({ request, context }) => ({
+      ...request,
+      query: {
+        ...request.query,
+        w: context?.width ? String(context.width) : '600',
+        // request.path is optional — guard it before signing
+        sig: signUrl(request.path ?? '')
+      }
+    })
+  }
+})
+```
+
+A `transform` (or `transformSync`) **replaces** the request — it doesn't merge — so spread `...request` (and `...request.query`) or you'll drop the `baseUrl` and other layers. The [`context`](/api/types/browser/#imagecontext) is an `ImageContext` with `width` / `height` in **pixels**, present only when the surface knows its display size (so guard with `context?.width`). `request.path` is also optional — it's only set if a `resolve` ran first — so guard it before signing (as above).
+
+`resolveSync` / `transformSync` are no-Promise variants of `resolve` / `transform`. Reach for them when the per-track config or final tweak needs no `await` — a synced query param, a locally-computed path — to skip a Promise allocation per image (the example above is fully sync for that reason). If you set _both_ the sync and async form of the **same** stage (e.g. `transform` _and_ `transformSync`), the async one runs first and the sync one tweaks its result; `resolve` and `transform` are independent stages that both always run.
+
+::: tip Per-route artwork
+A route can override the global `artwork` with its own config — `routes: { '/premium': { artwork: { baseUrl: '…' } } }` — so different content can load images from different hosts. See the [Browser](/guide/browser) guide.
+:::
+
+## SF Symbols (iOS)
+
+Prefix `artwork` with `sf:` to render an Apple [SF Symbol](https://developer.apple.com/sf-symbols/) instead of fetching an image — ideal for tab and category icons. Optional `bg` (background, transparent if omitted) and `fg` (symbol color, black if omitted) query params set the colors:
+
+```ts
+{
+  title: 'Favorites',
+  path: '/favorites',
+  artwork: 'sf:heart.fill?bg=#FF0090&fg=#fff'
+}
+```
+
+On CarPlay, an SF Symbol with **no explicit colors** is handed to CarPlay untinted, so CarPlay renders it in the appearance's own color (adapting to light/dark); give it a `bg`/`fg` and you get exactly those colors instead. The library renders the symbol to an image on device and caches it. This is iOS-only; on Android an `sf:` value is not a valid image.
+
+## Tinting and platform icons
+
+For monochrome **icons** (not full-color album art), let the system tint them to stay legible on either appearance:
+
+- **iOS CarPlay** — declare [`style: { artworkRendering: 'stencil' }`](/api/types/browser-nodes/#trackstyle) on the track. Inside a page it's an inherited style property (a section- or page-wide value covers every item); tabs render without a section context, so a tab icon needs the declaration on the tab track itself. CarPlay tints the glyph per appearance: black in light mode, white in dark.
+- **Android Auto** is dark-only, so there's no per-appearance tinting — ship an appropriately colored (e.g. white) icon. When a layout is declared (`display` on the section, page, or parent item), an `android.resource://…/drawable/…` artwork URI switches Android Auto to the **category** variant of that layout (which adds icon margins and lets Android Auto render it as an icon). The library only sets the category style; the visual treatment is Android Auto's — see [Browse display](/guide/android-auto#browse-display).
+
+```ts
+{
+  title: 'Settings',
+  path: '/settings',
+  artwork: 'sf:gear',
+  style: { artworkRendering: 'stencil' }
+}
+```
+
+**SVG** is supported on both platforms and detected by a `.svg` URL suffix — serve SVGs with a path ending in `.svg` and they decode as vectors rather than raster images.
+
+## Light and dark artwork
+
+Tinting recolors _one_ image. When the two appearances need genuinely **different** images — a logo whose colors change, a mark with a light-on-dark counterpart — set `artwork` to an [`ArtworkVariants`](/api/types/browser-nodes/#artworkvariants) pair instead of a URL:
+
+```ts
+{
+  title: 'Playlists',
+  path: '/playlists',
+  artwork: {
+    light: 'https://images.example.com/playlists-light.png',
+    dark: 'https://images.example.com/playlists-dark.png'
+  }
+}
+```
+
+Both fields are required — a pair with one side missing has no sensible fallback at render time.
+
+On CarPlay browse rows and tabs the library fetches both and registers them as a single adaptive image, so switching appearance mid-drive swaps the image **in place** — no re-fetch, and no re-query of the browse tree. Each URL runs through the [transform pipeline](#the-transform-pipeline) independently, so `baseUrl`, headers, `imageQueryParams` and `resolve` / `transform` apply to both.
+
+Everywhere a single image is required, a pair resolves to its `dark` URL:
+
+| Surface                                  | Uses                          |
+| ---------------------------------------- | ----------------------------- |
+| **CarPlay browse rows / tabs**           | both, adapting per appearance |
+| **Android Auto**                         | `dark` (dark-only platform)   |
+| **Now-playing** (all platforms)          | `dark`                        |
+| **`artworkSource`** (your own `<Image>`) | `dark`                        |
+
+::: tip Pair or tint?
+Prefer [`artworkRendering: 'stencil'`](#tinting-and-platform-icons) when recoloring the same shape gives the right result: it's one fetch instead of two, the variants can't drift apart, and it works from the image's alpha so the source color is irrelevant. Reach for a pair only when the appearances need different artwork.
+:::
+
+::: warning Android Auto fetches only `http(s)` artwork
+Browse artwork is served to Android Auto through an internal content provider that only fetches `http`/`https` URLs. `android.resource://` and `file://` URIs pass through and render directly; other custom schemes won't load there.
+:::
+
+## Now-playing artwork
+
+By default the now-playing image (lock screen, Control Center, CarPlay / Android Auto Now Playing) is the active track's `artwork` — the same image as its browse-row thumbnail. To resolve it differently, set `nowPlayingArtwork`, which builds the now-playing image from its **own** request and uniquely supports an `{id}` template filled from the active track's `id`:
+
+```ts
+import { configureBrowser } from 'react-native-audio-browser'
+
+configureBrowser({
+  nowPlayingArtwork: {
+    baseUrl: 'https://images.example.com',
+    // {id} is replaced with the active track's id
+    path: '/artwork/{id}',
+    // ask the CDN for a lock-screen-quality variant
+    imageQueryParams: { width: 'w', height: 'h' }
+  }
+})
+```
+
+Now-playing surfaces request a **much larger** image than list thumbnails — on iOS, up to the screen width in pixels, capped at 1200px — so with `imageQueryParams` set you fetch a fittingly large variant rather than upscaling a tiny thumbnail.
+
+Two separate ideas here: the **`{id}` template** is replaced with the active track's `id`; and if you _don't_ set `nowPlayingArtwork` at all, now-playing surfaces fall back to the `artwork` config (and to `track.artwork`).
+
+`nowPlayingArtwork` is an `ArtworkRequestConfig` like `artwork`, so it takes the same `resolve` / `transform` / `imageQueryParams`. It is **native-only**: the `{id}` template and the `nowPlayingArtwork` config are not applied by the web implementation, where now-playing artwork simply uses the `artwork` config like any other surface. Artwork is also the one now-playing field the text layers can't touch — the formatter / override / flash carry only `title` / `artist` / `album`. See [Now Playing](/guide/now-playing#now-playing-artwork) for the metadata side.
+
+::: warning Now-playing artwork follows the active track
+Now-playing artwork is resolved **once per active track**, keyed on its `id` — so it won't re-resolve while the same track keeps playing. There is no imperative way to swap _only_ the image mid-stream: `updateNowPlaying()` overrides `title` / `artist` / `album`, not artwork. Changing it means making a _new_ active track (a different `id` plus the new `artwork`) the current one, which reloads playback — so it's not a fit for, say, updating live-radio cover art on each song. An in-place update API is tracked in [issue #76](https://github.com/radio-garden/react-native-audio-browser/issues/76).
+:::
+
+## Tile sections
+
+A page's [`Section`](/api/types/browser-nodes/#section) can render its tracks as tappable artwork tiles by declaring `style: { display: 'grid' }` (wrapping; add `gridWrap: false` for a single line of tiles):
+
+```ts
+{
+  path: '/home',
+  title: 'Home',
+  sections: [
+    {
+      title: 'Featured',
+      style: { display: 'grid', gridWrap: false },
+      path: '/browse/featured', // header / "view all" target
+      children: [
+        { title: 'Jazz', path: '/browse/jazz', artwork: 'https://…/jazz.jpg' },
+        { title: 'Rock', path: '/browse/rock', artwork: 'https://…/rock.jpg' }
+      ]
+    }
+  ]
+}
+```
+
+Each tile is an ordinary Track, so its `artwork` runs through the same pipeline as any other. Tile styles presume artwork: a track without any renders as a placeholder tile plus its title — the artwork `resolve` hook is the place to supply fallback art. On CarPlay a single-line grid (`gridWrap: false`) shows the tiles that fit (roughly eight, width-dependent; the rest are truncated) and a wrapping grid takes as many lines as it needs on iOS 26+ (rendering as a list before that); Android Auto's grid always wraps, so it renders both identically. See [Browser → Presentation](/guide/browser#presentation) for the full per-surface rundown.
+
+## API summary
+
+| Symbol                                                                | Purpose                                                                               |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| [`Track.artwork`](/api/types/browser-nodes/#track)                    | The image you set — `https` URL, `sf:` symbol (iOS), or platform URI.                 |
+| [`Track.artworkSource`](/api/types/browser-nodes/#track)              | Output-only resolved `ImageSource` for your own `<Image>`.                            |
+| [`TrackStyle.artworkRendering`](/api/types/browser-nodes/#trackstyle) | `'stencil'` tints a monochrome icon per CarPlay light/dark (iOS only).                |
+| [`ArtworkVariants`](/api/types/browser-nodes/#artworkvariants)        | A `{ light, dark }` pair set on `artwork` when the appearances need different images. |
+| [`artwork`](/api/types/browser/#artworkrequestconfig)                 | Config for browse-row image requests (and the default everywhere).                    |
+| `nowPlayingArtwork`                                                   | Separate config for now-playing art; supports `{id}`; native-only.                    |
+| [`imageQueryParams`](/api/types/browser/#imagequeryparams)            | Map the surface's requested size to your CDN's query params.                          |
+| [`ImageContext`](/api/types/browser/#imagecontext)                    | Requested `width`/`height` in pixels, passed to `transform`.                          |
+| [`Section.style`](/api/types/browser-nodes/#sectionstyle)             | `display: 'grid'` (± `gridWrap: false`) renders a section's tracks as artwork tiles.  |

package/website/guide/audio-output.md

@@ -0,0 +1,135 @@
+---
+description: 'Read where audio is currently playing (speaker, Bluetooth, AirPlay, the car), react when the route changes, and open the system output switcher.'
+---
+
+# Audio Output
+
+Read where audio is currently playing (speaker, Bluetooth, AirPlay, the car…),
+react when it changes, and open the system output switcher so the listener can
+move playback to another device. Both layers are **cross-platform**:
+
+- **Reading the current output** — `getOutput()` / `useOutput()` /
+  `onOutputChanged`. iOS reports the active route while a session is active;
+  Android reports the active output route from `AudioManager` (the `type` is
+  coarse — e.g. wired headphones may report as `speaker`).
+- **Opening the switcher** — `openOutputPicker()` / `supportsOutputSwitcher()`:
+  the system route picker on iOS, the system Output Switcher on Android 11+.
+
+::: tip Gate the switcher button on `supportsOutputSwitcher()`
+Surface your output button only when `supportsOutputSwitcher()` is `true` — it's
+`true` on iOS and Android 11+ (API 30), `false` on older Android and web.
+Reading the current output works more broadly, but `getOutput()` can still be
+`undefined` (before playback, or when unknown) — so guard for it.
+:::
+
+The UI snippets import `Text` / `Button` from `react-native`; everything else is
+from `react-native-audio-browser`.
+
+## The current output
+
+[`useOutput()`](/api/features/output/#useoutput) returns the active output and
+re-renders whenever it changes (AirPods connect, headphones unplug, a Bluetooth
+speaker is selected):
+
+```tsx
+import { Text } from 'react-native'
+import { useOutput } from 'react-native-audio-browser'
+
+function OutputLabel() {
+  const output = useOutput()
+  if (!output) return null // not yet known
+  return <Text>Playing on {output.name}</Text>
+}
+```
+
+An [`Output`](/api/features/output/#output) is:
+
+| Field      | Type         | Meaning                                                                         |
+| ---------- | ------------ | ------------------------------------------------------------------------------- |
+| `name`     | `string`     | Human-readable device name, e.g. `"AirPods Pro"`, `"Kitchen speaker"`.          |
+| `type`     | `OutputType` | The output kind (see below).                                                    |
+| `external` | `boolean`    | `false` only for the built-in speaker/receiver; `true` for everything external. |
+
+`type` is one of `'speaker'`, `'receiver'` (the iOS earpiece), `'headphones'`,
+`'bluetooth'`, `'airplay'`, `'car'`, `'hdmi'`, `'usb'`, `'cast'` (a remote
+speaker / TV), or `'other'`. Both platforms map their native ports/routes into
+this shared set — e.g. iOS's separate Bluetooth ports all collapse to
+`'bluetooth'`.
+
+::: warning Android reports a coarser type
+On Android the type comes from the system route and is coarser: wired headphones
+often report as `'speaker'` (the built-in route), and really only `'bluetooth'`
+is reliably distinguished from it (`'cast'` requires active route discovery,
+which the reader doesn't run, so it won't appear here). The device **name** still
+comes through.
+:::
+
+Outside React, read a snapshot with `getOutput()` or subscribe with
+[`onOutputChanged`](/api/features/output/#onoutputchanged):
+
+```ts
+import { getOutput, onOutputChanged } from 'react-native-audio-browser'
+
+getOutput() // Output | undefined
+
+const unsubscribe = onOutputChanged.addListener((output) => {
+  console.log('now playing on', output.name)
+})
+
+// later:
+unsubscribe()
+```
+
+## Opening the output picker
+
+[`openOutputPicker()`](/api/features/output/#openoutputpicker) presents the
+system output switcher — the AirPlay / Bluetooth / speaker chooser on iOS, and
+the Bluetooth / speaker / Cast switcher on Android (11+). Wire it to your own
+output button, shown only when
+[`supportsOutputSwitcher()`](/api/features/output/#supportsoutputswitcher) is
+`true`:
+
+```tsx
+import { Button } from 'react-native'
+import {
+  openOutputPicker,
+  supportsOutputSwitcher
+} from 'react-native-audio-browser'
+
+function OutputButton() {
+  if (!supportsOutputSwitcher()) return null // older Android / web
+  return <Button title="Output" onPress={() => openOutputPicker()} />
+}
+```
+
+`openOutputPicker()` is safe to call unconditionally — it's a no-op where no
+switcher exists — but gating the button on `supportsOutputSwitcher()` keeps you
+from showing a control that would do nothing.
+
+On Android the switcher is the system one (the picker from the media
+notification); selecting a Bluetooth speaker there routes audio at the OS level.
+The library can't force playback to a _specific_ Bluetooth device itself — route
+selection is the system's job, which is what this hands off to. Sonos appears on
+iOS (as an AirPlay target); on Android it isn't a system route, so it won't show.
+
+## You may not need this for unplug handling
+
+When the current output **disappears** — headphones unplugged, a Bluetooth
+speaker powered off — the player **pauses automatically** rather than blaring out
+of the built-in speaker (the convention every media app follows). It's a
+deliberate pause: the listener presses play again when ready. So you don't need
+to watch `onOutputChanged` just to handle unplugging — reach for these APIs to
+_display_ the output or to _offer_ a switcher.
+
+## API summary
+
+| API                        | Platforms        | Purpose                                                                    |
+| -------------------------- | ---------------- | -------------------------------------------------------------------------- |
+| `openOutputPicker()`       | iOS, Android 11+ | Present the system output switcher (Bluetooth / AirPlay / speaker / Cast). |
+| `supportsOutputSwitcher()` | all              | Whether a switcher can be shown — gate your output button on it.           |
+| `useOutput()`              | iOS, Android     | Reactive current output (`Output \| undefined`).                           |
+| `getOutput()`              | iOS, Android     | One-off snapshot of the current output.                                    |
+| `onOutputChanged`          | iOS, Android     | Subscribe outside React; `addListener(cb)` returns an unsubscribe fn.      |
+
+The whole API is cross-platform; only the switcher needs Android 11+ (gate on
+`supportsOutputSwitcher()`), and Android reports coarser output `type`s than iOS.

package/website/guide/automotive.md

@@ -0,0 +1,86 @@
+---
+description: 'How CarPlay, Android Auto, and Android Automotive all reuse the browse tree, queue, now-playing metadata, and search source you have already built.'
+---
+
+# In the car
+
+CarPlay, Android Auto, and Android Automotive all show your content on the car
+screen and play through the same player as your app. You don't build a separate
+"car app" — the car surfaces are driven by the **same cross-cutting pieces you've
+already built**:
+
+- your [browse tree](/guide/browser) becomes the car's browsable menus,
+- your [now-playing metadata](/guide/now-playing) fills the car's now-playing
+  screen,
+- the [player and queue](/guide/playback) are shared, so playback is continuous
+  whether the user started it in-app or in the car,
+- your [`search` source](/guide/search) answers in-car voice commands
+  ("play jazz"),
+- [favorites](/guide/favorites) surface a heart and a "play my favorites" intent.
+
+Build those once and they light up every car surface. The per-platform pages
+handle the platform-specific **setup**: **[Android Auto](/guide/android-auto)**
+(also Android Automotive) and **[CarPlay](/guide/carplay)**.
+
+## Shared vs platform-specific
+
+| Concern                               | Where it's handled                                                                                                       |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Browse tree / menus                   | Shared — [Browser](/guide/browser)                                                                                       |
+| Now-playing metadata & artwork        | Shared — [Now Playing](/guide/now-playing)                                                                               |
+| Player, queue, playback               | Shared — [Playback](/guide/playback)                                                                                     |
+| Voice search ("play …")               | Shared — your [`search`](/guide/search) source                                                                           |
+| Favorites heart & "play my favorites" | Shared — [Favorites](/guide/favorites)                                                                                   |
+| App setup, entitlements, manifest     | Per-platform — [Android Auto](/guide/android-auto) / [CarPlay](/guide/carplay)                                           |
+| Now-playing buttons                   | Per-platform — [Button layout](/guide/remote-controls#button-layout-android) (Android) / [CarPlay](/guide/carplay) (iOS) |
+
+The takeaway: spend your effort on the shared content model; reach for a platform
+page only for that platform's setup and buttons.
+
+## Detecting a car connection
+
+To adapt your in-app UI while connected to a car (a "now playing in your car"
+state, a simplified screen), use
+[`useCarConnected()`](/api/features/carConnection/#usecarconnected). It's `true`
+for a CarPlay connection on iOS, and an Android Auto **or Android Automotive**
+connection on Android (`false` on web):
+
+```tsx
+import { Text } from 'react-native'
+import { useCarConnected } from 'react-native-audio-browser'
+
+function CarBadge() {
+  const inCar = useCarConnected()
+  if (!inCar) return null
+  return <Text>Playing in your car</Text>
+}
+```
+
+Outside React, read a snapshot with
+[`isCarConnected()`](/api/features/carConnection/#iscarconnected) or subscribe
+with [`onCarConnectedChanged`](/api/features/carConnection/#oncarconnectedchanged)
+(`addListener` returns an unsubscribe function):
+
+```ts
+import {
+  isCarConnected,
+  onCarConnectedChanged
+} from 'react-native-audio-browser'
+
+isCarConnected() // boolean
+
+const unsubscribe = onCarConnectedChanged.addListener((connected) => {
+  // ...
+})
+// later: unsubscribe()
+```
+
+## Next steps
+
+1. Set up the platform(s) you ship to —
+   **[Android Auto](/guide/android-auto)** (and Android Automotive) and/or
+   **[CarPlay](/guide/carplay)**.
+2. Make sure your [browse tree](/guide/browser) and
+   [now-playing](/guide/now-playing) are in good shape — that's what the car
+   renders.
+3. Wire your [`search` source](/guide/search) so voice commands work in the car.

package/website/guide/basic-usage.md

@@ -0,0 +1,151 @@
+---
+description: 'The browse tree in one page: browsable versus playable Tracks, setting up the player, declaring content, and playing it.'
+---
+
+# Basic Usage
+
+This guide covers the core idea — the **browse tree** — and the minimal code to set up the player, define some content, and play it. Installation is in [Getting Started](/guide/getting-started).
+
+## The browse tree
+
+The library models all content as one navigable tree of **Tracks**. A single Track is **browsable**, **playable**, or both, depending on which fields you set:
+
+- **Browsable** — has a `path`; navigating into it resolves its children.
+- **Playable** — has a `src`; the player can stream it.
+
+Three fields at a glance — each answers a different question about a Track:
+
+| Field  | Answers            | Meaning                                                   |
+| ------ | ------------------ | --------------------------------------------------------- |
+| `path` | where does it go?  | the browse-tree address navigating opens                  |
+| `src`  | what does it play? | the media identifier the player streams                   |
+| `id`   | which item is it?  | identity across surfaces — falls back to `src` when unset |
+
+```mermaid
+graph TD
+    Root[Root]
+    Root --> Favorites[Favorites]
+    Root --> Recent[Recently Played]
+    Root --> Browse[Browse]
+
+    Browse --> Jazz[Jazz]
+    Browse --> Rock[Rock]
+
+    Jazz --> J1[Smooth Floret FM]
+    Jazz --> J2[The Stalk 88.5]
+    Rock --> R90[Vintage]
+    Rock --> R1[Crunchy Greens]
+    Rock --> R2[Stem City Radio]
+    R90 --> R3[Funky Floret 101.3]
+    R90 --> R4[Wilted Greens FM]
+
+    classDef browsable fill:#e3f2fd,stroke:#1976d2
+    classDef playable fill:#e8f5e9,stroke:#388e3c
+
+    class Root,Favorites,Recent,Browse,Jazz,Rock,R90 browsable
+    class J1,J2,R1,R2,R3,R4 playable
+```
+
+<div style="display: flex; gap: 1rem; margin-top: 0.5rem; font-size: 0.9em;">
+  <span><span style="display: inline-block; width: 12px; height: 12px; background: #e3f2fd; border: 1px solid #1976d2; margin-right: 4px;"></span> Browsable: opens to children</span>
+  <span><span style="display: inline-block; width: 12px; height: 12px; background: #e8f5e9; border: 1px solid #388e3c; margin-right: 4px;"></span> Playable: streams audio</span>
+</div>
+
+One tree powers both your in-app UI and the native browse views on CarPlay and Android Auto.
+
+## Set up the player
+
+Call `setupPlayer()` once at startup to initialize the player:
+
+```ts
+import { setupPlayer } from 'react-native-audio-browser'
+
+await setupPlayer()
+```
+
+## Define a browse tree
+
+Describe the tree with `configureBrowser`: **tabs** along the top, and **routes** that resolve each path to its children. The simplest source is static data declared inline:
+
+```ts
+import { configureBrowser } from 'react-native-audio-browser'
+
+configureBrowser({
+  tabs: [{ title: 'Browse', path: '/browse' }],
+  routes: {
+    '/browse': {
+      path: '/browse',
+      title: 'Browse',
+      children: [
+        {
+          title: 'Jazz',
+          // A path makes this browsable — tapping it opens that path.
+          path: '/browse/jazz'
+        },
+        {
+          title: 'Smooth Floret FM',
+          // A src makes this playable — tapping it streams the track.
+          src: 'https://example.com/floret.mp3'
+        }
+      ]
+    },
+    '/browse/jazz': {
+      path: '/browse/jazz',
+      title: 'Jazz',
+      children: [
+        {
+          title: 'The Stalk 88.5',
+          src: 'https://example.com/stalk.mp3'
+        }
+      ]
+    }
+  }
+})
+```
+
+A route value is a [`BrowserSource`](/api/types/browser/#browsersource): the static page object shown above, an **async callback** that returns one (`'/path': async ({ routeParams }) => ({ title, children })`), or an HTTP request config that fetches it from your API — handy for trees too large to declare upfront.
+
+A page can also group its tracks into titled, styled **sections** (`sections: [{ title, style, children }, …]`) — a flat `children` list like the ones above is shorthand for a single untitled section. See [Browser → How a path resolves](/guide/browser#how-a-path-resolves).
+
+## Play a track
+
+On CarPlay and Android Auto, tapping a playable Track plays it for you. To drive playback from your own UI, set a queue and call `play`:
+
+```ts
+import { setQueue, play } from 'react-native-audio-browser'
+
+setQueue([{ title: 'Smooth Floret FM', src: 'https://example.com/floret.mp3' }])
+play()
+```
+
+## The queue
+
+The player works through a **queue** of Tracks. The Track at the current position is the **active track** — it's what plays, and what external next/previous controls (car, headphones, lock screen) move between.
+
+**Now Playing** is the metadata shown on the lock screen, notification, and car surfaces. By default it mirrors the active track; for live streams you can override it as the current song changes — see [Now Playing](/guide/now-playing).
+
+## Read state in your UI
+
+Reactive hooks keep your in-app UI in sync with playback — they re-render automatically as it changes:
+
+```tsx
+import {
+  togglePlayback,
+  usePlayingState,
+  useActiveTrack
+} from 'react-native-audio-browser'
+
+function PlayPauseButton() {
+  const { playing } = usePlayingState()
+  const track = useActiveTrack()
+
+  return (
+    <Button
+      title={playing ? `Pause ${track?.title ?? ''}` : 'Play'}
+      onPress={() => togglePlayback()}
+    />
+  )
+}
+```
+
+See the [API reference](/api/) for the full set of hooks (`useProgress`, `useQueue`, `useNowPlaying`, and more).