react-native-audio-browser 0.2.0-next.54 → 0.2.0-next.56

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (271) hide show
  1. package/README.md +32 -19
  2. package/lib/commonjs/CLAUDE.md +7 -2
  3. package/lib/commonjs/features/battery.js +16 -12
  4. package/lib/commonjs/features/battery.js.map +1 -1
  5. package/lib/commonjs/features/browser-config.js +1 -1
  6. package/lib/commonjs/features/browser.js +74 -24
  7. package/lib/commonjs/features/browser.js.map +1 -1
  8. package/lib/commonjs/features/carConnection.js +3 -4
  9. package/lib/commonjs/features/carConnection.js.map +1 -1
  10. package/lib/commonjs/features/equalizer.js +9 -5
  11. package/lib/commonjs/features/equalizer.js.map +1 -1
  12. package/lib/commonjs/features/errors.js +35 -21
  13. package/lib/commonjs/features/errors.js.map +1 -1
  14. package/lib/commonjs/features/favorites.js +15 -13
  15. package/lib/commonjs/features/favorites.js.map +1 -1
  16. package/lib/commonjs/features/gate.js +12 -6
  17. package/lib/commonjs/features/gate.js.map +1 -1
  18. package/lib/commonjs/features/metadata.js +16 -14
  19. package/lib/commonjs/features/metadata.js.map +1 -1
  20. package/lib/commonjs/features/network.js +5 -1
  21. package/lib/commonjs/features/network.js.map +1 -1
  22. package/lib/commonjs/features/nowPlaying.js +28 -14
  23. package/lib/commonjs/features/nowPlaying.js.map +1 -1
  24. package/lib/commonjs/features/output.js +8 -4
  25. package/lib/commonjs/features/output.js.map +1 -1
  26. package/lib/commonjs/features/playback/controls.js +10 -5
  27. package/lib/commonjs/features/playback/controls.js.map +1 -1
  28. package/lib/commonjs/features/playback/playWhenReady.js +6 -5
  29. package/lib/commonjs/features/playback/playWhenReady.js.map +1 -1
  30. package/lib/commonjs/features/playback/playing.js +5 -3
  31. package/lib/commonjs/features/playback/playing.js.map +1 -1
  32. package/lib/commonjs/features/playback/progress.js +11 -5
  33. package/lib/commonjs/features/playback/progress.js.map +1 -1
  34. package/lib/commonjs/features/playback/state.js +3 -3
  35. package/lib/commonjs/features/playback/state.js.map +1 -1
  36. package/lib/commonjs/features/playback/trackPlaybackTime.js +6 -1
  37. package/lib/commonjs/features/playback/trackPlaybackTime.js.map +1 -1
  38. package/lib/commonjs/features/playback/volume.js +6 -5
  39. package/lib/commonjs/features/playback/volume.js.map +1 -1
  40. package/lib/commonjs/features/player/options.js +20 -10
  41. package/lib/commonjs/features/player/options.js.map +1 -1
  42. package/lib/commonjs/features/player/setup.js +34 -38
  43. package/lib/commonjs/features/player/setup.js.map +1 -1
  44. package/lib/commonjs/features/queue/activeTrack.js +0 -1
  45. package/lib/commonjs/features/queue/activeTrack.js.map +1 -1
  46. package/lib/commonjs/features/queue/queue.js +48 -20
  47. package/lib/commonjs/features/queue/queue.js.map +1 -1
  48. package/lib/commonjs/features/queue/repeatMode.js +2 -1
  49. package/lib/commonjs/features/queue/repeatMode.js.map +1 -1
  50. package/lib/commonjs/features/queue/shuffle.js +0 -1
  51. package/lib/commonjs/features/queue/shuffle.js.map +1 -1
  52. package/lib/commonjs/features/remoteControls.js +59 -35
  53. package/lib/commonjs/features/remoteControls.js.map +1 -1
  54. package/lib/commonjs/features/sleepTimer.js +15 -6
  55. package/lib/commonjs/features/sleepTimer.js.map +1 -1
  56. package/lib/commonjs/utils/LazyNativeEmitter.js +6 -9
  57. package/lib/commonjs/utils/LazyNativeEmitter.js.map +1 -1
  58. package/lib/commonjs/utils/NativeUpdatedValue.js +13 -12
  59. package/lib/commonjs/utils/NativeUpdatedValue.js.map +1 -1
  60. package/lib/commonjs/utils/getTrackIdentity.js +6 -4
  61. package/lib/commonjs/utils/getTrackIdentity.js.map +1 -1
  62. package/lib/commonjs/utils/useDebug.js +16 -3
  63. package/lib/commonjs/utils/useDebug.js.map +1 -1
  64. package/lib/commonjs/web/NativeAudioBrowser.js +2 -4
  65. package/lib/commonjs/web/NativeAudioBrowser.js.map +1 -1
  66. package/lib/commonjs/web/browser/parseSearchResponse.js +3 -4
  67. package/lib/commonjs/web/browser/parseSearchResponse.js.map +1 -1
  68. package/lib/commonjs/web/browser/sections.js +1 -1
  69. package/lib/commonjs/web/util/BrowserPathHelper.js +1 -3
  70. package/lib/commonjs/web/util/BrowserPathHelper.js.map +1 -1
  71. package/lib/module/CLAUDE.md +7 -2
  72. package/lib/module/features/battery.js +16 -12
  73. package/lib/module/features/battery.js.map +1 -1
  74. package/lib/module/features/browser-config.js +1 -1
  75. package/lib/module/features/browser.js +74 -24
  76. package/lib/module/features/browser.js.map +1 -1
  77. package/lib/module/features/carConnection.js +3 -4
  78. package/lib/module/features/carConnection.js.map +1 -1
  79. package/lib/module/features/equalizer.js +9 -5
  80. package/lib/module/features/equalizer.js.map +1 -1
  81. package/lib/module/features/errors.js +35 -21
  82. package/lib/module/features/errors.js.map +1 -1
  83. package/lib/module/features/favorites.js +15 -13
  84. package/lib/module/features/favorites.js.map +1 -1
  85. package/lib/module/features/gate.js +12 -6
  86. package/lib/module/features/gate.js.map +1 -1
  87. package/lib/module/features/metadata.js +16 -14
  88. package/lib/module/features/metadata.js.map +1 -1
  89. package/lib/module/features/network.js +5 -1
  90. package/lib/module/features/network.js.map +1 -1
  91. package/lib/module/features/nowPlaying.js +28 -14
  92. package/lib/module/features/nowPlaying.js.map +1 -1
  93. package/lib/module/features/output.js +8 -4
  94. package/lib/module/features/output.js.map +1 -1
  95. package/lib/module/features/playback/controls.js +10 -5
  96. package/lib/module/features/playback/controls.js.map +1 -1
  97. package/lib/module/features/playback/playWhenReady.js +6 -5
  98. package/lib/module/features/playback/playWhenReady.js.map +1 -1
  99. package/lib/module/features/playback/playing.js +5 -3
  100. package/lib/module/features/playback/playing.js.map +1 -1
  101. package/lib/module/features/playback/progress.js +11 -5
  102. package/lib/module/features/playback/progress.js.map +1 -1
  103. package/lib/module/features/playback/state.js +3 -3
  104. package/lib/module/features/playback/state.js.map +1 -1
  105. package/lib/module/features/playback/trackPlaybackTime.js +6 -1
  106. package/lib/module/features/playback/trackPlaybackTime.js.map +1 -1
  107. package/lib/module/features/playback/volume.js +6 -5
  108. package/lib/module/features/playback/volume.js.map +1 -1
  109. package/lib/module/features/player/options.js +20 -10
  110. package/lib/module/features/player/options.js.map +1 -1
  111. package/lib/module/features/player/setup.js +34 -38
  112. package/lib/module/features/player/setup.js.map +1 -1
  113. package/lib/module/features/queue/activeTrack.js +0 -1
  114. package/lib/module/features/queue/activeTrack.js.map +1 -1
  115. package/lib/module/features/queue/queue.js +48 -20
  116. package/lib/module/features/queue/queue.js.map +1 -1
  117. package/lib/module/features/queue/repeatMode.js +2 -1
  118. package/lib/module/features/queue/repeatMode.js.map +1 -1
  119. package/lib/module/features/queue/shuffle.js +0 -1
  120. package/lib/module/features/queue/shuffle.js.map +1 -1
  121. package/lib/module/features/remoteControls.js +59 -35
  122. package/lib/module/features/remoteControls.js.map +1 -1
  123. package/lib/module/features/sleepTimer.js +15 -6
  124. package/lib/module/features/sleepTimer.js.map +1 -1
  125. package/lib/module/utils/LazyNativeEmitter.js +6 -9
  126. package/lib/module/utils/LazyNativeEmitter.js.map +1 -1
  127. package/lib/module/utils/NativeUpdatedValue.js +13 -12
  128. package/lib/module/utils/NativeUpdatedValue.js.map +1 -1
  129. package/lib/module/utils/getTrackIdentity.js +6 -4
  130. package/lib/module/utils/getTrackIdentity.js.map +1 -1
  131. package/lib/module/utils/useDebug.js +16 -3
  132. package/lib/module/utils/useDebug.js.map +1 -1
  133. package/lib/module/web/NativeAudioBrowser.js +2 -4
  134. package/lib/module/web/NativeAudioBrowser.js.map +1 -1
  135. package/lib/module/web/browser/parseSearchResponse.js +3 -4
  136. package/lib/module/web/browser/parseSearchResponse.js.map +1 -1
  137. package/lib/module/web/browser/sections.js +1 -1
  138. package/lib/module/web/util/BrowserPathHelper.js +1 -3
  139. package/lib/module/web/util/BrowserPathHelper.js.map +1 -1
  140. package/lib/typescript/src/features/battery.d.ts +17 -12
  141. package/lib/typescript/src/features/battery.d.ts.map +1 -1
  142. package/lib/typescript/src/features/browser.d.ts +64 -24
  143. package/lib/typescript/src/features/browser.d.ts.map +1 -1
  144. package/lib/typescript/src/features/carConnection.d.ts +3 -4
  145. package/lib/typescript/src/features/carConnection.d.ts.map +1 -1
  146. package/lib/typescript/src/features/equalizer.d.ts +9 -5
  147. package/lib/typescript/src/features/equalizer.d.ts.map +1 -1
  148. package/lib/typescript/src/features/errors.d.ts +37 -22
  149. package/lib/typescript/src/features/errors.d.ts.map +1 -1
  150. package/lib/typescript/src/features/favorites.d.ts +15 -13
  151. package/lib/typescript/src/features/favorites.d.ts.map +1 -1
  152. package/lib/typescript/src/features/gate.d.ts +14 -8
  153. package/lib/typescript/src/features/gate.d.ts.map +1 -1
  154. package/lib/typescript/src/features/metadata.d.ts +37 -17
  155. package/lib/typescript/src/features/metadata.d.ts.map +1 -1
  156. package/lib/typescript/src/features/network.d.ts +5 -1
  157. package/lib/typescript/src/features/network.d.ts.map +1 -1
  158. package/lib/typescript/src/features/nowPlaying.d.ts +28 -14
  159. package/lib/typescript/src/features/nowPlaying.d.ts.map +1 -1
  160. package/lib/typescript/src/features/output.d.ts +8 -4
  161. package/lib/typescript/src/features/output.d.ts.map +1 -1
  162. package/lib/typescript/src/features/playback/controls.d.ts +10 -5
  163. package/lib/typescript/src/features/playback/controls.d.ts.map +1 -1
  164. package/lib/typescript/src/features/playback/playWhenReady.d.ts +6 -5
  165. package/lib/typescript/src/features/playback/playWhenReady.d.ts.map +1 -1
  166. package/lib/typescript/src/features/playback/playing.d.ts +16 -3
  167. package/lib/typescript/src/features/playback/playing.d.ts.map +1 -1
  168. package/lib/typescript/src/features/playback/progress.d.ts +11 -5
  169. package/lib/typescript/src/features/playback/progress.d.ts.map +1 -1
  170. package/lib/typescript/src/features/playback/state.d.ts +8 -3
  171. package/lib/typescript/src/features/playback/state.d.ts.map +1 -1
  172. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts +9 -2
  173. package/lib/typescript/src/features/playback/trackPlaybackTime.d.ts.map +1 -1
  174. package/lib/typescript/src/features/playback/volume.d.ts +6 -5
  175. package/lib/typescript/src/features/playback/volume.d.ts.map +1 -1
  176. package/lib/typescript/src/features/player/options.d.ts +52 -37
  177. package/lib/typescript/src/features/player/options.d.ts.map +1 -1
  178. package/lib/typescript/src/features/player/setup.d.ts +65 -60
  179. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  180. package/lib/typescript/src/features/queue/activeTrack.d.ts +0 -1
  181. package/lib/typescript/src/features/queue/activeTrack.d.ts.map +1 -1
  182. package/lib/typescript/src/features/queue/queue.d.ts +48 -20
  183. package/lib/typescript/src/features/queue/queue.d.ts.map +1 -1
  184. package/lib/typescript/src/features/queue/repeatMode.d.ts +1 -1
  185. package/lib/typescript/src/features/queue/repeatMode.d.ts.map +1 -1
  186. package/lib/typescript/src/features/queue/shuffle.d.ts +0 -1
  187. package/lib/typescript/src/features/queue/shuffle.d.ts.map +1 -1
  188. package/lib/typescript/src/features/remoteControls.d.ts +58 -25
  189. package/lib/typescript/src/features/remoteControls.d.ts.map +1 -1
  190. package/lib/typescript/src/features/sleepTimer.d.ts +15 -7
  191. package/lib/typescript/src/features/sleepTimer.d.ts.map +1 -1
  192. package/lib/typescript/src/types/browser-nodes.d.ts +54 -57
  193. package/lib/typescript/src/types/browser-nodes.d.ts.map +1 -1
  194. package/lib/typescript/src/types/browser.d.ts +181 -144
  195. package/lib/typescript/src/types/browser.d.ts.map +1 -1
  196. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts +6 -9
  197. package/lib/typescript/src/utils/LazyNativeEmitter.d.ts.map +1 -1
  198. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts +13 -12
  199. package/lib/typescript/src/utils/NativeUpdatedValue.d.ts.map +1 -1
  200. package/lib/typescript/src/utils/getTrackIdentity.d.ts +6 -4
  201. package/lib/typescript/src/utils/getTrackIdentity.d.ts.map +1 -1
  202. package/lib/typescript/src/utils/useDebug.d.ts +16 -3
  203. package/lib/typescript/src/utils/useDebug.d.ts.map +1 -1
  204. package/package.json +1 -1
  205. package/src/CLAUDE.md +7 -2
  206. package/src/docs-floors.test.ts +71 -0
  207. package/src/features/battery.ts +17 -13
  208. package/src/features/browser-config.ts +1 -1
  209. package/src/features/browser.ts +65 -24
  210. package/src/features/carConnection.ts +3 -4
  211. package/src/features/equalizer.ts +9 -5
  212. package/src/features/errors.ts +37 -22
  213. package/src/features/favorites.ts +15 -13
  214. package/src/features/gate.ts +14 -8
  215. package/src/features/metadata.ts +37 -17
  216. package/src/features/network.ts +5 -1
  217. package/src/features/nowPlaying.ts +28 -14
  218. package/src/features/output.ts +8 -4
  219. package/src/features/playback/controls.ts +10 -5
  220. package/src/features/playback/playWhenReady.ts +6 -5
  221. package/src/features/playback/playing.ts +16 -3
  222. package/src/features/playback/progress.ts +11 -5
  223. package/src/features/playback/state.ts +8 -3
  224. package/src/features/playback/trackPlaybackTime.ts +9 -2
  225. package/src/features/playback/volume.ts +6 -5
  226. package/src/features/player/options.ts +54 -43
  227. package/src/features/player/setup.ts +67 -61
  228. package/src/features/queue/activeTrack.ts +0 -1
  229. package/src/features/queue/queue.ts +48 -20
  230. package/src/features/queue/repeatMode.ts +1 -1
  231. package/src/features/queue/shuffle.ts +0 -1
  232. package/src/features/remoteControls.ts +59 -35
  233. package/src/features/sleepTimer.ts +15 -7
  234. package/src/types/browser-nodes.ts +54 -57
  235. package/src/types/browser.ts +183 -146
  236. package/src/utils/LazyNativeEmitter.ts +6 -9
  237. package/src/utils/NativeUpdatedValue.ts +13 -12
  238. package/src/utils/getTrackIdentity.ts +6 -4
  239. package/src/utils/useDebug.ts +16 -3
  240. package/src/web/NativeAudioBrowser.ts +2 -4
  241. package/src/web/browser/parseSearchResponse.ts +3 -4
  242. package/src/web/browser/sections.ts +1 -1
  243. package/src/web/util/BrowserPathHelper.ts +1 -3
  244. package/website/guide/android-auto.md +25 -13
  245. package/website/guide/android-certificates.md +199 -120
  246. package/website/guide/artwork.md +93 -48
  247. package/website/guide/audio-output.md +86 -68
  248. package/website/guide/automotive.md +15 -10
  249. package/website/guide/basic-usage.md +5 -2
  250. package/website/guide/battery.md +50 -23
  251. package/website/guide/browser.md +155 -68
  252. package/website/guide/carplay.md +132 -49
  253. package/website/guide/configuration.md +85 -49
  254. package/website/guide/equalizer.md +36 -32
  255. package/website/guide/errors.md +106 -64
  256. package/website/guide/favorites.md +41 -31
  257. package/website/guide/gate.md +24 -10
  258. package/website/guide/getting-started.md +55 -2
  259. package/website/guide/hooks.md +53 -47
  260. package/website/guide/live-streams.md +80 -49
  261. package/website/guide/metadata.md +87 -53
  262. package/website/guide/migrating-from-track-player.md +94 -49
  263. package/website/guide/native-callback-fetch.md +46 -36
  264. package/website/guide/network.md +36 -20
  265. package/website/guide/now-playing.md +72 -44
  266. package/website/guide/playback.md +112 -35
  267. package/website/guide/queue.md +77 -43
  268. package/website/guide/remote-controls.md +87 -29
  269. package/website/guide/search.md +37 -22
  270. package/website/guide/sleep-timer.md +35 -14
  271. package/website/guide/track.md +59 -35
