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

package/src/audio.ts

@@ -0,0 +1,221 @@
+/**
+ * Call audio on Android: the speaker or the earpiece, headsets and Bluetooth, through this package's audio router (a
+ * port of the Android SDK's AudioRouter, AudioSwitch's rules). Process-wide, like Android's AudioManager: every
+ * connected client holds the call audio (the provider does it), and the last to let go puts the device's audio mode,
+ * speakerphone and microphone mute back as it found them. setSpeakerphoneOn and selectAudioOutput work before any
+ * client exists: the choice is kept for the call.
+ *
+ * In the audio mode `media` (the Expo plugin's android.audioMode, for apps whose users only listen) sound follows the
+ * system's media routing: there is no earpiece and nothing to choose. On iOS (preview) there is no routing at all.
+ */
+import { useMemo, useSyncExternalStore } from 'react';
+import { Platform } from 'react-native';
+import { RpcError, type MediaDevice, type StreamClient } from '@voltkit-rtc/client';
+import { listen, nativeConstants, nativeModule, requireNative, toMediaDevice } from './native';
+import { logError, nativeFailure } from './errors';
+
+/** Whether this app chose the speaker itself (setSpeakerphoneOn): the provider then leaves that choice alone. */
+let speakerChosen: boolean | null = null;
+
+/**
+ * Play call audio on the loudspeaker (true) or the earpiece (false) when no headset is connected; a wired or Bluetooth
+ * headset still wins. Kept until changed, and applied to calls joined later. Rejects with `media-unavailable` on iOS
+ * and where the native module is missing.
+ */
+export async function setSpeakerphoneOn(on: boolean): Promise<void> {
+  const module = requireNative('Choosing the speaker or the earpiece');
+  module.setSpeakerphoneOn(Boolean(on));
+  speakerChosen = Boolean(on);
+  outputs.preferenceChanged();
+}
+
+/**
+ * Play call audio on this output (a deviceId from useAudioOutput().outputs) while it stays connected. Rejects with
+ * `bad-params` for an output that is not there and in the audio mode `media`, and with `media-unavailable` on iOS and
+ * where the native module is missing.
+ */
+export async function selectAudioOutput(deviceId: string): Promise<void> {
+  const module = requireNative('Choosing the audio output');
+  let routed: boolean;
+  try {
+    routed = await module.selectAudioOutput(deviceId);
+  } catch (err) {
+    throw nativeFailure(err);
+  }
+  if (!routed) {
+    throw new RpcError('bad-params', nativeConstants()?.audioMode === 'media'
+      ? 'in the audio mode media, sound follows the system\'s media routing: there is no output to choose'
+      : `there is no audio output with the id ${deviceId}`);
+  }
+}
+
+/**
+ * The speaker preference a newly joined call holds the audio with: the provider's (default the loudspeaker), unless
+ * the app chose with setSpeakerphoneOn, which the router keeps (null).
+ */
+export function speakerPreference(provider: boolean | undefined): boolean | null {
+  return speakerChosen !== null ? null : provider ?? true;
+}
+
+// ------------------------------------------------------------------------------------------- holding the call audio
+
+/**
+ * One client's hold on the call audio: acquired once it is connected, released when it closes or the provider lets go
+ * of it. Released a moment late, so React's StrictMode (an effect unmounted and mounted again at once) neither
+ * releases nor acquires twice.
+ */
+class AudioHold {
+  private holder: Promise<number | null> | null = null;
+  private users = 0;
+  private pendingRelease = false;
+
+  constructor(private readonly onError: (error: Error) => void) {}
+
+  retain(): void {
+    this.users += 1;
+    this.pendingRelease = false;
+  }
+
+  /** One user less; the hold goes when none is left. */
+  unretain(): void {
+    this.users = Math.max(0, this.users - 1);
+    if (this.users > 0) return;
+    this.pendingRelease = true;
+    queueMicrotask(() => {
+      if (this.pendingRelease && this.users === 0) this.release();
+    });
+  }
+
+  acquire(speakerphone: boolean | null): void {
+    if (this.holder) return;
+    const module = nativeModule();
+    if (!module) return;
+    this.holder = module.audioAcquire(speakerphone).then(
+      (id) => id,
+      (err: unknown) => {
+        this.onError(nativeFailure(err));
+        return null;
+      },
+    );
+  }
+
+  release(): void {
+    this.pendingRelease = false;
+    const holder = this.holder;
+    if (!holder) return;
+    this.holder = null;
+    void holder.then((id) => {
+      if (id !== null) nativeModule()?.audioRelease(id);
+    });
+  }
+}
+
+const holds = new WeakMap<StreamClient, AudioHold>();
+
+/** The call audio hold of `client`. */
+export function audioHoldOf(client: StreamClient, onError: (error: Error) => void): AudioHold {
+  let hold = holds.get(client);
+  if (!hold) {
+    hold = new AudioHold(onError);
+    holds.set(client, hold);
+  }
+  return hold;
+}
+
+// ------------------------------------------------------------------------------------------- useAudioOutput
+
+export interface AudioOutput {
+  /** Outputs can be chosen here: Android with the native module, in the audio mode `communication`. */
+  supported: boolean;
+  /** Where call audio can play: speaker, earpiece, wired and USB headsets, Bluetooth. Empty where not supported. */
+  outputs: MediaDevice[];
+  /** Where call audio plays now, while a call holds the audio; null otherwise. */
+  current: MediaDevice | null;
+  /** The loudspeaker is in use (or, with no call holding the audio, preferred). */
+  speakerphone: boolean;
+  /** Play call audio on this output (selectAudioOutput). */
+  select(deviceId: string): Promise<void>;
+  /** The loudspeaker (true) or the earpiece (false), when no headset is connected (setSpeakerphoneOn). */
+  setSpeakerphoneOn(on: boolean): Promise<void>;
+}
+
+interface OutputState {
+  supported: boolean;
+  outputs: MediaDevice[];
+  current: MediaDevice | null;
+  speakerphone: boolean;
+}
+
+const NONE: OutputState = Object.freeze({ supported: false, outputs: Object.freeze([]) as unknown as MediaDevice[], current: null, speakerphone: false });
+
+/** The audio outputs, kept current from the router's events while something listens. */
+class OutputStore {
+  private state: OutputState = NONE;
+  private readonly listeners = new Set<() => void>();
+  private stop: (() => void) | null = null;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    if (this.listeners.size === 1) this.start();
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0) {
+        this.stop?.();
+        this.stop = null;
+      }
+    };
+  };
+
+  snapshot = (): OutputState => this.state;
+
+  /** The app changed the speaker preference: what is shown before a call holds the audio follows it. */
+  preferenceChanged(): void {
+    if (this.listeners.size > 0) this.set({ ...this.state, speakerphone: this.state.current ? this.state.current.type === 'speaker' : speakerChosen ?? true });
+  }
+
+  private start(): void {
+    const module = nativeModule();
+    const supported = Platform.OS === 'android' && module !== null && nativeConstants()?.audioMode !== 'media';
+    if (!module) {
+      this.set(NONE);
+      return;
+    }
+    this.set({ ...this.state, supported, speakerphone: this.state.current ? this.state.current.type === 'speaker' : speakerChosen ?? true });
+    const stops = [
+      listen(module.onAudioDevicesChanged, 'onAudioDevicesChanged', (e) => this.setOutputs(e.devices.map(toMediaDevice))),
+      listen(module.onAudioOutputChanged, 'onAudioOutputChanged', (e) => this.setCurrent(e.device ? toMediaDevice(e.device) : null)),
+    ];
+    this.stop = () => {
+      for (const stop of stops) stop();
+    };
+    module.listAudioDevices().then((list) => this.setOutputs(list.map(toMediaDevice)), (err: unknown) => logError('could not list the audio devices', err));
+    module.currentAudioOutput().then((device) => this.setCurrent(device ? toMediaDevice(device) : null), (err: unknown) => logError('could not read the audio output', err));
+  }
+
+  private setOutputs(devices: MediaDevice[]): void {
+    const outputs = this.state.supported ? devices.filter((d) => d.kind === 'audiooutput') : [];
+    const same = outputs.length === this.state.outputs.length && outputs.every((d, i) => d.deviceId === this.state.outputs[i].deviceId && d.label === this.state.outputs[i].label);
+    if (!same) this.set({ ...this.state, outputs });
+  }
+
+  private setCurrent(device: MediaDevice | null): void {
+    if (device?.deviceId === this.state.current?.deviceId) return;
+    this.set({ ...this.state, current: device, speakerphone: device ? device.type === 'speaker' : speakerChosen ?? true });
+  }
+
+  private set(next: OutputState): void {
+    this.state = next;
+    for (const listener of [...this.listeners]) listener();
+  }
+}
+
+const outputs = new OutputStore();
+
+/**
+ * Where call audio plays, and the choice of output (an Android "speaker / phone / headset" picker). Works before any
+ * call: a choice made then is kept. On iOS and without the native module `supported` is false and the calls reject.
+ */
+export function useAudioOutput(): AudioOutput {
+  const state = useSyncExternalStore(outputs.subscribe, outputs.snapshot, outputs.snapshot);
+  return useMemo(() => ({ ...state, select: selectAudioOutput, setSpeakerphoneOn }), [state]);
+}

