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
@@ -47,7 +47,6 @@ export function getActiveTrackIndex(): number | undefined {
47
47
  * {@link onFavoriteChanged} instead; {@link useActiveTrack} subscribes to
48
48
  * both, so UI bound through the hook still re-renders on a heart toggle.
49
49
  *
50
- * @param callback - Called when the active track changes
51
50
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
52
51
  */
53
52
  export const onActiveTrackChanged =
@@ -23,6 +23,8 @@ export interface PlaybackQueueEndedEvent {
23
23
  * @param tracks - The tracks to add to the queue.
24
24
  * @param insertBeforeIndex - (Optional) The index to insert the tracks before.
25
25
  * By default the tracks 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.
26
28
  */
27
29
  export function add(tracks: Track[], insertBeforeIndex?: number): void
28
30
  /**
@@ -30,6 +32,8 @@ export function add(tracks: Track[], insertBeforeIndex?: number): void
30
32
  * @param track - The track to add to the queue.
31
33
  * @param insertBeforeIndex - (Optional) The index to insert the track before.
32
34
  * By default the track will be added to the end of the queue.
35
+ * @throws If `insertBeforeIndex` is negative or past the queue's length.
36
+ * Android and the web treat `-1` as append; iOS throws on it.
33
37
  */
34
38
  export function add(track: Track, insertBeforeIndex?: number): void
35
39
  export function add(tracks: Track | Track[], insertBeforeIndex?: number): void {
@@ -42,6 +46,7 @@ export function add(tracks: Track | Track[], insertBeforeIndex?: number): void {
42
46
  /**
43
47
  * Replaces the current track or loads the track as the first in the queue.
44
48
  * @param track - The track to load.
49
+ * @throws If called before `setupPlayer`.
45
50
  */
46
51
  export function load(track: Track): void {
47
52
  nativeBrowser.load(track)
@@ -50,8 +55,10 @@ export function load(track: Track): void {
50
55
  /**
51
56
  * Move a track within the queue.
52
57
  * @param fromIndex - The index of the track to be moved.
53
- * @param toIndex - The index to move the track to. If the index is larger than
54
- * the size of the queue, then the track is moved to the end of the queue.
58
+ * @param toIndex - The index to move the track to. On iOS and Android an index
59
+ * past the end moves the track to the end of the queue; the web throws.
60
+ * @throws If `fromIndex` is outside the queue or `toIndex` is negative (on the
61
+ * web, also if `toIndex` is past the last index).
55
62
  */
56
63
  export function move(fromIndex: number, toIndex: number): void {
57
64
  nativeBrowser.move(fromIndex, toIndex)
@@ -60,21 +67,32 @@ export function move(fromIndex: number, toIndex: number): void {
60
67
  /**
61
68
  * Removes multiple tracks from the queue by their indexes.
62
69
  *
63
- * If the current track is removed, the next track will activated. If the
64
- * current track was the last track in the queue, the first track will be
65
- * activated.
70
+ * If the active track is removed, the track after it becomes active. On iOS
71
+ * and the web that is the next index, wrapping to the first track. On Android
72
+ * it is the next track in playback order (shuffle and repeat apply), and
73
+ * removing the last track with repeat `off` makes the first track active but
74
+ * ends playback.
66
75
  *
67
76
  * @param indexes - The indexes of the tracks to be removed.
77
+ * @throws If an index is outside the queue. Android checks every index before
78
+ * removing any, and also throws if an index appears twice. iOS removes from the
79
+ * highest index down, so an invalid index can throw after some tracks are gone,
80
+ * and a repeated index also removes the track that moved into its place. The
81
+ * web skips invalid and repeated indexes without throwing.
68
82
  */
69
83
  export function remove(indexes: number[]): void
70
84
  /**
71
85
  * Removes a track from the queue by its index.
72
86
  *
73
- * If the current track is removed, the next track will activated. If the
74
- * current track was the last track in the queue, the first track will be
75
- * activated.
87
+ * If the active track is removed, the track after it becomes active. On iOS
88
+ * and the web that is the next index, wrapping to the first track. On Android
89
+ * it is the next track in playback order (shuffle and repeat apply), and
90
+ * removing the last track with repeat `off` makes the first track active but
91
+ * ends playback.
76
92
  *
77
93
  * @param index - The index of the track to be removed.
94
+ * @throws If `index` is outside the queue, on iOS and Android; the web
95
+ * ignores it.
78
96
  */
79
97
  export function remove(index: number): void
80
98
  export function remove(indexOrIndexes: number | number[]): void {
@@ -84,7 +102,8 @@ export function remove(indexOrIndexes: number | number[]): void {
84
102
  }
85
103
 
86
104
  /**
87
- * Clears any upcoming tracks from the queue.
105
+ * Removes every track after the active track's index in the queue. With
106
+ * shuffle on, this is queue order, not the shuffled play order.
88
107
  */
89
108
  export function removeUpcomingTracks(): void {
90
109
  nativeBrowser.removeUpcomingTracks()
@@ -94,6 +113,7 @@ export function removeUpcomingTracks(): void {
94
113
  * Skips to a track in the queue.
95
114
  * @param index - The index of the track to skip to.
96
115
  * @param initialPosition - (Optional) The initial position to seek to in seconds.
116
+ * @throws If `index` is outside the queue.
97
117
  */
98
118
  export function skip(index: number, initialPosition?: number): void {
99
119
  nativeBrowser.skip(index, initialPosition)
@@ -101,7 +121,9 @@ export function skip(index: number, initialPosition?: number): void {
101
121
 
102
122
  /**
103
123
  * Skips to the next track in the queue.
104
- * @param initialPosition - (Optional) The initial position to seek to in seconds.
124
+ * @param initialPosition - (Optional) The position in seconds to start the next
125
+ * track from. On iOS and Android, with no next track the active track seeks to
126
+ * it instead; on the web the call does nothing.
105
127
  */
106
128
  export function skipToNext(initialPosition?: number): void {
107
129
  nativeBrowser.skipToNext(initialPosition)
@@ -109,7 +131,9 @@ export function skipToNext(initialPosition?: number): void {
109
131
 
110
132
  /**
111
133
  * Skips to the previous track in the queue.
112
- * @param initialPosition - (Optional) The initial position to seek to in seconds.
134
+ * @param initialPosition - (Optional) The position in seconds to start the
135
+ * previous track from. On iOS and Android, with no previous track the active
136
+ * track seeks to it instead; on the web the call does nothing.
113
137
  */
114
138
  export function skipToPrevious(initialPosition?: number): void {
115
139
  nativeBrowser.skipToPrevious(initialPosition)
@@ -118,12 +142,15 @@ export function skipToPrevious(initialPosition?: number): void {
118
142
  /**
119
143
  * Sets (replaces) the queue.
120
144
  *
121
- * This does not change the play/pause state: the player keeps playing if it was
122
- * playing and stays paused if it was paused. Call `play` explicitly to
123
- * start playback.
145
+ * On iOS and Android this does not change the play/pause state: the player
146
+ * keeps playing if it was playing and stays paused if it was paused. On the
147
+ * web it stops playback. Call `play` after it to start playback.
124
148
  *
125
149
  * @param tracks - The tracks to set as the queue.
126
150
  * @param startIndex - (Optional) The index of the track to make active.
151
+ * Defaults to 0 on iOS and Android; on the web, omitting it leaves no track
152
+ * active. iOS clamps an out-of-range index into the queue, Android throws, and
153
+ * the web ignores it.
127
154
  * @param startPosition - (Optional) The position in seconds to start the active track from.
128
155
  */
129
156
  export function setQueue(
@@ -155,8 +182,9 @@ export function getQueue(): Track[] {
155
182
  // MARK: - Event Callbacks
156
183
 
157
184
  /**
158
- * Subscribes to playback queue ended events.
159
- * @param callback - Called when playback has paused due to reaching the end of the queue
185
+ * Subscribes to playback queue ended events: fires when the last track in
186
+ * playback order finishes with repeat mode `off` and the playback state
187
+ * becomes `ended`. Never fires under `track` or `queue` repeat.
160
188
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
161
189
  */
162
190
  export const onQueueEnded =
@@ -166,10 +194,10 @@ export const onQueueEnded =
166
194
 
167
195
  /**
168
196
  * Subscribes to queue change events.
169
- * Called when tracks are added, removed, or reordered. An in-place mutation of
170
- * a queued track's metadata (a favorite toggle) emits `onFavoriteChanged`
171
- * instead; {@link useQueue} subscribes to both.
172
- * @param callback - Called with the updated queue
197
+ * Called when tracks are added, removed, or reordered. On iOS and Android a
198
+ * favorite toggle also fires it, alongside `onFavoriteChanged`. On web a
199
+ * favorite toggle fires only `onFavoriteChanged`. {@link useQueue} subscribes
200
+ * to both.
173
201
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
174
202
  */
175
203
  export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
@@ -32,6 +32,7 @@ export function setRepeatMode(repeatMode: RepeatMode) {
32
32
 
33
33
  // MARK: - Event Callbacks
34
34
 
35
+ /** Event data for when the repeat mode changes. */
35
36
  export interface RepeatModeChangedEvent {
36
37
  /** The new repeat mode */
37
38
  repeatMode: RepeatMode
@@ -39,7 +40,6 @@ export interface RepeatModeChangedEvent {
39
40
 
40
41
  /**
41
42
  * Subscribes to repeat mode changes.
42
- * @param callback - Called when repeat mode changes
43
43
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
44
44
  */
45
45
  export const onRepeatModeChanged =
@@ -31,7 +31,6 @@ export function toggleShuffle(): void {
31
31
 
32
32
  /**
33
33
  * Subscribes to shuffle mode changes.
34
- * @param callback - Called when shuffle mode changes
35
34
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
36
35
  */
37
36
  export const onShuffleChanged = NativeUpdatedValue.emitterize<boolean>(
@@ -20,7 +20,7 @@ export interface RemoteJumpForwardEvent {
20
20
  }
21
21
 
22
22
  /**
23
- * Remote play ID event (Android only).
23
+ * Payload of {@link onRemotePlayId}. No platform emits it.
24
24
  */
25
25
  export interface RemotePlayIdEvent {
26
26
  /** The ID of the track to play */
@@ -30,7 +30,7 @@ export interface RemotePlayIdEvent {
30
30
  }
31
31
 
32
32
  /**
33
- * Remote play search event (Android only).
33
+ * Payload of {@link onRemotePlaySearch}. No platform emits it.
34
34
  */
35
35
  export interface RemotePlaySearchEvent {
36
36
  /** The search query */
@@ -46,7 +46,7 @@ export interface RemoteSeekEvent {
46
46
  }
47
47
 
48
48
  /**
49
- * Remote skip event (Android only).
49
+ * Payload of {@link onRemoteSkip}. No platform emits it.
50
50
  */
51
51
  export interface RemoteSkipEvent {
52
52
  /** The index to skip to */
@@ -54,14 +54,13 @@ export interface RemoteSkipEvent {
54
54
  }
55
55
 
56
56
  // MARK: - Handler Override Functions
57
- //
58
- // Use these functions when you want to OVERRIDE the default remote control behavior.
59
- // These will replace the default handlers with your custom logic.
60
- // If you just want to listen to events for debugging/logging, use the onRemote* emitters below.
61
57
 
62
58
  /**
63
59
  * Sets a custom handler for remote play events, overriding the default behavior.
64
- * @param callback - Called when the user presses the play button. Pass undefined to disable.
60
+ * `onRemote*` listeners still fire.
61
+ *
62
+ * @param callback - Called when the user presses the play button. Pass
63
+ * `undefined` to restore the default behavior.
65
64
  */
66
65
  export function handleRemotePlay(callback: (() => void) | undefined) {
67
66
  nativeBrowser.handleRemotePlay = callback
@@ -69,7 +68,10 @@ export function handleRemotePlay(callback: (() => void) | undefined) {
69
68
 
70
69
  /**
71
70
  * Sets a custom handler for remote pause events, overriding the default behavior.
72
- * @param callback - Called when the user presses the pause button. Pass undefined to disable.
71
+ * `onRemote*` listeners still fire.
72
+ *
73
+ * @param callback - Called when the user presses the pause button. Pass
74
+ * `undefined` to restore the default behavior.
73
75
  */
74
76
  export function handleRemotePause(callback: (() => void) | undefined) {
75
77
  nativeBrowser.handleRemotePause = callback
@@ -77,7 +79,10 @@ export function handleRemotePause(callback: (() => void) | undefined) {
77
79
 
78
80
  /**
79
81
  * Sets a custom handler for remote next events, overriding the default behavior.
80
- * @param callback - Called when the user presses the next track button. Pass undefined to disable.
82
+ * `onRemote*` listeners still fire.
83
+ *
84
+ * @param callback - Called when the user presses the next track button. Pass
85
+ * `undefined` to restore the default behavior.
81
86
  */
82
87
  export function handleRemoteNext(callback: (() => void) | undefined) {
83
88
  nativeBrowser.handleRemoteNext = callback
@@ -85,7 +90,10 @@ export function handleRemoteNext(callback: (() => void) | undefined) {
85
90
 
86
91
  /**
87
92
  * Sets a custom handler for remote previous events, overriding the default behavior.
88
- * @param callback - Called when the user presses the previous track button. Pass undefined to disable.
93
+ * `onRemote*` listeners still fire.
94
+ *
95
+ * @param callback - Called when the user presses the previous track button. Pass
96
+ * `undefined` to restore the default behavior.
89
97
  */
90
98
  export function handleRemotePrevious(callback: (() => void) | undefined) {
91
99
  nativeBrowser.handleRemotePrevious = callback
@@ -93,7 +101,10 @@ export function handleRemotePrevious(callback: (() => void) | undefined) {
93
101
 
94
102
  /**
95
103
  * Sets a custom handler for remote stop events, overriding the default behavior.
96
- * @param callback - Called when the user presses the stop button. Pass undefined to disable.
104
+ * `onRemote*` listeners still fire.
105
+ *
106
+ * @param callback - Called when the user presses the stop button. Pass
107
+ * `undefined` to restore the default behavior.
97
108
  */
98
109
  export function handleRemoteStop(callback: (() => void) | undefined) {
99
110
  nativeBrowser.handleRemoteStop = callback
@@ -101,7 +112,10 @@ export function handleRemoteStop(callback: (() => void) | undefined) {
101
112
 
102
113
  /**
103
114
  * Sets a custom handler for remote seek events, overriding the default behavior.
104
- * @param callback - Called when the user changes the position of the timeline. Pass undefined to disable.
115
+ * `onRemote*` listeners still fire.
116
+ *
117
+ * @param callback - Called when the user changes the position of the timeline. Pass
118
+ * `undefined` to restore the default behavior.
105
119
  */
106
120
  export function handleRemoteSeek(
107
121
  callback: ((event: RemoteSeekEvent) => void) | undefined
@@ -111,7 +125,10 @@ export function handleRemoteSeek(
111
125
 
112
126
  /**
113
127
  * Sets a custom handler for remote jump forward events, overriding the default behavior.
114
- * @param callback - Called when the user presses the jump forward button. Pass undefined to disable.
128
+ * `onRemote*` listeners still fire.
129
+ *
130
+ * @param callback - Called when the user presses the jump forward button. Pass
131
+ * `undefined` to restore the default behavior.
115
132
  */
116
133
  export function handleRemoteJumpForward(
117
134
  callback: ((event: RemoteJumpForwardEvent) => void) | undefined
@@ -121,7 +138,10 @@ export function handleRemoteJumpForward(
121
138
 
122
139
  /**
123
140
  * Sets a custom handler for remote jump backward events, overriding the default behavior.
124
- * @param callback - Called when the user presses the jump backward button. Pass undefined to disable.
141
+ * `onRemote*` listeners still fire.
142
+ *
143
+ * @param callback - Called when the user presses the jump backward button. Pass
144
+ * `undefined` to restore the default behavior.
125
145
  */
126
146
  export function handleRemoteJumpBackward(
127
147
  callback: ((event: RemoteJumpBackwardEvent) => void) | undefined
@@ -129,16 +149,12 @@ export function handleRemoteJumpBackward(
129
149
  nativeBrowser.handleRemoteJumpBackward = callback
130
150
  }
131
151
 
132
- // MARK: - Event Callbacks (for listening/debugging only)
133
- //
134
- // Use these emitters when you want to LISTEN to remote control events without overriding
135
- // the default behavior. These are perfect for logging, analytics, or debugging.
136
- // Multiple listeners can be registered for the same event.
137
- // To override the default behavior, use the handleRemote* functions above.
152
+ // MARK: - Event Callbacks
138
153
 
139
154
  /**
140
155
  * Subscribes to remote jump backward events.
141
- * @param callback - Called when the user presses the jump backward button
156
+ * Fires when the user presses the jump backward button, including when a
157
+ * `handleRemoteJumpBackward` override is set.
142
158
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
143
159
  */
144
160
  export const onRemoteJumpBackward =
@@ -148,7 +164,8 @@ export const onRemoteJumpBackward =
148
164
 
149
165
  /**
150
166
  * Subscribes to remote jump forward events.
151
- * @param callback - Called when the user presses the jump forward button
167
+ * Fires when the user presses the jump forward button, including when a
168
+ * `handleRemoteJumpForward` override is set.
152
169
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
153
170
  */
154
171
  export const onRemoteJumpForward =
@@ -158,7 +175,8 @@ export const onRemoteJumpForward =
158
175
 
159
176
  /**
160
177
  * Subscribes to remote next events.
161
- * @param callback - Called when the user presses the next track button
178
+ * Fires when the user presses the next track button, including when a
179
+ * `handleRemoteNext` override is set.
162
180
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
163
181
  */
164
182
  export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
@@ -167,7 +185,8 @@ export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
167
185
 
168
186
  /**
169
187
  * Subscribes to remote pause events.
170
- * @param callback - Called when the user presses the pause button
188
+ * Fires when the user presses the pause button, including when a
189
+ * `handleRemotePause` override is set.
171
190
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
172
191
  */
173
192
  export const onRemotePause = LazyNativeEmitter.emitterize<void>(
@@ -176,7 +195,8 @@ export const onRemotePause = LazyNativeEmitter.emitterize<void>(
176
195
 
177
196
  /**
178
197
  * Subscribes to remote play events.
179
- * @param callback - Called when the user presses the play button
198
+ * Fires when the user presses the play button, including when a
199
+ * `handleRemotePlay` override is set.
180
200
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
181
201
  */
182
202
  export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
@@ -184,8 +204,8 @@ export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
184
204
  )
185
205
 
186
206
  /**
187
- * Subscribes to remote play ID events (Android only).
188
- * @param callback - Called when the user selects a track from an external device
207
+ * Subscribes to remote play ID events. Never fires: no platform (iOS,
208
+ * Android or web) emits them yet.
189
209
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
190
210
  */
191
211
  export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
@@ -193,8 +213,9 @@ export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
193
213
  )
194
214
 
195
215
  /**
196
- * Subscribes to remote play search events (Android only).
197
- * @param callback - Called when the user searches for a track (usually voice search)
216
+ * Subscribes to remote play search events. Never fires: no platform (iOS,
217
+ * Android or web) emits them yet. Voice search goes through the `search`
218
+ * source passed to `configureBrowser`.
198
219
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
199
220
  */
200
221
  export const onRemotePlaySearch =
@@ -204,7 +225,8 @@ export const onRemotePlaySearch =
204
225
 
205
226
  /**
206
227
  * Subscribes to remote previous events.
207
- * @param callback - Called when the user presses the previous track button
228
+ * Fires when the user presses the previous track button, including when a
229
+ * `handleRemotePrevious` override is set.
208
230
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
209
231
  */
210
232
  export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
@@ -213,7 +235,8 @@ export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
213
235
 
214
236
  /**
215
237
  * Subscribes to remote seek events.
216
- * @param callback - Called when the user changes the position of the timeline
238
+ * Fires when the user changes the position of the timeline, including when a
239
+ * `handleRemoteSeek` override is set.
217
240
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
218
241
  */
219
242
  export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
@@ -221,8 +244,8 @@ export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
221
244
  )
222
245
 
223
246
  /**
224
- * Subscribes to remote skip events (Android only).
225
- * @param callback - Called when the user presses the skip button
247
+ * Subscribes to remote skip events. Never fires: no platform (iOS, Android
248
+ * or web) emits them yet.
226
249
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
227
250
  */
228
251
  export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
@@ -231,7 +254,8 @@ export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
231
254
 
232
255
  /**
233
256
  * Subscribes to remote stop events.
234
- * @param callback - Called when the user presses the stop button
257
+ * Fires when the user presses the stop button, including when a
258
+ * `handleRemoteStop` override is set.
235
259
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
236
260
  */
237
261
  export const onRemoteStop = LazyNativeEmitter.emitterize<void>(
@@ -5,15 +5,15 @@ import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
5
5
  // MARK: - Types
6
6
 
7
7
  /**
8
- * Time-based sleep timer that stops playback after a specific time.
8
+ * Time-based sleep timer that pauses playback after a specific time.
9
9
  */
10
10
  export type SleepTimerTime = {
11
- /** Time when playback should stop (milliseconds since epoch) */
11
+ /** Time when playback should pause (milliseconds since epoch) */
12
12
  time: number
13
13
  }
14
14
 
15
15
  /**
16
- * End-of-track sleep timer that stops playback when current track finishes.
16
+ * End-of-track sleep timer that pauses playback when current track finishes.
17
17
  */
18
18
  export type SleepTimerEndOfTrack = {
19
19
  /** Whether to sleep when current track finishes playing */
@@ -22,12 +22,16 @@ export type SleepTimerEndOfTrack = {
22
22
 
23
23
  /**
24
24
  * Sleep timer configuration:
25
- * - `SleepTimerTime`: Stop playback after a specific time
26
- * - `SleepTimerEndOfTrack`: Stop playback after current track finishes
25
+ * - `SleepTimerTime`: Pause playback after a specific time
26
+ * - `SleepTimerEndOfTrack`: Pause playback after current track finishes
27
27
  * - `null`: No sleep timer active
28
28
  */
29
29
  export type SleepTimer = SleepTimerTime | SleepTimerEndOfTrack | null
30
30
 
31
+ /**
32
+ * Payload of `onSleepTimerChanged`: the new timer, or `null` once it is
33
+ * cleared or has fired.
34
+ */
31
35
  export type SleepTimerChangedEvent = SleepTimer
32
36
 
33
37
  // MARK: - Getters and Setters
@@ -67,7 +71,12 @@ export function setSleepTimer(
67
71
  }
68
72
 
69
73
  /**
70
- * Sets a sleep timer to stop playback when the current track finishes playing.
74
+ * Sets a sleep timer to pause playback when the current track finishes playing.
75
+ * A live stream never ends, so on one this timer never fires; use
76
+ * `setSleepTimer` instead. On iOS a change of current track before it ends
77
+ * (skip, new queue) cancels the timer. On Android and web it stays set until a
78
+ * track plays to its end. On Android it never fires while the repeat mode is
79
+ * `track`.
71
80
  */
72
81
  export function setSleepTimerToEndOfTrack(): void {
73
82
  nativeBrowser.setSleepTimerToEndOfTrack()
@@ -85,7 +94,6 @@ export function clearSleepTimer(): boolean {
85
94
 
86
95
  /**
87
96
  * Subscribes to sleep timer changes.
88
- * @param callback - Called when the sleep timer state changes
89
97
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
90
98
  */
91
99
  export const onSleepTimerChanged = NativeUpdatedValue.emitterize<SleepTimer>(