@stream-io/video-react-native-sdk 1.43.0 → 1.45.0

package/src/hooks/push/useCallingExpWithCallingStateEffect.ts

@@ -17,7 +17,7 @@ export const useCallingExpWithCallingStateEffect = () => {
     useCallStateHooks();
 
   const activeCall = useCall();
-  const { isMute, microphone } = useMicrophoneState();
+  const { optimisticStatus, microphone } = useMicrophoneState();
   const callMembers = useCallMembers();
   const participants = useParticipants();
 
@@ -30,7 +30,7 @@ export const useCallingExpWithCallingStateEffect = () => {
 
   const callDisplayName = useMemo(
     () =>
-      callCustomDisplayName ??
+      callCustomDisplayName ||
       getCallDisplayName(callMembers, participants, currentUserId),
     [callMembers, participants, currentUserId, callCustomDisplayName],
   );
@@ -135,8 +135,14 @@ export const useCallingExpWithCallingStateEffect = () => {
       return;
     }
 
-    callingx.setMutedCall(activeCallCid, isMute);
-  }, [activeCallCid, isMute]);
+    if (optimisticStatus === undefined) {
+      logger.debug(
+        `useCallingExpWithCallingStateEffect: mic status is not resolved yet, skipping mute sync for: ${activeCallCid}`,
+      );
+      return;
+    }
+    callingx.setMutedCall(activeCallCid, optimisticStatus === 'disabled');
+  }, [activeCallCid, optimisticStatus]);
 
   // Sync mute state from CallKit → app (only for system-initiated mute actions)
   useEffect(() => {
@@ -165,7 +171,8 @@ export const useCallingExpWithCallingStateEffect = () => {
           return;
         }
 
-        const isCurrentlyMuted = microphone.state.status === 'disabled';
+        const isCurrentlyMuted =
+          microphone.state.optimisticStatus === 'disabled';
         if (isCurrentlyMuted === muted) {
           logger.debug(
             `useCallingExpWithCallingStateEffect: Mic toggle is already in the desired state: ${muted} for call: ${activeCallCid}`,

package/src/hooks/useLoopbackRecording.ts

@@ -1,146 +1,71 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { NativeModules } from 'react-native';
-import { combineLatest } from 'rxjs';
 import {
-  Call,
   CallingState,
+  DEFAULT_LOOPBACK_RECORDING_DURATION_MS,
+  LOOPBACK_STREAMS_WAIT_TIMEOUT_MS,
+  clampLoopbackRecordingDuration,
+  getLoopbackStreams,
   videoLoggerSystem,
-  type StreamVideoParticipant,
+  waitForLoopbackStreams,
+  withLoopbackAudioEnabled,
+  type LoopbackStreams,
+  type LoopbackTracks,
 } from '@stream-io/video-client';
+
 import { useCall, useCallStateHooks } from '@stream-io/video-react-bindings';
 
 /** @internal */
 const { StreamVideoReactNative } = NativeModules;
 
-// Upper bound on how long `startRecording` will wait for the SFU to
-// echo loopback tracks back via the Subscriber. Tuned generously since
-// this includes connection setup; consumers that want shorter feedback
-// should call `stopRecording` to cancel the wait early.
-const STREAMS_WAIT_TIMEOUT_MS = 10 * 1000;
-const DEFAULT_RECORDING_DURATION = 10 * 1000;
-const MIN_RECORDING_DURATION = 5 * 1000;
-const MAX_RECORDING_DURATION = 2 * 60 * 1000;
-
-type LoopbackStreams = {
-  loopbackVideoStream?: MediaStream;
-  loopbackAudioStream?: MediaStream;
-};
-
 export type LoopbackRecordingState = 'idle' | 'awaiting-streams' | 'recording';
 
-export type ResolvedStreams = {
-  audioTrack?: MediaStreamTrack;
-  videoTrack?: MediaStreamTrack;
-};
+export type ResolvedStreams = LoopbackTracks;
 
 export interface StartLoopbackRecordingOptions {
-  /**
-   * Whether to include the loopback video track in the recording.
-   * Defaults to `true`. Set to `false` for an audio-only recording.
-   * Audio is always recorded — there is no video-only mode.
-   */
+  /** Whether to include loopback video. Audio is always recorded. */
   includeVideo?: boolean;
-  /**
-   * Maximum recording duration in milliseconds, after which the
-   * recording auto-stops and finalises the file.
-   *
-   * Defaults to `10_000` (10 seconds). Clamped to
-   * `[5_000, 120_000]` (5 seconds — 2 minutes).
-   */
+  /** Maximum recording duration in milliseconds. */
   maxDurationMs?: number;
 }
 
 export interface UseLoopbackRecordingResult {
-  /**
-   * Start a recording. The hook waits internally for the SFU loopback
-   * streams to arrive on `localParticipant`, then begins recording.
-   *
-   * The returned promise resolves with the produced `file://` URI **at
-   * the recording's terminal moment** — whether that is the auto-stop
-   * timer expiring, an explicit `stopRecording` call, or a cleanup-
-   * driven stop on unmount/leave. Resolves with `null` if no file was
-   * produced (writer torn down before any buffer arrived, or
-   * `stopRecording` was called while still awaiting streams). Rejects
-   * on a fatal error, if a recording is already running, or if the
-   * stream-wait times out.
-   */
+  /** Starts recording and resolves with a `file://` URI. */
   startRecording: (
     options?: StartLoopbackRecordingOptions,
   ) => Promise<string | null>;
-  /**
-   * Signal an early termination. While `awaiting-streams` this aborts
-   * the wait and the pending `startRecording` resolves with `null`.
-   * While `recording` this signals native finalisation and resolves
-   * once it completes.
-   */
+  /** Stops the current recording or stream wait. */
   stopRecording: () => Promise<void>;
-  /**
-   * Recursively delete every file under the SDK's recordings directory.
-   */
+  /** Deletes all SDK recording files. */
   clearRecordings: () => Promise<void>;
-  /**
-   * List every `file://` URI in the SDK's recordings directory, sorted
-   * most-recent first. Returns an empty array if the directory doesn't
-   * exist yet.
-   */
+  /** Lists SDK recording file URIs. */
   getRecordings: () => Promise<string[]>;
-  /**
-   * Lifecycle phase of the recording, owned by the hook:
-   *  - `'idle'`: no recording in progress.
-   *  - `'awaiting-streams'`: `startRecording` was called but the SFU
-   *    has not yet echoed the loopback tracks back.
-   *  - `'recording'`: native pipeline is actively writing.
-   */
+  /** Lifecycle phase of the recording. */
   recordingState: LoopbackRecordingState;
-  /**
-   * The SFU loopback video stream on the local participant, when
-   * present. Identified by reference inequality against
-   * `call.camera.state.mediaStream`.
-   */
+  /** SFU-echoed video stream on the local participant. */
   loopbackVideoStream?: MediaStream;
-  /**
-   * The SFU loopback audio stream on the local participant, when
-   * present. Identified by reference inequality against
-   * `call.microphone.state.mediaStream`.
-   */
+  /** SFU-echoed audio stream on the local participant. */
   loopbackAudioStream?: MediaStream;
 }
 
-/**
- * Records the SFU loopback streams (audio + video) on the local participant
- * to a local MP4 file. Designed for the `allowOwnTracksLoopback` pre-call test mode:
- * the SFU echoes the caller's published tracks back through the Subscriber
- * peer connection. The hook identifies the loopback streams on the local
- * participant by reference inequality against
- * `call.camera.state.mediaStream` / `call.microphone.state.mediaStream` —
- * the canonical references to the local capture — and captures them.
- */
+/** Records SFU loopback streams to a local MP4 file. */
 export function useLoopbackRecording(): UseLoopbackRecordingResult {
   const call = useCall();
-  const {
-    useCallCallingState,
-    useParticipantCount,
-    useLocalParticipant,
-    useCameraState,
-    useMicrophoneState,
-  } = useCallStateHooks();
+  const { useCallCallingState, useParticipantCount, useLocalParticipant } =
+    useCallStateHooks();
   const callingState = useCallCallingState();
   const participantCount = useParticipantCount();
   const localParticipant = useLocalParticipant();
-  const { mediaStream: cameraStream } = useCameraState();
-  const { mediaStream: microphoneStream } = useMicrophoneState();
 
   const [recordingState, setRecordingState] =
     useState<LoopbackRecordingState>('idle');
   const recordingStateRef = useRef<LoopbackRecordingState>('idle');
   const isMountedRef = useRef(true);
-  // Used to abort the awaiting-streams wait on stop / leave / unmount.
   const awaitAbortRef = useRef<AbortController | null>(null);
 
   const loopbackStreams = useMemo<LoopbackStreams>(
-    () =>
-      getLoopbackStreamsFor(localParticipant, cameraStream, microphoneStream),
-    [localParticipant, cameraStream, microphoneStream],
+    () => getLoopbackStreams(call, localParticipant),
+    [call, localParticipant],
   );
 
   const updateState = useCallback((next: LoopbackRecordingState) => {
@@ -177,7 +102,7 @@ export function useLoopbackRecording(): UseLoopbackRecordingResult {
   const startRecording = useCallback(
     async ({
       includeVideo = true,
-      maxDurationMs = DEFAULT_RECORDING_DURATION,
+      maxDurationMs = DEFAULT_LOOPBACK_RECORDING_DURATION_MS,
     }: StartLoopbackRecordingOptions = {}): Promise<string | null> => {
       if (!call) {
         return null;
@@ -200,12 +125,11 @@ export function useLoopbackRecording(): UseLoopbackRecordingResult {
       awaitAbortRef.current = new AbortController();
       updateState('awaiting-streams');
 
-      let audioTrack: MediaStreamTrack | undefined;
       try {
         const streams = await waitForLoopbackStreams(call, {
           includeVideo,
           signal: awaitAbortRef.current.signal,
-          timeoutMs: STREAMS_WAIT_TIMEOUT_MS,
+          timeoutMs: LOOPBACK_STREAMS_WAIT_TIMEOUT_MS,
         });
 
         if (streams === null) {
@@ -215,38 +139,21 @@ export function useLoopbackRecording(): UseLoopbackRecordingResult {
           return null;
         }
 
-        audioTrack = streams.audioTrack;
-        const videoTrackId = streams.videoTrack?.id;
-
-        // The loopback audio track lands disabled (the SDK default-mutes
-        // it to prevent echo). Enable it so the native recording
-        // pipeline receives PCM; `finally` returns it to muted.
-        if (audioTrack) {
-          audioTrack.enabled = true;
-        }
         updateState('recording');
 
-        const clampedDuration = Math.min(
-          MAX_RECORDING_DURATION,
-          Math.max(MIN_RECORDING_DURATION, maxDurationMs),
-        );
-
-        // Pre-size the native encoder to the publisher's max video
-        // publish-option dimension. Without this, the encoder locks to
-        // whatever the SFU happens to echo *first* and stays there for the
-        // rest of the recording even after the network improves and
-        // higher layers arrive.
         const publishMaxDim = call.getMaxVideoPublishDimension();
 
         try {
-          const uri: string | null =
-            await StreamVideoReactNative.startTrackRecording({
-              videoTrackId,
-              maxDurationMs: Math.round(clampedDuration),
-              targetWidth: publishMaxDim?.width,
-              targetHeight: publishMaxDim?.height,
-            });
-          return uri;
+          return await withLoopbackAudioEnabled(
+            streams,
+            (): Promise<string | null> =>
+              StreamVideoReactNative.startTrackRecording({
+                videoTrackId: streams.videoTrack?.id,
+                maxDurationMs: clampLoopbackRecordingDuration(maxDurationMs),
+                targetWidth: publishMaxDim?.width,
+                targetHeight: publishMaxDim?.height,
+              }),
+          );
         } catch (error) {
           videoLoggerSystem
             .getLogger('useLoopbackRecording')
@@ -254,9 +161,6 @@ export function useLoopbackRecording(): UseLoopbackRecordingResult {
           throw new Error('failed to start recording');
         }
       } finally {
-        if (audioTrack) {
-          audioTrack.enabled = false;
-        }
         awaitAbortRef.current = null;
         updateState('idle');
       }
@@ -288,11 +192,6 @@ export function useLoopbackRecording(): UseLoopbackRecordingResult {
     }
   }, []);
 
-  // Auto-stop on call leave / end. Aborts an awaiting-streams wait or
-  // signals native finalisation depending on which phase we're in.
-  // Without this, leaving the call mid-recording would leave native
-  // encoders mid-write while the SFU subscriber tracks end under their
-  // feet — undefined final file state.
   useEffect(() => {
     if (
       callingState === CallingState.LEFT ||
@@ -305,8 +204,6 @@ export function useLoopbackRecording(): UseLoopbackRecordingResult {
     }
   }, [callingState, stopRecording]);
 
-  // Auto-stop if another participant joins. Loopback recording is a
-  // single-user pre-call test.
   useEffect(() => {
     if (recordingState !== 'idle' && participantCount > 1) {
       stopRecording().catch(() => {});
@@ -337,112 +234,3 @@ export function useLoopbackRecording(): UseLoopbackRecordingResult {
     loopbackAudioStream: loopbackStreams.loopbackAudioStream,
   };
 }
-
-function getLoopbackStreamsFor(
-  participant: StreamVideoParticipant | undefined,
-  cameraStream: MediaStream | undefined,
-  microphoneStream: MediaStream | undefined,
-): LoopbackStreams {
-  return {
-    loopbackVideoStream:
-      participant?.videoStream && participant.videoStream !== cameraStream
-        ? participant.videoStream
-        : undefined,
-    loopbackAudioStream:
-      participant?.audioStream && participant.audioStream !== microphoneStream
-        ? participant.audioStream
-        : undefined,
-  };
-}
-
-/**
- * Subscribe to `localParticipant$` and resolve once the requested loopback
- * streams are present on the participant. Aborts cleanly on `signal`
- * (resolves `null`) and rejects on timeout.
- */
-function waitForLoopbackStreams(
-  call: Call,
-  opts: { includeVideo: boolean; signal: AbortSignal; timeoutMs: number },
-): Promise<ResolvedStreams | null> {
-  return new Promise((resolve, reject) => {
-    const initial = getLoopbackStreams(
-      call.state.localParticipant,
-      call.camera.state.mediaStream,
-      call.microphone.state.mediaStream,
-      opts.includeVideo,
-    );
-    if (initial) {
-      resolve(initial);
-      return;
-    }
-
-    const cleanup = () => {
-      subscription.unsubscribe();
-      if (timeoutId !== undefined) {
-        clearTimeout(timeoutId);
-      }
-      opts.signal.removeEventListener('abort', onAbort);
-    };
-
-    const onAbort = () => {
-      cleanup();
-      resolve(null);
-    };
-
-    opts.signal.addEventListener('abort', onAbort);
-
-    const timeoutId = setTimeout(() => {
-      cleanup();
-      reject(
-        new Error(
-          'useLoopbackRecording: timed out waiting for loopback streams. ' +
-            'Ensure the call was joined with `allowOwnTracksLoopback: true` and ' +
-            'that the SFU is configured to echo self-sub tracks.',
-        ),
-      );
-    }, opts.timeoutMs);
-
-    const subscription = combineLatest([
-      call.state.localParticipant$,
-      call.camera.state.mediaStream$,
-      call.microphone.state.mediaStream$,
-    ]).subscribe(([participant, cameraStream, microphoneStream]) => {
-      const ready = getLoopbackStreams(
-        participant,
-        cameraStream,
-        microphoneStream,
-        opts.includeVideo,
-      );
-      if (ready) {
-        cleanup();
-        resolve(ready);
-      }
-    });
-  });
-}
-
-function getLoopbackStreams(
-  participant: StreamVideoParticipant | undefined,
-  cameraStream: MediaStream | undefined,
-  microphoneStream: MediaStream | undefined,
-  includeVideo: boolean,
-): ResolvedStreams | undefined {
-  if (!participant) return undefined;
-
-  const { loopbackAudioStream, loopbackVideoStream } = getLoopbackStreamsFor(
-    participant,
-    cameraStream,
-    microphoneStream,
-  );
-
-  const audioTrack = loopbackAudioStream?.getAudioTracks()[0];
-  const videoTrack = includeVideo
-    ? loopbackVideoStream?.getVideoTracks()[0]
-    : undefined;
-
-  if (!audioTrack || (includeVideo && !videoTrack)) {
-    return undefined;
-  }
-
-  return { audioTrack, videoTrack };
-}

package/src/modules/call-manager/CallManager.ts

@@ -9,8 +9,8 @@ import type {
   AudioEndpoint as CallingxAudioEndpoint,
   AudioEndpointsSnapshot as CallingxAudioSnapshot,
 } from '@stream-io/react-native-callingx';
-import { getCallingxLibIfAvailable } from '../../utils/push/libs/callingx';
 import { videoLoggerSystem } from '@stream-io/video-client';
+import { getCallingxLibIfAvailable } from '../../utils/push/libs';
 
 const NativeManager = NativeModules.StreamInCallManager;
 const CallingxModule = getCallingxLibIfAvailable();
@@ -296,26 +296,32 @@ class SpeakerManager {
   };
 }
 
-const shouldBypassForCallKit = (): boolean => {
-  if (Platform.OS !== 'ios') {
-    return false;
-  }
-  if (!CallingxModule) {
-    return false;
-  }
-  return (
-    CallingxModule.isSetup &&
-    (CallingxModule.hasRegisteredCall() || CallingxModule.isOngoingCallsEnabled)
-  );
-};
-
 export class CallManager {
   audioDevices = new AudioDevicesManager();
   ios = new IOSCallManager();
   speaker = new SpeakerManager();
 
   /**
-   * Starts the in call manager.
+   * The audio config recorded via {@link start}. The SDK's internal call manager reads it at the
+   * next join-time start and applies it before the native audio manager is activated.
+   */
+  private storedConfig?: StreamInCallManagerConfig;
+
+  /**
+   * The config recorded via {@link start}.
+   *
+   * @internal Read by the SDK's internal call manager at join; not intended for app use.
+   */
+  getStoredConfig = (): StreamInCallManagerConfig | undefined =>
+    this.storedConfig;
+
+  /**
+   * Records the desired audio config for the call.
+   *
+   * This does NOT start the native audio manager — the SDK owns native start/stop and applies this
+   * config at the next join-time start (before the audio manager is activated). Call it **before**
+   * joining. Calling it mid-call only updates the stored config; it does not change the running
+   * call's audio, and the new config takes effect on the next call/rejoin.
    *
    * @param config.audioRole The audio role to set. It can be one of the following:
    * - `'communicator'`: (Default) For use cases like video or voice calls.
@@ -325,80 +331,43 @@ export class CallManager {
    * It prioritizes high-quality stereo audio streaming.
    * Audio routing is controlled by the OS, and manual switching is not supported.
    *
-   * @param config.deviceEndpointType The default audio device endpoint type to set. It can be one of the following:
-   * - `'speaker'`: (Default) For normal video or voice calls.
+   * @param config.deviceEndpointType Overrides the default audio device endpoint. When omitted,
+   * the SDK uses the device derived from the call settings. It can be one of the following:
+   * - `'speaker'`: For normal video or voice calls.
    * - `'earpiece'`: For voice-only mobile call type scenarios.
-   *
-   * @param config.enableStereoAudioOutput Whether to enable stereo audio output. Only supported for listener audio role.
    */
   start = (config?: StreamInCallManagerConfig): void => {
-    if (shouldBypassForCallKit()) {
-      if (config?.audioRole === 'communicator' && CallingxModule) {
-        const type = config.deviceEndpointType ?? 'speaker';
-        safeNativeCall('setDefaultAudioDeviceEndpointType (callingx)', () =>
-          CallingxModule.setDefaultAudioDeviceEndpointType(type),
-        );
-        safeNativeCall('setDefaultAudioDeviceEndpointType', () =>
-          NativeManager.setDefaultAudioDeviceEndpointType(type),
-        );
-      }
-      videoLoggerSystem
-        .getLogger('CallManager')
-        .debug(
-          'start: skipping start as callkit is handling the audio session',
-        );
-      return;
-    }
-    if (isAndroidTelecomManaged()) {
-      // Telecom owns routing/focus; forward the sticky preference to callingx and run in
-      // telecom-managed mode (StreamInCallManager keeps proximity/keep-screen-on only).
-      if (config?.audioRole !== 'listener' && CallingxModule) {
-        safeNativeCall('setDefaultAudioDeviceEndpointType (callingx)', () =>
-          CallingxModule.setDefaultAudioDeviceEndpointType(
-            config?.deviceEndpointType ?? 'speaker',
-          ),
-        );
-      }
-      NativeManager.setTelecomManagedMode(true);
-      NativeManager.setAudioRole(config?.audioRole ?? 'communicator');
-      NativeManager.start();
-      return;
-    }
-    if (Platform.OS === 'android') {
-      NativeManager.setTelecomManagedMode(false);
-    }
-    NativeManager.setAudioRole(config?.audioRole ?? 'communicator');
-    if (config?.audioRole === 'communicator') {
-      const type = config.deviceEndpointType ?? 'speaker';
-      NativeManager.setDefaultAudioDeviceEndpointType(type);
-    }
-    if (config?.audioRole === 'listener' && config.enableStereoAudioOutput) {
-      NativeManager.setEnableStereoAudioOutput(true);
-    }
-    NativeManager.start();
+    this.storedConfig = config;
+    videoLoggerSystem
+      .getLogger('CallManager')
+      .debug('start: stored call manager config', { config });
   };
 
   /**
-   * Stops the in call manager.
+   * Clears the stored audio config.
    */
   stop = (): void => {
-    if (shouldBypassForCallKit()) {
-      videoLoggerSystem
-        .getLogger('CallManager')
-        .debug('stop: skipping stop as callkit is handling the audio session');
-      return;
-    }
-    NativeManager.stop();
+    this.storedConfig = undefined;
+    videoLoggerSystem
+      .getLogger('CallManager')
+      .debug('[public] stop(): cleared stored config');
   };
 
   /**
    * For debugging purposes, will emit a log event with the current audio state.
    * in the native layer.
+   *
+   * NOTE: This method might be called outside of the call JOIN/LEFT window,
+   * so it may lead to default peer connection factory and adm being created.
    */
   logAudioState = (): void => NativeManager.logAudioState();
 
   /**
    * For debugging purposes, returns the current audio state as a string.
+   *
+   * NOTE: This method might be called outside of the call JOIN/LEFT window,
+   * so it may lead to default peer connection factory and adm being created.
+   *
    * @returns A string containing the current audio state information.
    */
   getAudioStateLog = (): string => NativeManager.getAudioStateLog();

package/src/modules/call-manager/native-module.d.ts

@@ -92,6 +92,19 @@ export interface CallManager extends NativeModule {
    */
   setEnableStereoAudioOutput: (enable: boolean) => void;
 
+  /**
+   * Sets the microphone mute mode on the call's ADM. No-ops when no call ADM is active. iOS-only.
+   * @param mode - The `AudioEngineMuteMode` value.
+   */
+  setMuteMode: (mode: number) => void;
+
+  /**
+   * Keeps the recording chain prepared while muted so the engine stays
+   * full-duplex. No-ops when no call ADM is active. iOS-only.
+   * @param enabled - Whether to keep recording always prepared.
+   */
+  setRecordingAlwaysPreparedMode: (enabled: boolean) => void;
+
   /**
    * Log the current audio state natively.
    * Meant for debugging purposes.

package/src/modules/call-manager/types.ts

@@ -56,5 +56,4 @@ export type StreamInCallManagerConfig =
     }
   | {
       audioRole: 'listener';
-      enableStereoAudioOutput?: boolean;
     };

package/src/utils/StreamVideoRN/index.ts

@@ -1,6 +1,7 @@
 import type { StreamVideoConfig } from './types';
 import pushLogoutCallbacks from '../internal/pushLogoutCallback';
 import { setupIosVoipPushEvents } from '../push/setupIosVoipPushEvents';
+import { setupAndroidPushEvents } from '../push/setupAndroidPushEvents';
 import { setupCallingExpEvents } from '../push/setupCallingExpEvents';
 import {
   extractCallingExpOptions,
@@ -133,6 +134,7 @@ export class StreamVideoRN {
 
     setupCallingExpEvents(pushConfig);
     setupIosVoipPushEvents(pushConfig);
+    setupAndroidPushEvents(pushConfig);
   }
 
   static getConfig() {

package/src/utils/StreamVideoRN/types.ts

@@ -26,6 +26,9 @@ export type StreamVideoConfig = {
    * @default undefined
    */
   push?: {
+    /**
+     * @deprecated Expo is auto-detected; this value is ignored and the property will be removed in a future major version.
+     */
     isExpo?: boolean;
     /**
      * The publish options to be used when joining a call from a push notification.