package/src/components.tsx

@@ -0,0 +1,233 @@
+/**
+ * VideoTrack and AudioTrack, React Native's versions of @voltkit-rtc/react's.
+ *
+ * VideoTrack shows a track in react-native-webrtc's RTCView, which plays a stream by URL. Its stream is a wrapper made
+ * through platform/streams.ts, one per track and shared by every view of it, released (never the track) when the last
+ * view goes -- or earlier, while the connection still exists, when the client is about to close what receives the
+ * track or stops it: releasing a wrapper after its track died kills the app (Phase 0 finding 1). The URL is set one
+ * frame after mounting, and the native view is mounted again once if no frame size arrives within 3 s
+ * (react-native-webrtc #1611, black video).
+ *
+ * AudioTrack renders nothing: React Native plays every remote audio track by itself. It sets one track's volume
+ * (react-native-webrtc's `_setVolume`, unity at 1) or mutes it here only.
+ */
+import { useCallback, useEffect, useRef, useState, type ReactElement } from 'react';
+import { StyleSheet, View, type LayoutChangeEvent, type StyleProp, type ViewStyle } from 'react-native';
+import type { StreamClient, ViewBox, ViewSource } from '@voltkit-rtc/client';
+import { useVoltkitClient } from '@voltkit-rtc/react';
+import { loadWebRTC } from './globals';
+import { logError } from './errors';
+import { streamBook } from './platform/streams';
+import type { MediaStreamTrackLike } from './platform/common';
+
+/** How long a view waits for its first frame before its native view is mounted again (react-native-webrtc #1611). */
+export const FIRST_FRAME_TIMEOUT_MS = 3000;
+
+export interface VideoTrackProps {
+  /**
+   * The video to show: a remote track's `track`, or your camera (`useLocalMedia().stream?.getVideoTracks()[0]`). Nothing
+   * while null. Typed by shape (`MediaStreamTrackLike`), so the app needs no DOM library for it.
+   */
+  track: MediaStreamTrackLike | null | undefined;
+  /**
+   * The remote video's `producerId`: it is then received at the size this view is shown and paused at the server while
+   * the view is not `visible` (adaptive stream). Leave it out for your own camera.
+   */
+  producerId?: string;
+  /** Flip it horizontally, as people expect to see their own front camera. */
+  mirror?: boolean;
+  /** `cover` (the default: fill the view, cropping) or `contain` (all of the picture, with bars). */
+  objectFit?: 'cover' | 'contain';
+  /** Which of two overlapping videos is on top (RTCView's zOrder): 0 for a full-screen video, 1 for a preview over it. */
+  zOrder?: number;
+  /** Whether the view can be seen now (a list scrolled past it, a hidden tab): with `producerId`, the video pauses at the server while false. */
+  visible?: boolean;
+  /** The video's size in pixels: its first frame arrived, or the size changed. */
+  onDimensionsChange?: (size: { width: number; height: number }) => void;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+type Report = (box: ViewBox | null, visible: boolean | null) => void;
+
+/** A video track in an RTCView, sized by `style`. */
+export function VideoTrack({
+  track,
+  producerId,
+  mirror = false,
+  objectFit = 'cover',
+  zOrder,
+  visible = true,
+  onDimensionsChange,
+  style,
+  testID,
+}: VideoTrackProps): ReactElement {
+  const client = useVoltkitClient();
+  const [url, setUrl] = useState<string | null>(null);
+  // The RTCView's key: changed once to mount it again when no frame came.
+  const [mount, setMount] = useState(0);
+  const sawFrame = useRef(false);
+  const dimensions = useRef(onDimensionsChange);
+  useEffect(() => {
+    dimensions.current = onDimensionsChange;
+  });
+
+  // The wrapper stream, held while this view shows the track; its URL one frame after mounting.
+  useEffect(() => {
+    setUrl(null);
+    if (!track) return;
+    const view = streamBook().view(track);
+    if (!view) return;
+    let frame: number | null = requestAnimationFrame(() => {
+      frame = null;
+      setUrl(view.url);
+    });
+    const stopEnd = view.onEnd(() => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      frame = null;
+      setUrl(null);
+    });
+    return () => {
+      if (frame !== null) cancelAnimationFrame(frame);
+      stopEnd();
+      view.release();
+    };
+  }, [track]);
+
+  // react-native-webrtc #1611: a view that never shows a frame is mounted again, once per stream.
+  useEffect(() => {
+    sawFrame.current = false;
+    if (!url) return;
+    const timer = setTimeout(() => {
+      if (!sawFrame.current) setMount((n) => n + 1);
+    }, FIRST_FRAME_TIMEOUT_MS);
+    return () => clearTimeout(timer);
+  }, [url]);
+
+  // Adaptive stream: the view reports its size (onLayout) and visibility (`visible`) through a ViewSource.
+  const box = useRef<ViewBox | null>(null);
+  const shown = useRef(visible);
+  const reports = useRef(new Set<Report>());
+  const tell = (nextBox: ViewBox | null, nextVisible: boolean | null) => {
+    for (const report of [...reports.current]) {
+      try {
+        report(nextBox, nextVisible);
+      } catch (err) {
+        logError('listener for videoView threw', err);
+      }
+    }
+  };
+
+  useEffect(() => {
+    if (shown.current === visible) return;
+    shown.current = visible;
+    tell(null, visible);
+  }, [visible]);
+
+  useEffect(() => {
+    if (!box.current || box.current.fit === objectFit) return;
+    box.current = { ...box.current, fit: objectFit };
+    tell(box.current, null);
+  }, [objectFit]);
+
+  useEffect(() => {
+    const attach = (client as (StreamClient & { attachVideo?: StreamClient['attachVideo'] }) | null)?.attachVideo;
+    if (!client || !producerId || typeof attach !== 'function') return;
+    const source: ViewSource = {
+      subscribe(onChange) {
+        reports.current.add(onChange);
+        if (box.current || !shown.current) onChange(box.current, shown.current);
+        return () => {
+          reports.current.delete(onChange);
+        };
+      },
+    };
+    return attach.call(client, producerId, source);
+  }, [client, producerId]);
+
+  const onLayout = useCallback((event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    const previous = box.current;
+    if (previous && previous.width === width && previous.height === height && previous.fit === objectFit) return;
+    box.current = { width, height, fit: objectFit };
+    tell(box.current, null);
+  }, [objectFit]);
+
+  const onFrameSize = useCallback((event: { nativeEvent: { width: number; height: number } }) => {
+    sawFrame.current = true;
+    const { width, height } = event.nativeEvent;
+    try {
+      dimensions.current?.({ width, height });
+    } catch (err) {
+      logError('listener for onDimensionsChange threw', err);
+    }
+  }, []);
+
+  const RTCView = loadWebRTC()?.RTCView;
+  return (
+    <View style={style} onLayout={onLayout} testID={testID} collapsable={false}>
+      {RTCView && url ? (
+        <RTCView
+          key={mount}
+          streamURL={url}
+          mirror={mirror}
+          objectFit={objectFit}
+          zOrder={zOrder}
+          onDimensionsChange={onFrameSize}
+          style={StyleSheet.absoluteFill}
+        />
+      ) : null}
+    </View>
+  );
+}
+
+export interface AudioTrackProps {
+  /** The audio to set: a remote track's `track`. Nothing while null. Typed by shape (`MediaStreamTrackLike`). */
+  track: MediaStreamTrackLike | null | undefined;
+  /** 0 to 1, clamped (1 is the track as received). Unset leaves it as it is. This track only. */
+  volume?: number;
+  /** Silence it here only (the track is switched off while muted, and back on after). */
+  muted?: boolean;
+}
+
+interface AudioLike {
+  readonly kind: string;
+  readonly readyState: string;
+  enabled: boolean;
+  _setVolume?(volume: number): void;
+}
+
+/** One remote audio track's volume, or muted, while mounted. Renders nothing: React Native plays remote audio itself. */
+export function AudioTrack({ track, volume, muted = false }: AudioTrackProps): null {
+  useEffect(() => {
+    const audio = track as unknown as AudioLike | null | undefined;
+    if (!audio || audio.kind !== 'audio' || typeof audio._setVolume !== 'function') return;
+    if (typeof volume !== 'number' || Number.isNaN(volume)) return;
+    const gain = Math.min(1, Math.max(0, volume));
+    try {
+      audio._setVolume(gain);
+    } catch (err) {
+      logError('could not set a track\'s volume', err);
+    }
+    return () => {
+      if (audio.readyState === 'ended') return;
+      try {
+        audio._setVolume?.(1);
+      } catch (err) {
+        logError('could not set a track\'s volume', err);
+      }
+    };
+  }, [track, volume]);
+
+  useEffect(() => {
+    const audio = track as unknown as AudioLike | null | undefined;
+    if (!audio || !muted) return;
+    const was = audio.enabled;
+    audio.enabled = false;
+    return () => {
+      if (audio.readyState !== 'ended') audio.enabled = was;
+    };
+  }, [track, muted]);
+
+  return null;
+}

