react-native-audio-browser 0.1.1 → 0.2.0-next.10

package/lib/typescript/src/features/player/setup.d.ts

@@ -1,3 +1,103 @@
+import type { Track } from '../../types';
+import type { PlaybackError } from '../errors';
+import type { NowPlayingUpdate, TimedMetadata } from '../metadata';
+import type { RepeatMode } from '../queue/repeatMode';
+import type { AndroidUpdateOptions, IOSUpdateOptions, UpdateOptions } from './options';
+/**
+ * Parameters passed to the {@link FormatNowPlayingCallback}.
+ *
+ * The formatter owns every line shown on the now-playing surface — the track text, the live song,
+ * *and* any transient status (reconnecting / error). The library no longer renders status copy
+ * itself, so these fields give you what you need to render (and localize) it yourself. The formatter
+ * is re-invoked on track change, each timed-metadata update, play/pause + error/rebuffer
+ * transitions, and device connectivity changes.
+ */
+export type FormatNowPlayingParams = {
+    /** The currently playing track. */
+    track: Track;
+    /**
+     * Timed metadata (ICY / ID3 "now playing song") received during playback, if any.
+     * Always `undefined` on web — see `onTimedMetadata` for why.
+     */
+    timedMetadata?: TimedMetadata;
+    /** The play/pause intent — `false` while paused. Stays `true` through buffers, so the song line won't flicker. */
+    playWhenReady: boolean;
+    /**
+     * Present (truthy) only while ongoing playback has stalled waiting for data — a mid-stream halt,
+     * never an initial connect or a seek (it won't flash on track start or bleed into playback). The
+     * value classifies *why*, so a "Reconnecting…" vs "No internet connection" line needs no separate
+     * connectivity read:
+     *  - `'buffering'` — the stream is rebuffering while the device is online (rejoining the live edge);
+     *  - `'offline'` — the device has no connectivity.
+     * Safe to use on its own (`if (stalled)`); compare the value (`stalled === 'offline'`) for the reason.
+     */
+    stalled?: StallReason;
+    /** The current playback error, if playback has failed. */
+    error?: PlaybackError;
+};
+/**
+ * Why ongoing playback has stalled, surfaced via {@link FormatNowPlayingParams.stalled}:
+ * - `'buffering'` — rebuffering while online (the live stream is rejoining the live edge);
+ * - `'offline'` — the device has no network connectivity.
+ */
+export type StallReason = 'buffering' | 'offline';
+/**
+ * Customizes what's rendered on the now-playing surface — lock screen, notification, Control Center,
+ * CarPlay, and Android Auto — for the currently playing track.
+ *
+ * Configure it via {@link SetupPlayerOptions.nowPlaying}. Where the default behavior
+ * simply publishes the track's own `title` / `artist`, the formatter hands you the two now-playing
+ * text lines outright: render the live timed metadata (the ICY / ID3 "now playing song"), surface a
+ * transient status line ("Reconnecting…", an error message), drop the song while paused — anything
+ * you can derive from the {@link FormatNowPlayingParams} for that moment.
+ *
+ * The callback is **synchronous** and should stay cheap: it's a pure formatting function, run on the
+ * JS thread and awaited natively. Don't do I/O in it. If you need asynchronously-fetched data (e.g.
+ * album art), resolve it out-of-band and stamp it imperatively rather than awaiting inside here.
+ *
+ * ### When it's invoked
+ * The player re-invokes the formatter whenever the now-playing could change:
+ * - on track change (a new item becomes current);
+ * - on each timed-metadata update ({@link FormatNowPlayingParams.timedMetadata} arrives or changes);
+ * - on every playback transition — play / pause, a stall starting or recovering, an error.
+ *
+ * Identical results are de-duplicated natively before they reach the media session, so returning the
+ * same fields across a rapid burst of transitions is cheap and won't flicker the surface.
+ *
+ * ### What to return
+ * Return a {@link NowPlayingUpdate} with the fields to display. Each field falls back **independently**
+ * to the track's own value when omitted — so `{ artist: 'Some Song' }` replaces only the secondary
+ * line and leaves the title as the track's title. Return `undefined` (or `{}`) to use the library
+ * default entirely (the track's own `title` / `artist`).
+ *
+ * @param params - The current track, latest timed metadata, and playback signals for this moment
+ *   ({@link FormatNowPlayingParams}), including a {@link StallReason} that already classifies an
+ *   offline stall — no separate connectivity read needed for the now-playing line.
+ * @returns The now-playing fields to display, or `undefined` to fall back to the track's own
+ *   `title` / `artist`.
+ *
+ * @example
+ * ```ts
+ * setupPlayer({
+ *   nowPlaying: ({ timedMetadata, playWhenReady, stalled, error }) => {
+ *     if (error)   return { artist: error.message ?? 'Playback error' }
+ *     if (stalled) return { artist: stalled === 'offline' ? 'No internet connection' : 'Reconnecting…' }
+ *     // Show the live song only while actually playing; otherwise fall back to the track default.
+ *     if (!playWhenReady || !timedMetadata?.title) return
+ *     return {
+ *       artist: timedMetadata.artist
+ *         ? `${timedMetadata.artist} — ${timedMetadata.title}`
+ *         : timedMetadata.title
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @see {@link FormatNowPlayingParams} - the per-invocation signals passed in
+ * @see {@link NowPlayingUpdate} - the shape returned
+ * @see {@link SetupPlayerOptions.nowPlaying} - where the callback is configured
+ */
+export type FormatNowPlayingCallback = (params: FormatNowPlayingParams) => NowPlayingUpdate | undefined;
 /**
  * AndroidAudioContentType options:
  * - `'music'`: Content type value to use when the content type is music. See
@@ -121,19 +221,49 @@ export interface AndroidAudioOffloadSettings {
 }
 /**
  * Configuration for retry behavior.
+ *
+ * Two budgets apply, chosen by whether the current load has ever produced
+ * audio:
+ *
+ * - **First connect** (the load has never played): retries are bounded by
+ *   `firstConnectMaxRetryDurationMs`. A stream that fails before ever playing
+ *   is usually dead, and the listener is actively waiting for a verdict —
+ *   seconds, not minutes.
+ * - **Recovery** (the load played, then failed): retries are bounded by
+ *   `maxRetryDurationMs`. Playback proved the stream works; drops are usually
+ *   transient (tunnels, network handovers, a station's encoder restarting)
+ *   and patience is what recovers them unattended.
+ *
+ * While the device is offline, the first-connect budget does not apply: the
+ * player waits for connectivity to return (bounded by `maxRetryDurationMs`),
+ * so a station tapped in a tunnel still starts when the network comes back.
+ * Any offline observation restarts the first-connect clock, so it only ever
+ * measures a contiguous online stretch.
+ *
+ * Native platforms only — the web implementation has no automatic retry.
  */
 export type RetryConfig = {
     /**
-     * Maximum number of retry attempts before giving up.
+     * Maximum number of retry attempts before giving up. Omit to retry without an attempt
+     * limit, bounded only by the duration budgets.
      */
-    maxRetries: number;
+    maxRetries?: number;
     /**
-     * Maximum duration in milliseconds to keep retrying before giving up.
+     * Maximum duration in milliseconds to keep retrying a load that had been
+     * playing before it failed, and any load while the device is offline.
      * This prevents surprising playback resumption after long periods offline.
      *
      * @default 120000 (2 minutes)
      */
     maxRetryDurationMs?: number;
+    /**
+     * Maximum duration in milliseconds to keep retrying a load that has never
+     * produced audio, while the device is online. When it runs out, the terminal
+     * error carries the real diagnosis (`unreachable`, `not-found`, …).
+     *
+     * @default 12000 (12 seconds)
+     */
+    firstConnectMaxRetryDurationMs?: number;
 };
 /**
  * AndroidWakeMode options:
@@ -145,9 +275,12 @@ export type RetryConfig = {
  */
 export type AndroidPlayerWakeMode = 'none' | 'local' | 'network';
 /**
- * Android-specific player setup options.
+ * Android setup options: the engine-construction fields plus the Android runtime options
+ * ({@link AndroidUpdateOptions} — `remoteButtonLayout`, `skipSilence`, …), all expressible at
+ * launch. The consumer never has to know which is which; `setupPlayer` routes each field to
+ * where it's applied.
  */
