react-native-audio-browser 0.2.0-next.50 → 0.2.0-next.51

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 (90) hide show
  1. package/android/build.gradle +15 -0
  2. package/android/src/cast/java/com/audiobrowser/cast/CastSupport.kt +215 -0
  3. package/android/src/main/AndroidManifest.xml +11 -0
  4. package/android/src/main/java/com/audiobrowser/AudioBrowser.kt +0 -4
  5. package/android/src/main/java/com/audiobrowser/RemoteOutputs.kt +47 -10
  6. package/android/src/main/java/com/audiobrowser/model/PlayerSetupOptions.kt +12 -3
  7. package/android/src/main/java/com/audiobrowser/player/EqualizerController.kt +4 -1
  8. package/android/src/main/java/com/audiobrowser/player/LocalEngine.kt +49 -0
  9. package/android/src/main/java/com/audiobrowser/player/Player.kt +170 -119
  10. package/android/src/main/java/com/audiobrowser/player/PlayerListener.kt +18 -13
  11. package/android/src/main/java/com/audiobrowser/player/TransformingDataSource.kt +10 -13
  12. package/android/src/main/java/com/audiobrowser/remote/RemoteItem.kt +64 -0
  13. package/android/src/main/java/com/audiobrowser/remote/RemoteOutputsController.kt +98 -0
  14. package/android/src/main/java/com/audiobrowser/remote/RemotePlayback.kt +42 -0
  15. package/android/src/main/java/com/audiobrowser/remote/RemoteQueue.kt +110 -0
  16. package/android/src/main/java/com/audiobrowser/remote/RemoteSwitchingPlayer.kt +696 -0
  17. package/android/src/main/java/com/audiobrowser/sonos/DeviceDescriptionParser.kt +113 -0
  18. package/android/src/main/java/com/audiobrowser/sonos/DidlLite.kt +39 -0
  19. package/android/src/main/java/com/audiobrowser/sonos/SoapClient.kt +59 -0
  20. package/android/src/main/java/com/audiobrowser/sonos/SoapEnvelopes.kt +92 -0
  21. package/android/src/main/java/com/audiobrowser/sonos/SoapResponseParser.kt +105 -0
  22. package/android/src/main/java/com/audiobrowser/sonos/SonosDiscoverer.kt +69 -0
  23. package/android/src/main/java/com/audiobrowser/sonos/SonosOutputs.kt +128 -0
  24. package/android/src/main/java/com/audiobrowser/sonos/SonosPlayer.kt +550 -0
  25. package/android/src/main/java/com/audiobrowser/sonos/SonosRemote.kt +99 -0
  26. package/android/src/main/java/com/audiobrowser/sonos/SonosRouteProviderService.kt +201 -0
  27. package/android/src/main/java/com/audiobrowser/sonos/SonosStreamUri.kt +15 -0
  28. package/android/src/main/java/com/audiobrowser/sonos/SonosTransport.kt +66 -0
  29. package/android/src/main/java/com/audiobrowser/sonos/SpeakerXml.kt +26 -0
  30. package/android/src/main/java/com/audiobrowser/sonos/SsdpDiscovery.kt +63 -0
  31. package/android/src/main/java/com/audiobrowser/sonos/SsdpMessages.kt +63 -0
  32. package/android/src/main/java/com/audiobrowser/sonos/ZoneGroupState.kt +68 -0
  33. package/android/src/main/java/com/audiobrowser/util/OutputMonitor.kt +2 -1
  34. package/android/src/nocast/java/com/audiobrowser/cast/CastSupport.kt +18 -0
  35. package/android/src/test/java/com/audiobrowser/RemoteOutputsTest.kt +20 -3
  36. package/android/src/test/java/com/audiobrowser/model/PlayerSetupOptionsTest.kt +35 -0
  37. package/android/src/test/java/com/audiobrowser/player/EqualizerControllerTest.kt +12 -0
  38. package/android/src/test/java/com/audiobrowser/player/PlayerCastTest.kt +136 -0
  39. package/android/src/test/java/com/audiobrowser/player/PlayerSonosTest.kt +213 -0
  40. package/android/src/test/java/com/audiobrowser/remote/FakeRemote.kt +275 -0
  41. package/android/src/test/java/com/audiobrowser/remote/RemoteItemTest.kt +61 -0
  42. package/android/src/test/java/com/audiobrowser/remote/RemoteOutputsControllerTest.kt +77 -0
  43. package/android/src/test/java/com/audiobrowser/remote/RemoteQueueTest.kt +101 -0
  44. package/android/src/test/java/com/audiobrowser/remote/RemoteSwitchingPlayerTest.kt +815 -0
  45. package/android/src/test/java/com/audiobrowser/sonos/DeviceDescriptionParserTest.kt +203 -0
  46. package/android/src/test/java/com/audiobrowser/sonos/DidlLiteTest.kt +90 -0
  47. package/android/src/test/java/com/audiobrowser/sonos/SoapClientTest.kt +73 -0
  48. package/android/src/test/java/com/audiobrowser/sonos/SoapEnvelopesTest.kt +135 -0
  49. package/android/src/test/java/com/audiobrowser/sonos/SoapResponseParserTest.kt +170 -0
  50. package/android/src/test/java/com/audiobrowser/sonos/SonosDiscovererTest.kt +174 -0
  51. package/android/src/test/java/com/audiobrowser/sonos/SonosPlayerTest.kt +691 -0
  52. package/android/src/test/java/com/audiobrowser/sonos/SonosRemoteTest.kt +129 -0
  53. package/android/src/test/java/com/audiobrowser/sonos/SonosRoutesTest.kt +165 -0
  54. package/android/src/test/java/com/audiobrowser/sonos/SonosStreamUriTest.kt +64 -0
  55. package/android/src/test/java/com/audiobrowser/sonos/SonosTransportTest.kt +204 -0
  56. package/android/src/test/java/com/audiobrowser/sonos/SsdpMessagesTest.kt +99 -0
  57. package/android/src/test/java/com/audiobrowser/sonos/ZoneGroupStateTest.kt +139 -0
  58. package/android/src/test/java/com/audiobrowser/util/OutputMonitorTest.kt +12 -10
  59. package/android/src/test/resources/sonos/device_description.xml +78 -0
  60. package/android/src/testCast/java/com/audiobrowser/cast/CastEndsTest.kt +56 -0
  61. package/android/src/testCast/java/com/audiobrowser/cast/SendingMediaItemConverterTest.kt +79 -0
  62. package/lib/commonjs/features/player/setup.js +2 -0
  63. package/lib/commonjs/features/player/setup.js.map +1 -1
  64. package/lib/module/features/player/setup.js +2 -0
  65. package/lib/module/features/player/setup.js.map +1 -1
  66. package/lib/typescript/src/features/player/setup.d.ts +37 -7
  67. package/lib/typescript/src/features/player/setup.d.ts.map +1 -1
  68. package/lib/typescript/src/specs/audio-browser.nitro.d.ts +3 -3
  69. package/lib/typescript/src/specs/audio-browser.nitro.d.ts.map +1 -1
  70. package/nitrogen/generated/android/c++/JHybridAudioBrowserSpec.cpp +4 -0
  71. package/nitrogen/generated/android/c++/JNativeSetupPlayerOptions.hpp +7 -5
  72. package/nitrogen/generated/android/c++/JOutputType.hpp +3 -0
  73. package/nitrogen/generated/android/c++/JRemoteOutputsOptions.hpp +66 -0
  74. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/NativeSetupPlayerOptions.kt +3 -3
  75. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/OutputType.kt +3 -2
  76. package/nitrogen/generated/android/kotlin/com/margelo/nitro/audiobrowser/RemoteOutputsOptions.kt +61 -0
  77. package/nitrogen/generated/ios/AudioBrowser-Swift-Cxx-Bridge.hpp +18 -0
  78. package/nitrogen/generated/ios/AudioBrowser-Swift-Cxx-Umbrella.hpp +3 -0
  79. package/nitrogen/generated/ios/c++/HybridAudioBrowserSpecSwift.hpp +3 -0
  80. package/nitrogen/generated/ios/swift/NativeSetupPlayerOptions.swift +5 -12
  81. package/nitrogen/generated/ios/swift/OutputType.swift +4 -0
  82. package/nitrogen/generated/ios/swift/RemoteOutputsOptions.swift +78 -0
  83. package/nitrogen/generated/shared/c++/NativeSetupPlayerOptions.hpp +8 -5
  84. package/nitrogen/generated/shared/c++/OutputType.hpp +6 -2
  85. package/nitrogen/generated/shared/c++/RemoteOutputsOptions.hpp +92 -0
  86. package/package.json +1 -1
  87. package/src/features/player/setup.ts +38 -7
  88. package/src/specs/audio-browser.nitro.ts +4 -3
  89. package/website/guide/audio-output.md +185 -4
  90. package/website/guide/configuration.md +6 -0