package/src/create-client.ts

@@ -0,0 +1,53 @@
+/**
+ * A StreamClient for React Native: react-native-webrtc's mediasoup handler (ReactNative106) and this package's
+ * platform, with the background pause on for the camera. The provider makes its clients this way; an app that makes and
+ * owns its client (the provider's `client` prop, a PK battle's second client) uses createClient.
+ */
+import { StreamClient, type ClientOptions } from '@voltkit-rtc/client';
+import { registerVoltkitGlobals } from './globals';
+import { webrtcMissing } from './errors';
+import { reactNativePlatform } from './platform';
+
+/** What happens to the camera and microphone while the app is in the background. */
+export interface BackgroundOptions {
+  /**
+   * Switch the camera off while the app is in the background or the screen is off, and back on when it returns (only
+   * if this switched it off): viewers see the camera off rather than a frozen picture. Android stops a background
+   * app's camera anyway. Default true.
+   */
+  pauseCamera?: boolean;
+  /** The same for the microphone. Leave it off for calls, which go on talking in the background. Default false. */
+  pauseMic?: boolean;
+}
+
+export interface CreateClientOptions {
+  /** The background pause: camera on by default, microphone off. */
+  background?: BackgroundOptions;
+  /** StreamClient options of your own; they win over the ones set here. */
+  clientOptions?: ClientOptions;
+}
+
+/**
+ * The ClientOptions a React Native client is made with: `{ handlerName: 'ReactNative106', platform,
+ * pauseCameraInBackground, pauseMicInBackground, ...clientOptions }`.
+ */
+export function reactNativeClientOptions(options: CreateClientOptions = {}): ClientOptions {
+  const { background, clientOptions } = options;
+  return {
+    handlerName: 'ReactNative106',
+    platform: reactNativePlatform(),
+    pauseCameraInBackground: background?.pauseCamera ?? true,
+    pauseMicInBackground: background?.pauseMic ?? false,
+    ...clientOptions,
+  };
+}
+
+/**
+ * A StreamClient for React Native, not yet connected: call `connect()`. Throws `media-unavailable` with
+ * `{ reason: 'webrtc-missing' }` where react-native-webrtc's native module is missing (Expo Go: it needs a development
+ * build).
+ */
+export function createClient(wsUrl: string, token: string, options: CreateClientOptions = {}): StreamClient {
+  if (!registerVoltkitGlobals()) throw webrtcMissing();
+  return new StreamClient(wsUrl, token, reactNativeClientOptions(options));
+}