-export type PartialAndroidSetupPlayerOptions = {
+export interface AndroidSetupOptions extends AndroidUpdateOptions {
     /**
      * Minimum duration of media that the player will attempt to buffer in ms.
      *
@@ -242,106 +375,9 @@ export type PartialAndroidSetupPlayerOptions = {
      * @default 'none'
      */
     wakeMode?: AndroidPlayerWakeMode;
-};
-export interface AndroidSetupPlayerOptions {
-    /**
-     * Minimum duration of media that the player will attempt to buffer in ms.
-     *
-     * @throws Will throw if min buffer is higher than max buffer.
-     * @default 50000
-     */
-    minBuffer: number;
-    /**
-     * Audio offload configuration for power-efficient playback.
-     *
-     * - `true`: Enable with default settings (gapless and rate change support required)
-     * - `false`: Disable audio offload
-     * - `{ gaplessSupportRequired?, rateChangeSupportRequired? }`: Enable with custom requirements
-     *
-     * Audio offload moves audio processing to dedicated hardware when available, saving battery
-     * during longer playbacks, especially with screen off. Requirements determine which features
-     * must be supported for offload to activate:
-     * - `gaplessSupportRequired`: Smooth track transitions without silence
-     * - `rateChangeSupportRequired`: Variable playback speeds (0.5x, 1.25x, 2x, etc.)
-     *
-     * @see https://developer.android.com/media/media3/exoplayer/track-selection#audioOffload
-     */
-    audioOffload: boolean | AndroidAudioOffloadSettings;
-    /**
-     * Maximum duration of media that the player will attempt to buffer in ms.
-     * Max buffer may not be lower than min buffer.
-     *
-     * @throws Will throw if max buffer is lower than min buffer.
-     * @default 50000
-     */
-    maxBuffer: number;
-    /**
-     * Duration in ms that should be kept in the buffer behind the current
-     * playhead time.
-     *
-     * @default 0
-     */
-    backBuffer: number;
-    /**
-     * Duration of media in ms that must be buffered for playback to start or
-     * resume following a user action such as a seek.
-     *
-     * @default 2500
-     */
-    playBuffer: number;
-    /**
-     * Duration of media in ms that must be buffered for playback to resume
-     * after a rebuffer (when the buffer runs empty during playback).
-     *
-     * When null (the default), uses automatic mode:
-     * - Starts at `playBuffer` value
-     * - On rebuffer, measures how fast the buffer drained
-     * - Calculates how much buffer is needed to sustain 60s of playback
-     * - Increases threshold accordingly (up to 8000ms max)
-     * - Resets when changing tracks
-     *
-     * Set to a number for a fixed threshold in ms. Should be >= playBuffer,
-     * otherwise playback may rebuffer repeatedly (resuming with less buffer
-     * than initial start).
-     *
-     * @default null (automatic)
-     */
-    rebufferBuffer: number | null;
-    /**
-     * Maximum cache size in MB.
-     *
-     * @default 0
-     */
-    maxCacheSize: number;
-    /**
-     * The audio content type indicates to the android system how
-     * you intend to use audio in your app.
-     *
-     * With `audioContentType: AndroidAudioContentType.Speech`, the audio will be
-     * paused during short interruptions, such as when a message arrives.
-     * Otherwise the playback volume is reduced while the notification is playing.
-     *
-     * @default AndroidAudioContentType.Music
-     */
-    audioContentType: AndroidAudioContentType;
-    /**
-     * Whether the player should automatically pause when audio becomes noisy
-     * (e.g., when headphones are unplugged).
-     *
-     * @default true
-     */
-    handleAudioBecomingNoisy: boolean;
-    /**
-     * Wake mode for the player to use.
-     *
-     * Determines whether wake locks are held to keep the CPU and/or
-     * WiFi active during playback.
-     *
-     * @default 'none'
-     */
-    wakeMode: AndroidPlayerWakeMode;
 }
-export interface PartialIOSSetupPlayerOptions {
+/** iOS setup options: the audio-session fields plus the iOS runtime options. */
+export interface IOSSetupOptions extends IOSUpdateOptions {
     /**
      * Preferred forward buffer duration in ms. When set to 0 (default), AVPlayer
      * chooses an appropriate level of buffering automatically.
@@ -379,93 +415,106 @@ export interface PartialIOSSetupPlayerOptions {
      */
     categoryPolicy?: IOSCategoryPolicy;
 }
-export interface IOSSetupPlayerOptions {
+/**
+ * Public setup options: the full launch description of a player in one bag — engine
+ * construction, runtime options (`capabilities`, jump intervals, …), and initial player state
+ * (`playWhenReady`, `repeatMode`). Everything is applied natively in one atomic setup; there
+ * is no call ordering to get right. `setupPlayer` normalizes this into the wire taxonomy —
+ * consumers never see the split.
+ */
+export type SetupPlayerOptions = Pick<UpdateOptions, 'capabilities' | 'forwardJumpInterval' | 'backwardJumpInterval' | 'progressUpdateEventInterval'> & {
     /**
-     * Preferred forward buffer duration in ms. When set to 0 (default), AVPlayer
-     * chooses an appropriate level of buffering automatically.
+     * The initial play/pause intent, applied natively as soon as the player exists. Set it to
+     * `true` so the first queued track starts playing the moment it loads.
      *
-     * Setting this to a value greater than 0 disables `automaticallyWaitsToMinimizeStalling`.
+     * Interleaves with `setPlayWhenReady` by strict last-write-wins, whether or not the
+     * player exists yet.
      *
-     * [Read more from Apple Documentation](https://developer.apple.com/documentation/avfoundation/avplayeritem/1643630-preferredforwardbufferduration)
-     *
-     * @default 0
+     * @default false
      */
-    buffer?: number;
+    playWhenReady?: boolean;
     /**
-     * [AVAudioSession.Category](https://developer.apple.com/documentation/avfoundation/avaudiosession/1616615-category)
-     * for iOS. Sets on `play()`.
-     */
-    category?: IOSCategory;
-    /**
-     * The audio session mode, together with the audio session category,
-     * indicates to the system how you intend to use audio in your app. You can use
-     * a mode to configure the audio system for specific use cases such as video
-     * recording, voice or video chat, or audio analysis.
-     * Sets on `play()`.
+     * The initial repeat mode, applied natively as soon as the player exists. Interleaves with
+     * `setRepeatMode` by strict last-write-wins, whether or not the player exists yet.
      *
-     * See https://developer.apple.com/documentation/avfoundation/avaudiosession/1616508-mode
+     * @default 'off'
      */
-    categoryMode?: IOSCategoryMode;
-    /**
-     * [AVAudioSession.CategoryOptions](https://developer.apple.com/documentation/avfoundation/avaudiosession/1616503-categoryoptions) for iOS.
-     * Sets on `play()`.
-     */
-    categoryOptions?: IOSCategoryOptions[];
-    /**
-     * [AVAudioSession.RouteSharingPolicy](https://developer.apple.com/documentation/AVFAudio/AVAudioSession/RouteSharingPolicy-swift.enum) for iOS.
-     * Sets on `play()`.
-     */
-    categoryPolicy?: IOSCategoryPolicy;
-}
-export interface PartialSetupPlayerOptions {
-    /** Android-specific configuration options for setup */
-    android?: PartialAndroidSetupPlayerOptions;
-    /** iOS-specific configuration options for setup */
-    ios?: PartialIOSSetupPlayerOptions;
-    /**
-     * Indicates whether the player should automatically update now playing metadata data in control center / notification.
-     * Defaults to `true`.
-     */
-    autoUpdateMetadata?: boolean;
+    repeatMode?: RepeatMode;
     /**
      * Retry policy for load errors (network failures, timeouts, etc.)
-     * - `true`: Retry indefinitely with exponential backoff (2 minute timeout)
+     * - `true`: Retry indefinitely with exponential backoff, under the default
+     *   duration budgets (12s before first audio, 2 minutes after — see
+     *   {@link RetryConfig})
      * - `false`/`undefined`: No automatic retry (default)
      * - `{ maxRetries: n }`: Retry up to n times with exponential backoff
-     * - `{ maxRetries: n, maxRetryDurationMs: m }`: Retry with custom timeout
+     * - `RetryConfig`: custom attempt and duration budgets
      *
      * Exponential backoff delays: 1s → 1.5s → 2.3s → 3.4s → 5s (capped)
      *
      * @default false
      */
     retry?: boolean | RetryConfig;
-}
-export interface PlayerOptions {
-    /** Android-specific configuration options for setup */
-    android?: AndroidSetupPlayerOptions;
-    /** iOS-specific configuration options for setup */
-    ios?: PartialIOSSetupPlayerOptions;
     /**
-     * Indicates whether the player should automatically update now playing metadata data in control center / notification.
-     * Defaults to `true`.
+     * Keep the media session alive and controllable through a terminal playback error (e.g. a dead
+     * stream), so external controllers (Android Auto / CarPlay) keep their transport controls
+     * (next / previous) instead of tearing the session down. The error is still reported via
+     * `onPlaybackError` / `playbackState`; this only affects what the OS media session observes.
+     *
+     * Only Android can tear the session down, so this is the Android opt-out; on iOS the media
+     * session always stays controllable through errors (the player resolves a terminal error to
+     * paused and retains the now-playing).
+     * @default true
      */
-    autoUpdateMetadata: boolean;
+    keepSessionAliveOnError?: boolean;
+    /** Android-specific options: engine construction and runtime, merged. */
+    android?: AndroidSetupOptions;
+    /** iOS-specific options: audio session and runtime, merged. */
+    ios?: IOSSetupOptions;
     /**
-     * Retry policy for load errors (network failures, timeouts, etc.)
-     * - `true`: Retry indefinitely with exponential backoff (2 minute timeout)
-     * - `false`/`undefined`: No automatic retry (default)
-     * - `{ maxRetries: n }`: Retry up to n times with exponential backoff
-     * - `{ maxRetries: n, maxRetryDurationMs: m }`: Retry with custom timeout
+     * Controls what the player renders on the now-playing surface (lock screen / notification /
+     * Control Center / CarPlay / Android Auto).
      *
-     * Exponential backoff delays: 1s → 1.5s → 2.3s → 3.4s → 5s (capped)
+     * - `true` (default): publish the track's own title / artist.
+     * - `false`: don't manage the now-playing metadata at all.
+     * - a {@link FormatNowPlayingCallback}: render it yourself — the callback owns every line,
+     *   including any transient status (buffering / reconnecting / offline / error), which the
+     *   library no longer renders on your behalf.
      *
-     * @default false
+     * @default true
      */
-    retry?: boolean | RetryConfig;
-}
+    nowPlaying?: boolean | FormatNowPlayingCallback;
+};
 /**
- * Initializes the player with the specified options.
+ * Initializes the player with the specified options — the full launch description in one
+ * declarative, atomic call. Runtime options (`capabilities`, jump intervals,
+ * `remoteButtonLayout`, …) and the initial `playWhenReady` / `repeatMode` are applied
+ * natively as part of setup itself, so there is no setup-then-command ordering for consumers
+ * to know about, and no window where the player exists without its options.
+ *
+ * Calling it again reconfigures the player in place: newly provided fields are merged over
+ * the previous ones, and the audio engine is rebuilt when construction-bound fields (buffers,
+ * wake mode, …) changed.
+ *
  * @param options - The options to initialize the player with.
+ *
+ * @example
+ * ```ts
+ * await setupPlayer({
+ *   retry: true,
+ *   playWhenReady: true,
+ *   repeatMode: 'queue',
+ *   capabilities: { favorite: true },
+ *   android: {
+ *     audioContentType: 'music',
+ *     remoteButtonLayout: {
+ *       back: 'jump-backward',
+ *       forward: 'jump-forward',
+ *       overflow: ['favorite']
+ *     }
+ *   },
+ *   ios: { category: 'playback' }
+ * })
+ * ```
  */
-export declare function setupPlayer(options?: PartialSetupPlayerOptions): Promise<void>;
+export declare function setupPlayer(options?: SetupPlayerOptions): Promise<void>;
 //# sourceMappingURL=setup.d.ts.map

package/lib/typescript/src/features/player/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../../src/features/player/setup.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,uBAAuB,GAC/B,OAAO,GACP,QAAQ,GACR,cAAc,GACd,OAAO,GACP,SAAS,CAAA;AAEb;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,WAAW,GACnB,UAAU,GACV,eAAe,GACf,YAAY,GACZ,SAAS,GACT,aAAa,GACb,QAAQ,CAAA;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,UAAU,GACV,aAAa,GACb,eAAe,GACf,aAAa,GACb,WAAW,GACX,gBAAgB,GAChB,WAAW,GACX,aAAa,CAAA;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,YAAY,GACZ,sCAAsC,GACtC,gBAAgB,GAChB,oBAAoB,GACpB,cAAc,GACd,kBAAkB,CAAA;AAEtB;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,eAAe,GAAG,eAAe,CAAA;AAE7E,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAA;IAEhC;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,OAAO,CAAA;CACpC;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;AAEhE;;GAEG;AACH,MAAM,MAAM,gCAAgC,GAAG;IAC7C;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,2BAA2B,CAAA;IAEpD;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAE9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,uBAAuB,CAAA;IAE1C;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAA;IAElC;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAA;CACjC,CAAA;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;;;;;;;;;;;;OAcG;IACH,YAAY,EAAE,OAAO,GAAG,2BAA2B,CAAA;IAEnD;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAA;IAEjB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAA;IAElB;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAE7B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;;;;;;;;OASG;IACH,gBAAgB,EAAE,uBAAuB,CAAA;IAEzC;;;;;OAKG;IACH,wBAAwB,EAAE,OAAO,CAAA;IAEjC;;;;;;;OAOG;IACH,QAAQ,EAAE,qBAAqB,CAAA;CAChC;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAA;IAEtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,eAAe,CAAA;IAE9B;;;OAGG;IACH,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAEtC;;;OAGG;IACH,cAAc,CAAC,EAAE,iBAAiB,CAAA;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,WAAW,CAAA;IAEtB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,eAAe,CAAA;IAE9B;;;OAGG;IACH,eAAe,CAAC,EAAE,kBAAkB,EAAE,CAAA;IAEtC;;;OAGG;IACH,cAAc,CAAC,EAAE,iBAAiB,CAAA;CACnC;AAED,MAAM,WAAW,yBAAyB;IACxC,uDAAuD;IACvD,OAAO,CAAC,EAAE,gCAAgC,CAAA;IAC1C,mDAAmD;IACnD,GAAG,CAAC,EAAE,4BAA4B,CAAA;IAClC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAE5B;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAAA;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,CAAC,EAAE,yBAAyB,CAAA;IACnC,mDAAmD;IACnD,GAAG,CAAC,EAAE,4BAA4B,CAAA;IAClC;;;OAGG;IACH,kBAAkB,EAAE,OAAO,CAAA;IAE3B;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAAA;CAC9B;AAID;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAEf"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../../src/features/player/setup.ts"],"names":[],"mappings":"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"}

