react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.30

package/website/guide/configuration.md

@@ -0,0 +1,173 @@
+---
+description: 'The whole options surface — setupPlayer, updateOptions, and getOptions — mapped to the feature guide that covers each area in depth.'
+---
+
+# Configuration
+
+Everything about how the player behaves is set through three functions:
+
+- [`setupPlayer(options?)`](/api/features/player/#setupplayer) — the one
+  declarative call that initializes the player, run once at startup.
+- [`updateOptions(options)`](/api/features/player/#updateoptions) — change a
+  subset of options later, at runtime.
+- [`getOptions()`](/api/features/player/#getoptions) /
+  [`useOptions()`](/api/features/player/#useoptions) — read the current,
+  resolved options.
+
+This page maps the whole options surface and links to the feature guide that
+covers each area in depth.
+
+## `setupPlayer`
+
+Call it once at startup. It's `async`, and applies all options atomically — the
+player never exists without its configuration:
+
+```ts
+import { setupPlayer } from 'react-native-audio-browser'
+
+await setupPlayer({
+  playWhenReady: true,
+  repeatMode: 'queue',
+  capabilities: { favorite: true },
+  progressUpdateEventInterval: 0.5,
+  android: { audioContentType: 'music' },
+  ios: { category: 'playback' }
+})
+```
+
+Calling `setupPlayer` again **reconfigures in place**: the fields you pass are
+merged over the previous ones, and the audio engine is only rebuilt when a
+construction-bound field (buffers, wake mode, …) actually changed. This is also
+how you change a [setup-only option](#setup-only-vs-updatable) after launch.
+
+## `updateOptions`
+
+Use it to change runtime options after setup. Every field is optional — pass only
+what changes; the values you provide are **merged** over the current ones.
+
+```ts
+import { updateOptions } from 'react-native-audio-browser'
+
+updateOptions({ capabilities: { shuffleMode: false } })
+updateOptions({ progressUpdateEventInterval: null }) // disable progress events
+updateOptions({ ios: { carPlayNowPlayingButtons: ['repeat'] } })
+```
+
+`null` is meaningful on exactly two fields, where it turns the feature off:
+`progressUpdateEventInterval: null` disables progress events, and
+`android.remoteButtonLayout: null` empties the layout (deriving it from
+capabilities). Elsewhere, just omit a field to leave it unchanged.
+
+## Setup-only vs updatable
+
+`updateOptions` can change only a subset. The rest are set in `setupPlayer`
+(call it again to change them later).
+
+| Option                                                                                   | `setupPlayer` | `updateOptions` |
+| ---------------------------------------------------------------------------------------- | :-----------: | :-------------: |
+| `capabilities`                                                                           |       ✓       |        ✓        |
+| `forwardJumpInterval` / `backwardJumpInterval`                                           |       ✓       |        ✓        |
+| `progressUpdateEventInterval`                                                            |       ✓       |        ✓        |
+| `android.appKilledPlaybackBehavior` / `skipSilence` / `remoteButtonLayout`               |       ✓       |        ✓        |
+| `ios.playbackRates` / `carPlayUpNextButton` / `carPlayNowPlayingButtons`                 |       ✓       |        ✓        |
+| `nowPlaying` (metadata formatter)                                                        |       ✓       |        —        |
+| `playWhenReady`, `repeatMode` (initial values)                                           |       ✓       |        —        |
+| `retry`, `keepSessionAliveOnError`                                                       |       ✓       |        —        |
+| `android` / `ios` audio engine & session (`audioContentType`, `wakeMode`, `category`, …) |       ✓       |        —        |
+
+`playWhenReady` and `repeatMode` set the _initial_ state; change them at runtime
+with [`setPlayWhenReady`](/guide/playback#play-when-ready) /
+[`setRepeatMode`](/guide/queue#repeat-and-shuffle), not `updateOptions`.
+
+## Capabilities
+
+`capabilities` controls which transport controls the system surfaces (lock
+screen, notification, CarPlay, Android Auto) expose. **All default to `true`
+except `jumpForward`, `jumpBackward`, and `favorite`, which default to `false`.**
+Capabilities **merge** — list only the ones you want to change, and the rest keep
+their current value:
+
+```ts
+updateOptions({
+  capabilities: { jumpForward: true, jumpBackward: true } // podcast controls
+})
+```
+
+| Capability                      | Default | Notes                                          |
+| ------------------------------- | ------- | ---------------------------------------------- |
+| `play` / `pause` / `stop`       | `true`  | Core transport.                                |
+| `seekTo`                        | `true`  | Scrub the timeline.                            |
+| `skipToNext` / `skipToPrevious` | `true`  | Move between queue items.                      |
+| `jumpForward` / `jumpBackward`  | `false` | Podcast/audiobook seek by interval.            |
+| `playbackRate`                  | `true`  | Speed control (Control Center / CarPlay).      |
+| `shuffleMode` / `repeatMode`    | `true`  | Shuffle / repeat toggles.                      |
+| `favorite`                      | `false` | The heart — see [Favorites](/guide/favorites). |
+
+## Controls & progress
+
+| Option                        | Default | What                                                                                                         |
+| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
+| `forwardJumpInterval`         | `15`    | Seconds for the jump-forward control.                                                                        |
+| `backwardJumpInterval`        | `15`    | Seconds for the jump-backward control.                                                                       |
+| `progressUpdateEventInterval` | `null`  | Seconds between progress events; `null` disables them — see [Playback → Progress](/guide/playback#progress). |
+
+## Now Playing
+
+`nowPlaying` controls what's published to the now-playing surfaces:
+
+- `true` (default) — publish the track's own title / artist.
+- `false` — don't manage now-playing metadata.
+- a formatter callback — render every line yourself.
+
+It's **setup-only** (a function can't cross `updateOptions`). See
+[Now Playing → the formatter](/guide/now-playing#the-formatter-derived-continuous).
+
+## Android options (`android`)
+
+| Option                      | Default               | What                                                                                                                                                                  |
+| --------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `appKilledPlaybackBehavior` | `'continue-playback'` | What happens when the app is swiped away (`continue-playback` / `pause-playback` / `stop-playback-and-remove-notification`).                                          |
+| `skipSilence`               | `false`               | Skip silent segments during playback.                                                                                                                                 |
+| `remoteButtonLayout`        | `null`                | Explicit button placement (`back` / `forward` / `overflow`); `null` derives it from capabilities — see [Button layout](/guide/remote-controls#button-layout-android). |
+| `audioContentType`          | `'music'`             | Audio attributes content type (setup-only).                                                                                                                           |
+| `wakeMode`                  | `'none'`              | CPU/network wake lock during playback (setup-only).                                                                                                                   |
+
+## iOS options (`ios`)
+
+| Option                     | Default                | What                                                                                                  |
+| -------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
+| `playbackRates`            | `[0.5, 1.0, 1.5, 2.0]` | Rates offered by the rate control.                                                                    |
+| `carPlayUpNextButton`      | `true`                 | Show the "Up Next" button on CarPlay (auto-hidden when the queue has one track).                      |
+| `carPlayNowPlayingButtons` | `[]`                   | Buttons on the CarPlay now-playing screen (max **5**, left-to-right) — see [CarPlay](/guide/carplay). |
+| `category`                 | _(none)_               | iOS audio session category (setup-only).                                                              |
+
+## Reading the current options
+
+[`getOptions()`](/api/features/player/#getoptions) returns the resolved
+[`Options`](/api/features/player/#options) (capabilities, intervals,
+`progressUpdateEventInterval`, and the `android` / `ios` blocks for the current
+platform). [`useOptions()`](/api/features/player/#useoptions) is the reactive
+hook; [`onOptionsChanged`](/api/features/player/#onoptionschanged) is the
+subscription.
+
+```tsx
+import { useOptions } from 'react-native-audio-browser'
+
+function JumpInterval() {
+  const { forwardJumpInterval } = useOptions()
+  return <Text>Jump {forwardJumpInterval}s</Text>
+}
+```
+
+`getOptions` reports the _runtime_ options above — it doesn't echo back the
+setup-only `nowPlaying` / `playWhenReady` / `repeatMode` (read those via their
+own getters/hooks, e.g. [`useRepeatMode`](/guide/queue#repeat-and-shuffle)).
+
+## API summary
+
+| API                             | Purpose                                                                                                |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `setupPlayer(options?)`         | Initialize (and reconfigure) the player; `async`, once at startup.                                     |
+| `updateOptions(options)`        | Change runtime options later (merged over current); `null` disables on the two fields that support it. |
+| `getOptions()` / `useOptions()` | Read the resolved runtime options.                                                                     |
+| `onOptionsChanged`              | Subscribe to options changes outside React.                                                            |

package/website/guide/equalizer.md

@@ -0,0 +1,231 @@
+---
+description: 'Shape playback tone with the Android system equalizer: named presets, custom band levels, and handling its absence on iOS.'
+---
+
+# Equalizer
+
+The equalizer lets you shape playback tone — boost the bass, tame the treble —
+either by applying a named **preset** (e.g. "Rock", "Jazz") or by setting
+**custom band levels** yourself. It wraps the system equalizer effect.
+
+::: warning Android only
+The equalizer is **Android-only**. Every getter returns `undefined` and every
+setter is a no-op on iOS — Apple exposes no equivalent system equalizer. Always
+treat the settings as possibly-absent (see [Availability](#availability)).
+:::
+
+The UI snippets below import `View` / `Text` / `Button` from `react-native` and
+`Slider` from `@react-native-community/slider`; those import lines are omitted
+for brevity. Everything else comes from `react-native-audio-browser`.
+
+## Availability
+
+[`getEqualizerSettings()`](/api/features/equalizer/#getequalizersettings)
+returns [`EqualizerSettings | undefined`](/api/features/equalizer/#equalizersettings).
+It's `undefined` whenever the equalizer isn't available — on iOS, and **on
+Android until the player has an audio session**, which only exists once playback
+has started. A settings screen opened before anything has played may see
+`undefined`; use the reactive hook so it fills in when playback begins.
+
+## Reading the settings
+
+[`useEqualizerSettings()`](/api/features/equalizer/#useequalizersettings) returns
+the current settings and re-renders when they change:
+
+```tsx
+import { useEqualizerSettings } from 'react-native-audio-browser'
+
+function EqualizerStatus() {
+  const eq = useEqualizerSettings()
+  if (!eq) return <Text>Equalizer unavailable</Text>
+  return (
+    <Text>
+      {eq.enabled ? 'On' : 'Off'} · {eq.bandCount} bands
+    </Text>
+  )
+}
+```
+
+The [`EqualizerSettings`](/api/features/equalizer/#equalizersettings) object:
+
+| Field                   | Type                  | Meaning                                               |
+| ----------------------- | --------------------- | ----------------------------------------------------- |
+| `enabled`               | `boolean`             | Whether the effect is currently applied.              |
+| `bandCount`             | `number`              | Number of frequency bands.                            |
+| `bandLevels`            | `number[]`            | Current level per band, in **millibels**.             |
+| `centerBandFrequencies` | `number[]`            | Center frequency per band, in **milliHertz**.         |
+| `lowerBandLevelLimit`   | `number`              | Minimum level (millibels) any band accepts.           |
+| `upperBandLevelLimit`   | `number`              | Maximum level (millibels) any band accepts.           |
+| `presets`               | `string[]`            | Available preset names.                               |
+| `activePreset`          | `string \| undefined` | The applied preset, or `undefined` for custom levels. |
+
+See [the units note](#a-note-on-units) — both level and frequency values use
+"milli" units.
+
+Outside React, read a snapshot with `getEqualizerSettings()` or subscribe with
+[`onEqualizerChanged`](/api/features/equalizer/#onequalizerchanged).
+
+All the `setEqualizer*` calls below are fire-and-forget — they return `void`.
+The updated settings come back through `useEqualizerSettings` /
+`onEqualizerChanged`, not as a return value.
+
+## Turning it on
+
+The effect does nothing audible until it's enabled. Toggle it with
+[`setEqualizerEnabled`](/api/features/equalizer/#setequalizerenabled):
+
+```ts
+import { setEqualizerEnabled } from 'react-native-audio-browser'
+
+setEqualizerEnabled(true)
+```
+
+## Applying a preset
+
+[`setEqualizerPreset`](/api/features/equalizer/#setequalizerpreset) takes one of
+the names from `settings.presets`. The match is case-insensitive; an unknown
+name is ignored (a warning is logged), so drive your UI from the actual
+`presets` list rather than hard-coded strings:
+
+```tsx
+import {
+  setEqualizerPreset,
+  useEqualizerSettings
+} from 'react-native-audio-browser'
+
+function PresetPicker() {
+  const eq = useEqualizerSettings()
+  if (!eq) return null
+  return (
+    <View>
+      {eq.presets.map((preset) => (
+        <Button
+          key={preset}
+          title={preset}
+          onPress={() => setEqualizerPreset(preset)}
+        />
+      ))}
+    </View>
+  )
+}
+```
+
+After applying a preset, `activePreset` reflects it. Available presets come from
+the device's system equalizer, so the exact list varies by device.
+
+## Custom band levels
+
+[`setEqualizerLevels`](/api/features/equalizer/#setequalizerlevels) sets every
+band at once, in **millibels**. The array length **must equal `bandCount`** — a
+mismatched array is ignored — and each value should fall within
+`lowerBandLevelLimit … upperBandLevelLimit`:
+
+```ts
+import { setEqualizerLevels } from 'react-native-audio-browser'
+
+// Flatten all bands to 0, then boost the lowest band by 6 dB (600 mB).
+const flat = new Array(eq.bandCount).fill(0)
+flat[0] = 600
+setEqualizerLevels(flat)
+```
+
+Setting custom levels clears `activePreset` (it becomes `undefined`) — you're no
+longer on a named preset. To go back, apply a preset again.
+
+Whichever you choose, the settings persist across track and audio-session
+changes: a preset wins over custom levels, and the enabled state always carries
+over.
+
+## A complete equalizer screen
+
+Guard for availability, then render an enable toggle, the device presets, and a
+slider per band:
+
+```tsx
+import { View, Text, Button } from 'react-native'
+import Slider from '@react-native-community/slider'
+import {
+  useEqualizerSettings,
+  setEqualizerEnabled,
+  setEqualizerPreset,
+  setEqualizerLevels
+} from 'react-native-audio-browser'
+
+// Center frequencies are milliHertz; levels are millibels (1/100 dB).
+const formatHz = (mHz: number) => {
+  const hz = mHz / 1000
+  if (hz < 1000) return `${hz.toFixed(0)} Hz`
+  return `${(hz / 1000).toFixed(hz >= 10000 ? 0 : 1)} kHz`
+}
+
+function EqualizerScreen() {
+  const eq = useEqualizerSettings()
+  if (!eq) return <Text>Equalizer not available</Text>
+
+  const setBand = (index: number, millibels: number) => {
+    const next = [...eq.bandLevels]
+    next[index] = millibels
+    setEqualizerLevels(next)
+  }
+
+  return (
+    <View>
+      <Button
+        title={eq.enabled ? 'Disable' : 'Enable'}
+        onPress={() => setEqualizerEnabled(!eq.enabled)}
+      />
+
+      {eq.presets.map((preset) => (
+        <Button
+          key={preset}
+          title={preset === eq.activePreset ? `• ${preset}` : preset}
+          onPress={() => setEqualizerPreset(preset)}
+        />
+      ))}
+
+      {eq.bandLevels.map((level, index) => (
+        <View key={eq.centerBandFrequencies[index]}>
+          <Text>
+            {formatHz(eq.centerBandFrequencies[index])}:{' '}
+            {(level / 100).toFixed(1)} dB
+          </Text>
+          <Slider
+            minimumValue={eq.lowerBandLevelLimit}
+            maximumValue={eq.upperBandLevelLimit}
+            value={level}
+            // Commit on release; onValueChange fires continuously.
+            onSlidingComplete={(millibels) => setBand(index, millibels)}
+          />
+        </View>
+      ))}
+    </View>
+  )
+}
+```
+
+Note: `@react-native-community/slider`'s `value` is the _initial_ value only —
+the slider keeps its own state after mounting. That's fine here, but if you want
+the thumbs to jump when a preset is applied, give each `Slider` a
+`key={eq.activePreset}` so it remounts with the new levels.
+
+## A note on units
+
+The system equalizer works in "milli" units, so convert for display:
+
+- **Levels** (`bandLevels`, the limits, and what you pass to
+  `setEqualizerLevels`) are in **millibels** — hundredths of a decibel. `600`
+  mB = 6 dB; divide by 100 for dB.
+- **Center frequencies** (`centerBandFrequencies`) are in **milliHertz**.
+  `60000` = 60 Hz; divide by 1000 for Hz.
+
+## API summary
+
+| API                                                 | Purpose                                       |
+| --------------------------------------------------- | --------------------------------------------- |
+| `useEqualizerSettings()` / `getEqualizerSettings()` | Read settings (`undefined` if unavailable).   |
+| `onEqualizerChanged`                                | Subscribe to settings changes outside React.  |
+| `setEqualizerEnabled(bool)`                         | Turn the effect on or off.                    |
+| `setEqualizerPreset(name)`                          | Apply a preset from `settings.presets`.       |
+| `setEqualizerLevels(millibels[])`                   | Set all bands; length must equal `bandCount`. |
+
+All are **Android-only** — no-ops / `undefined` on iOS.