package/src/errors.ts

@@ -0,0 +1,81 @@
+/**
+ * The errors this package raises. Every one is an RpcError with a code from the VoltKit error registry
+ * (@voltkit-rtc/client ERROR_CODES, checked code for code against every SDK by scripts/test/sdk-contract-sdks.mjs), so
+ * an app switches on `error.code` exactly as it does in a browser or the Android SDK. What is missing goes in `data`:
+ *
+ * - `media-unavailable` `{ reason: 'webrtc-missing' }`: react-native-webrtc's native module is not in the app (Expo Go,
+ *   or an app not rebuilt after installing it). The message says it needs a development build.
+ * - `media-unavailable` `{ reason: 'native-missing', feature }`: this package's own native module is not in the app.
+ * - `media-unavailable` `{ platform: 'ios', feature }`: not in the iOS preview (audio routing: setSpeakerphoneOn,
+ *   selectAudioOutput, switchDevice('audiooutput')). The call service and screen sharing do not raise it there: the
+ *   service is simply not declared (useCallService), and the client answers `screen-share-unsupported`.
+ * - `media-unavailable` `{ permission: 'camera' | 'microphone', status: 'denied' | 'blocked' }`: a refused permission,
+ *   the field names of the Android SDK.
+ * - `media-unavailable` `{ feature: 'callService' }`: the call service could not start or keep running.
+ */
+import { RpcError } from '@voltkit-rtc/client';
+
+export type MediaPermissionKind = 'camera' | 'microphone';
+
+/** react-native-webrtc's native module is missing: Expo Go, or the app was not rebuilt. */
+export function webrtcMissing(): RpcError {
+  return new RpcError(
+    'media-unavailable',
+    "react-native-webrtc's native module is not in this app: @voltkit-rtc/react-native needs a development build (Expo Go cannot load it). Install react-native-webrtc and rebuild the app (npx expo run:android, or an EAS development build).",
+    { reason: 'webrtc-missing' },
+  );
+}
+
+/** This package's own native module is missing: the app was not rebuilt after installing it. */
+export function nativeMissing(feature: string): RpcError {
+  return new RpcError(
+    'media-unavailable',
+    `${feature} needs @voltkit-rtc/react-native's native module, which is not in this app: it needs a development build. Rebuild the app after installing the package (Expo Go cannot load it).`,
+    { reason: 'native-missing', feature },
+  );
+}
+
+/** Not in the iOS preview of 0.1.0. */
+export function iosUnsupported(feature: string): RpcError {
+  return new RpcError('media-unavailable', `${feature} is not available in the iOS preview of @voltkit-rtc/react-native`, { platform: 'ios', feature });
+}
+
+/** A camera or microphone permission the user refused: `blocked` when Android will not ask again. */
+export function permissionRefused(permission: MediaPermissionKind, status: 'denied' | 'blocked'): RpcError {
+  const what = permission === 'camera' ? 'camera' : 'microphone';
+  const why = status === 'blocked'
+    ? `the ${what} permission is blocked: the user has to allow it in the app's settings`
+    : `the ${what} permission was not granted`;
+  return new RpcError('media-unavailable', why, { permission, status });
+}
+
+/** The call service could not start, or Android stopped it. */
+export function callServiceFailed(message: string): RpcError {
+  return new RpcError('media-unavailable', `the call service: ${message}`, { feature: 'callService' });
+}
+
+/** A failure a native module or react-native-webrtc reported, as an RpcError with a registry code. */
+export function nativeFailure(error: unknown, code: 'media-unavailable' | 'camera-failed' | 'screen-share-failed' = 'media-unavailable', data?: Record<string, unknown>): RpcError {
+  if (error instanceof RpcError) return error;
+  return new RpcError(code, describeError(error), data);
+}
+
+/** A readable message from anything thrown: an Error, react-native-webrtc's MediaStreamError (not an Error), a string. */
+export function describeError(error: unknown): string {
+  if (typeof error === 'string') return error;
+  if (error && typeof error === 'object') {
+    const { name, message } = error as { name?: unknown; message?: unknown };
+    const text = typeof message === 'string' && message.length > 0 ? message : '';
+    const label = typeof name === 'string' && name.length > 0 && name !== 'Error' ? name : '';
+    if (label && text && !text.includes(label)) return `${label}: ${text}`;
+    if (text) return text;
+    if (label) return label;
+  }
+  return String(error);
+}
+
+/** Report a failure from code no caller awaits: the error listener's own errors never escape into the app. */
+export function logError(context: string, error: unknown): void {
+  // eslint-disable-next-line no-console
+  console.error(`[voltkit-rtc] ${context}`, error);
+}

