@capgo/capacitor-audio-recorder

Record audio from the microphone on iOS, Android and the web with one Capacitor API. Pause, resume, read the input level and save the clip when you are done.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-audio-recorder in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-audio-recorder to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Record: startRecording(), stopRecording() and cancelRecording() to capture or discard a clip.
• Pause and resume: pauseRecording() and resumeRecording() without starting a new file.
• Input level: getCurrentAmplitude() returns the microphone level from 0 to 1 for meters and waveforms.
• Status and events: getRecordingStatus() plus recordingPaused, recordingStopped, recordingError, and (iOS only) recordingInterruptionBegan / recordingInterruptionEnded listeners.
• Permissions: checkPermissions() and requestPermissions() for microphone access.
• Platforms: iOS, Android and Web. iOS uses AVFoundation, Android uses MediaRecorder, and web uses the browser recorder.

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

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

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-audio-recorder` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

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()
• resetAudioSessionForPlayback()
• getRecordingStatus()
• getCurrentAmplitude()
• checkPermissions()
• requestPermissions()
• addListener('recordingError', ...)
• addListener('recordingPaused', ...)
• addListener('recordingStopped', ...)
• addListener('recordingInterruptionBegan', ...)
• addListener('recordingInterruptionEnded', ...)
• 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.

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

resetAudioSessionForPlayback()

resetAudioSessionForPlayback() => Promise<void>

Reset the iOS audio session to .playback for normal-volume playback of recorded audio in the same app process (for example via an HTML audio element). No-op on Android and Web.

Since: 8.2.10

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.

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.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('recordingStopped', ...)

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

Listen for recording completion events.

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('recordingInterruptionBegan', ...)

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

Listen for the start of an audio session interruption while recording.

Only emitted on iOS when the system pauses or archives the active recording (for example when a phone call begins).

Returns: Promise<PluginListenerHandle>

Since: 8.2.0

addListener('recordingInterruptionEnded', ...)

addListener(eventName: 'recordingInterruptionEnded', listenerFunc: (event: RecordingInterruptionEndedEvent) => void) => Promise<PluginListenerHandle>

Listen for the end of an audio session interruption while recording.

Only emitted on iOS. Usually follows recordingInterruptionBegan, but may also fire after a recorder failure without a prior began event, with shouldResume set to false.

Returns: Promise<PluginListenerHandle>

Since: 8.2.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}.

StopRecordingResult

Result returned by {@link CapacitorAudioRecorderPlugin.stopRecording}.

GetRecordingStatusResult

Result returned by {@link CapacitorAudioRecorderPlugin.getRecordingStatus}.

GetCurrentAmplitudeResult

Result returned by {@link CapacitorAudioRecorderPlugin.getCurrentAmplitude}.

PermissionStatus

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

PluginListenerHandle

RecordingErrorEvent

Event emitted when an error occurs during recording.

RecordingInterruptionEndedEvent

Event emitted when an audio session interruption ends on iOS (for example after a phone call).

Type Aliases

PermissionState

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

RecordingStoppedEvent

Event emitted when a recording completes.

StopRecordingResult

Enums

AudioSessionCategoryOption

AudioSessionMode

RecordingStatus

Credit

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