@@ -69,8 +69,8 @@ export type EqualizerSettings = {
69
69
  /**
70
70
  * Cross-platform audio output kind. Each platform maps its native ports into
71
71
  * this shared set: iOS's granular Bluetooth ports (`bluetoothA2DP`/`HFP`/`LE`)
72
- * all collapse to `'bluetooth'`. `'airplay'` comes from iOS only, `'remote'`
73
- * from Android only (with `remoteOutputs` on), and `'cast'` is reserved.
72
+ * all collapse to `'bluetooth'`. `'airplay'` comes from iOS only, `'remote'`,
73
+ * `'cast'` and `'sonos'` from Android only (with `remoteOutputs` on).
74
74
  */
75
75
  export type OutputType =
76
76
  | 'speaker' // built-in loudspeaker
@@ -81,7 +81,8 @@ export type OutputType =
81
81
  | 'car' // car audio (CarPlay / Android Auto / car Bluetooth)
82
82
  | 'hdmi'
83
83
  | 'usb'
84
- | 'cast' // Cast device (reserved)
84
+ | 'cast' // Cast device, playing through the library's Cast support (Android)
85
+ | 'sonos' // Sonos room, playing through the library's Sonos support (Android)
85
86
  | 'remote' // a media route provider's speaker or TV, selected in the Output Switcher (Android)
86
87
  | 'other'
87
88
 
@@ -51,8 +51,8 @@ An [`Output`](/api/features/output/#output) is:
51
51
  | `external` | `boolean` | `false` only for the built-in speaker/receiver; `true` for everything external. |
52
52
 
53
53
  `type` is one of `'speaker'`, `'receiver'` (the iOS earpiece), `'headphones'`,
54
- `'bluetooth'`, `'airplay'`, `'car'`, `'hdmi'`, `'usb'`, `'cast'` (reserved),
55
- `'remote'` (a remote speaker or TV, see below), or `'other'`. Both platforms map their native ports/routes into
54
+ `'bluetooth'`, `'airplay'`, `'car'`, `'hdmi'`, `'usb'`, `'cast'` and `'sonos'`
55
+ (see below), `'remote'` (a remote speaker or TV, see below), or `'other'`. Both platforms map their native ports/routes into
56
56
  this shared set — e.g. iOS's separate Bluetooth ports all collapse to
57
57
  `'bluetooth'`.
58
58
 
@@ -64,7 +64,7 @@ is reliably distinguished from it. The device **name** still comes through.
64
64
 
65
65
  ### Remote outputs (Android)
66
66
 
67
- With `remoteOutputs: true` in [`setupPlayer`](/guide/configuration), the system
67
+ With `remoteOutputs: {}` in [`setupPlayer`](/guide/configuration), the system
68
68
  Output Switcher (Android 11+) also lists the speakers and TVs of media route
69
69
  providers, and the one the listener selects becomes the output, with
70
70
  `type: 'remote'`. While one is selected, the switcher offers **Stop casting**
@@ -82,11 +82,192 @@ it turns on transfer for any MediaRouter in the app, Cast's included:
82
82
  Without it, the switcher lists only the phone's own outputs, and the library
83
83
  logs a warning saying the receiver is missing.
84
84
 
85
+ Each `setupPlayer` sets the remote outputs: a call that leaves `remoteOutputs`
86
+ out turns them off, and playback on one comes back to the phone.
87
+
88
+ ::: tip Migrating from `remoteOutputs: true`
89
+ `remoteOutputs` was a boolean; it is now an object, with a flag for each output
90
+ the library plays on. `remoteOutputs: true` becomes `remoteOutputs: {}`.
91
+ :::
92
+
85
93
  A provider offers its routes by declaring the library's control category,
86
94
  `com.audiobrowser.RemoteOutputs.CATEGORY`, in their control filters. Only the
87
95
  selection is reported: the library keeps playing locally, and rendering the
88
96
  audio on the speaker is the provider's job.
89
97
 
98
+ ### Google Cast (Android)
99
+
100
+ With `remoteOutputs: { cast: true }`, selecting a Cast device in the switcher
101
+ moves playback there, through Google's Default Media Receiver, or the receiver
102
+ `castReceiverApplicationId` names. The output
103
+ reports `type: 'cast'`, and the queue, the position and the play intent move
104
+ across both ways: **Stop casting** brings playback back to the phone, at the
105
+ same track.
106
+
107
+ ```ts
108
+ await setupPlayer({ remoteOutputs: { cast: true } })
109
+ ```
110
+
111
+ Cast is opt-in at build time, so apps that don't cast don't ship Google Play
112
+ services' Cast framework. Turn it on in the app's `gradle.properties`:
113
+
114
+ ```properties
115
+ # android/gradle.properties
116
+ AudioBrowser_castEnabled=true
117
+ ```
118
+
119
+ The device and its notifications show the receiver's name: "Default Media
120
+ Receiver" for Google's. To show the app's own, register a Styled Media Receiver
121
+ in the [Google Cast SDK Developer Console](https://cast.google.com/publish) and
122
+ pass its ID; Cast takes it once per app process, so a change takes effect after
123
+ a restart:
124
+
125
+ ```ts
126
+ await setupPlayer({
127
+ remoteOutputs: { cast: true, castReceiverApplicationId: 'ABCD1234' }
128
+ })
129
+ ```
130
+
131
+ The app also declares `MediaTransferReceiver`, as above. Without the build
132
+ property, or on a device without Google Play services, playback stays on the
133
+ phone and the library logs a warning.
134
+
135
+ The receiver fetches the stream itself:
136
+
137
+ - It gets the URL your media transform resolves, without its headers, so a
138
+ stream that needs request headers won't play on it.
139
+ - A track without a file extension is sent as `audio/mpeg`; the receiver works
140
+ out the real codec. A track with `live: true` loads as a live stream.
141
+ - The receiver shows the track's title, artist and artwork. It doesn't read
142
+ song titles from the stream, so the live song doesn't update while casting.
143
+
144
+ While casting, what only makes sense on the phone steps aside:
145
+
146
+ - `setVolume` moves the receiver's volume;
147
+ - the equalizer and the skip-silence setting wait for playback to come back;
148
+ - the sleep timer pauses the receiver without fading;
149
+ - load retries and stall recovery are the receiver's own, and a receiver error
150
+ reaches the app as a playback error.
151
+
152
+ Known limits:
153
+
154
+ - No live song titles on the receiver or the phone while casting: the Default
155
+ Media Receiver keeps the metadata it was loaded with.
156
+ - The receiver is one that takes the same media as the Default Media Receiver:
157
+ Google's own, or a Styled Media Receiver registered for the app.
158
+ - Android only. On iOS, the route picker lists AirPlay devices.
159
+ - A receiver error is not retried; the app decides what to do with it.
160
+
161
+ ### Sonos (Android)
162
+
163
+ With `remoteOutputs: { sonos: true }`, the switcher lists the Sonos rooms on the
164
+ local network, and selecting one moves playback there. The output reports
165
+ `type: 'sonos'` and the room's name.
166
+
167
+ ```ts
168
+ await setupPlayer({ remoteOutputs: { sonos: true } })
169
+ ```
170
+
171
+ The app declares `MediaTransferReceiver`, as above, and the permission to hold
172
+ a Wi-Fi multicast lock while it looks for rooms. No build property is needed:
173
+ the library talks to the speakers itself.
174
+
175
+ ```xml
176
+ <!-- android/app/src/main/AndroidManifest.xml -->
177
+ <uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
178
+ ```
179
+
180
+ Without the permission, the library logs a warning and looks for rooms without
181
+ the lock, so a room can be missed while the phone saves power on Wi-Fi.
182
+
183
+ Local network access: the library finds and controls the rooms itself, over
184
+ the local network. An app that targets SDK 36 or lower has that access through
185
+ `INTERNET`, and needs nothing more. From target SDK 37 (Android 17), Android
186
+ blocks the local network until the app is granted the runtime permission
187
+ `ACCESS_LOCAL_NETWORK`, which the library doesn't request yet. Without it, rooms
188
+ don't appear and can't be controlled. Android exempts apps that use the Output
189
+ Switcher for Cast, whose discovery the system runs; its docs don't yet say
190
+ whether that covers rooms the library finds itself, so plan for the permission.
191
+ See Android's
192
+ [local network permission](https://developer.android.com/privacy-and-security/local-network-permission).
193
+
194
+ ::: warning Sonos support is a bonus, not a promise
195
+ The library controls the speakers over UPnP, on port 1400 of each speaker. Sonos
196
+ calls UPnP unsupported and no longer maintained, and lets the listener switch it
197
+ off in the Sonos app (Account › Privacy & Security). When it is off, or Sonos
198
+ removes it, the rooms don't appear in the switcher. The library doesn't use
199
+ Sonos's cloud or local Control APIs, which need Sonos's approval.
200
+ :::
201
+
202
+ What plays:
203
+
204
+ - The speaker fetches the stream itself, from the URL your media transform
205
+ resolves, without its headers. A live stream goes as a radio stream: the
206
+ speaker follows redirects and works out the codec, so MP3, AAC and HLS
207
+ streams play, over `https` and plain `http`. A track goes as a file, in a
208
+ format the speaker plays, so the speaker knows its duration and can seek in it.
209
+ - The speaker is sent the track's title, artist and artwork to show.
210
+ - The speaker reads song titles from the stream (ICY titles, and the ID3 titles
211
+ of HLS streams). The library polls them and reports them through
212
+ `onTimedMetadata`, as it does for local playback, so the live song keeps
213
+ updating.
214
+ - Play, pause, skip and the volume act on the speaker. A live stream that
215
+ refuses to pause is stopped instead, and playing it again restarts it.
216
+ - A track shows the position and duration the speaker reports.
217
+ - Pausing or stopping in the Sonos app shows up as paused here.
218
+
219
+ Grouping:
220
+
221
+ - The switcher lists rooms, not speakers. A stereo pair or a home theatre is one
222
+ room.
223
+ - Rooms grouped in the Sonos app are listed once, named after the room that
224
+ leads the group: "Kitchen + 2". Playing there plays in every room of the group,
225
+ and the volume is the group's, as the Sonos app's group volume is.
226
+ - The library doesn't group or ungroup rooms; the listener does that in the
227
+ Sonos app.
228
+
229
+ While on Sonos, local-only behaviour steps aside as it does for Cast: the
230
+ volume is the speaker's, the equalizer waits for the phone, and a speaker error
231
+ reaches the app as a playback error, as does a speaker that stops answering.
232
+
233
+ Known limits:
234
+
235
+ - Rooms are found by SSDP multicast on the local network, so the phone and the
236
+ speakers must share it; guest and isolated Wi-Fi networks hide them.
237
+ - A track that needs request headers won't play.
238
+ - The state is polled every two seconds, so a change made in the Sonos app shows
239
+ up here after a moment.
240
+ - If another app or the Sonos app starts something else on the room, this app
241
+ reads as paused and leaves the room alone; playing again loads its own track.
242
+ - Android only. On iOS, a Sonos speaker with AirPlay 2 appears in the route
243
+ picker as an AirPlay target.
244
+
245
+ ### On every remote output
246
+
247
+ Cast and Sonos play the queue the same way:
248
+
249
+ - The queue stays in the app. The receiver is sent one item at a time, at the
250
+ position it plays from, and the app sends the next when one ends, as the
251
+ repeat mode says. Editing the queue reaches the receiver only when the
252
+ current item changes.
253
+ - The shuffle mode is kept and comes back to the phone, but a remote output
254
+ plays the queue in list order
255
+ ([#210](https://github.com/radio-garden/react-native-audio-browser/issues/210)).
256
+ - Selecting an output moves the queue, the position, the play intent and the
257
+ repeat mode there. The phone plays on until the current item's URL is
258
+ resolved for the receiver, and the output already reports `'cast'` or
259
+ `'sonos'` meanwhile.
260
+ - Moving from one room or Cast device to another goes straight there, without
261
+ the phone in between.
262
+ - A receiver that fails to play reaches the app as a playback error with code
263
+ `remote-error`, as does an item whose URL can't be resolved for it, and one
264
+ the receiver hasn't started within 30 seconds of being sent or played.
265
+ Playing again loads the item there anew.
266
+
267
+ The library's Sonos route provider service is exported, as the Output Switcher
268
+ needs to bind it: another app on the phone can bind it too, list the rooms,
269
+ select one and set its volume, as through any media route provider.
270
+
90
271
  Outside React, read a snapshot with `getOutput()` or subscribe with
91
272
  [`onOutputChanged`](/api/features/output/#onoutputchanged):
92
273
 
@@ -133,7 +314,7 @@ On Android the switcher is the system one (the picker from the media
133
314
  notification); selecting a Bluetooth speaker there routes audio at the OS level.
134
315
  The library can't force playback to a _specific_ Bluetooth device itself — route
135
316
  selection is the system's job, which is what this hands off to. Sonos appears on
136
- iOS (as an AirPlay target); on Android it isn't a system route, so it won't show.
317
+ iOS as an AirPlay target, and on Android with `remoteOutputs: { sonos: true }`.
137
318
 
138
319
  ## You may not need this for unplug handling
139
320
 
@@ -75,6 +75,12 @@ capabilities). Elsewhere, just omit a field to leave it unchanged.
75
75
  | `retry`, `keepSessionAliveOnError`, `remoteOutputs` | ✓ | — |
76
76
  | `android` / `ios` audio engine & session (`audioContentType`, `wakeMode`, `category`, …) | ✓ | — |
77
77
 
78
+ `remoteOutputs` (Android) turns on the outputs of the system Output Switcher
79
+ beyond the phone's own: `{}` lists media route providers' speakers, and
80
+ `{ cast: true, sonos: true }` plays on Cast devices and Sonos rooms. Left out of
81
+ a `setupPlayer` call, they are off; see
82
+ [Remote outputs](/guide/audio-output#remote-outputs-android).
83
+
78
84
  `playWhenReady` and `repeatMode` set the _initial_ state; change them at runtime
79
85
  with [`setPlayWhenReady`](/guide/playback#play-when-ready) /
80
86
  [`setRepeatMode`](/guide/queue#repeat-and-shuffle), not `updateOptions`.