backward compatible

Author: hiroshihorie

example/index.js

@@ -1,7 +1,7 @@
 import { AppRegistry } from 'react-native';
 import App from './src/App';
 import { name as appName } from './app.json';
-import { registerGlobals, setLogLevel, useIOSAudioManagement } from '@livekit/react-native';
+import { registerGlobals, setLogLevel, setupIOSAudioManagement } from '@livekit/react-native';
 import { LogLevel } from 'livekit-client';
 import { setupErrorLogHandler } from './src/utils/ErrorLogHandler';
 import { setupCallService } from './src/callservice/CallService';
@@ -17,4 +17,4 @@ setupCallService();
 registerGlobals();
 AppRegistry.registerComponent(appName, () => App);
 
-useIOSAudioManagement();
+setupIOSAudioManagement();

src/audio/AudioManager.ts

@@ -1,3 +1,4 @@
+import { Platform } from 'react-native';
 import AudioSession, {
   type AppleAudioConfiguration,
 } from './AudioSession';
@@ -10,65 +11,97 @@ export type AudioEngineConfigurationState = {
   preferSpeakerOutput: boolean;
 };
 
+type CleanupFn = () => void;
+
 /**
- * Handles setting the appropriate AVAudioSession options automatically
- * depending on the audio track states of the Room.
+ * Sets up automatic iOS audio session management based on audio engine state.
+ *
+ * Call this once at app startup (e.g. in index.js). For usage inside React
+ * components, use {@link useIOSAudioManagement} instead.
  *
- * @param preferSpeakerOutput
- * @param onConfigureNativeAudio A custom method for determining options used.
+ * @param preferSpeakerOutput - Whether to prefer speaker output. Defaults to true.
+ * @param onConfigureNativeAudio - Optional custom callback for determining audio configuration.
+ * @returns A cleanup function that removes the event handlers.
  */
