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
@@ -9,9 +9,10 @@ export type { FormattedNavigationError } from '../types/browser'
9
9
  /**
10
10
  * Normalized, cross-platform classification of a playback failure.
11
11
  *
12
- * Both platforms map their native failure onto this set, so consumers can
13
- * branch on it without knowing whether the error came from AVFoundation or
14
- * ExoPlayer. Use this — not `code` — for anything user-visible.
12
+ * Every platform (AVFoundation on iOS, ExoPlayer on Android, Shaka on web)
13
+ * maps its native failure onto this set, so consumers can branch on it without
14
+ * knowing where the error came from. Use this — not `code` — for anything
15
+ * user-visible.
15
16
  *
16
17
  * - `'offline'` - The device had no network connection at the moment of
17
18
  * failure. The stream itself may be fine.
@@ -19,11 +20,14 @@ export type { FormattedNavigationError } from '../types/browser'
19
20
  * connection refused, timed out, or the connection dropped while loading.
20
21
  * - `'not-found'` - The server said this stream is gone (HTTP 404 / 410).
21
22
  * Retrying will not help; the station is dead.
22
- * - `'rejected'` - The server refused the request (HTTP 401 / 403), e.g.
23
- * geo-blocking or an expired token.
23
+ * - `'rejected'` - The server refused the request: any HTTP 4xx other than
24
+ * 404 / 410 (auth, geo-blocking, rate limiting), a DRM or licence refusal
25
+ * (Android and web), or a region, account or parental-control refusal
26
+ * (Android).
24
27
  * - `'server-error'` - The server responded with 5xx. Usually transient.
25
- * - `'unplayable'` - The stream was fetched but cannot be played: unknown
26
- * container, unsupported codec, or a decoder failure.
28
+ * - `'unplayable'` - The stream cannot be played: an invalid source URL, a
29
+ * blocked cleartext URL (Android), an unknown container, an unsupported
30
+ * codec, or a decoder failure.
27
31
  * - `'stalled'` - Playback had started and then stopped, and the player
28
32
  * exhausted its recovery budget without recovering.
29
33
  * - `'unknown'` - The failure could not be classified. Inspect `code`.
@@ -38,6 +42,7 @@ export type PlaybackErrorKind =
38
42
  | 'stalled'
39
43
  | 'unknown'
40
44
 
45
+ /** A classified playback failure: branch on `kind`, log `code`. */
41
46
  export type PlaybackError = {
42
47
  /** Normalized classification. Branch on this, not on `code`. */
43
48
  kind: PlaybackErrorKind
@@ -45,9 +50,11 @@ export type PlaybackError = {
45
50
  * The raw native failure identifier, for diagnostics and telemetry only.
46
51
  * Platform-specific and unstable: loader cases on iOS
47
52
  * (`failed-to-load`, `playback-failed`, …), lower-cased ExoPlayer error
48
- * names on Android (`io-bad-http-status`, `parsing-container-malformed`, …).
53
+ * names on Android (`io-bad-http-status`, `parsing-container-malformed`, …),
54
+ * Shaka error codes as strings on web.
49
55
  */
50
56
  code: string
57
+ /** A diagnostic description, not copy for the user. */
51
58
  message: string
52
59
  /** HTTP status code, when the failure came from an HTTP response. */
53
60
  statusCode?: number
@@ -90,9 +97,11 @@ export interface PlaybackErrorEvent {
90
97
  * Use this for business logic errors like authentication failures or subscription requirements.
91
98
  * - `'unknown-error'` - An unexpected error occurred (e.g., invalid configuration).
92
99
  * - `'empty-content'` - The path resolved successfully but the container has no children (e.g. an
93
- * empty Favorites tab, a search with no results).
100
+ * empty Favorites tab, a search with no results). Reaches only the `formatNavigationError`
101
+ * callback, for car-surface copy, never `useNavigationError`.
94
102
  * - `'timeout'` - The resolve did not complete within the allotted time (a stalled request or
95
- * unresponsive bridge). Surfaced on External surfaces that render their own browse list.
103
+ * unresponsive bridge). CarPlay only, and like `'empty-content'` it reaches only the
104
+ * `formatNavigationError` callback, never `useNavigationError`.
96
105
  */
97
106
  export type NavigationErrorType =
98
107
  | 'content-not-found'
@@ -103,8 +112,10 @@ export type NavigationErrorType =
103
112
  | 'empty-content'
104
113
  | 'timeout'
105
114
 
115
+ /** A failed browse or search resolve. */
106
116
  export type NavigationError = {
107
117
  code: NavigationErrorType
118
+ /** A diagnostic description, not copy for the user. */
108
119
  message: string
109
120
  /** HTTP status code when code is 'http-error' */
110
121
  statusCode?: number
@@ -132,9 +143,9 @@ export function getPlaybackError(): PlaybackError | undefined {
132
143
  // MARK: - Event Callbacks
133
144
 
134
145
  /**
135
- * Subscribes to playback error events.
136
- * @param callback - Called when a playback error occurs
137
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
146
+ * Emits when the playback error is set or cleared (`error` is `undefined`
147
+ * when it clears). Subscribe with `addListener`, which returns the
148
+ * unsubscribe function.
138
149
  */
139
150
  export const onPlaybackError =
140
151
  NativeUpdatedValue.emitterize<PlaybackErrorEvent>(
@@ -163,9 +174,9 @@ export function getNavigationError(): NavigationError | undefined {
163
174
  }
164
175
 
165
176
  /**
166
- * Subscribes to navigation error events.
167
- * @param callback - Called when a navigation error occurs
168
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
177
+ * Emits when the navigation error is set or cleared (`error` is `undefined`
178
+ * when it clears). Subscribe with `addListener`, which returns the
179
+ * unsubscribe function.
169
180
  */
170
181
  export const onNavigationError =
171
182
  NativeUpdatedValue.emitterize<NavigationErrorEvent>(
@@ -196,9 +207,8 @@ export function getFormattedNavigationError():
196
207
  }
197
208
 
198
209
  /**
199
- * Subscribes to formatted navigation error changes.
200
- * @param callback - Called when the formatted navigation error changes
201
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
210
+ * Emits each time the formatted navigation error changes. Subscribe with
211
+ * `addListener`, which returns the unsubscribe function.
202
212
  */
203
213
  export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
204
214
  FormattedNavigationError | undefined
@@ -208,10 +218,15 @@ export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
208
218
  * Hook that returns the current navigation error formatted for display.
209
219
  *
210
220
  * Native formats the error using the `formatNavigationError` callback configured
211
- * in `BrowserConfiguration`, or falls back to default English messages.
221
+ * in `BrowserConfiguration`, or falls back to built-in English titles with the
222
+ * error's own message. An HTTP error's title is its status text,
223
+ * system-localized on iOS; on Android an English name for common codes. It is
224
+ * `Server Error` when there is no status code, for codes Android does not
225
+ * name, and always on web.
212
226
  *
213
- * The same formatted error is used by CarPlay and Android Auto error dialogs,
214
- * ensuring consistent error presentation across your app and external controllers.
227
+ * CarPlay and Android Auto format their own browse errors with the same
228
+ * `formatNavigationError` callback, so the copy matches across your app and
229
+ * the car.
215
230
  *
216
231
  * @returns Formatted error with title and message, or undefined if no error
217
232
  *
@@ -5,12 +5,12 @@ import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
5
5
  // MARK: - Setters
6
6
 
7
7
  /**
8
- * Sets the favorited state of the currently playing track.
9
- * Updates the heart icon in media controllers (notification, Android Auto).
8
+ * Sets the favorited state of the Active Track.
9
+ * Updates the heart icon in media controllers (notification, Android Auto, CarPlay).
10
10
  *
11
- * Use this for programmatic favorite changes (e.g., from a favorite button in your app).
12
- * For heart button taps from media controllers, use `onFavoriteChanged` instead -
13
- * the native side handles those automatically.
11
+ * Use this for favorite changes from your app, such as a favorite button.
12
+ * It emits `onFavoriteChanged`, so persist the change there, not again in your
13
+ * button handler.
14
14
  *
15
15
  * @param favorited - Whether the track is favorited
16
16
  *
@@ -24,7 +24,7 @@ export function setActiveTrackFavorited(favorited: boolean): void {
24
24
  }
25
25
 
26
26
  /**
27
- * Toggles the favorited state of the currently playing track.
27
+ * Toggles the favorited state of the Active Track. Emits `onFavoriteChanged`.
28
28
  *
29
29
  * @example
30
30
  * ```ts
@@ -69,8 +69,10 @@ export function setFavorites(favorites: string[]): void {
69
69
  // MARK: - Event Callbacks
70
70
 
71
71
  /**
72
- * Event data for when the favorite state of the active track changes.
73
- * Emitted when the user taps the heart button in a media controller (notification, Android Auto, CarPlay).
72
+ * Event data for when the favorite state of the Active Track changes.
73
+ * Emitted on every change: a heart tap in a media controller (notification,
74
+ * Android Auto, CarPlay), a Siri request (iOS), `setActiveTrackFavorited` or
75
+ * `toggleActiveTrackFavorited`.
74
76
  */
75
77
  export interface FavoriteChangedEvent {
76
78
  /** The track whose favorite state changed. */
@@ -80,11 +82,11 @@ export interface FavoriteChangedEvent {
80
82
  }
81
83
 
82
84
  /**
83
- * Subscribes to favorite state change events.
84
- * Called when the user taps the heart button in a media controller.
85
- * The native side has already updated the track's favorite state and UI.
86
- *
87
- * @param callback - Called with the track and its new favorite state
85
+ * Subscribes to favorite changes of the Active Track, with the track and its
86
+ * new favorite state. Fires on every change: a heart tap in a media controller,
87
+ * a Siri request (iOS), `setActiveTrackFavorited` or
88
+ * `toggleActiveTrackFavorited`. Persist favorites here, in one place. The
89
+ * native side has already updated the track's favorite state and UI.
88
90
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
89
91
  *
90
92
  * @example
@@ -39,19 +39,22 @@ export type GateEvent = { reason: GateReason }
39
39
  /**
40
40
  * A gate's chrome (title and optional message).
41
41
  *
42
- * While the gate is active, every browse or search request on car surfaces
43
- * (CarPlay, Android Auto) shows this page instead of the real content.
44
- * Playback, the queue, and now-playing are unaffected.
42
+ * While the gate is up, a gated browse or search on CarPlay or Android Auto
43
+ * shows this page instead of the content, and a gated voice search (Siri on
44
+ * iOS, Google Assistant on Android, including from the phone) is refused.
45
+ * Playback and the queue are unaffected.
45
46
  *
46
- * - **CarPlay**: plain centered message page.
47
- * - **Android Auto**: one non-playable list tile (message not shown).
47
+ * - **CarPlay**: plain centered message page. Now Playing keeps its transport
48
+ * controls but hides the `carPlayNowPlayingButtons`.
49
+ * - **Android Auto**: one non-playable list tile, with the title as its main
50
+ * line and the message as its subtitle.
48
51
  */
49
52
  export type Gate = {
50
53
  /** Headline shown on the gate page. */
51
54
  title: string
52
55
  /**
53
- * The explanatory copy under the title. On CarPlay this is the centered
54
- * message body; newlines become spaces. Android Auto does not display it.
56
+ * The explanatory copy under the title: the centered message body on
57
+ * CarPlay, the tile subtitle on Android Auto. Newlines become spaces on both.
55
58
  */
56
59
  message?: string
57
60
  }
@@ -76,6 +79,8 @@ export type GateRequest =
76
79
  * - Return a {@link Gate} to gate with specific chrome for this request.
77
80
  * - Return `true` to gate using the default chrome (or the built-in fallback).
78
81
  * - Return `false` to allow the request through.
82
+ * - If the resolver throws, the request is gated (fails closed): only `false`
83
+ * lets a request through.
79
84
  */
80
85
  export type GateResolver = (request: GateRequest) => Gate | boolean
81
86
 
@@ -147,7 +152,8 @@ export function setGate(a: Gate | GateResolver, b?: GateResolver): void {
147
152
  }
148
153
 
149
154
  /**
150
- * Drops the gate — the real content comes back, and the current tab is kept.
155
+ * Drops the gate — the real content comes back. Android Auto keeps the current
156
+ * tab; CarPlay rebuilds its tab bar on the first tab.
151
157
  *
152
158
  * @platform ios android
153
159
  * A no-op on web, where no gate was ever raised.
@@ -3,6 +3,7 @@ import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
3
3
 
4
4
  // MARK: - Types
5
5
 
6
+ /** The track fields {@link NowPlayingMetadata} carries. */
6
7
  export interface TrackMetadataBase {
7
8
  /** The track title */
8
9
  title?: string
@@ -16,20 +17,29 @@ export interface TrackMetadataBase {
16
17
  artwork?: string
17
18
  /** track description */
18
19
  description?: string
19
- /** track mediaId */
20
+ /**
21
+ * The track's `src`, or its `path` when it has none, on iOS and Android.
22
+ * On web, the track's Identity (`id` when set, else `src`), or its `path`:
23
+ * a track with an `id` reports different values on web and native.
24
+ */
20
25
  mediaId?: string
21
26
  /** The track genre */
22
27
  genre?: string
23
28
  }
24
29
 
25
30
  export interface NowPlayingMetadata extends TrackMetadataBase {
31
+ /**
32
+ * Playback position in seconds when this metadata was emitted or read, not
33
+ * a live value. iOS only; absent on Android and web. For a live position use
34
+ * `useProgress`.
35
+ */
26
36
  elapsedTime?: number
27
37
  }
28
38
 
29
39
  /**
30
40
  * Metadata update for the now playing notification.
31
- * Pass to `updateNowPlaying()` to override what's shown in the notification/lock screen.
32
- * Pass `null` to clear overrides and revert to track metadata.
41
+ * Pass to `updateNowPlaying()` to override what's shown in the
42
+ * notification/lock screen; pass it `null` to clear the override.
33
43
  */
34
44
  export type NowPlayingUpdate = {
35
45
  /** Title shown in notification */
@@ -45,8 +55,8 @@ export type NowPlayingUpdate = {
45
55
  }
46
56
 
47
57
  /**
48
- * Timed metadata received during playback.
49
- * Contains metadata from ICY streams (radio) or ID3 frames.
58
+ * Timed metadata received during playback: ICY (radio) or ID3 frames.
59
+ * On iOS, also a file's own tags, once on load, when the file has no chapters.
50
60
  */
51
61
  export interface TimedMetadata {
52
62
  title?: string
@@ -57,8 +67,9 @@ export interface TimedMetadata {
57
67
  }
58
68
 
59
69
  /**
60
- * Static track metadata from the media file.
61
- * Contains standardized metadata fields.
70
+ * Static track metadata. On iOS, the media file's own tags. On Android,
71
+ * Media3's merged metadata, where the Track's fields and the now-playing lines win over
72
+ * the file's tags. `compilation` and `url` are never set.
62
73
  */
63
74
  export interface TrackMetadata {
64
75
  title?: string
@@ -66,14 +77,24 @@ export interface TrackMetadata {
66
77
  albumTitle?: string
67
78
  subtitle?: string
68
79
  description?: string
80
+ /**
81
+ * Android only: the artwork URL published for the Track, not embedded
82
+ * cover art.
83
+ */
69
84
  artworkUri?: string
70
85
  trackNumber?: string
71
86
  composer?: string
72
87
  conductor?: string
73
88
  genre?: string
74
89
  compilation?: string
90
+ /** Android only: the station name from a Shoutcast / Icecast stream. */
75
91
  station?: string
92
+ /** Android only: a Media3 `MEDIA_TYPE_*` constant, as a number string. */
76
93
  mediaType?: string
94
+ /**
95
+ * iOS: the tag's date string. Android: day and month only, as `DDMM` (or
96
+ * `DD` or `MM`), no year.
97
+ */
77
98
  creationDate?: string
78
99
  creationYear?: string
79
100
  url?: string
@@ -88,9 +109,9 @@ export interface ChapterMetadata {
88
109
  startTime: number
89
110
  /** Chapter end time in seconds */
90
111
  endTime: number
91
- /** Chapter title */
112
+ /** Chapter title. Android falls back to the chapter's element ID. */
92
113
  title?: string
93
- /** URL associated with the chapter */
114
+ /** URL associated with the chapter. Android only. */
94
115
  url?: string
95
116
  }
96
117
 
@@ -103,7 +124,6 @@ export interface ChapterMetadata {
103
124
  * Never fires on web — the web player does not read chapter markers. See
104
125
  * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
105
126
  *
106
- * @param callback - Called when chapter metadata is received
107
127
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
108
128
  */
109
129
  export const onChapterMetadata = NativeUpdatedValue.emitterize<
@@ -111,13 +131,14 @@ export const onChapterMetadata = NativeUpdatedValue.emitterize<
111
131
  >((cb) => (nativeBrowser.onChapterMetadata = cb))
112
132
 
113
133
  /**
114
- * Subscribes to track metadata events.
134
+ * Subscribes to track metadata events. On iOS it fires once on load, when the
135
+ * file has tags. On Android it fires whenever the player's merged metadata
136
+ * changes.
115
137
  *
116
138
  * @platform ios android
117
139
  * Never fires on web — the web player does not read embedded file tags. See
118
140
  * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
119
141
  *
120
- * @param callback - Called when static track metadata is received
121
142
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
122
143
  */
123
144
  export const onTrackMetadata = NativeUpdatedValue.emitterize<TrackMetadata>(
@@ -125,15 +146,14 @@ export const onTrackMetadata = NativeUpdatedValue.emitterize<TrackMetadata>(
125
146
  )
126
147
 
127
148
  /**
128
- * Subscribes to timed metadata events (ICY/ID3 from live streams).
149
+ * Subscribes to timed metadata events (ICY/ID3 from live streams). On iOS it
150
+ * also fires on load with a file's own tags when the file has no chapters.
129
151
  *
130
152
  * @platform ios android
131
- * Never fires on web. ICY metadata is stripped by the browser before the player
132
- * can see it, and no browser API exposes it; in-band ID3 from HLS is reachable
133
- * but not yet wired. See
153
+ * Never fires on web: the browser strips ICY metadata before the player sees
154
+ * it, and the web player does not read in-band ID3 from HLS. See
134
155
  * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
135
156
  *
136
- * @param callback - Called when stream metadata is received (title, artist from ICY/ID3 tags)
137
157
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
138
158
  */
139
159
  export const onTimedMetadata = NativeUpdatedValue.emitterize<TimedMetadata>(
@@ -6,6 +6,8 @@ import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
6
6
 
7
7
  /**
8
8
  * Gets the current network connectivity state.
9
+ * On Android it reads `true` before `setupPlayer` has connected the player, and
10
+ * while its service restarts.
9
11
  * @returns true if the device is online, false otherwise
10
12
  */
11
13
  export function getOnline(): boolean {
@@ -16,7 +18,8 @@ export function getOnline(): boolean {
16
18
 
17
19
  /**
18
20
  * Subscribes to network connectivity changes.
19
- * @param callback - Called when network state changes
21
+ * On Android it fires nothing until `setupPlayer` has connected the player, and then
22
+ * fires once with the current state.
20
23
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
21
24
  */
22
25
  export const onOnlineChanged = NativeUpdatedValue.emitterize<boolean>(
@@ -27,6 +30,7 @@ export const onOnlineChanged = NativeUpdatedValue.emitterize<boolean>(
27
30
 
28
31
  /**
29
32
  * Hook that returns the current network connectivity state and updates when it changes.
33
+ * On Android it reads `true` until `setupPlayer` has connected the player.
30
34
  * @returns true if the device is online, false otherwise
31
35
  */
32
36
  export function useOnline(): boolean {
@@ -7,7 +7,11 @@ import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
7
7
 
8
8
  /**
9
9
  * Updates the now playing notification metadata.
10
- * Pass null/undefined to clear overrides and revert to track metadata.
10
+ *
11
+ * Lasts until you pass `null`, which clears it, or the active track changes. A `nowPlaying`
12
+ * formatter's fields win over it. With `nowPlaying: false` the iOS and
13
+ * Android surface ignores it, though `getNowPlaying` still reports it; web
14
+ * ignores `nowPlaying`.
11
15
  *
12
16
  * @example
13
17
  * ```ts
@@ -17,7 +21,7 @@ import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
17
21
  * artist: streamMetadata.artist,
18
22
  * })
19
23
  *
20
- * // Clear overrides, revert to track metadata
24
+ * // Clear the override
21
25
  * updateNowPlaying(null)
22
26
  * ```
23
27
  */
@@ -26,7 +30,10 @@ export function updateNowPlaying(update: NowPlayingUpdate | null): void {
26
30
  }
27
31
 
28
32
  /**
29
- * Gets the current now playing metadata (override if set, else track metadata).
33
+ * Returns what the now-playing surface shows: flash, formatter output,
34
+ * override or track fields, in that priority. `undefined` when there is no
35
+ * active track. With `nowPlaying: false`, it returns the flash, override or
36
+ * track fields, regardless of what the surface shows.
30
37
  */
31
38
  export function getNowPlaying(): NowPlayingMetadata | undefined {
32
39
  return nativeBrowser.getNowPlaying() ?? undefined
@@ -34,15 +41,19 @@ export function getNowPlaying(): NowPlayingMetadata | undefined {
34
41
 
35
42
  /**
36
43
  * Temporarily replaces now-playing fields for `durationMs`, then reverts to
37
- * the live metadata. The flash outranks the now-playing formatter and the
38
- * `updateNowPlaying` override while active (live metadata can't stomp it),
39
- * and the revert runs on a native timer — JS timers pause in a backgrounded
40
- * host (the lock screen case) — so it fires reliably. A track change clears
41
- * the flash early; repeated calls restart the window.
44
+ * the live metadata. While active it outranks the `nowPlaying` formatter
45
+ * ({@link features/player!FormatNowPlayingCallback | FormatNowPlayingCallback}) and the `updateNowPlaying` override.
46
+ * The revert runs on a native timer, so it fires while the app is
47
+ * backgrounded. A track change clears the flash early; repeated calls
48
+ * restart the window.
49
+ *
50
+ * On web the flash is a plain `updateNowPlaying` override on a JS timer. It
51
+ * replaces any override you set, the revert clears the override instead of
52
+ * restoring it, and a track change does not cancel the timer, so the revert
53
+ * can also clear an override set for the next track. With
54
+ * `nowPlaying: false`, Android ignores the flash; iOS still shows it.
42
55
  *
43
- * The feedback channel for refused remote commands: external surfaces have
44
- * no toast primitive, so a transient metadata swap is the only way to talk
45
- * to the user there.
56
+ * See the [Now playing guide](https://audiobrowser.dev/guide/now-playing#the-flash-transient-top-priority).
46
57
  *
47
58
  * @example
48
59
  * ```ts
@@ -62,7 +73,8 @@ export function flashNowPlaying(
62
73
 
63
74
  /**
64
75
  * Clears an active flash immediately, reverting to the live metadata.
65
- * No-op when no flash is active.
76
+ * No-op when no flash is active. On web it also clears the
77
+ * `updateNowPlaying` override.
66
78
  */
67
79
  export function clearNowPlayingFlash(): void {
68
80
  nativeBrowser.clearNowPlayingFlash()
@@ -72,8 +84,10 @@ export function clearNowPlayingFlash(): void {
72
84
 
73
85
  /**
74
86
  * Subscribes to now playing metadata change events.
75
- * Fires when updateNowPlaying is called or when the track changes.
76
- * @param callback - Called when now playing metadata changes
87
+ * Fires when the now-playing lines change: track change, `updateNowPlaying`,
88
+ * a flash starting or ending, or a new formatter result. On iOS and
89
+ * Android, an update that leaves the lines unchanged does not fire; on web
90
+ * every `updateNowPlaying` call, flash start and revert fires.
77
91
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
78
92
  */
79
93
  export const onNowPlayingChanged =
@@ -33,9 +33,11 @@ export function supportsOutputSwitcher(): boolean {
33
33
 
34
34
  /**
35
35
  * The current audio output, or `undefined` when unknown. iOS reports one while a
36
- * session is active; Android reports the active output route via AudioManager
37
- * (the `type` is coarse — e.g. wired headphones may report as `speaker`), or the
38
- * remote output selected in the Output Switcher when `remoteOutputs` is on.
36
+ * session is active. Android reports the device media is routed to, from
37
+ * AudioManager, or the remote output selected in the Output Switcher when
38
+ * `remoteOutputs` is on. On Android 13+ (API 33) the route is exact and follows
39
+ * manual reroutes. Below that it is picked from the connected devices and misses
40
+ * a reroute while a device stays connected.
39
41
  * Guard for `undefined`.
40
42
  */
41
43
  export function getOutput(): Output | undefined {
@@ -46,7 +48,9 @@ export function getOutput(): Output | undefined {
46
48
 
47
49
  /**
48
50
  * Subscribes to current-output changes (headphones unplugged, Bluetooth speaker
49
- * connected, AirPlay/route selected). Fires on iOS and Android 11+; never below.
51
+ * connected, AirPlay/route selected). Fires on iOS and Android; never on web.
52
+ * On Android below 13 it cannot see a manual reroute between two connected
53
+ * devices.
50
54
  * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
51
55
  */
52
56
  export const onOutputChanged = NativeUpdatedValue.emitterize<Output>(
@@ -31,16 +31,20 @@ export function togglePlayback(): void {
31
31
  }
32
32
 
33
33
  /**
34
- * Stops playback and resets position to the beginning.
35
- * The track remains loaded and can be resumed with play().
36
- * For live streams, position is not reset.
34
+ * Stops playback. The track stays current, and play() starts it again.
35
+ * iOS rewinds a non-live track to the start; Android and web keep the
36
+ * position, so play() resumes where it stopped.
37
37
  */
38
38
  export function stop(): void {
39
39
  nativeBrowser.stop()
40
40
  }
41
41
 
42
42
  /**
43
- * Retries playing the current item when the playback state is `'error'`.
43
+ * Retries playing the current item. Meant for the `'error'` state, but not
44
+ * gated on it: on iOS it reloads the current item in any state, even while
45
+ * playing. On Android and web it reloads whenever the player is stopped or
46
+ * failed, without setting the play intent, so after stop() it loads the item
47
+ * but does not play it.
44
48
  *
45
49
  * @see {@link PlaybackState}
46
50
  * @see {@link usePlayback}
@@ -61,7 +65,8 @@ export function seekTo(position: number): void {
61
65
  * Jump to the live edge of the current track; no-op unless the track
62
66
  * declares `live: true`. A stream with a seekable live window (HLS) seeks
63
67
  * to the window's edge; a non-seekable stream (e.g. ICY radio) reconnects
64
- * to rejoin live — an expired URL re-resolves through `media.resolve`.
68
+ * to rejoin live. iOS re-runs `media.resolve` on the reconnect; Android
69
+ * reuses the resolved URL and re-resolves only after it fails to open.
65
70
  */
66
71
  export function seekToLiveEdge(): void {
67
72
  nativeBrowser.seekToLiveEdge()
@@ -23,8 +23,9 @@ export function getPlayWhenReady(): boolean {
23
23
 
24
24
  /**
25
25
  * Sets whether the player will play automatically when it is ready to do so.
26
- * This is the equivalent of calling `play()` when `playWhenReady = true`
27
- * or `pause()` when `playWhenReady = false`.
26
+ * Before setupPlayer resolves, the value is kept and applied at setup, while
27
+ * play() is dropped on iOS and Android. On Android, `true` does not restart a
28
+ * stopped or failed player; call play() or retry() for that.
28
29
  */
29
30
  export function setPlayWhenReady(playWhenReady: boolean): void {
30
31
  nativeBrowser.setPlayWhenReady(playWhenReady)
@@ -33,9 +34,9 @@ export function setPlayWhenReady(playWhenReady: boolean): void {
33
34
  // MARK: - Event Callbacks
34
35
 
35
36
  /**
36
- * Subscribes to play when ready changes.
37
- * @param callback - Called when playWhenReady changes
38
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
37
+ * Emits each time `playWhenReady` changes. Subscribe with
38
+ * `onPlayWhenReadyChanged.addListener(cb)`, which returns an unsubscribe
39
+ * function.
39
40
  */
40
41
  export const onPlayWhenReadyChanged =
41
42
  NativeUpdatedValue.emitterize<PlaybackPlayWhenReadyChangedEvent>(
@@ -4,8 +4,21 @@ import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
4
4
 
5
5
  // MARK: - Types
6
6
 
7
+ /** Whether the player is playing, and whether it is buffering while it does. */
7
8
  export type PlayingState = {
9
+ /**
10
+ * True while the player intends to play and can: `playWhenReady` is set and
11
+ * the state is not `'none'`, `'stopped'`, `'ended'` or `'error'`. Also true
12
+ * while loading or buffering, so it does not mean sound is audible. On
13
+ * Android, also false while a transient audio-focus loss holds output back,
14
+ * though `playWhenReady` stays true.
15
+ */
8
16
  playing: boolean
17
+ /**
18
+ * True while the player intends to play and the state is `'loading'` or
19
+ * `'buffering'`. On Android, also false while a transient audio-focus loss
20
+ * holds output back, though `playWhenReady` stays true.
21
+ */
9
22
  buffering: boolean
10
23
  }
11
24
 
@@ -21,9 +34,9 @@ export function getPlayingState(): PlayingState {
21
34
  // MARK: - Event Callbacks
22
35
 
23
36
  /**
24
- * Subscribes to playing state changes.
25
- * @param callback - Called when playing or buffering state changes
26
- * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
37
+ * Emits the {@link PlayingState} each time `playing` or `buffering` changes.
38
+ * Subscribe with `onPlayingState.addListener(cb)`, which returns an
39
+ * unsubscribe function.
27
40
  */
28
41
  export const onPlayingState = NativeUpdatedValue.emitterize<PlayingState>(
29
42
  (cb) => (nativeBrowser.onPlaybackPlayingState = cb)