@capgo/capacitor-audio-recorder

Capture audio clips across iOS, Android, and the Web with a consistent Capacitor API.

Why Capacitor Audio Recorder?

The only free and up-to-date audio recording plugin for Capacitor:

• Same JavaScript API - Compatible interface with paid plugins
• Full feature set - Pause/resume, configurable bitrates, sample rates
• Cross-platform - iOS, Android, and Web support
• Modern implementation - Uses latest platform APIs
• Event listeners - Real-time recording status and error handling

Perfect for voice memo apps, audio messaging, podcast recording, and any app needing audio capture.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/audio-recorder/

Compatibility

| Plugin version | Capacitor compatibility | Maintained | | -------------- | ----------------------- | ---------- | | v8.*.* | v8.*.* | ✅ | | v7.*.* | v7.*.* | On demand | | v6.*.* | v6.*.* | ❌ | | v5.*.* | v5.*.* | ❌ |

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

npm install @capgo/capacitor-audio-recorder
npx cap sync

Background recording

The plugin does not automatically put your app into a background-safe mode — you need to configure each platform so the process is allowed to keep running while the screen is locked.

• iOS: Enable the Background Modes → Audio capability in Xcode (or add UIBackgroundModes with an audio entry in Info.plist). With that flag enabled, startRecording will continue while the device is locked because the plugin already uses an AVAudioSession category that supports background capture.

• Android: Recording continues as long as the app process stays alive. For hour-long sessions you should move the recording work into a foreground service with an ongoing notification to prevent the OS from stopping the process. Add the required permissions, e.g.:

  <!-- android/app/src/main/AndroidManifest.xml -->
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
  <uses-permission android:name="android.permission.WAKE_LOCK" />

  Then start a foreground service before calling startRecording (or trigger the recording inside that service). The plugin itself does not create the service for you, so you can use your preferred foreground-service implementation or a background-task helper plugin to start/stop it alongside the recording UI.

API

• startRecording(...)
• pauseRecording()
• resumeRecording()
• stopRecording()
• cancelRecording()
• getRecordingStatus()
• getCurrentAmplitude()
• checkPermissions()
• requestPermissions()
• addListener('recordingError', ...)
• addListener('recordingPaused', ...)
• addListener('recordingStopped', ...)
• removeAllListeners()
• getPluginVersion()
• Interfaces
• Type Aliases
• Enums

Capacitor plugin contract for recording audio.

startRecording(...)

startRecording(options?: StartRecordingOptions | undefined) => Promise<void>

Start recording audio using the device microphone.

| Param | Type | Description | | ------------- | ----------------------------------------------------------------------- | -------------------------------- | | options | StartRecordingOptions | Recording configuration options. |

Since: 1.0.0

pauseRecording()

pauseRecording() => Promise<void>

Pause the ongoing recording. Only available on Android (API 24+), iOS, and Web.

Since: 1.0.0

resumeRecording()

resumeRecording() => Promise<void>

Resume a previously paused recording.

Since: 1.0.0

stopRecording()

stopRecording() => Promise<StopRecordingResult>

Stop the current recording and persist the recorded audio.

Returns: Promise<StopRecordingResult>

Since: 1.0.0

cancelRecording()

cancelRecording() => Promise<void>

Cancel the current recording and discard any captured audio.

Since: 1.0.0

getRecordingStatus()

getRecordingStatus() => Promise<GetRecordingStatusResult>

Retrieve the current recording status.

Returns: Promise<GetRecordingStatusResult>

Since: 1.0.0

getCurrentAmplitude()

getCurrentAmplitude() => Promise<GetCurrentAmplitudeResult>

Retrieve the current input amplitude (microphone level) as a normalized number in the [0, 1] range.

Intended for driving live visualizations such as VU meters or waveforms while recording. Returns 0 when no recording is active. Designed for UI-rate polling — a 60–100 ms interval is a good starting point for a waveform. Avoid calling it in a tight loop; each call crosses the JS/native bridge.

Returns: Promise<GetCurrentAmplitudeResult>

Since: 8.1.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Return the current permission state for accessing the microphone.

Returns: Promise<PermissionStatus>

Since: 1.0.0

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request permission to access the microphone.

Returns: Promise<PermissionStatus>

Since: 1.0.0

addListener('recordingError', ...)

addListener(eventName: 'recordingError', listenerFunc: (event: RecordingErrorEvent) => void) => Promise<PluginListenerHandle>

