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

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).

package/website/guide/battery.md

@@ -0,0 +1,115 @@
+---
+description: 'Detect the Android 12+ battery restrictions that block the foreground service the player needs, and prompt the listener to fix their settings.'
+---
+
+# Battery
+
+On Android 12+, if the OS has put your app under battery restrictions, it
+**blocks the foreground service** the player needs to start audio in the
+background. So when a Bluetooth device or car head unit tries to resume playback
+while your app is killed, nothing happens. This feature detects that block and
+lets you prompt the user to fix their battery settings.
+
+::: warning Android only
+This is an **Android-only** concern (Android 12+ foreground-service limits).
+On iOS every getter/hook here is inert: `getBatteryWarningPending()` is always
+`false`, `getBatteryOptimizationStatus()` is always `'unrestricted'`, the events
+never fire, and `dismissBatteryWarning()` / `openBatterySettings()` are no-ops.
+So you can render the banner below unconditionally — it simply never shows on iOS.
+:::
+
+The UI snippet imports `View` / `Text` / `Button` from `react-native`; everything
+else is from `react-native-audio-browser`.
+
+## The warning banner
+
+A warning becomes **pending** when a background resume is actually blocked. Show
+a banner only while `pending` is true, offering to open settings or dismiss.
+[`useBatteryWarning()`](/api/features/battery/#usebatterywarning) bundles
+everything you need:
+
+```tsx
+import { View, Text, Button } from 'react-native'
+import { useBatteryWarning } from 'react-native-audio-browser'
+
+function BatteryWarningBanner() {
+  const { pending, status, dismiss, openSettings } = useBatteryWarning()
+  if (!pending) return null
+
+  return (
+    <View>
+      <Text>Playback was blocked by battery settings ({status}).</Text>
+      <Button title="Fix" onPress={openSettings} />
+      <Button title="Dismiss" onPress={dismiss} />
+    </View>
+  )
+}
+```
+
+- `openSettings` ([`openBatterySettings`](/api/features/battery/#openbatterysettings))
+  opens this app's system battery settings. When the user returns having set the
+  app to unrestricted, the warning clears itself.
+- `dismiss` ([`dismissBatteryWarning`](/api/features/battery/#dismissbatterywarning))
+  hides the warning without changing settings.
+
+## When the warning clears
+
+`pending` goes back to `false` when any of these happens — you don't clear it
+manually:
+
+- the user calls `dismiss`, or
+- the battery status becomes `'unrestricted'` (e.g. they fixed it in settings).
+
+## Battery optimization status
+
+`status` is the device's current setting for your app:
+
+| Status           | Meaning                                                              |
+| ---------------- | -------------------------------------------------------------------- |
+| `'unrestricted'` | The user allowed the app to run freely in the background.            |
+| `'optimized'`    | Default — the system may limit background work (Doze / App Standby). |
+| `'restricted'`   | Background work is severely limited; services are blocked.           |
+
+Background resume is reliable only when `'unrestricted'`, which is why the "Fix"
+button sends users to settings to grant it.
+
+## Reading state directly
+
+If you don't want the bundled hook, the pieces are available individually:
+
+```ts
+import {
+  getBatteryWarningPending,
+  getBatteryOptimizationStatus,
+  onBatteryWarningPendingChanged,
+  onBatteryOptimizationStatusChanged
+} from 'react-native-audio-browser'
+
+getBatteryWarningPending() // boolean
+getBatteryOptimizationStatus() // 'unrestricted' | 'optimized' | 'restricted'
+
+const off = onBatteryWarningPendingChanged.addListener(({ pending }) => {})
+const off2 = onBatteryOptimizationStatusChanged.addListener(({ status }) => {})
+
+// each addListener returns an unsubscribe function:
+off()
+off2()
+```
+
+The reactive hooks [`useBatteryWarningPending()`](/api/features/battery/#usebatterywarningpending)
+and [`useBatteryOptimizationStatus()`](/api/features/battery/#usebatteryoptimizationstatus)
+wrap the getter+event pairs; `useBatteryWarning()` simply combines both with the
+two actions.
+
+## API summary
+
+| API                                                                     | Purpose                                                                |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `useBatteryWarning()`                                                   | Everything for a banner: `{ pending, status, dismiss, openSettings }`. |
+| `getBatteryWarningPending()` / `useBatteryWarningPending()`             | Is a warning pending? (Android; `false` on iOS)                        |
+| `getBatteryOptimizationStatus()` / `useBatteryOptimizationStatus()`     | Current status (Android; `'unrestricted'` on iOS)                      |
+| `onBatteryWarningPendingChanged` / `onBatteryOptimizationStatusChanged` | Subscribe outside React.                                               |
+| `openBatterySettings()`                                                 | Open the app's system battery settings (Android).                      |
+| `dismissBatteryWarning()`                                               | Dismiss the warning without changing settings (Android).               |
+
+All are **Android-only** — inert (`false` / `'unrestricted'` / no-op) on iOS.