Add audioSessionConfiguration to ElevenLabsProvider (#397)

feat: Add audioSessionConfiguration to ElevenLabsProvider

- Add AudioSessionConfiguration interface to types
- Add audioSessionConfiguration prop to ElevenLabsProvider
- Configure LiveKit audio session based on allowMixingWithOthers setting
- Update README with usage documentation
- Add .pnpm-store to .gitignore

Author: coryetzkorn

.gitignore

@@ -12,6 +12,7 @@ __pycache__
 
 # dependencies
 node_modules
+.pnpm-store
 
 # IDEs and editors
 /.idea

packages/react-native/README.md

@@ -51,6 +51,27 @@ function App() {
     </ElevenLabsProvider>
   );
 }
+```
+
+### Audio Session Configuration
+
+By default, ElevenLabs uses an exclusive audio session for optimal voice quality. To allow concurrent audio playback (e.g., sound effects, notifications, background music):
+
+```typescript
+import React from 'react';
+import { ElevenLabsProvider, useConversation } from '@elevenlabs/react-native';
+
+function App() {
+  return (
+    <ElevenLabsProvider
+      audioSessionConfiguration={{
+        allowMixingWithOthers: true,
+      }}
+    >
+      <ConversationComponent />
+    </ElevenLabsProvider>
+  );
+}
 
 function ConversationComponent() {
   const conversation = useConversation({
@@ -207,7 +228,39 @@ console.log(conversation.isSpeaking);
 console.log(conversation.canSendFeedback);
 ```
 
-### Configuration Options
+### ElevenLabsProvider Configuration
+
+Configure the provider with optional settings:
+
+#### Audio Session Configuration
+
+Control how the SDK manages audio sessions with other audio sources:
+
+```typescript
+<ElevenLabsProvider
+  audioSessionConfiguration={{
+    allowMixingWithOthers: true, // Default: false
+  }}
+>
+  {/* Your app */}
+</ElevenLabsProvider>
+```
+
+**When to use `allowMixingWithOthers: true`:**
+- Playing connection/disconnection sound effects during conversations
+- Background music in your app
+- Notification sounds while agent is speaking
+- Multiple concurrent audio sources
+
+**Default behavior (`false`):**
+- Exclusive audio session for best voice quality
+- Other audio sources will be paused during conversations
+
+**Platform Notes:**
+- **iOS**: Adds `AVAudioSessionCategoryOptionMixWithOthers` to the audio session
+- **Android**: Uses `AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK` for audio focus
+
+### Conversation Hook Options
 
 Pass to `useConversation` hook to customize SDK behavior:
 

packages/react-native/src/ElevenLabsProvider.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import { createContext, useContext, useState } from 'react';
 import { registerGlobals } from '@livekit/react-native';
 import type { LocalParticipant } from 'livekit-client';
-import type { Callbacks, ConversationConfig, ConversationStatus, ClientToolsConfig } from './types';
+import type { Callbacks, ConversationConfig, ConversationStatus, ClientToolsConfig, AudioSessionConfiguration } from './types';
 import { constructOverrides } from './utils/overrides';
 import { DEFAULT_SERVER_URL } from './utils/constants';
 import { useConversationCallbacks } from './hooks/useConversationCallbacks';
@@ -81,9 +81,10 @@ export const useConversation = (options: ConversationOptions = {}): Conversation
 
 interface ElevenLabsProviderProps {
   children: React.ReactNode;
+  audioSessionConfiguration?: AudioSessionConfiguration;
 }
 
-export const ElevenLabsProvider: React.FC<ElevenLabsProviderProps> = ({ children }) => {
+export const ElevenLabsProvider: React.FC<ElevenLabsProviderProps> = ({ children, audioSessionConfiguration }) => {
   // Initialize globals on mount
   registerGlobals();
 
@@ -319,6 +320,7 @@ export const ElevenLabsProvider: React.FC<ElevenLabsProviderProps> = ({ children
         clientTools={clientToolsRef.current}
         updateCurrentEventId={updateCurrentEventId}
         onEndSession={endSession}
+        audioSessionConfiguration={audioSessionConfiguration}
       >
         {children}
       </LiveKitRoomWrapper>

packages/react-native/src/components/LiveKitRoomWrapper.tsx

@@ -2,7 +2,7 @@
 import React from 'react';
 import { LiveKitRoom } from '@livekit/react-native';
 import type { LocalParticipant } from 'livekit-client';
-import type { Callbacks, ClientToolsConfig } from '../types';
+import type { Callbacks, ClientToolsConfig, AudioSessionConfiguration } from '../types';
 import { MessageHandler } from './MessageHandler';
 
 interface LiveKitRoomWrapperProps {
@@ -20,6 +20,7 @@ interface LiveKitRoomWrapperProps {
   clientTools: ClientToolsConfig['clientTools'];
   onEndSession: (reason?: "user" | "agent") => void;
   updateCurrentEventId?: (eventId: number) => void;
+  audioSessionConfiguration?: AudioSessionConfiguration;
 }
 
 export const LiveKitRoomWrapper = ({
@@ -37,13 +38,32 @@ export const LiveKitRoomWrapper = ({
   clientTools,
   updateCurrentEventId,
   onEndSession,
+  audioSessionConfiguration,
 }: LiveKitRoomWrapperProps) => {
+  // Configure audio options based on audioSessionConfiguration
+  const audioOptions = React.useMemo(() => {
+    if (!audioSessionConfiguration?.allowMixingWithOthers) {
+      return true;
+    }
+
+    // When mixing is enabled, configure audio to allow concurrent playback
+    return {
+      audio: {
+        noiseSuppression: true,
+        echoCancellation: true,
+      },
+      audioSessionConfiguration: {
+        allowMixingWithOthers: true,
+      },
+    };
+  }, [audioSessionConfiguration]);
+
   return (
     <LiveKitRoom
       serverUrl={serverUrl}
       token={token}
       connect={connect}
-      audio={true}
+      audio={audioOptions}
       video={false}
       options={{
         adaptiveStream: { pixelDensity: 'screen' },

packages/react-native/src/index.ts

@@ -12,4 +12,5 @@ export type {
   ConversationOptions,
   ConversationConfig,
   ConversationEvent,
+  AudioSessionConfiguration,
 } from "./types";

packages/react-native/src/types.ts

@@ -1,15 +1,15 @@
 import type * as Types from "@elevenlabs/types";
 import type {
+  AsrInitiationMetadataEvent as AsrMetadataEvent,
+  Callbacks,
+  ConversationMetadata,
+  Mode as ConversationMode,
   Incoming,
-  Outgoing,
   Interruption,
-  ConversationMetadata,
-  Ping,
   Role as MessageRole,
-  Mode as ConversationMode,
+  Outgoing,
+  Ping,
   Status,
-  Callbacks,
-  AsrInitiationMetadataEvent as AsrMetadataEvent,
 } from "@elevenlabs/types";
 export type { Callbacks } from "@elevenlabs/types";
 
@@ -139,3 +139,20 @@ export type ConversationEvent =
   | ConversationMetadataEvent
   | AsrInitiationMetadataEvent
   | AgentChatResponsePartEvent;
+
+/**
+ * Audio session configuration for controlling how the SDK handles audio
+ */
+export interface AudioSessionConfiguration {
+  /**
+   * Whether audio should mix with other audio sources.
+   * When true, the SDK will configure the audio session to allow
+   * concurrent audio playback with other audio sources.
+   *
+   * iOS: Adds AVAudioSessionCategoryOptionMixWithOthers
+   * Android: Uses AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK
+   *
+   * @default false (exclusive audio session)
+   */
+  allowMixingWithOthers?: boolean;
+}