-export function useIOSAudioManagement(
+export function setupIOSAudioManagement(
   preferSpeakerOutput = true,
-  onConfigureNativeAudio?: (configurationState: AudioEngineConfigurationState) => AppleAudioConfiguration
-) {
+  onConfigureNativeAudio?: (
+    configurationState: AudioEngineConfigurationState
+  ) => AppleAudioConfiguration
+): CleanupFn {
+  if (Platform.OS !== 'ios') {
+    return () => {};
+  }
+
   let audioEngineState: AudioEngineConfigurationState = {
     isPlayoutEnabled: false,
     isRecordingEnabled: false,
-    preferSpeakerOutput: preferSpeakerOutput,
+    preferSpeakerOutput,
   };
 
-  const tryConfigure = async (newState: AudioEngineConfigurationState, oldState: AudioEngineConfigurationState) => {
-    if ((!newState.isPlayoutEnabled && !newState.isRecordingEnabled) && (oldState.isPlayoutEnabled || oldState.isRecordingEnabled)) {
-      log.info("AudioSession deactivating...")
-      await AudioSession.stopAudioSession()
+  const tryConfigure = async (
+    newState: AudioEngineConfigurationState,
+    oldState: AudioEngineConfigurationState
+  ) => {
+    if (
+      !newState.isPlayoutEnabled &&
+      !newState.isRecordingEnabled &&
+      (oldState.isPlayoutEnabled || oldState.isRecordingEnabled)
+    ) {
+      log.info('AudioSession deactivating...');
+      await AudioSession.stopAudioSession();
     } else if (newState.isRecordingEnabled || newState.isPlayoutEnabled) {
-      const config = onConfigureNativeAudio ? onConfigureNativeAudio(newState) : getDefaultAppleAudioConfigurationForAudioState(newState);
-      log.info("AudioSession configuring category:", config.audioCategory)
-      await AudioSession.setAppleAudioConfiguration(config)
+      const config = onConfigureNativeAudio
+        ? onConfigureNativeAudio(newState)
+        : getDefaultAppleAudioConfigurationForAudioState(newState);
+      log.info('AudioSession configuring category:', config.audioCategory);
+      await AudioSession.setAppleAudioConfiguration(config);
       if (!oldState.isPlayoutEnabled && !oldState.isRecordingEnabled) {
-        log.info("AudioSession activating...")
-        await AudioSession.startAudioSession()
+        log.info('AudioSession activating...');
+        await AudioSession.startAudioSession();
       }
     }
   };
 
-  const handleEngineStateUpdate = async ({ isPlayoutEnabled, isRecordingEnabled }: { isPlayoutEnabled: boolean, isRecordingEnabled: boolean }) => {
+  const handleEngineStateUpdate = async ({
+    isPlayoutEnabled,
+    isRecordingEnabled,
+  }: {
+    isPlayoutEnabled: boolean;
+    isRecordingEnabled: boolean;
+  }) => {
     const oldState = audioEngineState;
-    const newState = {
+    const newState: AudioEngineConfigurationState = {
       isPlayoutEnabled,
       isRecordingEnabled,
       preferSpeakerOutput: audioEngineState.preferSpeakerOutput,
     };
 
-    // If this throws, the audio engine will not continue it's operation
+    // If this throws, the audio engine will not continue its operation
     await tryConfigure(newState, oldState);
     // Update the audio state only if configure succeeds
     audioEngineState = newState;
   };
 
-  // Attach audio engine events
   audioDeviceModuleEvents.setWillEnableEngineHandler(handleEngineStateUpdate);
   audioDeviceModuleEvents.setDidDisableEngineHandler(handleEngineStateUpdate);
+
+  return () => {
+    audioDeviceModuleEvents.setWillEnableEngineHandler(null);
+    audioDeviceModuleEvents.setDidDisableEngineHandler(null);
+  };
 }
 
 function getDefaultAppleAudioConfigurationForAudioState(
-  configurationState: AudioEngineConfigurationState,
+  configurationState: AudioEngineConfigurationState
 ): AppleAudioConfiguration {
   if (configurationState.isRecordingEnabled) {
     return {
       audioCategory: 'playAndRecord',
       audioCategoryOptions: ['allowBluetooth', 'mixWithOthers'],
-      audioMode: configurationState.preferSpeakerOutput ? 'videoChat' : 'voiceChat',
+      audioMode: configurationState.preferSpeakerOutput
+        ? 'videoChat'
+        : 'voiceChat',
     };
   } else if (configurationState.isPlayoutEnabled) {
     return {

src/audio/AudioManagerLegacy.ts

@@ -0,0 +1,89 @@
+/**
+ * Backward-compatible wrappers for the legacy AudioManager API.
+ *
+ * These exports preserve the old `useIOSAudioManagement(room, ...)` signature
+ * and the removed `getDefaultAppleAudioConfigurationForMode` function so that
+ * existing consumers continue to compile without changes.
+ *
+ * New code should use `setupIOSAudioManagement` from `./AudioManager` instead.
+ */
+import { useEffect } from 'react';
+import type { Room } from 'livekit-client';
+import type { AppleAudioConfiguration, AudioTrackState } from './AudioSession';
+import {
+  setupIOSAudioManagement,
+  type AudioEngineConfigurationState,
+} from './AudioManager';
+
+/**
+ * @deprecated Use {@link setupIOSAudioManagement} instead.
+ *   The `room` parameter is ignored — audio session is now managed
+ *   via audio engine events, not room track counts.
+ */
+export function useIOSAudioManagement(
+  room: Room,
+  preferSpeakerOutput: boolean = true,
+  onConfigureNativeAudio?: (
+    trackState: AudioTrackState,
+    preferSpeakerOutput: boolean
+  ) => AppleAudioConfiguration
+) {
+  useEffect(() => {
+    let wrappedOnConfig:
+      | ((state: AudioEngineConfigurationState) => AppleAudioConfiguration)
+      | undefined;
+
+    if (onConfigureNativeAudio) {
+      const legacyCb = onConfigureNativeAudio;
+      wrappedOnConfig = (state: AudioEngineConfigurationState) =>
+        legacyCb(engineStateToTrackState(state), state.preferSpeakerOutput);
+    }
+
+    const cleanup = setupIOSAudioManagement(
+      preferSpeakerOutput,
+      wrappedOnConfig
+    );
+    return cleanup;
+  }, [preferSpeakerOutput, onConfigureNativeAudio]);
+}
+
+/**
+ * @deprecated Use the default behavior of `setupIOSAudioManagement` instead.
+ */
+export function getDefaultAppleAudioConfigurationForMode(
+  mode: AudioTrackState,
+  preferSpeakerOutput: boolean = true
+): AppleAudioConfiguration {
+  if (mode === 'remoteOnly') {
+    return {
+      audioCategory: 'playback',
+      audioCategoryOptions: ['mixWithOthers'],
+      audioMode: 'spokenAudio',
+    };
+  } else if (mode === 'localAndRemote' || mode === 'localOnly') {
+    return {
+      audioCategory: 'playAndRecord',
+      audioCategoryOptions: ['allowBluetooth', 'mixWithOthers'],
+      audioMode: preferSpeakerOutput ? 'videoChat' : 'voiceChat',
+    };
+  }
+
+  return {
+    audioCategory: 'soloAmbient',
+    audioCategoryOptions: [],
+    audioMode: 'default',
+  };
+}
+
+function engineStateToTrackState(
+  state: AudioEngineConfigurationState
+): AudioTrackState {
+  if (state.isRecordingEnabled && state.isPlayoutEnabled) {
+    return 'localAndRemote';
+  } else if (state.isRecordingEnabled) {
+    return 'localOnly';
+  } else if (state.isPlayoutEnabled) {
+    return 'remoteOnly';
+  }
+  return 'none';
+}

src/audio/AudioSession.ts

@@ -197,6 +197,15 @@ export type AppleAudioConfiguration = {
   audioMode?: AppleAudioMode;
 };
 
+/**
+ * @deprecated Use `AudioEngineConfigurationState` from `AudioManager` instead.
+ */
+export type AudioTrackState =
+  | 'none'
+  | 'remoteOnly'
+  | 'localOnly'
+  | 'localAndRemote';
+
 export default class AudioSession {
   /**
    * Applies the provided audio configuration to the underlying AudioSession.

src/index.tsx

@@ -17,6 +17,7 @@ import AudioSession, {
   type AppleAudioCategoryOption,
   type AppleAudioConfiguration,
   type AppleAudioMode,
+  type AudioTrackState,
 } from './audio/AudioSession';
 import type { AudioConfiguration } from './audio/AudioSession';
 import { PixelRatio, Platform } from 'react-native';
@@ -165,6 +166,7 @@ export * from './useParticipant'; // deprecated
 export * from './useRoom'; // deprecated
 export * from './logger';
 export * from './audio/AudioManager';
+export * from './audio/AudioManagerLegacy';
 
 export {
   AudioSession,
@@ -183,6 +185,7 @@ export type {
   AppleAudioCategoryOption,
   AppleAudioConfiguration,
   AppleAudioMode,
+  AudioTrackState,
   LogLevel,
   SetLogLevelOptions,
   RNKeyProviderOptions,