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

package/lib/module/features/metadata.js

@@ -30,22 +30,39 @@ import { NativeUpdatedValue } from '../utils/NativeUpdatedValue';
 
 /**
  * Subscribes to chapter metadata events.
+ *
+ * @platform ios android
+ * Never fires on web — the web player does not read chapter markers. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when chapter metadata is received
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onChapterMetadata = NativeUpdatedValue.emitterize(cb => nativeBrowser.onChapterMetadata = cb);
 
 /**
  * Subscribes to track metadata events.
+ *
+ * @platform ios android
+ * Never fires on web — the web player does not read embedded file tags. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when static track metadata is received
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onTrackMetadata = NativeUpdatedValue.emitterize(cb => nativeBrowser.onTrackMetadata = cb);
 
 /**
  * Subscribes to timed metadata events (ICY/ID3 from live streams).
+ *
+ * @platform ios android
+ * Never fires on web. ICY metadata is stripped by the browser before the player
+ * can see it, and no browser API exposes it; in-band ID3 from HLS is reachable
+ * but not yet wired. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when stream metadata is received (title, artist from ICY/ID3 tags)
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onTimedMetadata = NativeUpdatedValue.emitterize(cb => nativeBrowser.onTimedMetadata = cb);
 //# sourceMappingURL=metadata.js.map

package/lib/module/features/metadata.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","NativeUpdatedValue","onChapterMetadata","emitterize","cb","onTrackMetadata","onTimedMetadata"],"sourceRoot":"../../../src","sources":["features/metadata.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;;AAEhE;;AAoCA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;;AASA;AACA;AACA;AACA;;AAoBA;AACA;AACA;AACA;;AAYA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAAGD,kBAAkB,CAACE,UAAU,CAE3DC,EAAE,IAAMJ,aAAa,CAACE,iBAAiB,GAAGE,EAAG,CAAC;;AAEjD;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAGJ,kBAAkB,CAACE,UAAU,CACzDC,EAAE,IAAMJ,aAAa,CAACK,eAAe,GAAGD,EAC3C,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,eAAe,GAAGL,kBAAkB,CAACE,UAAU,CACzDC,EAAE,IAAMJ,aAAa,CAACM,eAAe,GAAGF,EAC3C,CAAC","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","NativeUpdatedValue","onChapterMetadata","emitterize","cb","onTrackMetadata","onTimedMetadata"],"sourceRoot":"../../../src","sources":["features/metadata.ts"],"mappings":";;AAAA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;;AAEhE;;AAyBA;AACA;AACA;AACA;AACA;;AAcA;AACA;AACA;AACA;;AASA;AACA;AACA;AACA;;AAoBA;AACA;AACA;AACA;;AAYA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAAGD,kBAAkB,CAACE,UAAU,CAE3DC,EAAE,IAAMJ,aAAa,CAACE,iBAAiB,GAAGE,EAAG,CAAC;;AAEjD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAGJ,kBAAkB,CAACE,UAAU,CACzDC,EAAE,IAAMJ,aAAa,CAACK,eAAe,GAAGD,EAC3C,CAAC;;AAED;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,eAAe,GAAGL,kBAAkB,CAACE,UAAU,CACzDC,EAAE,IAAMJ,aAAa,CAACM,eAAe,GAAGF,EAC3C,CAAC","ignoreList":[]}

package/lib/module/features/network.js

@@ -19,7 +19,7 @@ export function getOnline() {
 /**
  * Subscribes to network connectivity changes.
  * @param callback - Called when network state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onOnlineChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onOnlineChanged = cb);
 

package/lib/module/features/nowPlaying.js

@@ -33,13 +33,46 @@ export function getNowPlaying() {
   return nativeBrowser.getNowPlaying() ?? undefined;
 }
 
+/**
+ * Temporarily replaces now-playing fields for `durationMs`, then reverts to
+ * the live metadata. The flash outranks the now-playing formatter and the
+ * `updateNowPlaying` override while active (live metadata can't stomp it),
+ * and the revert runs on a native timer — JS timers pause in a backgrounded
+ * host (the lock screen case) — so it fires reliably. A track change clears
+ * the flash early; repeated calls restart the window.
+ *
+ * The feedback channel for refused remote commands: external surfaces have
+ * no toast primitive, so a transient metadata swap is the only way to talk
+ * to the user there.
+ *
+ * @example
+ * ```ts
+ * // A radio product with an hourly skip allowance:
+ * handleRemoteNext(() => {
+ *   if (skipsRemaining() > 0) skipToNext()
+ *   else flashNowPlaying({ artist: 'Skip limit reached' }, 3000)
+ * })
+ * ```
+ */
+export function flashNowPlaying(update, durationMs) {
+  nativeBrowser.flashNowPlaying(update, durationMs);
+}
+
+/**
+ * Clears an active flash immediately, reverting to the live metadata.
+ * No-op when no flash is active.
+ */
+export function clearNowPlayingFlash() {
+  nativeBrowser.clearNowPlayingFlash();
+}
+
 // MARK: - Event Callbacks
 
 /**
  * Subscribes to now playing metadata change events.
  * Fires when updateNowPlaying is called or when the track changes.
  * @param callback - Called when now playing metadata changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onNowPlayingChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onNowPlayingChanged = cb);
 

package/lib/module/features/nowPlaying.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","updateNowPlaying","update","undefined","getNowPlaying","onNowPlayingChanged","emitterize","cb","useNowPlaying"],"sourceRoot":"../../../src","sources":["features/nowPlaying.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;AAChE,SAASC,qBAAqB,QAAQ,gCAAgC;;AAEtE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,gBAAgBA,CAACC,MAA+B,EAAQ;EACtEJ,aAAa,CAACG,gBAAgB,CAACC,MAAM,IAAIC,SAAS,CAAC;AACrD;;AAEA;AACA;AACA;AACA,OAAO,SAASC,aAAaA,CAAA,EAAmC;EAC9D,OAAON,aAAa,CAACM,aAAa,CAAC,CAAC,IAAID,SAAS;AACnD;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAME,mBAAmB,GAC9BN,kBAAkB,CAACO,UAAU,CAC1BC,EAAE,IAAMT,aAAa,CAACO,mBAAmB,GAAGE,EAC/C,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,aAAaA,CAAA,EAAmC;EAC9D,OAAOR,qBAAqB,CAACI,aAAa,EAAEC,mBAAmB,CAAC;AAClE","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","updateNowPlaying","update","undefined","getNowPlaying","flashNowPlaying","durationMs","clearNowPlayingFlash","onNowPlayingChanged","emitterize","cb","useNowPlaying"],"sourceRoot":"../../../src","sources":["features/nowPlaying.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;AAChE,SAASC,qBAAqB,QAAQ,gCAAgC;;AAEtE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,gBAAgBA,CAACC,MAA+B,EAAQ;EACtEJ,aAAa,CAACG,gBAAgB,CAACC,MAAM,IAAIC,SAAS,CAAC;AACrD;;AAEA;AACA;AACA;AACA,OAAO,SAASC,aAAaA,CAAA,EAAmC;EAC9D,OAAON,aAAa,CAACM,aAAa,CAAC,CAAC,IAAID,SAAS;AACnD;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,eAAeA,CAC7BH,MAAwB,EACxBI,UAAkB,EACZ;EACNR,aAAa,CAACO,eAAe,CAACH,MAAM,EAAEI,UAAU,CAAC;AACnD;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,oBAAoBA,CAAA,EAAS;EAC3CT,aAAa,CAACS,oBAAoB,CAAC,CAAC;AACtC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,mBAAmB,GAC9BT,kBAAkB,CAACU,UAAU,CAC1BC,EAAE,IAAMZ,aAAa,CAACU,mBAAmB,GAAGE,EAC/C,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,aAAaA,CAAA,EAAmC;EAC9D,OAAOX,qBAAqB,CAACI,aAAa,EAAEI,mBAAmB,CAAC;AAClE","ignoreList":[]}

package/lib/module/features/output.js

@@ -6,42 +6,55 @@ import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue';
 // MARK: - Actions
 
 /**
- * Opens the system output picker (iOS only).
- * Allows users to select output device (speaker, AirPlay, Bluetooth, etc.).
- * No-op on Android.
+ * Presents the system audio output switcher so the listener can move playback to
+ * another output. Cross-platform:
+ * - **iOS** — the system route picker (Bluetooth, AirPlay / Sonos-via-AirPlay,
+ *   speaker). Always available.
+ * - **Android** — the system Output Switcher (Bluetooth / speaker / Cast list) on
+ *   Android 11+. No-op on older Android — gate on {@link supportsOutputSwitcher}.
+ * - **Web** — no-op.
  */