package/lib/typescript/src/features/player/validateOptions.d.ts

@@ -0,0 +1,9 @@
+import type { IOSUpdateOptions } from './options';
+/**
+ * Warns when more CarPlay now-playing buttons are configured than CarPlay renders.
+ * Shared by `updateOptions` and `setupPlayer` (both can carry `ios` options).
+ * Kept out of `options.ts`, which the barrel re-exports — see
+ * public-surface.test.ts.
+ */
+export declare function validateIOSUpdateOptions(ios?: IOSUpdateOptions): void;
+//# sourceMappingURL=validateOptions.d.ts.map

package/lib/typescript/src/features/player/validateOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateOptions.d.ts","sourceRoot":"","sources":["../../../../../src/features/player/validateOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAIjD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAQrE"}

package/lib/typescript/src/features/queue/activeTrack.d.ts

@@ -27,7 +27,7 @@ export declare function getActiveTrackIndex(): number | undefined;
 /**
  * Subscribes to active track change events.
  * @param callback - Called when the active track changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onActiveTrackChanged: NativeUpdatedValue<PlaybackActiveTrackChangedEvent>;
 /**

package/lib/typescript/src/features/queue/queue.d.ts

@@ -76,10 +76,17 @@ export declare function skipToNext(initialPosition?: number): void;
  */
 export declare function skipToPrevious(initialPosition?: number): void;
 /**
- * Sets the queue.
+ * Sets (replaces) the queue.
+ *
+ * This does not change the play/pause state: the player keeps playing if it was
+ * playing and stays paused if it was paused. Call `play` explicitly to
+ * start playback.
+ *
  * @param tracks - The tracks to set as the queue.
+ * @param startIndex - (Optional) The index of the track to make active.
+ * @param startPosition - (Optional) The position in seconds to start the active track from.
  */
