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

package/src/specs/NativeVoltkitRtc.ts

@@ -0,0 +1,180 @@
+/**
+ * The native side of @voltkit-rtc/react-native on Android, as one codegen TurboModule (plan §5.1): audio routing
+ * (ported from the Android SDK's AudioRouter), the call service, native timers, app visibility from the process
+ * lifecycle, the network, and stopping react-native-webrtc's screen-share service. iOS has no native module in 0.1.0.
+ *
+ * Read it through src/native.ts, never directly: this module is null in Expo Go, on iOS and wherever the app was not
+ * rebuilt after installing the package, and native.ts turns that into a typed error.
+ *
+ * Strings that hold one of a few values are typed `string` here, as codegen needs; the values are listed beside each.
+ */
+import type { CodegenTypes, TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/** An audio input or output, as the Android SDK lists it (`MediaDevice`). */
+export type AudioDevice = {
+  /** Stable while connected: `speaker`, `earpiece`, `wired`, `bluetooth:12`, `usb:7`, `mic`, `wired-mic`, ... */
+  deviceId: string;
+  /** `audioinput` | `audiooutput`. */
+  kind: string;
+  /** A name to show: "Speaker", "Phone", "Pixel Buds". */
+  label: string;
+  /** `speaker` | `earpiece` | `wiredHeadset` | `bluetooth` | `usb` | `builtinMic` | `other`. */
+  type: string;
+  /** A headset's microphone and earphones share one. */
+  groupId: string;
+};
+
+/** Devices came or went while a client held the audio (a headset plugged in, Bluetooth connected). */
+export type AudioDevicesChangedEvent = {
+  devices: AudioDevice[];
+  added: AudioDevice[];
+  removed: AudioDevice[];
+};
+
+/** Where call audio plays now; null once the last client let the audio go. */
+export type AudioOutputChangedEvent = {
+  device: AudioDevice | null;
+};
+
+/** Audio focus, while a client holds the audio: `gain` | `loss` | `lossTransient` | `lossTransientCanDuck`. */
+export type AudioFocusChangedEvent = {
+  focus: string;
+};
+
+/** The audio device module could not open or keep the microphone. */
+export type MicrophoneErrorEvent = {
+  message: string;
+};
+
+/** The app went to the foreground (any activity started) or the background, from ProcessLifecycleOwner. */
+export type AppVisibilityChangedEvent = {
+  visible: boolean;
+};
+
+/** The network came back (`handover` false) or the default network changed, say Wi-Fi to mobile data (true). */
+export type NetworkAvailableEvent = {
+  handover: boolean;
+};
+
+/** What the call service shows and the call it runs for: its foreground service types are worked out from these. */
+export type CallServiceOptions = {
+  /** The notification's title and text, and the label of its Leave action. */
+  title: string;
+  text: string;
+  leaveLabel: string;
+  /** The provider's `background.pauseCamera`: true never asks for the camera type. */
+  pauseCamera: boolean;
+  /** What the call publishes now. */
+  micPublished: boolean;
+  cameraPublished: boolean;
+  /** A screen share is live: on Android 14 and later the `mediaProjection` type is asked for only while it is. */
+  sharing: boolean;
+};
+
+/** The call service: whether the app declares it, and whether it runs, with which foreground service types. */
+export type CallServiceStatus = {
+  declared: boolean;
+  running: boolean;
+  /** `microphone`, `mediaPlayback`, `camera`, `mediaProjection`: what it runs with now (empty when stopped). */
+  types: string[];
+};
+
+/** `started` | `updated` | `stopped` | `leave` (the notification's action) | `taskRemoved` | `failed`. */
+export type CallServiceEvent = {
+  type: string;
+  /** The types it runs with after this event. */
+  types: string[];
+  /** Why it failed; empty otherwise. */
+  message: string;
+};
+
+export type Constants = {
+  /** `communication` | `media`, from the meta-data in.voltkit.rtc.AUDIO_MODE: fixed for the life of the process. */
+  audioMode: string;
+  /** in.voltkit.rtc.HW_AEC: the handset's own echo canceller and noise suppressor, where it has them. */
+  hardwareEchoCancellation: boolean;
+  /** in.voltkit.rtc.SCREEN_SHARE: react-native-webrtc's screen-share service is enabled. */
+  screenShareEnabled: boolean;
+  /** Whether the app's manifest declares the call service (VoltkitCallService), and its declared types. */
+  callServiceDeclared: boolean;
+  callServiceTypes: string[];
+  /** android.os.Build.VERSION.SDK_INT. */
+  sdkInt: number;
+  /** The version of this package the native code was built from: a mismatch with the JavaScript means a stale build. */
+  nativeVersion: string;
+  /**
+   * Whether react-native-webrtc uses the audio device module the init provider made, so audioMode and
+   * hardwareEchoCancellation apply. False when the app set its own in MainApplication (selectAudioInput still works
+   * when that one is a JavaAudioDeviceModule) or the provider did not run.
+   */
+  audioDeviceModule: boolean;
+};
+
+export interface Spec extends TurboModule {
+  getConstants(): Constants;
+
+  // ---- audio: mode, focus and routing, process-wide; held by each connected client --------------------------------
+  /**
+   * A client connected and manages audio: set up the call audio (mode, focus, routing) while any client holds it.
+   * Resolves with the holder to release. `speakerphone` sets the speaker-or-earpiece preference; null keeps the
+   * one setSpeakerphoneOn set.
+   */
+  audioAcquire(speakerphone: boolean | null): Promise<number>;
+  /** That client left; the last holder out puts the device's audio back as it found it. Unknown holders are ignored. */
+  audioRelease(holder: number): void;
+  /** The loudspeaker (true) or the earpiece (false) when no headset is connected; a headset still wins. Kept until changed. */
+  setSpeakerphoneOn(on: boolean): void;
+  /** The audio inputs and outputs now. */
+  listAudioDevices(): Promise<AudioDevice[]>;
+  /** Play call audio on this output while it stays connected. False when there is no such output, or in media mode. */
+  selectAudioOutput(deviceId: string): Promise<boolean>;
+  /**
+   * Record from this microphone (null: the default). False when there is no such input, or react-native-webrtc's audio
+   * device module is not a JavaAudioDeviceModule.
+   */
+  selectAudioInput(deviceId: string | null): Promise<boolean>;
+  /** Where call audio plays now, while a client holds the audio. */
+  currentAudioOutput(): Promise<AudioDevice | null>;
+
+  // ---- visibility ------------------------------------------------------------------------------------------------
+  /** Whether an activity of the app is started now (ProcessLifecycleOwner; AppState says background under dialogs). */
+  isAppVisible(): boolean;
+
+  // ---- the call service --------------------------------------------------------------------------------------------
+  /**
+   * Start the call service: a foreground service that keeps the call's network, microphone and timers alive in the
+   * background. Start it while the app is visible (Android's while-in-use rules). Rejects when the app does not
+   * declare it, a permission it needs is missing, or Android refuses it.
+   */
+  startCallService(options: CallServiceOptions): Promise<CallServiceStatus>;
+  /** New text, or new types (a camera published, a share started or ended). Widen the types only while visible. */
+  updateCallService(options: CallServiceOptions): Promise<CallServiceStatus>;
+  /** Stop it (the call ended). Resolves when stopped; stopping one that is not running does nothing. */
+  stopCallService(): Promise<CallServiceStatus>;
+  getCallServiceStatus(): CallServiceStatus;
+
+  // ---- screen share ------------------------------------------------------------------------------------------------
+  /** Stop react-native-webrtc's MediaProjectionService once a share ended. True when one was running. */
+  stopScreenShareService(): Promise<boolean>;
+
+  // ---- native timers -----------------------------------------------------------------------------------------------
+  /**
+   * Fire onTimer(id) after `ms`, and every `ms` after that when `repeat`. A new start with a live id replaces it. Ids
+   * come from the caller and are never reused: a fire may already be on its way when the timer is stopped, so a fire
+   * for an id the caller no longer has is to be ignored.
+   */
+  timerStart(id: number, ms: number, repeat: boolean): void;
+  timerStop(id: number): void;
+
+  readonly onAudioDevicesChanged: CodegenTypes.EventEmitter<AudioDevicesChangedEvent>;
+  readonly onAudioOutputChanged: CodegenTypes.EventEmitter<AudioOutputChangedEvent>;
+  readonly onAudioFocusChanged: CodegenTypes.EventEmitter<AudioFocusChangedEvent>;
+  readonly onMicrophoneError: CodegenTypes.EventEmitter<MicrophoneErrorEvent>;
+  readonly onAppVisibilityChanged: CodegenTypes.EventEmitter<AppVisibilityChangedEvent>;
+  readonly onNetworkAvailable: CodegenTypes.EventEmitter<NetworkAvailableEvent>;
+  readonly onCallServiceEvent: CodegenTypes.EventEmitter<CallServiceEvent>;
+  readonly onTimer: CodegenTypes.EventEmitter<number>;
+}
+
+export default TurboModuleRegistry.get<Spec>('VoltkitRtc');