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

package/lib/commonjs/features/playback/progress.js

@@ -8,6 +8,7 @@ exports.onProgressUpdated = void 0;
 exports.usePolledProgress = usePolledProgress;
 exports.useProgress = useProgress;
 var _react = require("react");
+var _reactNative = require("react-native");
 var _native = require("../../native");
 var _NativeUpdatedValue = require("../../utils/NativeUpdatedValue");
 var _useNativeUpdatedValue = require("../../utils/useNativeUpdatedValue");
@@ -55,6 +56,9 @@ function useProgress() {
  *
  * Use this when you need custom polling behavior instead of event-based updates.
  *
+ * Skips updates while the app is backgrounded and refreshes once it becomes
+ * active again.
+ *
  * @param updateInterval - Update interval in milliseconds (default: 1000)
  * @returns The current playback progress
  */
@@ -65,7 +69,8 @@ function usePolledProgress(updateInterval = 1000) {
     buffered: 0
   });
   (0, _react.useEffect)(() => {
-    let mounted = true;
+    let timer;
+    let unsubscribeState;
     const update = () => {
       try {
         const {
@@ -73,7 +78,6 @@ function usePolledProgress(updateInterval = 1000) {
           duration,
           buffered
         } = getProgress();
-        if (!mounted) return;
         setState(currentState => position === currentState.position && duration === currentState.duration && buffered === currentState.buffered ? currentState : {
           position,
           duration,
@@ -83,20 +87,32 @@ function usePolledProgress(updateInterval = 1000) {
         // Ignore failures (e.g., before setup)
       }
     };
-
-    // Update immediately on playback state changes
-    const unsubscribeState = _state.onPlaybackChanged.addListener(update);
     const poll = () => {
       update();
-      if (!mounted) return;
-      setTimeout(() => {
-        if (mounted) poll();
-      }, updateInterval);
+      timer = setTimeout(poll, updateInterval);
+    };
+
+    // We only poll and listen for playback changes while the app is active. On
+    // return to the foreground we update once and restart the loop so the
+    // interval timing stays correct.
+    const start = () => {
+      if (timer !== undefined) return;
+      unsubscribeState = _state.onPlaybackChanged.addListener(update);
+      poll();
+    };
+    const stop = () => {
+      clearTimeout(timer);
+      timer = undefined;
+      unsubscribeState?.();
+      unsubscribeState = undefined;
     };
-    poll();
+    const appStateSub = _reactNative.AppState.addEventListener('change', next => {
+      if (next === 'active') start();else stop();
+    });
+    if (_reactNative.AppState.currentState === 'active') start();
     return () => {
-      mounted = false;
-      unsubscribeState();
+      stop();
+      appStateSub.remove();
     };
   }, [updateInterval]);
   return state;

package/lib/commonjs/features/playback/progress.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","_native","_NativeUpdatedValue","_useNativeUpdatedValue","_state","getProgress","nativeBrowser","onProgressUpdated","exports","NativeUpdatedValue","emitterize","cb","onPlaybackProgressUpdated","useProgress","useNativeUpdatedValue","usePolledProgress","updateInterval","state","setState","useState","position","duration","buffered","useEffect","mounted","update","currentState","unsubscribeState","onPlaybackChanged","addListener","poll","setTimeout"],"sourceRoot":"../../../../src","sources":["features/playback/progress.ts"],"mappings":";;;;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,mBAAA,GAAAF,OAAA;AACA,IAAAG,sBAAA,GAAAH,OAAA;AACA,IAAAI,MAAA,GAAAJ,OAAA;AAEA;;AAiBA;AACA;AACA;;AAMA;;AAEA;AACA;AACA;AACA;AACA;AACO,SAASK,WAAWA,CAAA,EAAa;EACtC,OAAOC,qBAAa,CAACD,WAAW,CAAC,CAAC;AACpC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAME,iBAAiB,GAAAC,OAAA,CAAAD,iBAAA,GAC5BE,sCAAkB,CAACC,UAAU,CAC1BC,EAAE,IAAML,qBAAa,CAACM,yBAAyB,GAAGD,EACrD,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,WAAWA,CAAA,EAAa;EACtC,OAAO,IAAAC,4CAAqB,EAACT,WAAW,EAAEE,iBAAiB,CAAC;AAC9D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASQ,iBAAiBA,CAACC,cAAc,GAAG,IAAI,EAAY;EACjE,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAG,IAAAC,eAAQ,EAAW;IAC3CC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE;EACZ,CAAC,CAAC;EAEF,IAAAC,gBAAS,EAAC,MAAM;IACd,IAAIC,OAAO,GAAG,IAAI;IAElB,MAAMC,MAAM,GAAGA,CAAA,KAAM;MACnB,IAAI;QACF,MAAM;UAAEL,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CAAC,GAAGjB,WAAW,CAAC,CAAC;QACtD,IAAI,CAACmB,OAAO,EAAE;QAEdN,QAAQ,CAAEQ,YAAY,IACpBN,QAAQ,KAAKM,YAAY,CAACN,QAAQ,IAClCC,QAAQ,KAAKK,YAAY,CAACL,QAAQ,IAClCC,QAAQ,KAAKI,YAAY,CAACJ,QAAQ,GAC9BI,YAAY,GACZ;UAAEN,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CACrC,CAAC;MACH,CAAC,CAAC,MAAM;QACN;MAAA;IAEJ,CAAC;;IAED;IACA,MAAMK,gBAAgB,GAAGC,wBAAiB,CAACC,WAAW,CAACJ,MAAM,CAAC;IAE9D,MAAMK,IAAI,GAAGA,CAAA,KAAM;MACjBL,MAAM,CAAC,CAAC;MACR,IAAI,CAACD,OAAO,EAAE;MACdO,UAAU,CAAC,MAAM;QACf,IAAIP,OAAO,EAAEM,IAAI,CAAC,CAAC;MACrB,CAAC,EAAEd,cAAc,CAAC;IACpB,CAAC;IAEDc,IAAI,CAAC,CAAC;IAEN,OAAO,MAAM;MACXN,OAAO,GAAG,KAAK;MACfG,gBAAgB,CAAC,CAAC;IACpB,CAAC;EACH,CAAC,EAAE,CAACX,cAAc,CAAC,CAAC;EAEpB,OAAOC,KAAK;AACd","ignoreList":[]}
+{"version":3,"names":["_react","require","_reactNative","_native","_NativeUpdatedValue","_useNativeUpdatedValue","_state","getProgress","nativeBrowser","onProgressUpdated","exports","NativeUpdatedValue","emitterize","cb","onPlaybackProgressUpdated","useProgress","useNativeUpdatedValue","usePolledProgress","updateInterval","state","setState","useState","position","duration","buffered","useEffect","timer","unsubscribeState","update","currentState","poll","setTimeout","start","undefined","onPlaybackChanged","addListener","stop","clearTimeout","appStateSub","AppState","addEventListener","next","remove"],"sourceRoot":"../../../../src","sources":["features/playback/progress.ts"],"mappings":";;;;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AACA,IAAAG,mBAAA,GAAAH,OAAA;AACA,IAAAI,sBAAA,GAAAJ,OAAA;AACA,IAAAK,MAAA,GAAAL,OAAA;AAEA;;AAiBA;AACA;AACA;;AAMA;;AAEA;AACA;AACA;AACA;AACA;AACO,SAASM,WAAWA,CAAA,EAAa;EACtC,OAAOC,qBAAa,CAACD,WAAW,CAAC,CAAC;AACpC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAME,iBAAiB,GAAAC,OAAA,CAAAD,iBAAA,GAC5BE,sCAAkB,CAACC,UAAU,CAC1BC,EAAE,IAAML,qBAAa,CAACM,yBAAyB,GAAGD,EACrD,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,WAAWA,CAAA,EAAa;EACtC,OAAO,IAAAC,4CAAqB,EAACT,WAAW,EAAEE,iBAAiB,CAAC;AAC9D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASQ,iBAAiBA,CAACC,cAAc,GAAG,IAAI,EAAY;EACjE,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAG,IAAAC,eAAQ,EAAW;IAC3CC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE;EACZ,CAAC,CAAC;EAEF,IAAAC,gBAAS,EAAC,MAAM;IACd,IAAIC,KAAgD;IACpD,IAAIC,gBAA0C;IAE9C,MAAMC,MAAM,GAAGA,CAAA,KAAM;MACnB,IAAI;QACF,MAAM;UAAEN,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CAAC,GAAGjB,WAAW,CAAC,CAAC;QAEtDa,QAAQ,CAAES,YAAY,IACpBP,QAAQ,KAAKO,YAAY,CAACP,QAAQ,IAClCC,QAAQ,KAAKM,YAAY,CAACN,QAAQ,IAClCC,QAAQ,KAAKK,YAAY,CAACL,QAAQ,GAC9BK,YAAY,GACZ;UAAEP,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CACrC,CAAC;MACH,CAAC,CAAC,MAAM;QACN;MAAA;IAEJ,CAAC;IAED,MAAMM,IAAI,GAAGA,CAAA,KAAM;MACjBF,MAAM,CAAC,CAAC;MACRF,KAAK,GAAGK,UAAU,CAACD,IAAI,EAAEZ,cAAc,CAAC;IAC1C,CAAC;;IAED;IACA;IACA;IACA,MAAMc,KAAK,GAAGA,CAAA,KAAM;MAClB,IAAIN,KAAK,KAAKO,SAAS,EAAE;MACzBN,gBAAgB,GAAGO,wBAAiB,CAACC,WAAW,CAACP,MAAM,CAAC;MACxDE,IAAI,CAAC,CAAC;IACR,CAAC;IAED,MAAMM,IAAI,GAAGA,CAAA,KAAM;MACjBC,YAAY,CAACX,KAAK,CAAC;MACnBA,KAAK,GAAGO,SAAS;MACjBN,gBAAgB,GAAG,CAAC;MACpBA,gBAAgB,GAAGM,SAAS;IAC9B,CAAC;IAED,MAAMK,WAAW,GAAGC,qBAAQ,CAACC,gBAAgB,CAAC,QAAQ,EAAGC,IAAI,IAAK;MAChE,IAAIA,IAAI,KAAK,QAAQ,EAAET,KAAK,CAAC,CAAC,MACzBI,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;IAEF,IAAIG,qBAAQ,CAACV,YAAY,KAAK,QAAQ,EAAEG,KAAK,CAAC,CAAC;IAE/C,OAAO,MAAM;MACXI,IAAI,CAAC,CAAC;MACNE,WAAW,CAACI,MAAM,CAAC,CAAC;IACtB,CAAC;EACH,CAAC,EAAE,CAACxB,cAAc,CAAC,CAAC;EAEpB,OAAOC,KAAK;AACd","ignoreList":[]}

package/lib/commonjs/features/playback/trackPlaybackTime.js

@@ -0,0 +1,92 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.__emitTickForTests = __emitTickForTests;
+exports.trackPlaybackTime = trackPlaybackTime;
+var _native = require("../../native");
+var _activeTrack = require("../queue/activeTrack");
+// MARK: - Types
+
+// MARK: - State
+
+const handles = new Set();
+let installed = false;
+let currentTrack;
+
+// The native tick fires once per second while playback is `playing` (and stops
+// while paused/buffering/stopped), so advancing each handle by one second per
+// tick yields cumulative *playback* time that freezes on interruption.
+function onTick() {
+  for (const handle of handles) {
+    handle.totalSeconds += 1;
+    const sinceLast = handle.totalSeconds - handle.lastFireSeconds;
+    if (sinceLast >= handle.period) {
+      handle.lastFireSeconds = handle.totalSeconds;
+      handle.callback({
+        total: handle.totalSeconds,
+        sinceLast,
+        track: currentTrack
+      });
+    }
+  }
+}
+function install() {
+  if (installed) return;
+  installed = true;
+  _native.nativeBrowser.onPlaybackInterval = onTick;
+  _activeTrack.onActiveTrackChanged.addListener(event => {
+    currentTrack = event.track;
+  });
+}
+
+// MARK: - Public API
+
+/**
+ * Calls `callback` every `period` seconds of cumulative playback — time spent in
+ * the `playing` state. The clock advances only while playing and freezes on
+ * pause/buffering/stop, resuming where it left off; it is never reset (cancel and
+ * re-subscribe for a fresh `total`). Coarse, best-effort cadence (~1s resolution),
+ * not a precise timer.
+ *
+ * Typical use is a periodic "still listening" signal: fire an analytics ping, a
+ * listen-check, or a heartbeat every N seconds of *actual* listening, so paused
+ * time doesn't inflate the count.
+ *
+ * Note this counts cumulative play time across the whole session, NOT per track:
+ * `total` keeps climbing through track changes, and `track` only tells you what
+ * was playing at the moment each callback fired. To measure playtime per track,
+ * subscribe to {@link onActiveTrackChanged} and cancel + re-subscribe here on each
+ * change, so every track gets a fresh `total` starting at zero.
+ *
+ * @param callback Invoked once per elapsed `period`, with cumulative play time
+ *                 and the currently playing track.
+ * @param period  Seconds of playback between calls. Must be >= 1.
+ * @returns A function that cancels this subscription (idempotent — safe to call
+ *          more than once).
+ */
+function trackPlaybackTime(callback, period) {
+  if (!(period >= 1)) {
+    throw new Error('trackPlaybackTime: period must be >= 1');
+  }
+  install();
+  const handle = {
+    period,
+    totalSeconds: 0,
+    lastFireSeconds: 0,
+    callback
+  };
+  handles.add(handle);
+  if (handles.size === 1) _native.nativeBrowser.setPlaybackIntervalEnabled(true);
+  return () => {
+    if (!handles.delete(handle)) return;
+    if (handles.size === 0) _native.nativeBrowser.setPlaybackIntervalEnabled(false);
+  };
+}
+
+/** @internal test hook — drives the fan-out without a native tick. */
+function __emitTickForTests(ticks = 1) {
+  for (let i = 0; i < ticks; i++) onTick();
+}
+//# sourceMappingURL=trackPlaybackTime.js.map

package/lib/commonjs/features/playback/trackPlaybackTime.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_native","require","_activeTrack","handles","Set","installed","currentTrack","onTick","handle","totalSeconds","sinceLast","lastFireSeconds","period","callback","total","track","install","nativeBrowser","onPlaybackInterval","onActiveTrackChanged","addListener","event","trackPlaybackTime","Error","add","size","setPlaybackIntervalEnabled","delete","__emitTickForTests","ticks","i"],"sourceRoot":"../../../../src","sources":["features/playback/trackPlaybackTime.ts"],"mappings":";;;;;;;AACA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AAEA;;AAkBA;;AAEA,MAAME,OAAO,GAAG,IAAIC,GAAG,CAAS,CAAC;AACjC,IAAIC,SAAS,GAAG,KAAK;AACrB,IAAIC,YAA+B;;AAEnC;AACA;AACA;AACA,SAASC,MAAMA,CAAA,EAAG;EAChB,KAAK,MAAMC,MAAM,IAAIL,OAAO,EAAE;IAC5BK,MAAM,CAACC,YAAY,IAAI,CAAC;IACxB,MAAMC,SAAS,GAAGF,MAAM,CAACC,YAAY,GAAGD,MAAM,CAACG,eAAe;IAC9D,IAAID,SAAS,IAAIF,MAAM,CAACI,MAAM,EAAE;MAC9BJ,MAAM,CAACG,eAAe,GAAGH,MAAM,CAACC,YAAY;MAC5CD,MAAM,CAACK,QAAQ,CAAC;QACdC,KAAK,EAAEN,MAAM,CAACC,YAAY;QAC1BC,SAAS;QACTK,KAAK,EAAET;MACT,CAAC,CAAC;IACJ;EACF;AACF;AAEA,SAASU,OAAOA,CAAA,EAAG;EACjB,IAAIX,SAAS,EAAE;EACfA,SAAS,GAAG,IAAI;EAChBY,qBAAa,CAACC,kBAAkB,GAAGX,MAAM;EACzCY,iCAAoB,CAACC,WAAW,CAAEC,KAAK,IAAK;IAC1Cf,YAAY,GAAGe,KAAK,CAACN,KAAK;EAC5B,CAAC,CAAC;AACJ;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASO,iBAAiBA,CAC/BT,QAA4C,EAC5CD,MAAc,EACF;EACZ,IAAI,EAAEA,MAAM,IAAI,CAAC,CAAC,EAAE;IAClB,MAAM,IAAIW,KAAK,CAAC,wCAAwC,CAAC;EAC3D;EACAP,OAAO,CAAC,CAAC;EACT,MAAMR,MAAc,GAAG;IACrBI,MAAM;IACNH,YAAY,EAAE,CAAC;IACfE,eAAe,EAAE,CAAC;IAClBE;EACF,CAAC;EACDV,OAAO,CAACqB,GAAG,CAAChB,MAAM,CAAC;EACnB,IAAIL,OAAO,CAACsB,IAAI,KAAK,CAAC,EAAER,qBAAa,CAACS,0BAA0B,CAAC,IAAI,CAAC;EACtE,OAAO,MAAM;IACX,IAAI,CAACvB,OAAO,CAACwB,MAAM,CAACnB,MAAM,CAAC,EAAE;IAC7B,IAAIL,OAAO,CAACsB,IAAI,KAAK,CAAC,EAAER,qBAAa,CAACS,0BAA0B,CAAC,KAAK,CAAC;EACzE,CAAC;AACH;;AAEA;AACO,SAASE,kBAAkBA,CAACC,KAAK,GAAG,CAAC,EAAE;EAC5C,KAAK,IAAIC,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGD,KAAK,EAAEC,CAAC,EAAE,EAAEvB,MAAM,CAAC,CAAC;AAC1C","ignoreList":[]}

package/lib/commonjs/features/playback/volume.js

@@ -41,7 +41,7 @@ function setVolume(level) {
 /**
  * Sets the system volume.
  * @param level - The volume as a number between 0 and 1.
- * @note On iOS this is a no-op as Apple doesn't provide a public API to set system volume.
+ * @remarks On iOS this is a no-op as Apple doesn't provide a public API to set system volume.
  */
 function setSystemVolume(level) {
   _native.nativeBrowser.setSystemVolume(level);

package/lib/commonjs/features/player/options.js

@@ -7,6 +7,7 @@ exports.getOptions = getOptions;
 exports.onOptionsChanged = void 0;
 exports.updateOptions = updateOptions;
 exports.useOptions = useOptions;
+exports.validateIOSUpdateOptions = validateIOSUpdateOptions;
 var _native = require("../../native");
 var _NativeUpdatedValue = require("../../utils/NativeUpdatedValue");
 var _useNativeUpdatedValue = require("../../utils/useNativeUpdatedValue");
@@ -14,7 +15,8 @@ var _useNativeUpdatedValue = require("../../utils/useNativeUpdatedValue");
 
 /**
  * Player capabilities control which media controls are available to the user.
- * All capabilities are enabled by default - only specify ones you want to disable.
+ * Most capabilities are enabled by default - only specify the ones you want to change.
+ * Exceptions that default to off: `jumpForward`, `jumpBackward`, and `favorite`.
  *
  * @example
  * ```typescript
@@ -83,13 +85,32 @@ var _useNativeUpdatedValue = require("../../utils/useNativeUpdatedValue");
  * @example
  * ```typescript
  * const options = getOptions();
- * console.log(options.repeatMode); // 'off'
+ * console.log(options.forwardJumpInterval); // 15
  * console.log(options.capabilities); // { shuffleMode: false } - only disabled caps shown
  * console.log(options.android?.skipSilence); // true (Android only)
- * console.log(options.ios?.likeOptions); // { isActive: false, title: 'Like' } (iOS only)
  * ```
  */
 
+/**
+ * iOS-specific player options with resolved defaults (from {@link getOptions}).
+ * Only present on iOS.
+ */
+
+/**
+ * Wire shape of {@link AndroidUpdateOptions} — what crosses the Nitro bridge.
+ * @internal
+ */
+
+/**
+ * iOS-specific player options that can be changed at runtime via {@link updateOptions}.
+ * @platform ios
+ */
+
+/**
+ * Wire shape of {@link IOSUpdateOptions} — what crosses the Nitro bridge.
+ * @internal
+ */
+
 /**
  * Partial options for updating player configuration.
  * Only specify the properties you want to change - all properties are optional.
@@ -97,9 +118,6 @@ var _useNativeUpdatedValue = require("../../utils/useNativeUpdatedValue");
  *
  * @example
  * ```typescript
- * // Update only repeat mode
- * updateOptions({ repeatMode: 'track' });
- *
  * // Disable specific capabilities
  * updateOptions({
  *   capabilities: { shuffleMode: false, repeatMode: false }
@@ -112,14 +130,34 @@ var _useNativeUpdatedValue = require("../../utils/useNativeUpdatedValue");
  *
  * // Platform-specific options
  * updateOptions({
- *   android: { skipSilence: true },
- *   ios: { likeOptions: { isActive: true, title: 'Love' } }
+ *   android: { skipSilence: true }
  * });
  * ```
  */
 
+/**
+ * Wire shape of {@link UpdateOptions} — what crosses the Nitro bridge.
+ * @internal
+ */
+
 // MARK: - Functions
 
+const MAX_CARPLAY_NOW_PLAYING_BUTTONS = 5;
+
+/**
+ * Warns when more CarPlay now-playing buttons are configured than CarPlay renders.
+ * Shared by {@link updateOptions} and `setupPlayer` (both can carry `ios` options).
+ *
+ * @internal Validation helper, not public API — `stripInternal` removes it from
+ * the published types and typedoc hides it from the docs.
+ */
+function validateIOSUpdateOptions(ios) {
+  const buttons = ios?.carPlayNowPlayingButtons;
+  if (buttons && buttons.length > MAX_CARPLAY_NOW_PLAYING_BUTTONS) {
+    console.warn(`[react-native-audio-browser] ${buttons.length} CarPlay now-playing ` + `buttons configured; CarPlay shows at most ${MAX_CARPLAY_NOW_PLAYING_BUTTONS}.`);
+  }
+}
+
 /**
  * Updates the configuration for the components.
  * Pass only the properties you want to change - all properties are optional.
@@ -128,9 +166,6 @@ var _useNativeUpdatedValue = require("../../utils/useNativeUpdatedValue");
  * @see {@link getOptions} to get current options
  * @example
  * ```typescript
- * // Update single property
- * updateOptions({ repeatMode: 'track' });
- *
  * // Disable specific capabilities
  * updateOptions({
  *   capabilities: { shuffleMode: false },
@@ -139,6 +174,7 @@ var _useNativeUpdatedValue = require("../../utils/useNativeUpdatedValue");
  * ```
  */
 function updateOptions(options) {
+  validateIOSUpdateOptions(options.ios);
   _native.nativeBrowser.updateOptions(options);
 }
 
@@ -152,8 +188,8 @@ function updateOptions(options) {
  * @example
  * ```typescript
  * const options = getOptions();
- * if (options.repeatMode === 'track') {
- *   // Handle track repeat mode
+ * if (options.capabilities.shuffleMode === false) {
+ *   // Shuffle is disabled
  * }
  * ```
  */

package/lib/commonjs/features/player/options.js.map

@@ -1 +1 @@
-{"version":3,"names":["_native","require","_NativeUpdatedValue","_useNativeUpdatedValue","updateOptions","options","nativeBrowser","getOptions","onOptionsChanged","exports","NativeUpdatedValue","emitterize","cb","useOptions","useNativeUpdatedValue"],"sourceRoot":"../../../../src","sources":["features/player/options.ts"],"mappings":";;;;;;;;;AAEA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,mBAAA,GAAAD,OAAA;AACA,IAAAE,sBAAA,GAAAF,OAAA;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAqEA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAcA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAuIA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAkFA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,aAAaA,CAACC,OAAsB,EAAQ;EAC1DC,qBAAa,CAACF,aAAa,CAACC,OAAO,CAAC;AACtC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,UAAUA,CAAA,EAAY;EACpC,OAAOD,qBAAa,CAACC,UAAU,CAAC,CAAC;AACnC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAMC,gBAAgB,GAAAC,OAAA,CAAAD,gBAAA,GAAGE,sCAAkB,CAACC,UAAU,CAC1DC,EAAE,IAAMN,qBAAa,CAACE,gBAAgB,GAAGI,EAC5C,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACO,SAASC,UAAUA,CAAA,EAAY;EACpC,OAAO,IAAAC,4CAAqB,EAACP,UAAU,EAAEC,gBAAgB,CAAC;AAC5D","ignoreList":[]}
+{"version":3,"names":["_native","require","_NativeUpdatedValue","_useNativeUpdatedValue","MAX_CARPLAY_NOW_PLAYING_BUTTONS","validateIOSUpdateOptions","ios","buttons","carPlayNowPlayingButtons","length","console","warn","updateOptions","options","nativeBrowser","getOptions","onOptionsChanged","exports","NativeUpdatedValue","emitterize","cb","useOptions","useNativeUpdatedValue"],"sourceRoot":"../../../../src","sources":["features/player/options.ts"],"mappings":";;;;;;;;;;AAEA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,mBAAA,GAAAD,OAAA;AACA,IAAAE,sBAAA,GAAAF,OAAA;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA+FA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAcA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAMA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAkCA;AACA;AACA;AACA;;AA4EA;AACA;AACA;AACA;;AAOA;AACA;AACA;AACA;;AA6BA;AACA;AACA;AACA;;AAOA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA6CA;AACA;AACA;AACA;;AA8BA;;AAEA,MAAMG,+BAA+B,GAAG,CAAC;;AAEzC;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,wBAAwBA,CAACC,GAAsB,EAAQ;EACrE,MAAMC,OAAO,GAAGD,GAAG,EAAEE,wBAAwB;EAC7C,IAAID,OAAO,IAAIA,OAAO,CAACE,MAAM,GAAGL,+BAA+B,EAAE;IAC/DM,OAAO,CAACC,IAAI,CACV,gCAAgCJ,OAAO,CAACE,MAAM,uBAAuB,GACnE,6CAA6CL,+BAA+B,GAChF,CAAC;EACH;AACF;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASQ,aAAaA,CAACC,OAAsB,EAAQ;EAC1DR,wBAAwB,CAACQ,OAAO,CAACP,GAAG,CAAC;EACrCQ,qBAAa,CAACF,aAAa,CAACC,OAAO,CAAC;AACtC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,UAAUA,CAAA,EAAY;EACpC,OAAOD,qBAAa,CAACC,UAAU,CAAC,CAAC;AACnC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAMC,gBAAgB,GAAAC,OAAA,CAAAD,gBAAA,GAAGE,sCAAkB,CAACC,UAAU,CAC1DC,EAAE,IAAMN,qBAAa,CAACE,gBAAgB,GAAGI,EAC5C,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACO,SAASC,UAAUA,CAAA,EAAY;EACpC,OAAO,IAAAC,4CAAqB,EAACP,UAAU,EAAEC,gBAAgB,CAAC;AAC5D","ignoreList":[]}

package/lib/commonjs/features/player/setup.js

@@ -5,8 +5,82 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.setupPlayer = setupPlayer;
 var _native = require("../../native");
+var _options = require("./options");
 // MARK: - Types
 
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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
+ */
+
 /**
  * AndroidAudioContentType options:
  * - `'music'`: Content type value to use when the content type is music. See
@@ -116,6 +190,26 @@ var _native = require("../../native");
 
 /**
  * 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.
  */
 
 /**
@@ -128,16 +222,168 @@ var _native = require("../../native");
  */
 
 /**
- * Android-specific player setup options.
+ * Android setup options: the engine-construction fields plus the Android runtime options
+ * ({@link AndroidUpdateOptions} — `notificationButtons`, `skipSilence`, …), all expressible at
+ * launch. The consumer never has to know which is which; `setupPlayer` routes each field to
+ * where it's applied.
+ */
+
+/** iOS setup options: the audio-session fields plus the iOS runtime options. */
+
+/**
+ * @internal The wire shape `setupPlayer` sends across the bridge: the platform bags hold only
+ * construction fields, the runtime options nest under `options`, and the public `nowPlaying`
+ * option arrives normalized into the two now-playing fields.
  */
 
 // MARK: - Lifecycle
 
 /**
- * Initializes the player with the specified options.
+ * @internal Wire shape for {@link AndroidSetupOptions}: just the engine-construction fields —
+ * the runtime options travel separately under the wire payload's `options.android`.
+ */
+
+/**
+ * @internal Wire shape for {@link IOSSetupOptions}: just the audio-session fields — the
+ * runtime options travel separately under the wire payload's `options.ios`.
+ */
+
+/**
+ * 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.
+ */
+
+/** The normalized native now-playing fields, resolved from the public option. */
+
+/** Resolves the public `nowPlaying` option to the normalized native fields. */
+function resolveNowPlaying(value) {
+  if (typeof value === 'function') {
+    return {
+      autoUpdateNowPlayingMetadata: true,
+      nowPlayingMetadataFormatter: wrapNowPlayingFormatter(value)
+    };
+  }
+  // `undefined` defaults to on; `true`/`false` toggle the default mapping.
+  return {
+    autoUpdateNowPlayingMetadata: value ?? true,
+    nowPlayingMetadataFormatter: undefined
+  };
+}
+
+/**
+ * Wraps a {@link FormatNowPlayingCallback} so it never resolves the native callback to `null`.
+ *
+ * The callback contract lets consumers `return undefined` to mean "use the default". But Nitro's
+ * `Promise<T | undefined>.await()` throws `Failed to cast Object to T!` when the callback resolves
+ * to null/undefined — which surfaces on Android as the misleading "Cannot reject Promise … it is
+ * already resolved!" (the cast error is swallowed, then a reject is attempted on the
+ * already-resolved promise). So we coalesce `undefined` to an empty update before it crosses the
+ * boundary: the native side already falls back to the track's own title/artist for each missing
+ * field, so `{}` is equivalent to "use the default" without ever sending a null across.
+ */
+function wrapNowPlayingFormatter(formatter) {
+  return params => formatter(params) ?? {};
+}
+
+/**
+ * The object's entries whose values aren't `undefined`. `null` stays: it's meaningful on some
+ * fields (`progressUpdateEventInterval: null` disables progress events, `notificationButtons:
+ * null` empties the layout), so only `undefined` means "not provided".
+ */
+function definedFields(obj) {
+  const out = {};
+  for (const key in obj) {
+    if (obj[key] !== undefined) out[key] = obj[key];
+  }
+  return out;
+}
+
+/** Spreads `value` under `key` only when it has at least one field. */
+function nonEmpty(key, value) {
+  return Object.keys(value).length > 0 ? {
+    [key]: value
+  } : {};
+}
+
+/**
+ * Initializes the player with the specified options — the full launch description in one
+ * declarative, atomic call. Runtime options (`capabilities`, jump intervals,
+ * `notificationButtons`, …) 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', notificationButtons: { overflow: ['favorite'] } },
+ *   ios: { category: 'playback' }
+ * })
+ * ```
  */
 async function setupPlayer(options = {}) {
-  return _native.nativeBrowser.setupPlayer(options);
+  const {
+    nowPlaying,
+    capabilities,
+    forwardJumpInterval,
+    backwardJumpInterval,
+    progressUpdateEventInterval,
+    android = {},
+    ios = {},
+    ...nativeSetup
+  } = options;
+
+  // Split the merged public bags back into the wire taxonomy: construction fields stay under
+  // `android` / `ios`, runtime options nest under `options`. The consumer never has to learn
+  // which is which.
+  const {
+    appKilledPlaybackBehavior,
+    skipSilence,
+    notificationButtons,
+    ...androidSetup
+  } = android;
+  const {
+    playbackRates,
+    carPlayUpNextButton,
+    carPlayNowPlayingButtons,
+    ...iosSetup
+  } = ios;
+  const iosUpdate = definedFields({
+    playbackRates,
+    carPlayUpNextButton,
+    carPlayNowPlayingButtons
+  });
+  (0, _options.validateIOSUpdateOptions)(iosUpdate);
+  const updates = definedFields({
+    capabilities,
+    forwardJumpInterval,
+    backwardJumpInterval,
+    progressUpdateEventInterval,
+    ...nonEmpty('android', definedFields({
+      appKilledPlaybackBehavior,
+      skipSilence,
+      notificationButtons
+    })),
+    ...nonEmpty('ios', iosUpdate)
+  });
+  return _native.nativeBrowser.setupPlayer({
+    ...nativeSetup,
+    ...nonEmpty('android', definedFields(androidSetup)),
+    ...nonEmpty('ios', definedFields(iosSetup)),
+    ...resolveNowPlaying(nowPlaying),
+    ...nonEmpty('options', updates)
+  });
 }
 //# sourceMappingURL=setup.js.map

package/lib/commonjs/features/player/setup.js.map

@@ -1 +1 @@
-{"version":3,"names":["_native","require","setupPlayer","options","nativeBrowser"],"sourceRoot":"../../../../src","sources":["features/player/setup.ts"],"mappings":";;;;;;AAEA,IAAAA,OAAA,GAAAC,OAAA;AAFA;;AAIA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AASA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAmBA;AACA;AACA;;AAgBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;;AA+VA;;AAEA;AACA;AACA;AACA;AACO,eAAeC,WAAWA,CAC/BC,OAAkC,GAAG,CAAC,CAAC,EACxB;EACf,OAAOC,qBAAa,CAACF,WAAW,CAACC,OAAO,CAAC;AAC3C","ignoreList":[]}
+{"version":3,"names":["_native","require","_options","resolveNowPlaying","value","autoUpdateNowPlayingMetadata","nowPlayingMetadataFormatter","wrapNowPlayingFormatter","undefined","formatter","params","definedFields","obj","out","key","nonEmpty","Object","keys","length","setupPlayer","options","nowPlaying","capabilities","forwardJumpInterval","backwardJumpInterval","progressUpdateEventInterval","android","ios","nativeSetup","appKilledPlaybackBehavior","skipSilence","notificationButtons","androidSetup","playbackRates","carPlayUpNextButton","carPlayNowPlayingButtons","iosSetup","iosUpdate","validateIOSUpdateOptions","updates","nativeBrowser"],"sourceRoot":"../../../../src","sources":["features/player/setup.ts"],"mappings":";;;;;;AAYA,IAAAA,OAAA,GAAAC,OAAA;AACA,IAAAC,QAAA,GAAAD,OAAA;AAbA;;AAeA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAsBA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AASA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAUA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAmBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AA2BA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;;AA2GA;;AA4CA;AACA;AACA;AACA;AACA;;AAgCA;;AAEA;AACA;AACA;AACA;;AAMA;AACA;AAC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","ignoreList":[]}

package/lib/commonjs/features/queue/queue.js

@@ -123,11 +123,18 @@ function skipToPrevious(initialPosition) {
 }
 
 /**
- * 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.
  */
-function setQueue(tracks) {
-  _native.nativeBrowser.setQueue(tracks);
+function setQueue(tracks, startIndex, startPosition) {
+  _native.nativeBrowser.setQueue(tracks, startIndex, startPosition);
 }
 
 // MARK: - Getters