@@ -7,8 +7,8 @@ import type { AndroidUpdateOptions, IOSUpdateOptions, UpdateOptions } from './op
7
7
  * Parameters passed to the {@link FormatNowPlayingCallback}.
8
8
  *
9
9
  * The formatter owns every line shown on the now-playing surface — the track text, the live song,
10
- * *and* any transient status (reconnecting / error). The library no longer renders status copy
11
- * itself, so these fields give you what you need to render (and localize) it yourself. The formatter
10
+ * *and* any transient status (reconnecting / error). The library renders no status text; these
11
+ * fields let you render (and localize) it yourself. The formatter
12
12
  * is re-invoked on track change, each timed-metadata update, play/pause + error/rebuffer
13
13
  * transitions, and device connectivity changes.
14
14
  */
@@ -17,6 +17,7 @@ export type FormatNowPlayingParams = {
17
17
  track: Track;
18
18
  /**
19
19
  * Timed metadata (ICY / ID3 "now playing song") received during playback, if any.
20
+ * On iOS, also a file's own tags when the file has no chapters.
20
21
  * Always `undefined` on web — see `onTimedMetadata` for why.
21
22
  */
22
23
  timedMetadata?: TimedMetadata;
@@ -45,44 +46,28 @@ export type StallReason = 'buffering' | 'offline';
45
46
  * Customizes what's rendered on the now-playing surface — lock screen, notification, Control Center,
46
47
  * CarPlay, and Android Auto — for the currently playing track.
47
48
  *
48
- * Configure it via {@link SetupPlayerOptions.nowPlaying}. Where the default behavior
49
- * simply publishes the track's own `title` / `artist`, the formatter hands you the two now-playing
50
- * text lines outright: render the live timed metadata (the ICY / ID3 "now playing song"), surface a
51
- * transient status line ("Reconnecting…", an error message), drop the song while paused — anything
52
- * you can derive from the {@link FormatNowPlayingParams} for that moment.
49
+ * Configure it via {@link SetupPlayerOptions.nowPlaying}. It is re-invoked on track change, each
50
+ * timed-metadata update and every playback transition; identical results are de-duplicated
51
+ * natively, so they don't flicker the surface.
53
52
  *
54
- * The callback is **synchronous** and should stay cheap: it's a pure formatting function, run on the
55
- * JS thread and awaited natively. Don't do I/O in it. If you need asynchronously-fetched data (e.g.
56
- * album art), resolve it out-of-band and stamp it imperatively rather than awaiting inside here.
57
- *
58
- * ### When it's invoked
59
- * The player re-invokes the formatter whenever the now-playing could change:
60
- * - on track change (a new item becomes current);
61
- * - on each timed-metadata update ({@link FormatNowPlayingParams.timedMetadata} arrives or changes);
62
- * - on every playback transition — play / pause, a stall starting or recovering, an error.
63
- *
64
- * Identical results are de-duplicated natively before they reach the media session, so returning the
65
- * same fields across a rapid burst of transitions is cheap and won't flicker the surface.
66
- *
67
- * ### What to return
68
- * Return a {@link NowPlayingUpdate} with the fields to display. Each field falls back **independently**
69
- * to the track's own value when omitted — so `{ artist: 'Some Song' }` replaces only the secondary
70
- * line and leaves the title as the track's title. Return `undefined` (or `{}`) to use the library
71
- * default entirely (the track's own `title` / `artist`).
72
- *
73
- * @param params - The current track, latest timed metadata, and playback signals for this moment
74
- * ({@link FormatNowPlayingParams}), including a {@link StallReason} that already classifies an
75
- * offline stall — no separate connectivity read needed for the now-playing line.
76
- * @returns The now-playing fields to display, or `undefined` to fall back to the track's own
77
- * `title` / `artist`.
53
+ * The callback is **synchronous**, run on the JS thread and awaited natively: no I/O in it.
54
+ * Each returned field falls back **independently** to the track's own value, so
55
+ * `{ artist: 'Some Song' }` replaces only the secondary line; `undefined` (or `{}`) keeps the
56
+ * track's own `title` / `artist`. See the [Now playing guide](https://audiobrowser.dev/guide/now-playing).
78
57
  *
79
58
  * @example
80
59
  * ```ts
81
60
  * setupPlayer({
82
61
  * nowPlaying: ({ timedMetadata, playWhenReady, stalled, error }) => {
83
62
  * if (error) return { artist: error.message ?? 'Playback error' }
84
- * if (stalled) return { artist: stalled === 'offline' ? 'No internet connection' : 'Reconnecting…' }
85
- * // Show the live song only while actually playing; otherwise fall back to the track default.
63
+ * if (stalled) {
64
+ * return {
65
+ * artist: stalled === 'offline'
66
+ * ? 'No internet connection'
67
+ * : 'Reconnecting…'
68
+ * }
69
+ * }
70
+ * // Show the live song only while playing; else use the track default.
86
71
  * if (!playWhenReady || !timedMetadata?.title) return
87
72
  * return {
88
73
  * artist: timedMetadata.artist
@@ -131,7 +116,8 @@ export type AndroidAudioContentType = 'music' | 'speech' | 'sonification' | 'mov
131
116
  * - `'ambient'`: The category for an app in which sound playback is nonprimary
132
117
  * — that is, your app also works with the sound turned off. See
133
118
  * https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616560-ambient
134
- * - `'soloAmbient'`: The default audio session category. See
119
+ * - `'soloAmbient'`: The system's default audio session category; the library
120
+ * uses `'playback'` when `category` is omitted. See
135
121
  * https://developer.apple.com/documentation/avfaudio/avaudiosession/category/1616488-soloambient
136
122
  * - `'record'`: The category for recording audio while also silencing playback
137
123
  * audio. See
@@ -205,17 +191,23 @@ export type IOSCategoryOptions = 'mixWithOthers' | 'duckOthers' | 'interruptSpok
205
191
  * https://developer.apple.com/documentation/avfoundation/avaudiosession/routesharingpolicy/longformvideo
206
192
  */
207
193
  export type IOSCategoryPolicy = 'default' | 'longFormAudio' | 'longFormVideo';
194
+ /**
195
+ * Requirements for Android audio offload; see `audioOffload`.
196
+ * @platform android
197
+ */
208
198
  export interface AndroidAudioOffloadSettings {
209
199
  /**
210
200
  * Whether gapless playback support is required for offload.
211
201
  * Enables smooth transitions between tracks without silence gaps.
212
- * @default true
202
+ * Omitting it here means not required; `audioOffload: true` requires it.
203
+ * @default false
213
204
  */
214
205
  gaplessSupportRequired?: boolean;
215
206
  /**
216
207
  * Whether playback rate change support is required for offload.
217
208
  * Enables variable playback speeds (0.5x, 1.25x, 2x, etc.) during offload.
218
- * @default true
209
+ * Omitting it here means not required; `audioOffload: true` requires it.
210
+ * @default false
219
211
  */
220
212
  rateChangeSupportRequired?: boolean;
221
213
  }
@@ -283,8 +275,8 @@ export type AndroidPlayerWakeMode = 'none' | 'local' | 'network';
283
275
  export interface AndroidSetupOptions extends AndroidUpdateOptions {
284
276
  /**
285
277
  * Minimum duration of media that the player will attempt to buffer in ms.
278
+ * Has no effect: the player keeps loading until `maxBuffer` is buffered.
286
279
  *
287
- * @throws Will throw if min buffer is higher than max buffer.
288
280
  * @default 50000
289
281
  */
290
282
  minBuffer?: number;
@@ -296,17 +288,16 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
296
288
  *
297
289
  * - `true`: Enable with default settings (gapless + rate change support required)
298
290
  * - `false`/`undefined`: Disabled
299
- * - `{ gaplessSupportRequired: boolean, rateChangeSupportRequired: boolean }`:
300
- * Enable with specific requirements for gapless playback and playback rate changes
291
+ * - `{ gaplessSupportRequired?: boolean, rateChangeSupportRequired?: boolean }`:
292
+ * Enable with specific requirements for gapless playback and playback rate changes;
293
+ * an omitted field is not required, so `{}` enables offload with no requirements
301
294
  *
302
295
  * @default false
303
296
  */
304
297
  audioOffload?: boolean | AndroidAudioOffloadSettings;
305
298
  /**
306
299
  * Maximum duration of media that the player will attempt to buffer in ms.
307
- * Max buffer may not be lower than min buffer.
308
300
  *
309
- * @throws Will throw if max buffer is lower than min buffer.
310
301
  * @default 50000
311
302
  */
312
303
  maxBuffer?: number;
@@ -321,7 +312,7 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
321
312
  * Duration of media in ms that must be buffered for playback to start or
322
313
  * resume following a user action such as a seek.
323
314
  *
324
- * @default 2500
315
+ * @default 1000 (media3's `DEFAULT_BUFFER_FOR_PLAYBACK_MS`)
325
316
  */
326
317
  playBuffer?: number;
327
318
  /**
@@ -331,7 +322,6 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
331
322
  * When null (the default), uses automatic mode:
332
323
  * - Starts at `playBuffer` value
333
324
  * - On rebuffer, measures how fast the buffer drained
334
- * - Calculates how much buffer is needed to sustain 60s of playback
335
325
  * - Increases threshold accordingly (up to 8000ms max)
336
326
  * - Resets when changing tracks
337
327
  *
@@ -352,11 +342,11 @@ export interface AndroidSetupOptions extends AndroidUpdateOptions {
352
342
  * The audio content type indicates to the android system how
353
343
  * you intend to use audio in your app.
354
344
  *
355
- * With `audioContentType: AndroidAudioContentType.Speech`, the audio will be
345
+ * With `audioContentType: 'speech'`, the audio will be
356
346
  * paused during short interruptions, such as when a message arrives.
357
347
  * Otherwise the playback volume is reduced while the notification is playing.
358
348
  *
359
- * @default AndroidAudioContentType.Music
349
+ * @default 'music'
360
350
  */
361
351
  audioContentType?: AndroidAudioContentType;
362
352
  /**
@@ -391,7 +381,10 @@ export interface IOSSetupOptions extends IOSUpdateOptions {
391
381
  buffer?: number;
392
382
  /**
393
383
  * [AVAudioSession.Category](https://developer.apple.com/documentation/avfoundation/avaudiosession/1616615-category)
394
- * for iOS. Sets on `play()`.
384
+ * for iOS. Applied at `setupPlayer`; the session is activated when playback
385
+ * starts.
386
+ *
387
+ * @default 'playback'
395
388
  */
396
389
  category?: IOSCategory;
397
390
  /**
@@ -399,19 +392,25 @@ export interface IOSSetupOptions extends IOSUpdateOptions {
399
392
  * indicates to the system how you intend to use audio in your app. You can use
400
393
  * a mode to configure the audio system for specific use cases such as video
401
394
  * recording, voice or video chat, or audio analysis.
402
- * Sets on `play()`.
395
+ * Applied at `setupPlayer`; the session is activated when playback starts.
403
396
  *
404
397
  * See https://developer.apple.com/documentation/avfoundation/avaudiosession/1616508-mode
398
+ *
399
+ * @default 'default'
405
400
  */
406
401
  categoryMode?: IOSCategoryMode;
407
402
  /**
408
403
  * [AVAudioSession.CategoryOptions](https://developer.apple.com/documentation/avfoundation/avaudiosession/1616503-categoryoptions) for iOS.
409
- * Sets on `play()`.
404
+ * Applied at `setupPlayer`; the session is activated when playback starts.
405
+ *
406
+ * @default []
410
407
  */
411
408
  categoryOptions?: IOSCategoryOptions[];
412
409
  /**
413
410
  * [AVAudioSession.RouteSharingPolicy](https://developer.apple.com/documentation/AVFAudio/AVAudioSession/RouteSharingPolicy-swift.enum) for iOS.
414
- * Sets on `play()`.
411
+ * Applied at `setupPlayer`; the session is activated when playback starts.
412
+ *
413
+ * @default 'default'
415
414
  */
416
415
  categoryPolicy?: IOSCategoryPolicy;
417
416
  }
@@ -469,20 +468,22 @@ export type SetupPlayerOptions = Pick<UpdateOptions, 'capabilities' | 'forwardJu
469
468
  /**
470
469
  * Retry policy for load errors (network failures, timeouts, etc.)
471
470
  * - `true`: Retry indefinitely with exponential backoff, under the default
472
- * duration budgets (12s before first audio, 2 minutes after — see
473
- * {@link RetryConfig})
474
- * - `false`/`undefined`: No automatic retry (default)
471
+ * duration budgets of {@link RetryConfig}
472
+ * - `false`/`undefined`: no library retry. Android keeps media3's default
473
+ * handling, which retries a failed load a few times before surfacing the
474
+ * error; iOS fails at once.
475
475
  * - `{ maxRetries: n }`: Retry up to n times with exponential backoff
476
476
  * - `RetryConfig`: custom attempt and duration budgets
477
477
  *
478
- * Exponential backoff delays: 1s → 1.5s → 2.3s → 3.4s → 5s (capped)
478
+ * Backoff timing and budgets: see the
479
+ * [Errors guide](https://audiobrowser.dev/guide/errors#two-duration-budgets).
479
480
  *
480
481
  * @default false
481
482
  */
482
483
  retry?: boolean | RetryConfig;
483
484
  /**
484
485
  * Keep the media session alive and controllable through a terminal playback error (e.g. a dead
485
- * stream), so external controllers (Android Auto / CarPlay) keep their transport controls
486
+ * stream), so External Surfaces such as Android Auto keep their transport controls
486
487
  * (next / previous) instead of tearing the session down. The error is still reported via
487
488
  * `onPlaybackError` / `playbackState`; this only affects what the OS media session observes.
488
489
  *
@@ -504,7 +505,7 @@ export type SetupPlayerOptions = Pick<UpdateOptions, 'capabilities' | 'forwardJu
504
505
  * Each `setupPlayer` sets it: left out, remote outputs are off, and playback on one comes back
505
506
  * to the phone.
506
507
  *
507
- * Android 11+ only for now; ignored on iOS, whose route picker already lists AirPlay devices.
508
+ * Android 11+; ignored on iOS, whose route picker already lists AirPlay devices.
508
509
  * @default off
509
510
  */
510
511
  remoteOutputs?: RemoteOutputsOptions;
@@ -519,8 +520,7 @@ export type SetupPlayerOptions = Pick<UpdateOptions, 'capabilities' | 'forwardJu
519
520
  * - `true` (default): publish the track's own title / artist.
520
521
  * - `false`: don't manage the now-playing metadata at all.
521
522
  * - a {@link FormatNowPlayingCallback}: render it yourself — the callback owns every line,
522
- * including any transient status (buffering / reconnecting / offline / error), which the
523
- * library no longer renders on your behalf.
523
+ * including any transient status (buffering / reconnecting / offline / error).
524
524
  *
525
525
  * @default true
526
526
  */
@@ -533,9 +533,14 @@ export type SetupPlayerOptions = Pick<UpdateOptions, 'capabilities' | 'forwardJu
533
533
  * natively as part of setup itself, so there is no setup-then-command ordering for consumers
534
534
  * to know about, and no window where the player exists without its options.
535
535
  *
536
- * Calling it again reconfigures the player in place: newly provided fields are merged over
537
- * the previous ones, and the audio engine is rebuilt when construction-bound fields (buffers,
538
- * wake mode, …) changed.
536
+ * Calling it again is how a setup-only option changes after launch, and works differently per
537
+ * platform. On Android, newly provided fields are merged over the previous ones, except
538
+ * `remoteOutputs`, which is off when left out, and `nowPlaying`, which is on when left out
539
+ * and keeps an earlier formatter until a call passes another one. The audio engine is rebuilt
540
+ * only when construction-bound fields (buffers, wake mode, …) changed. On iOS, each call
541
+ * replaces the player: the queue is cleared, and setup-only fields you omit (`ios` session
542
+ * category and `buffer`, `retry`, …) go back to their defaults. Runtime options set earlier
543
+ * carry over on both.
539
544
  *
540
545
  * @param options - The options to initialize the player with.
541
546
  *
@@ -1 +1 @@
1
- {"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../../src/features/player/setup.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../../src/features/player/setup.ts"],"names":[],"mappings":"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"}
@@ -32,7 +32,6 @@ export declare function getActiveTrackIndex(): number | undefined;
32
32
  * {@link onFavoriteChanged} instead; {@link useActiveTrack} subscribes to
33
33
  * both, so UI bound through the hook still re-renders on a heart toggle.
34
34
  *
35
- * @param callback - Called when the active track changes
36
35
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
37
36
  */
38
37
  export declare const onActiveTrackChanged: NativeUpdatedValue<PlaybackActiveTrackChangedEvent>;
@@ -1 +1 @@
1
- {"version":3,"file":"activeTrack.d.ts","sourceRoot":"","sources":["../../../../../src/features/queue/activeTrack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAInE;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,KAAK,CAAA;IACjB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAID;;GAEG;AACH,wBAAgB,cAAc,IAAI,KAAK,GAAG,SAAS,CAElD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAExD;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,qDAG9B,CAAA;AAOH;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,KAAK,GAAG,SAAS,CAElD"}
1
+ {"version":3,"file":"activeTrack.d.ts","sourceRoot":"","sources":["../../../../../src/features/queue/activeTrack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAInE;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,KAAK,CAAA;IACjB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iFAAiF;IACjF,KAAK,CAAC,EAAE,KAAK,CAAA;CACd;AAID;;GAEG;AACH,wBAAgB,cAAc,IAAI,KAAK,GAAG,SAAS,CAElD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAExD;AAID;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,qDAG9B,CAAA;AAOH;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,KAAK,GAAG,SAAS,CAElD"}
@@ -14,6 +14,8 @@ export interface PlaybackQueueEndedEvent {
14
14
  * @param tracks - The tracks to add to the queue.
15
15
  * @param insertBeforeIndex - (Optional) The index to insert the tracks before.
16
16
  * By default the tracks will be added to the end of the queue.
17
+ * @throws If `insertBeforeIndex` is negative or past the queue's length.
18
+ * Android and the web treat `-1` as append; iOS throws on it.
17
19
  */
18
20
  export declare function add(tracks: Track[], insertBeforeIndex?: number): void;
19
21
  /**
@@ -21,69 +23,94 @@ export declare function add(tracks: Track[], insertBeforeIndex?: number): void;
21
23
  * @param track - The track to add to the queue.
22
24
  * @param insertBeforeIndex - (Optional) The index to insert the track before.
23
25
  * By default the track will be added to the end of the queue.
26
+ * @throws If `insertBeforeIndex` is negative or past the queue's length.
27
+ * Android and the web treat `-1` as append; iOS throws on it.
24
28
  */
25
29
  export declare function add(track: Track, insertBeforeIndex?: number): void;
26
30
  /**
27
31
  * Replaces the current track or loads the track as the first in the queue.
28
32
  * @param track - The track to load.
33
+ * @throws If called before `setupPlayer`.
29
34
  */
30
35
  export declare function load(track: Track): void;
31
36
  /**
32
37
  * Move a track within the queue.
33
38
  * @param fromIndex - The index of the track to be moved.
34
- * @param toIndex - The index to move the track to. If the index is larger than
35
- * the size of the queue, then the track is moved to the end of the queue.
39
+ * @param toIndex - The index to move the track to. On iOS and Android an index
40
+ * past the end moves the track to the end of the queue; the web throws.
41
+ * @throws If `fromIndex` is outside the queue or `toIndex` is negative (on the
42
+ * web, also if `toIndex` is past the last index).
36
43
  */
37
44
  export declare function move(fromIndex: number, toIndex: number): void;
38
45
  /**
39
46
  * Removes multiple tracks from the queue by their indexes.
40
47
  *
41
- * If the current track is removed, the next track will activated. If the
42
- * current track was the last track in the queue, the first track will be
43
- * activated.
48
+ * If the active track is removed, the track after it becomes active. On iOS
49
+ * and the web that is the next index, wrapping to the first track. On Android
50
+ * it is the next track in playback order (shuffle and repeat apply), and
51
+ * removing the last track with repeat `off` makes the first track active but
52
+ * ends playback.
44
53
  *
45
54
  * @param indexes - The indexes of the tracks to be removed.
55
+ * @throws If an index is outside the queue. Android checks every index before
56
+ * removing any, and also throws if an index appears twice. iOS removes from the
57
+ * highest index down, so an invalid index can throw after some tracks are gone,
58
+ * and a repeated index also removes the track that moved into its place. The
59
+ * web skips invalid and repeated indexes without throwing.
46
60
  */
47
61
  export declare function remove(indexes: number[]): void;
48
62
  /**
49
63
  * Removes a track from the queue by its index.
50
64
  *
51
- * If the current track is removed, the next track will activated. If the
52
- * current track was the last track in the queue, the first track will be
53
- * activated.
65
+ * If the active track is removed, the track after it becomes active. On iOS
66
+ * and the web that is the next index, wrapping to the first track. On Android
67
+ * it is the next track in playback order (shuffle and repeat apply), and
68
+ * removing the last track with repeat `off` makes the first track active but
69
+ * ends playback.
54
70
  *
55
71
  * @param index - The index of the track to be removed.
72
+ * @throws If `index` is outside the queue, on iOS and Android; the web
73
+ * ignores it.
56
74
  */
57
75
  export declare function remove(index: number): void;
58
76
  /**
59
- * Clears any upcoming tracks from the queue.
77
+ * Removes every track after the active track's index in the queue. With
78
+ * shuffle on, this is queue order, not the shuffled play order.
60
79
  */
61
80
  export declare function removeUpcomingTracks(): void;
62
81
  /**
63
82
  * Skips to a track in the queue.
64
83
  * @param index - The index of the track to skip to.
65
84
  * @param initialPosition - (Optional) The initial position to seek to in seconds.
85
+ * @throws If `index` is outside the queue.
66
86
  */
67
87
  export declare function skip(index: number, initialPosition?: number): void;
68
88
  /**
69
89
  * Skips to the next track in the queue.
70
- * @param initialPosition - (Optional) The initial position to seek to in seconds.
90
+ * @param initialPosition - (Optional) The position in seconds to start the next
91
+ * track from. On iOS and Android, with no next track the active track seeks to
92
+ * it instead; on the web the call does nothing.
71
93
  */
72
94
  export declare function skipToNext(initialPosition?: number): void;
73
95
  /**
74
96
  * Skips to the previous track in the queue.
75
- * @param initialPosition - (Optional) The initial position to seek to in seconds.
97
+ * @param initialPosition - (Optional) The position in seconds to start the
98
+ * previous track from. On iOS and Android, with no previous track the active
99
+ * track seeks to it instead; on the web the call does nothing.
76
100
  */
77
101
  export declare function skipToPrevious(initialPosition?: number): void;
78
102
  /**
79
103
  * Sets (replaces) the queue.
80
104
  *
81
- * This does not change the play/pause state: the player keeps playing if it was
82
- * playing and stays paused if it was paused. Call `play` explicitly to
83
- * start playback.
105
+ * On iOS and Android this does not change the play/pause state: the player
106
+ * keeps playing if it was playing and stays paused if it was paused. On the
107
+ * web it stops playback. Call `play` after it to start playback.
84
108
  *
85
109
  * @param tracks - The tracks to set as the queue.
86
110
  * @param startIndex - (Optional) The index of the track to make active.
111
+ * Defaults to 0 on iOS and Android; on the web, omitting it leaves no track
112
+ * active. iOS clamps an out-of-range index into the queue, Android throws, and
113
+ * the web ignores it.
87
114
  * @param startPosition - (Optional) The position in seconds to start the active track from.
88
115
  */
89
116
  export declare function setQueue(tracks: Track[], startIndex?: number, startPosition?: number): void;
@@ -98,17 +125,18 @@ export declare function getTrack(index: number): Track | undefined;
98
125
  */
99
126
  export declare function getQueue(): Track[];
100
127
  /**
101
- * Subscribes to playback queue ended events.
102
- * @param callback - Called when playback has paused due to reaching the end of the queue
128
+ * Subscribes to playback queue ended events: fires when the last track in
129
+ * playback order finishes with repeat mode `off` and the playback state
130
+ * becomes `ended`. Never fires under `track` or `queue` repeat.
103
131
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
104
132
  */
105
133
  export declare const onQueueEnded: NativeUpdatedValue<PlaybackQueueEndedEvent>;
106
134
  /**
107
135
  * Subscribes to queue change events.
108
- * Called when tracks are added, removed, or reordered. An in-place mutation of
109
- * a queued track's metadata (a favorite toggle) emits `onFavoriteChanged`
110
- * instead; {@link useQueue} subscribes to both.
111
- * @param callback - Called with the updated queue
136
+ * Called when tracks are added, removed, or reordered. On iOS and Android a
137
+ * favorite toggle also fires it, alongside `onFavoriteChanged`. On web a
138
+ * favorite toggle fires only `onFavoriteChanged`. {@link useQueue} subscribes
139
+ * to both.
112
140
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
113
141
  */
114
142
  export declare const onQueueChanged: NativeUpdatedValue<Track[]>;
@@ -1 +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;AAMnE;;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;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,6BAE1B,CAAA;AAOD;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,KAAK,EAAE,CAElC"}
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;AAMnE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;IACb,0FAA0F;IAC1F,QAAQ,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;AACtE;;;;;;;GAOG;AACH,wBAAgB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;AAQnE;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;AAC/C;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;AAO3C;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;;;;;;;;;;;GAaG;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;;;;;GAKG;AACH,eAAO,MAAM,YAAY,6CAGtB,CAAA;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,6BAE1B,CAAA;AAOD;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,KAAK,EAAE,CAElC"}
@@ -16,13 +16,13 @@ export declare function getRepeatMode(): RepeatMode;
16
16
  * @param repeatMode - The repeat mode to set
17
17
  */
18
18
  export declare function setRepeatMode(repeatMode: RepeatMode): void;
19
+ /** Event data for when the repeat mode changes. */
19
20
  export interface RepeatModeChangedEvent {
20
21
  /** The new repeat mode */
21
22
  repeatMode: RepeatMode;
22
23
  }
23
24
  /**
24
25
  * Subscribes to repeat mode changes.
25
- * @param callback - Called when repeat mode changes
26
26
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
27
27
  */
28
28
  export declare const onRepeatModeChanged: NativeUpdatedValue<RepeatModeChangedEvent>;
@@ -1 +1 @@
1
- {"version":3,"file":"repeatMode.d.ts","sourceRoot":"","sources":["../../../../../src/features/queue/repeatMode.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAKnE;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAA;AAIlD;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,QAEnD;AAID,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,4CAG7B,CAAA;AAIH;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}
1
+ {"version":3,"file":"repeatMode.d.ts","sourceRoot":"","sources":["../../../../../src/features/queue/repeatMode.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAKnE;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,CAAA;AAIlD;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,UAAU,QAEnD;AAID,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,UAAU,EAAE,UAAU,CAAA;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,4CAG7B,CAAA;AAIH;;;GAGG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}
@@ -15,7 +15,6 @@ export declare function setShuffle(enabled: boolean): void;
15
15
  export declare function toggleShuffle(): void;
16
16
  /**
17
17
  * Subscribes to shuffle mode changes.
18
- * @param callback - Called when shuffle mode changes
19
18
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
20
19
  */
21
20
  export declare const onShuffleChanged: NativeUpdatedValue<boolean>;
@@ -1 +1 @@
1
- {"version":3,"file":"shuffle.d.ts","sourceRoot":"","sources":["../../../../../src/features/queue/shuffle.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAKnE;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEjD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAE5B,CAAA;AAID;;;GAGG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC"}
1
+ {"version":3,"file":"shuffle.d.ts","sourceRoot":"","sources":["../../../../../src/features/queue/shuffle.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AAKnE;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEjD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAID;;;GAGG;AACH,eAAO,MAAM,gBAAgB,6BAE5B,CAAA;AAID;;;GAGG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC"}