-export declare function setQueue(tracks: Track[]): void;
+export declare function setQueue(tracks: Track[], startIndex?: number, startPosition?: number): void;
 /**
  * Gets a track object from the queue.
  * @param index - The index of the track.
@@ -93,14 +100,14 @@ export declare function getQueue(): Track[];
 /**
  * Subscribes to playback queue ended events.
  * @param callback - Called when playback has paused due to reaching the end of the queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onQueueEnded: NativeUpdatedValue<PlaybackQueueEndedEvent>;
 /**
  * Subscribes to queue change events.
  * Called when tracks are added, removed, reordered, or when track metadata changes.
  * @param callback - Called with the updated queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onQueueChanged: NativeUpdatedValue<Track[]>;
 /**

package/lib/typescript/src/features/queue/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../../../src/features/queue/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAKnE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAA;CACjB;AAID;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;AACtE;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;AAQnE;;;GAGG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAEvC;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;AAC/C;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;AAO3C;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAElE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAE9C;AAID;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAEzD;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,KAAK,EAAE,CAElC;AAID;;;;GAIG;AACH,eAAO,MAAM,YAAY,6CAGtB,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,6BAE1B,CAAA;AAID;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,KAAK,EAAE,CAElC"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../../../../src/features/queue/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAKnE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAA;CACjB;AAID;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;AACtE;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;AAQnE;;;GAGG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAEvC;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;AAC/C;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;AAO3C;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAElE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,KAAK,EAAE,EACf,UAAU,CAAC,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAEN;AAID;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAEzD;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,KAAK,EAAE,CAElC;AAID;;;;GAIG;AACH,eAAO,MAAM,YAAY,6CAGtB,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,6BAE1B,CAAA;AAID;;;GAGG;AACH,wBAAgB,QAAQ,IAAI,KAAK,EAAE,CAElC"}

package/lib/typescript/src/features/queue/repeatMode.d.ts

@@ -23,7 +23,7 @@ export interface RepeatModeChangedEvent {
 /**
  * Subscribes to repeat mode changes.
  * @param callback - Called when repeat mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onRepeatModeChanged: NativeUpdatedValue<RepeatModeChangedEvent>;
 /**

package/lib/typescript/src/features/queue/shuffle.d.ts

@@ -16,7 +16,7 @@ export declare function toggleShuffle(): void;
 /**
  * Subscribes to shuffle mode changes.
  * @param callback - Called when shuffle mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export declare const onShuffleChanged: NativeUpdatedValue<boolean>;
 /**