-export function openIosOutputPicker() {
-  nativeBrowser.openIosOutputPicker();
+export function openOutputPicker() {
+  nativeBrowser.openOutputPicker();
+}
+
+/**
+ * Whether {@link openOutputPicker} can present a switcher on this device — use it
+ * to decide whether to surface the output control in your UI.
+ * `true` on iOS and Android 11+ (API 30); `false` on older Android and web.
+ */
+export function supportsOutputSwitcher() {
+  return nativeBrowser.supportsOutputSwitcher();
 }
 
 // MARK: - Getters
 
 /**
- * Gets the current audio output info.
- * Always returns a value on iOS, undefined on Android.
+ * The current audio output, or `undefined` when unknown. iOS reports one while a
+ * session is active; Android reports the active output route via AudioManager
+ * (the `type` is coarse — e.g. wired headphones may report as `speaker`). Guard
+ * for `undefined`.
  */
-export function getIosOutput() {
-  return nativeBrowser.getIosOutput();
+export function getOutput() {
+  return nativeBrowser.getOutput();
 }
 
 // MARK: - Event Callbacks
 
 /**
- * Subscribes to output state changes (iOS only).
- * Never fires on Android.
- * @param callback - Called with output info when output changes
- * @returns Cleanup function to unsubscribe
+ * Subscribes to current-output changes (headphones unplugged, Bluetooth speaker
+ * connected, AirPlay/route selected). Fires on iOS and Android 11+; never below.
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
-export const onIosOutputChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onIosOutputChanged = cb);
+export const onOutputChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onOutputChanged = cb);
 
 // MARK: - Hooks
 
 /**
- * Hook that returns the current audio output info.
- * Updates when the output changes (e.g., AirPods connected/disconnected).
- * Always returns a value on iOS, undefined on Android.
+ * Reactive current audio output; re-renders when it changes (e.g. AirPods
+ * connect, a Bluetooth speaker is selected). `undefined` when unknown.
  */
-export function useIosOutput() {
-  return useNativeUpdatedValue(getIosOutput, onIosOutputChanged);
+export function useOutput() {
+  return useNativeUpdatedValue(getOutput, onOutputChanged);
 }
 //# sourceMappingURL=output.js.map

package/lib/module/features/output.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","openIosOutputPicker","getIosOutput","onIosOutputChanged","emitterize","cb","useIosOutput"],"sourceRoot":"../../../src","sources":["features/output.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;AAChE,SAASC,qBAAqB,QAAQ,gCAAgC;AAItE;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,mBAAmBA,CAAA,EAAS;EAC1CH,aAAa,CAACG,mBAAmB,CAAC,CAAC;AACrC;;AAEA;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,YAAYA,CAAA,EAA0B;EACpD,OAAOJ,aAAa,CAACI,YAAY,CAAC,CAAC;AACrC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,kBAAkB,GAAGJ,kBAAkB,CAACK,UAAU,CAC5DC,EAAE,IAAMP,aAAa,CAACK,kBAAkB,GAAGE,EAC9C,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,YAAYA,CAAA,EAA0B;EACpD,OAAON,qBAAqB,CAACE,YAAY,EAAEC,kBAAkB,CAAC;AAChE","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","openOutputPicker","supportsOutputSwitcher","getOutput","onOutputChanged","emitterize","cb","useOutput"],"sourceRoot":"../../../src","sources":["features/output.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,WAAW;AACzC,SAASC,kBAAkB,QAAQ,6BAA6B;AAChE,SAASC,qBAAqB,QAAQ,gCAAgC;AAItE;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,gBAAgBA,CAAA,EAAS;EACvCH,aAAa,CAACG,gBAAgB,CAAC,CAAC;AAClC;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,sBAAsBA,CAAA,EAAY;EAChD,OAAOJ,aAAa,CAACI,sBAAsB,CAAC,CAAC;AAC/C;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,SAASA,CAAA,EAAuB;EAC9C,OAAOL,aAAa,CAACK,SAAS,CAAC,CAAC;AAClC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,eAAe,GAAGL,kBAAkB,CAACM,UAAU,CACzDC,EAAE,IAAMR,aAAa,CAACM,eAAe,GAAGE,EAC3C,CAAC;;AAED;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,SAASA,CAAA,EAAuB;EAC9C,OAAOP,qBAAqB,CAACG,SAAS,EAAEC,eAAe,CAAC;AAC1D","ignoreList":[]}

package/lib/module/features/playback/controls.js

@@ -59,6 +59,14 @@ export function seekTo(position) {
   nativeBrowser.seekTo(position);
 }
 
+/**
+ * Jump to the live edge of the current track. No-op for non-live tracks; for
+ * live, seeks to the window end (HLS) or reconnects (non-seekable streams).
+ */
+export function seekToLiveEdge() {
+  nativeBrowser.seekToLiveEdge();
+}
+
 /**
  * Seeks by a relative time offset in the current track.
  * @param offset - The time offset to seek by in seconds.

package/lib/module/features/playback/controls.js.map

@@ -1 +1 @@
-{"version":3,"names":["nativeBrowser","reset","play","pause","togglePlayback","stop","retry","seekTo","position","seekBy","offset"],"sourceRoot":"../../../../src","sources":["features/playback/controls.ts"],"mappings":";;AAAA;;AAEA,SAASA,aAAa,QAAQ,cAAc;;AAE5C;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BD,aAAa,CAACC,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,IAAIA,CAAA,EAAS;EAC3BF,aAAa,CAACE,IAAI,CAAC,CAAC;AACtB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BH,aAAa,CAACG,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAA,EAAS;EACrCJ,aAAa,CAACI,cAAc,CAAC,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,IAAIA,CAAA,EAAS;EAC3BL,aAAa,CAACK,IAAI,CAAC,CAAC;AACtB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BN,aAAa,CAACM,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,QAAgB,EAAQ;EAC7CR,aAAa,CAACO,MAAM,CAACC,QAAQ,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,MAAc,EAAQ;EAC3CV,aAAa,CAACS,MAAM,CAACC,MAAM,CAAC;AAC9B","ignoreList":[]}
+{"version":3,"names":["nativeBrowser","reset","play","pause","togglePlayback","stop","retry","seekTo","position","seekToLiveEdge","seekBy","offset"],"sourceRoot":"../../../../src","sources":["features/playback/controls.ts"],"mappings":";;AAAA;;AAEA,SAASA,aAAa,QAAQ,cAAc;;AAE5C;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BD,aAAa,CAACC,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,IAAIA,CAAA,EAAS;EAC3BF,aAAa,CAACE,IAAI,CAAC,CAAC;AACtB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BH,aAAa,CAACG,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAA,EAAS;EACrCJ,aAAa,CAACI,cAAc,CAAC,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,IAAIA,CAAA,EAAS;EAC3BL,aAAa,CAACK,IAAI,CAAC,CAAC;AACtB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,KAAKA,CAAA,EAAS;EAC5BN,aAAa,CAACM,KAAK,CAAC,CAAC;AACvB;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,QAAgB,EAAQ;EAC7CR,aAAa,CAACO,MAAM,CAACC,QAAQ,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAA,EAAS;EACrCT,aAAa,CAACS,cAAc,CAAC,CAAC;AAChC;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASC,MAAMA,CAACC,MAAc,EAAQ;EAC3CX,aAAa,CAACU,MAAM,CAACC,MAAM,CAAC;AAC9B","ignoreList":[]}

package/lib/module/features/playback/index.js

@@ -5,6 +5,7 @@ export * from './state';
 export * from './playing';
 export * from './playWhenReady';
 export * from './progress';
+export * from './trackPlaybackTime';
 export * from './rate';
 export * from './volume';
 //# sourceMappingURL=index.js.map

package/lib/module/features/playback/index.js.map

@@ -1 +1 @@
-{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["features/playback/index.ts"],"mappings":";;AAAA,cAAc,YAAY;AAC1B,cAAc,SAAS;AACvB,cAAc,WAAW;AACzB,cAAc,iBAAiB;AAC/B,cAAc,YAAY;AAC1B,cAAc,QAAQ;AACtB,cAAc,UAAU","ignoreList":[]}
+{"version":3,"names":[],"sourceRoot":"../../../../src","sources":["features/playback/index.ts"],"mappings":";;AAAA,cAAc,YAAY;AAC1B,cAAc,SAAS;AACvB,cAAc,WAAW;AACzB,cAAc,iBAAiB;AAC/B,cAAc,YAAY;AAC1B,cAAc,qBAAqB;AACnC,cAAc,QAAQ;AACtB,cAAc,UAAU","ignoreList":[]}

package/lib/module/features/playback/playWhenReady.js

@@ -33,7 +33,7 @@ export function setPlayWhenReady(playWhenReady) {
 /**
  * Subscribes to play when ready changes.
  * @param callback - Called when playWhenReady changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlayWhenReadyChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackPlayWhenReadyChanged = cb);
 

package/lib/module/features/playback/playing.js

@@ -20,7 +20,7 @@ export function getPlayingState() {
 /**
  * Subscribes to playing state changes.
  * @param callback - Called when playing or buffering state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlayingState = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackPlayingState = cb);
 

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

@@ -1,6 +1,7 @@
 "use strict";
 
 import { useEffect, useState } from 'react';
+import { AppState } from 'react-native';
 import { nativeBrowser } from '../../native';
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue';
 import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue';
@@ -28,7 +29,7 @@ export function getProgress() {
 /**
  * Subscribes to playback progress updates.
  * @param callback - Called periodically with playback progress updates
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onProgressUpdated = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackProgressUpdated = cb);
 
@@ -49,6 +50,9 @@ export 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
  */
@@ -59,7 +63,8 @@ export function usePolledProgress(updateInterval = 1000) {
     buffered: 0
   });
   useEffect(() => {
-    let mounted = true;
+    let timer;
+    let unsubscribeState;
     const update = () => {
       try {
         const {
@@ -67,7 +72,6 @@ export function usePolledProgress(updateInterval = 1000) {
           duration,
           buffered
         } = getProgress();
-        if (!mounted) return;
         setState(currentState => position === currentState.position && duration === currentState.duration && buffered === currentState.buffered ? currentState : {
           position,
           duration,
@@ -77,20 +81,32 @@ export function usePolledProgress(updateInterval = 1000) {
         // Ignore failures (e.g., before setup)
       }
     };
-
-    // Update immediately on playback state changes
-    const unsubscribeState = 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 = onPlaybackChanged.addListener(update);
+      poll();
+    };
+    const stop = () => {
+      clearTimeout(timer);
+      timer = undefined;
+      unsubscribeState?.();
+      unsubscribeState = undefined;
     };
-    poll();
+    const appStateSub = AppState.addEventListener('change', next => {
+      if (next === 'active') start();else stop();
+    });
+    if (AppState.currentState === 'active') start();
     return () => {
-      mounted = false;
-      unsubscribeState();
+      stop();
+      appStateSub.remove();
     };
   }, [updateInterval]);
   return state;

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

@@ -1 +1 @@
-{"version":3,"names":["useEffect","useState","nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","onPlaybackChanged","getProgress","onProgressUpdated","emitterize","cb","onPlaybackProgressUpdated","useProgress","usePolledProgress","updateInterval","state","setState","position","duration","buffered","mounted","update","currentState","unsubscribeState","addListener","poll","setTimeout"],"sourceRoot":"../../../../src","sources":["features/playback/progress.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,QAAQ,QAAQ,OAAO;AAC3C,SAASC,aAAa,QAAQ,cAAc;AAC5C,SAASC,kBAAkB,QAAQ,gCAAgC;AACnE,SAASC,qBAAqB,QAAQ,mCAAmC;AACzE,SAASC,iBAAiB,QAAQ,SAAS;;AAE3C;;AAiBA;AACA;AACA;;AAMA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAAA,EAAa;EACtC,OAAOJ,aAAa,CAACI,WAAW,CAAC,CAAC;AACpC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAC5BJ,kBAAkB,CAACK,UAAU,CAC1BC,EAAE,IAAMP,aAAa,CAACQ,yBAAyB,GAAGD,EACrD,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,WAAWA,CAAA,EAAa;EACtC,OAAOP,qBAAqB,CAACE,WAAW,EAAEC,iBAAiB,CAAC;AAC9D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASK,iBAAiBA,CAACC,cAAc,GAAG,IAAI,EAAY;EACjE,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAGd,QAAQ,CAAW;IAC3Ce,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE;EACZ,CAAC,CAAC;EAEFlB,SAAS,CAAC,MAAM;IACd,IAAImB,OAAO,GAAG,IAAI;IAElB,MAAMC,MAAM,GAAGA,CAAA,KAAM;MACnB,IAAI;QACF,MAAM;UAAEJ,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CAAC,GAAGZ,WAAW,CAAC,CAAC;QACtD,IAAI,CAACa,OAAO,EAAE;QAEdJ,QAAQ,CAAEM,YAAY,IACpBL,QAAQ,KAAKK,YAAY,CAACL,QAAQ,IAClCC,QAAQ,KAAKI,YAAY,CAACJ,QAAQ,IAClCC,QAAQ,KAAKG,YAAY,CAACH,QAAQ,GAC9BG,YAAY,GACZ;UAAEL,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CACrC,CAAC;MACH,CAAC,CAAC,MAAM;QACN;MAAA;IAEJ,CAAC;;IAED;IACA,MAAMI,gBAAgB,GAAGjB,iBAAiB,CAACkB,WAAW,CAACH,MAAM,CAAC;IAE9D,MAAMI,IAAI,GAAGA,CAAA,KAAM;MACjBJ,MAAM,CAAC,CAAC;MACR,IAAI,CAACD,OAAO,EAAE;MACdM,UAAU,CAAC,MAAM;QACf,IAAIN,OAAO,EAAEK,IAAI,CAAC,CAAC;MACrB,CAAC,EAAEX,cAAc,CAAC;IACpB,CAAC;IAEDW,IAAI,CAAC,CAAC;IAEN,OAAO,MAAM;MACXL,OAAO,GAAG,KAAK;MACfG,gBAAgB,CAAC,CAAC;IACpB,CAAC;EACH,CAAC,EAAE,CAACT,cAAc,CAAC,CAAC;EAEpB,OAAOC,KAAK;AACd","ignoreList":[]}
+{"version":3,"names":["useEffect","useState","AppState","nativeBrowser","NativeUpdatedValue","useNativeUpdatedValue","onPlaybackChanged","getProgress","onProgressUpdated","emitterize","cb","onPlaybackProgressUpdated","useProgress","usePolledProgress","updateInterval","state","setState","position","duration","buffered","timer","unsubscribeState","update","currentState","poll","setTimeout","start","undefined","addListener","stop","clearTimeout","appStateSub","addEventListener","next","remove"],"sourceRoot":"../../../../src","sources":["features/playback/progress.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,QAAQ,QAAQ,OAAO;AAC3C,SAASC,QAAQ,QAAQ,cAAc;AACvC,SAASC,aAAa,QAAQ,cAAc;AAC5C,SAASC,kBAAkB,QAAQ,gCAAgC;AACnE,SAASC,qBAAqB,QAAQ,mCAAmC;AACzE,SAASC,iBAAiB,QAAQ,SAAS;;AAE3C;;AAiBA;AACA;AACA;;AAMA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,WAAWA,CAAA,EAAa;EACtC,OAAOJ,aAAa,CAACI,WAAW,CAAC,CAAC;AACpC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,iBAAiB,GAC5BJ,kBAAkB,CAACK,UAAU,CAC1BC,EAAE,IAAMP,aAAa,CAACQ,yBAAyB,GAAGD,EACrD,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASE,WAAWA,CAAA,EAAa;EACtC,OAAOP,qBAAqB,CAACE,WAAW,EAAEC,iBAAiB,CAAC;AAC9D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASK,iBAAiBA,CAACC,cAAc,GAAG,IAAI,EAAY;EACjE,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAGf,QAAQ,CAAW;IAC3CgB,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE;EACZ,CAAC,CAAC;EAEFnB,SAAS,CAAC,MAAM;IACd,IAAIoB,KAAgD;IACpD,IAAIC,gBAA0C;IAE9C,MAAMC,MAAM,GAAGA,CAAA,KAAM;MACnB,IAAI;QACF,MAAM;UAAEL,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CAAC,GAAGZ,WAAW,CAAC,CAAC;QAEtDS,QAAQ,CAAEO,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,MAAMK,IAAI,GAAGA,CAAA,KAAM;MACjBF,MAAM,CAAC,CAAC;MACRF,KAAK,GAAGK,UAAU,CAACD,IAAI,EAAEV,cAAc,CAAC;IAC1C,CAAC;;IAED;IACA;IACA;IACA,MAAMY,KAAK,GAAGA,CAAA,KAAM;MAClB,IAAIN,KAAK,KAAKO,SAAS,EAAE;MACzBN,gBAAgB,GAAGf,iBAAiB,CAACsB,WAAW,CAACN,MAAM,CAAC;MACxDE,IAAI,CAAC,CAAC;IACR,CAAC;IAED,MAAMK,IAAI,GAAGA,CAAA,KAAM;MACjBC,YAAY,CAACV,KAAK,CAAC;MACnBA,KAAK,GAAGO,SAAS;MACjBN,gBAAgB,GAAG,CAAC;MACpBA,gBAAgB,GAAGM,SAAS;IAC9B,CAAC;IAED,MAAMI,WAAW,GAAG7B,QAAQ,CAAC8B,gBAAgB,CAAC,QAAQ,EAAGC,IAAI,IAAK;MAChE,IAAIA,IAAI,KAAK,QAAQ,EAAEP,KAAK,CAAC,CAAC,MACzBG,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;IAEF,IAAI3B,QAAQ,CAACqB,YAAY,KAAK,QAAQ,EAAEG,KAAK,CAAC,CAAC;IAE/C,OAAO,MAAM;MACXG,IAAI,CAAC,CAAC;MACNE,WAAW,CAACG,MAAM,CAAC,CAAC;IACtB,CAAC;EACH,CAAC,EAAE,CAACpB,cAAc,CAAC,CAAC;EAEpB,OAAOC,KAAK;AACd","ignoreList":[]}

package/lib/module/features/playback/state.js

@@ -41,7 +41,7 @@ export function getPlayback() {
 /**
  * Subscribes to playback state changes.
  * @param callback - Called when the playback state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlaybackChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onPlaybackChanged = cb);
 

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

@@ -0,0 +1,83 @@
+"use strict";
+
+import { nativeBrowser } from '../../native';
+import { onActiveTrackChanged } from '../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;
+  nativeBrowser.onPlaybackInterval = onTick;
+  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).
+ */
+export 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) nativeBrowser.setPlaybackIntervalEnabled(true);
+  return () => {
+    if (!handles.delete(handle)) return;
+    if (handles.size === 0) nativeBrowser.setPlaybackIntervalEnabled(false);
+  };
+}
+//# sourceMappingURL=trackPlaybackTime.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["nativeBrowser","onActiveTrackChanged","handles","Set","installed","currentTrack","onTick","handle","totalSeconds","sinceLast","lastFireSeconds","period","callback","total","track","install","onPlaybackInterval","addListener","event","trackPlaybackTime","Error","add","size","setPlaybackIntervalEnabled","delete"],"sourceRoot":"../../../../src","sources":["features/playback/trackPlaybackTime.ts"],"mappings":";;AACA,SAASA,aAAa,QAAQ,cAAc;AAC5C,SAASC,oBAAoB,QAAQ,sBAAsB;;AAE3D;;AAkBA;;AAEA,MAAMC,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;EAChBJ,aAAa,CAACgB,kBAAkB,GAAGV,MAAM;EACzCL,oBAAoB,CAACgB,WAAW,CAAEC,KAAK,IAAK;IAC1Cb,YAAY,GAAGa,KAAK,CAACJ,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;AACA,OAAO,SAASK,iBAAiBA,CAC/BP,QAA4C,EAC5CD,MAAc,EACF;EACZ,IAAI,EAAEA,MAAM,IAAI,CAAC,CAAC,EAAE;IAClB,MAAM,IAAIS,KAAK,CAAC,wCAAwC,CAAC;EAC3D;EACAL,OAAO,CAAC,CAAC;EACT,MAAMR,MAAc,GAAG;IACrBI,MAAM;IACNH,YAAY,EAAE,CAAC;IACfE,eAAe,EAAE,CAAC;IAClBE;EACF,CAAC;EACDV,OAAO,CAACmB,GAAG,CAACd,MAAM,CAAC;EACnB,IAAIL,OAAO,CAACoB,IAAI,KAAK,CAAC,EAAEtB,aAAa,CAACuB,0BAA0B,CAAC,IAAI,CAAC;EACtE,OAAO,MAAM;IACX,IAAI,CAACrB,OAAO,CAACsB,MAAM,CAACjB,MAAM,CAAC,EAAE;IAC7B,IAAIL,OAAO,CAACoB,IAAI,KAAK,CAAC,EAAEtB,aAAa,CAACuB,0BAA0B,CAAC,KAAK,CAAC;EACzE,CAAC;AACH","ignoreList":[]}

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

@@ -33,7 +33,7 @@ export 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.
  */
 export function setSystemVolume(level) {
   nativeBrowser.setSystemVolume(level);
@@ -44,7 +44,7 @@ export function setSystemVolume(level) {
 /**
  * Subscribes to system volume changes.
  * @param callback - Called when the system volume changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onSystemVolumeChanged = NativeUpdatedValue.emitterize(cb => nativeBrowser.onSystemVolumeChanged = cb);