Listen for recording errors.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------- | | eventName | 'recordingError' | | listenerFunc | (event: RecordingErrorEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('recordingPaused', ...)

addListener(eventName: 'recordingPaused', listenerFunc: () => void) => Promise<PluginListenerHandle>

Listen for pause events emitted when a recording is paused.

| Param | Type | | ------------------ | ------------------------------ | | eventName | 'recordingPaused' | | listenerFunc | () => void |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('recordingStopped', ...)

addListener(eventName: 'recordingStopped', listenerFunc: (event: RecordingStoppedEvent) => void) => Promise<PluginListenerHandle>

Listen for recording completion events.

| Param | Type | | ------------------ | --------------------------------------------------------------------------------------- | | eventName | 'recordingStopped' | | listenerFunc | (event: StopRecordingResult) => void |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all registered listeners.

Since: 1.0.0

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns: Promise<{ version: string; }>

Since: 1.0.0

Interfaces

StartRecordingOptions

Options accepted by {@link CapacitorAudioRecorderPlugin.startRecording}.

| Prop | Type | Description | Since | | --------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | ----- | | audioSessionCategoryOptions | AudioSessionCategoryOption[] | The audio session category options for recording. Only available on iOS. | 1.0.0 | | audioSessionMode | AudioSessionMode | The audio session mode for recording. Only available on iOS. | 1.0.0 | | bitRate | number | The audio bit rate in bytes per second. Only available on Android and iOS. | 1.0.0 | | sampleRate | number | The audio sample rate in Hz. Only available on Android and iOS. | 1.0.0 |

StopRecordingResult

Result returned by {@link CapacitorAudioRecorderPlugin.stopRecording}.

| Prop | Type | Description | Since | | -------------- | ------------------- | ------------------------------------------------------------------------- | ----- | | blob | Blob | The recorded audio as a Blob. Only available on Web. | 1.0.0 | | duration | number | The duration of the recording in milliseconds. | 1.0.0 | | uri | string | The URI pointing to the recorded file. Only available on Android and iOS. | 1.0.0 |

GetRecordingStatusResult

Result returned by {@link CapacitorAudioRecorderPlugin.getRecordingStatus}.

| Prop | Type | Description | Since | | ------------ | ----------------------------------------------------------- | ----------------------------- | ----- | | status | RecordingStatus | The current recording status. | 1.0.0 |

GetCurrentAmplitudeResult

Result returned by {@link CapacitorAudioRecorderPlugin.getCurrentAmplitude}.

| Prop | Type | Description | Since | | ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | value | number | The current input amplitude normalized to the [0, 1] range, where 0 represents silence and 1 represents the maximum level the platform can report. The value is 0 when no recording is active. Note: the source signal differs between platforms — Android reports the peak sample amplitude since the last call, iOS reports the average power in dB converted to linear, and Web reports the RMS of the latest frame. Consumers that need cross-platform parity may want to apply a per-platform scaling curve. | 8.1.0 |

PermissionStatus

Permission information returned by {@link CapacitorAudioRecorderPlugin.checkPermissions} and {@link CapacitorAudioRecorderPlugin.requestPermissions}.

| Prop | Type | Description | Since | | ----------------- | ----------------------------------------------------------- | ----------------------------------------- | ----- | | recordAudio | PermissionState | The permission state for audio recording. | 1.0.0 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

RecordingErrorEvent

Event emitted when an error occurs during recording.

| Prop | Type | Description | Since | | ------------- | ------------------- | ------------------ | ----- | | message | string | The error message. | 1.0.0 |

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

RecordingStoppedEvent

Event emitted when a recording completes.

StopRecordingResult

Enums

AudioSessionCategoryOption

| Members | Value | | ------------------------------------------ | --------------------------------------------------------- | | AllowAirPlay | 'ALLOW_AIR_PLAY' | | AllowBluetooth | 'ALLOW_BLUETOOTH' | | AllowBluetoothA2DP | 'ALLOW_BLUETOOTH_A2DP' | | DefaultToSpeaker | 'DEFAULT_TO_SPEAKER' | | DuckOthers | 'DUCK_OTHERS' | | InterruptSpokenAudioAndMixWithOthers | 'INTERRUPT_SPOKEN_AUDIO_AND_MIX_WITH_OTHERS' | | MixWithOthers | 'MIX_WITH_OTHERS' | | OverrideMutedMicrophoneInterruption | 'OVERRIDE_MUTED_MICROPHONE_INTERRUPTION' |

AudioSessionMode

| Members | Value | | -------------------- | ------------------------------ | | Default | 'DEFAULT' | | GameChat | 'GAME_CHAT' | | Measurement | 'MEASUREMENT' | | SpokenAudio | 'SPOKEN_AUDIO' | | VideoChat | 'VIDEO_CHAT' | | VideoRecording | 'VIDEO_RECORDING' | | VoiceChat | 'VOICE_CHAT' |

RecordingStatus

| Members | Value | | --------------- | ------------------------ | | Inactive | 'INACTIVE' | | Recording | 'RECORDING' | | Paused | 'PAUSED' |

Credit

This plugin was inspired from: https://github.com/kesha-antonov/react-native-background-downloader