Skip to main content
Types for configuring iOS audio session settings. These are used when controlling audio behavior during transcription, particularly with realtime transcription.
These types are iOS-only and will have no effect on Android.

​
AudioSessionCategoryIos

Enum defining iOS audio session categories. Based on AVAudioSessionCategory.
​
Ambient
enum
Mix with other audio. Audio continues even when the device is locked or the silent switch is on.
​
SoloAmbient
enum
Default category. Silences other audio but allows playback when device is unlocked.
​
Playback
enum
For playing recorded audio or other media. Silences other audio.
​
Record
enum
For recording audio only. Silences playback audio.
​
PlayAndRecord
enum
For simultaneous recording and playback. Common for VoIP and voice chat apps.
​
MultiRoute
enum
For routing audio to multiple outputs simultaneously (e.g., USB and HDMI).

​
AudioSessionCategoryOptionIos

Enum defining iOS audio session category options. Based on AVAudioSessionCategoryOptions.
​
MixWithOthers
enum
Allow audio from this session to mix with audio from other apps.
​
DuckOthers
enum
Lower the volume of other audio sessions while this session is active.
​
InterruptSpokenAudioAndMixWithOthers
enum
Interrupt spoken audio content (like podcasts) but mix with other audio.
​
AllowBluetooth
enum
Allow Bluetooth hands-free devices to appear as available input routes.
​
AllowBluetoothA2DP
enum
Allow Bluetooth A2DP devices to appear as available output routes.
​
AllowAirPlay
enum
Allow AirPlay devices to appear as available output routes.
​
DefaultToSpeaker
enum
Route audio to the built-in speaker instead of the receiver.

​
AudioSessionModeIos

Enum defining iOS audio session modes. Based on AVAudioSessionMode.
​
Default
enum
Default audio session mode.
​
VoiceChat
enum
Optimized for two-way voice communication (e.g., VoIP).
​
VideoChat
enum
Optimized for video chat applications.
​
GameChat
enum
Optimized for in-game voice chat.
​
VideoRecording
enum
Optimized for recording video with audio.
​
Measurement
enum
For audio input/output measurements. Minimizes system audio processing.
​
MoviePlayback
enum
Optimized for playing back video content.
​
SpokenAudio
enum
For spoken audio content like podcasts or audiobooks.

​
AudioSessionSettingIos

Interface combining audio session configuration properties.
​
category
AudioSessionCategoryIos
required
The audio session category.
​
options
AudioSessionCategoryOptionIos[]
Array of category options to apply.
​
mode
AudioSessionModeIos
The audio session mode.
​
active
boolean
Whether to activate the audio session.

​
Usage Example

​
With Realtime Transcription

import { 
  AudioSessionCategoryIos,
  AudioSessionCategoryOptionIos,
  AudioSessionModeIos 
} from 'whisper.rn'

const options = {
  language: 'en',
  audioSessionOnStartIos: {
    category: AudioSessionCategoryIos.PlayAndRecord,
    options: [
      AudioSessionCategoryOptionIos.DefaultToSpeaker,
      AudioSessionCategoryOptionIos.AllowBluetooth
    ],
    mode: AudioSessionModeIos.VoiceChat,
    active: true
  },
  audioSessionOnStopIos: 'restore' // Restore previous audio session
}

const { promise, stop } = await context.transcribeRealtime(options)

​
Manual Audio Session Control

import { AudioSessionIos } from 'whisper.rn'

// Set category with options
await AudioSessionIos.setCategory(
  AudioSessionCategoryIos.Record,
  [AudioSessionCategoryOptionIos.AllowBluetooth]
)

// Set mode
await AudioSessionIos.setMode(AudioSessionModeIos.VoiceChat)

// Activate
await AudioSessionIos.setActive(true)

// Get current settings
const category = await AudioSessionIos.getCurrentCategory()
const mode = await AudioSessionIos.getCurrentMode()

​
Common Configurations

​
Voice Recording

{
  category: AudioSessionCategoryIos.Record,
  mode: AudioSessionModeIos.VoiceChat,
  active: true
}

​
VoIP Application

{
  category: AudioSessionCategoryIos.PlayAndRecord,
  options: [
    AudioSessionCategoryOptionIos.DefaultToSpeaker,
    AudioSessionCategoryOptionIos.AllowBluetooth
  ],
  mode: AudioSessionModeIos.VoiceChat,
  active: true
}

​
Background Audio Mixing

{
  category: AudioSessionCategoryIos.Playback,
  options: [AudioSessionCategoryOptionIos.MixWithOthers],
  mode: AudioSessionModeIos.SpokenAudio,
  active: true
}

​
Notes

  • Audio session changes only affect iOS devices
  • Use 'restore' for audioSessionOnStopIos to automatically restore the previous state
  • The AudioSessionIos utility is deprecated - prefer using audioSessionOnStartIos/audioSessionOnStopIos options
  • Changing audio session settings may require microphone permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us