package/src/globals.ts

@@ -0,0 +1,54 @@
+/**
+ * react-native-webrtc, loaded only once its native module is known to be in the app. Its entry module talks to
+ * WebRTCModule as soon as it runs, so in Expo Go (or an app not rebuilt after installing it) merely importing it can
+ * throw or leave the app in a broken state. This package never imports it at the top level: everything goes through
+ * `loadWebRTC()`, which answers null instead, and `registerVoltkitGlobals()` (run when the package is imported) is safe
+ * anywhere.
+ */
+import { NativeModules } from 'react-native';
+import type * as WebRTC from 'react-native-webrtc';
+
+export type WebRTCModule = typeof WebRTC;
+
+let loaded: WebRTCModule | null = null;
+let registered = false;
+
+/** Whether react-native-webrtc's native module is in this app. */
+export function webrtcAvailable(): boolean {
+  return (NativeModules as Record<string, unknown>).WebRTCModule != null;
+}
+
+/** react-native-webrtc, or null when its native module is not in the app (Expo Go, an app not rebuilt). */
+export function loadWebRTC(): WebRTCModule | null {
+  if (loaded) return loaded;
+  if (!webrtcAvailable()) return null;
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  loaded = require('react-native-webrtc') as WebRTCModule;
+  return loaded;
+}
+
+/**
+ * Install react-native-webrtc's WebRTC classes as globals (RTCPeerConnection, MediaStream, ...), which mediasoup-client
+ * needs. Runs when the package is imported; calling it again does nothing. Returns false, without throwing, where
+ * react-native-webrtc's native module is missing: the provider then reports `media-unavailable` with
+ * `{ reason: 'webrtc-missing' }`.
+ */
+export function registerVoltkitGlobals(): boolean {
+  if (registered) return true;
+  const webrtc = loadWebRTC();
+  if (!webrtc) return false;
+  webrtc.registerGlobals();
+  registered = true;
+  return true;
+}
+
+/** The version of react-native-webrtc in the app, for getDiagnostics(); null when it cannot be read. */
+export function webrtcVersion(): string | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const pkg = require('react-native-webrtc/package.json') as { version?: unknown };
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}