@voltkit-rtc/react-native 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+## 0.1.1
+
+2026-10-27. Two fixes from the testers' report on 0.1.0 (RN010-1, RN010-2). Peer dependency `@voltkit-rtc/client`
+`>=0.9.13 <0.10.0` (0.9.13 fixes C0912-1 and C0912-2 in the client this package runs: a noise-suppressed microphone
+back from the background, and a repeated switch in the same direction); the other peers are unchanged. The native code
+is the same, but build the app again after upgrading: its version check reads this package's version.
+
+- **The call service follows the client's own background camera setting** (RN010-1). A client the app made with
+  `createClient(wsUrl, token, { background: { pauseCamera: false } })` (a live streamer) and passed as the provider's
+  `client` prop was run with the provider's default, `pauseCamera: true`: the service never asked for the `camera`
+  foreground service type, and Android cut the camera in the background; the reverse mix asked for a camera type the
+  app did not need. The service reads `pauseCameraInBackground` from the client it runs for, since the client is what
+  pauses the camera; the provider's `background.pauseCamera` stands in only when the client's options cannot be read.
+  A client the provider makes is unchanged.
+- **One `onError` per call-service failure** (RN010-2). A refused start or update was reported twice: the native side
+  tells a `failed` event and then rejects the call, and both reached `onError`. A `failed` event while a start or update
+  is in flight is its rejection's twin and is reported once; a failure Android reports on its own, with nothing in
+  flight, still reaches `onError`.
+- **A client whose state cannot be read never stops the call service** (the verifier's F3 on this release). A client
+  wrapped so that reading its options throws (a logging or forbidding `Proxy`) is read like one without options: the
+  provider's `background.pauseCamera` stands in, and nothing is reported. A client whose state cannot be read at all
+  (a read of `local` that throws) is left out of the service, said once through `onError` as `media-unavailable`
+  `{ feature: 'callService' }`, and never keeps the other calls in the app from theirs; before, the throw escaped the
+  provider's effect and every later decision for every call failed the same way.
+
+## 0.1.0
+
+2026-10-27. The first release: VoltKit RTC calls, audio rooms and live video in React Native, on Android, with iOS in
+preview. Peer dependencies: `@voltkit-rtc/client` `>=0.9.12 <0.10.0`, `@voltkit-rtc/react` `^0.1.1`,
+`react-native-webrtc` `^155.0.1`, `react` `>=19.1.0` and `react-native` `>=0.82.0` (the New Architecture); `expo`
+`>=58` is optional, for the config plugin. Tested on Android (emulator, API 37.1); iOS in preview; earpiece and
+Bluetooth routing tested in unit tests, not on hardware.
+
+### What ships
+
+- **The React SDK's hooks, unchanged**, re-exported from `@voltkit-rtc/react` 0.1.1: `useVoltkitClient`, `useRoom`,
+  `useConnectionState`, `useParticipants`, `useRemoteTracks`, `useNetworkQuality`, `useWalletLow`, `useVoltkitEvent`,
+  `useActiveSpeakers`, `useAudioLevels`, `useCpuConstrained`, `useDevices`, `useIsSpeaking`, `useMediaWarnings`,
+  `usePublishFallback` and `useStreamFallback`, with the same type re-exports, so a React call screen ports by changing
+  the import and its markup. They run on `@voltkit-rtc/client` 0.9.12's injected platform layer
+  (`ClientOptions.platform`, this package's `reactNativePlatform()`) with mediasoup-client's `ReactNative106` handler:
+  capture, devices and audio routing, streams and their release order, the app's visibility from the process
+  lifecycle, the network coming back, and native timers for the client's own timers (the reconnect backoff, socket
+  liveness, sampling), which React Native's JavaScript timers cannot run in the background or with the screen off.
+- **`VoltkitProvider`**: the React provider's props (the token hand-over, `client`, `connect`, the callbacks and the
+  StrictMode behaviour included), plus `audio` (the call audio: `speakerphone`, `manage`), `background`
+  (`pauseCamera`, default true; `pauseMic`, default false) and `callService` (`true`, `false`, or the notification's
+  `title`, `text` and `leaveLabel`). It makes its client with `reactNativeClientOptions`. Where react-native-webrtc's
+  native module is missing (Expo Go, an app not built again) it makes no client and reports `media-unavailable`
+  `{ reason: 'webrtc-missing' }` through `onError`; on Android without this package's native module, `native-missing`.
+  Nothing throws.
+- **`useLocalMedia`**: the React SDK's, plus `switchCamera()` (front and back on the same track and producer, so
+  viewers see no gap; resolves to whether the front camera is in use) and `facingMode`. `publish()` asks for the
+  camera and microphone permissions before any device opens (a refusal rejects with `media-unavailable`
+  `{ permission, status }`, and the camera light never comes on), then captures through react-native-webrtc at the
+  frame and frame rate it will send, never more than the project allows. `startScreenShare()` goes through
+  react-native-webrtc's screen-capture consent on Android.
+- **`VideoTrack`** on react-native-webrtc's `RTCView`: one native stream per track, shared by its views and released
+  before the connection it came on closes (react-native-webrtc 155 kills the app when a stream is released after its
+  track's connection has gone); `producerId` drives adaptive stream from the view's size and `visible`; `mirror`,
+  `objectFit`, `zOrder` and `onDimensionsChange`; a view with no frame after 3 s mounts its native view again
+  (react-native-webrtc issue 1611). **`AudioTrack`** sets one remote track's `volume` or `muted` and renders nothing:
+  React Native plays remote audio by itself.
+- **Audio routing on Android**: `useAudioOutput()`, `setSpeakerphoneOn(on)` and `selectAudioOutput(deviceId)`, on a
+  port of the Android SDK's audio router: the loudspeaker, the earpiece, wired and USB headsets and Bluetooth
+  (`setCommunicationDevice` on Android 12 and later, SCO before); the call audio (mode, focus, routing) held from the
+  join to the close and shared by two clients, and put back as it was found; the `media` audio mode for listen-only
+  apps; the phone's own echo canceller and noise suppressor by default.
+- **Calls in the background on Android**: the foreground service `VoltkitCallService`, declared by the app (the Expo
+  plugin's `android.callService`, default on, or a manifest block), started by the provider when the call connects
+  while the app is visible, with the types `microphone` or `mediaPlayback`, and `camera` and `mediaProjection` when the
+  app declares them; one notification for every call, with a Leave action; the call ends when the app is swiped away.
+  The camera pauses in the background and comes back with the app (`background.pauseCamera`); the microphone keeps
+  going unless `pauseMic`. `useCallService()` says whether it is declared, running, and with which types.
+- **The network coming back, on Android**: the SDK watches the system's default network, so a reconnect waiting out
+  its backoff tries again as soon as a network is back, with the screen off too while the call service runs. It
+  reports the network 500 ms after Android's callback, and only if that network is still the default then: Android
+  hands the callback out before it has switched the app's routes to the new network (40 to 80 ms later on the API 37
+  emulator), and a connect made at once failed.
+- **Permissions**: `requestMediaPermissions`, `checkMediaPermissions` and `usePermissions` for `camera`, `microphone`
+  and `notifications` (Android 13 and later), with `granted`, `denied` and `blocked` (Android's "never ask again"; on
+  iOS every refusal). The SDK's own captures afterwards (a reconnect, a switch) only check and never ask.
+- **`preflight(wsUrl, token, options?)`** with this platform: it publishes the microphone after the join when its
+  permission is already granted, never asks for one, and never rejects.
+- **`createClient`, `reactNativeClientOptions`, `reactNativePlatform`, `registerVoltkitGlobals`** (run on import; safe
+  without the native module) and **`SDK_VERSION`** (what `getDiagnostics()` reports; a warning in the log when the
+  app's native code was built from another version of the package).
+- **The Expo config plugin** (`app.plugin.js`): `cameraPermission`, `microphonePermission`, `android.camera`,
+  `android.callService`, `android.callServiceCamera`, `android.screenShare`, `android.audioMode`,
+  `android.hardwareEchoCancellation`, `ios.backgroundAudio` and `ios.voip`. It writes the permissions, the call
+  service, the `in.voltkit.rtc.*` meta-data and `uses-feature android:required="false"` for the camera and microphone
+  features into the Android manifest, and the usage strings and background modes into Info.plist; the app's
+  `blockedPermissions` win, with a prebuild warning for a service that could not run; an unknown option stops prebuild
+  by name.
+- **R8 consumer rules**: `-dontwarn org.webrtc.Dav1dDecoder$Natives`, which every release build with
+  react-native-webrtc 155.0.1 needs, so apps add no rule of their own.
+- **Every frame reaches viewers**: react-native-webrtc's libwebrtc encodes a camera's simulcast layers with three
+  temporal layers whatever it is asked, so the platform tells the client to signal them (client 0.9.12's
+  `simulcastTemporalLayers`); signalled as one layer, the media server forwarded a quarter of the frames.
+- **Errors**: every error this package raises is an `RpcError` with a code from the shared registry, with what is
+  missing in `data`: `{ permission, status }`, `{ reason: 'webrtc-missing' | 'native-missing' | <a capture error> }`,
+  `{ feature: 'callService' }`, `{ platform: 'ios', feature }`.
+
+### Known gaps in 0.1.0 (the conformance list)
+
+- **iOS is a preview**: JavaScript only, with no native module of this package. The code is written for
+  react-native-webrtc's iOS side, but VoltKit has not compiled or run it on an iPhone or a simulator. Audio routing
+  (`setSpeakerphoneOn`, `selectAudioOutput`, `switchDevice('audiooutput', ...)`) rejects with `media-unavailable`
+  `{ platform: 'ios' }`, there is no call service (`useCallService().declared` is false), and `startScreenShare()`
+  rejects with `screen-share-unsupported`.
+- **Screen sharing is Android only**, and goes out without the screen's sound.
+- **No in-app music**: `publishMusic()` rejects with `music-unavailable`.
+- **No device recording**: `startRecording()` rejects with `media-unavailable`.
+- **No noise-suppression or video-effects processors**: they are browser-only in `@voltkit-rtc/client`.
+- **`play(element)` and `autoplayFailed` do not apply** (remote audio plays by itself), and
+  **`StreamClient.prepareConnection`** does nothing here.
+- **Earpiece and Bluetooth routing are tested in unit tests, not on hardware**: the emulator has only the
+  loudspeaker, and its microphone records silence, so publishing sound was checked by the bytes sent, not by level.
+- **Xiaomi, Redmi and POCO battery savers** were not tested: the docs give general advice only.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VoltKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.