Capacitor plugin for seamless audio recording using the device's microphone. Supports Android, iOS, and Web with advanced features and high performance.

The Capacitor Audio Recorder plugin is one of the most advanced audio recording solutions for Capacitor apps. Here are some of the key features:

• 🖥️ Cross-platform: Supports Android, iOS and Web.
• ⏯️ Full Control: Start, pause, resume, cancel and stop recording.
• 🚀 Performance: Record long audio sessions without any performance issues.
• 🔑 Permissions: Check and request microphone permissions.
• 🔊 Events: Listen for events like recordingError, recordingPaused or recordingStopped.
• 🌙 Background Mode: Record audio even when the app is in the background.
• 🤝 Compatibility: Compatible with the Audio Player, Speech Recognition and Speech Synthesis plugins.
• 📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
• 🔁 Up-to-date: Always supports the latest Capacitor version.
• ⭐️ Support: Priority support from the Capawesome Team.
• ✨ Handcrafted: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just open an issue and we'll take a look!

The Audio Recorder plugin is typically used whenever an app needs to capture audio with the device's microphone, for example:

• Voice messages: Record voice messages in chat apps and play them back with the Audio Player plugin.
• Voice notes and memos: Let users record notes with full control to pause, resume, or cancel the recording.
• Dictation and transcription: Capture spoken audio that is later transcribed, for example by a server-side speech-to-text service.
• Interviews and long sessions: Record long audio sessions without performance issues, even while the app is in the background.

• Announcing the Capacitor Audio Recorder Plugin
• Exploring the Capacitor Audio Recorder API

This plugin is only available to Capawesome Insiders. First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Attention: Replace <YOUR_LICENSE_KEY> with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a Capawesome Insider.

Next, you can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/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 @capawesome-team/capacitor-audio-recorder
npx cap sync

If you are using Proguard, you need to add the following rules to your proguard-rules.pro file:

-keep class io.capawesome.capacitorjs.plugins.** { *; }

If you want to record audio in the background, ensure Background Modes capability is enabled with Audio, AirPlay, and Picture in Picture in your Xcode project. See Add a capability to a target for more information.

Add the NSMicrophoneUsageDescription key to the ios/App/App/Info.plist file, which tells the user why your app needs access to the user's contacts:

<key>NSMicrophoneUsageDescription</key>
<string>We need access to your microphone to record audio.</string>

No configuration required for this plugin.

The following examples show how to manage permissions, start a recording, save it to a custom location, stop and play it back, pause, resume or cancel it, read the recording status, and listen for recording events.

Recording requires the microphone permission. Check and request it before starting a recording:

import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const checkPermissions = async () => {
  const { recordAudio } = await AudioRecorder.checkPermissions();
  console.log('Record audio permission:', recordAudio);
};

const requestPermissions = async () => {
  const { recordAudio } = await AudioRecorder.requestPermissions();
  console.log('Record audio permission:', recordAudio);
};

Start recording audio in AAC format. You can optionally configure the bitrate and sample rate (Android and iOS) as well as the audio session category options and mode (iOS only):

import { AudioRecorder, AudioSessionCategoryOption, AudioSessionMode } from '@capawesome-team/capacitor-audio-recorder';

const startRecording = async () => {
  await AudioRecorder.startRecording({
    audioSessionCategoryOptions: [AudioSessionCategoryOption.DuckOthers],
    audioSessionMode: AudioSessionMode.Measurement,
    bitRate: 192000,
    sampleRate: 44100
  });
};

By default, the recording is saved to a temporary location in the cache directory. On Android and iOS, use the uri option to save it to a custom location instead, for example one generated with the Capacitor Filesystem plugin:

import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';
import { Directory, Filesystem } from '@capacitor/filesystem';

const startRecordingToCustomLocation = async () => {
  const { uri } = await Filesystem.getUri({
    directory: Directory.Data,
    path: 'recordings/my-recording.aac'
  });
  await AudioRecorder.startRecording({ uri });
};

Stop the recording to receive the recorded audio as a Blob (Web) or URI (Android and iOS), which you can then play back, for example with the Audio Player plugin:

import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';
import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';

const stopRecording = async () => {
  // Stop recording and get the audio blob or URI
  const { blob, uri } = await AudioRecorder.stopRecording();
  // Play the audio
  if (blob) {
    // Only available on Web
    await AudioPlayer.play({ blob });
  } else if (uri) {
    // Only available on Android and iOS
    await AudioPlayer.play({ uri });
  }
};

Pause a running recording and resume it later, or cancel it to discard the recorded audio. Pausing and resuming is only available on Android (SDK 24+), iOS and Web:

import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const pauseRecording = async () => {
  await AudioRecorder.pauseRecording();
};

const resumeRecording = async () => {
  await AudioRecorder.resumeRecording();
};

const cancelRecording = async () => {
  await AudioRecorder.cancelRecording();
};

Check whether a recording is currently inactive, active or paused:

import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const getRecordingStatus = async () => {
  const { status } = await AudioRecorder.getRecordingStatus();
  console.log('Recording status:', status);
};

Get notified when the recording is paused (e.g. when it is interrupted by a phone call), when it is stopped, or when an error occurs. The recordingError event is only available on iOS:

import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder';

const addRecordingErrorListener = async () => {
  await AudioRecorder.addListener('recordingError', (event) => {
    console.error('Recording error:', event.message);
  });
};

const addRecordingPausedListener = async () => {
  await AudioRecorder.addListener('recordingPaused', () => {
    console.log('Recording paused');
  });
};

const addRecordingStoppedListener = async () => {
  await AudioRecorder.addListener('recordingStopped', (event) => {
    console.log('Recording stopped:', event.uri);
  });
};

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

cancelRecording() => Promise<void>

Cancel the recording.

Since: 7.0.0

getRecordingStatus() => Promise<GetRecordingStatusResult>

Check if the device supports audio recording.

Returns: Promise<GetRecordingStatusResult>

Since: 7.0.0

pauseRecording() => Promise<void>

Pause the recording.

This method is only available on Android (SDK 24+), iOS and Web.

Since: 7.0.0

resumeRecording() => Promise<void>

Resume the recording.

This method is only available on Android (SDK 24+), iOS and Web.

Since: 7.0.0

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

Start recording audio in AAC format.

Since: 7.0.0

stopRecording() => Promise<StopRecordingResult>

Stop recording audio.

Returns: Promise<StopRecordingResult>

Since: 7.0.0

checkPermissions() => Promise<PermissionStatus>

Check permissions for audio recording.

Returns: Promise<PermissionStatus>

Since: 7.0.0

requestPermissions() => Promise<PermissionStatus>

Request permissions for audio recording.

Returns: Promise<PermissionStatus>

Since: 7.0.0

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

Called when an error occurs during recording. The recording will be cancelled.

Only available on iOS.

Returns: Promise<PluginListenerHandle>

Since: 7.0.0

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

Called when the recording is paused (e.g. when the recording is interrupted by a phone call).

Returns: Promise<PluginListenerHandle>

Since: 7.1.0

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

Called when the recording is resumed (e.g. after an audio session interruption ends, when autoResumeAfterInterruption is enabled).

Returns: Promise<PluginListenerHandle>

Since: 8.2.0

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

Called when the recording is stopped.

Note: This will not be called if the recording is cancelled or paused or if an error occurs.

Returns: Promise<PluginListenerHandle>

Since: 6.0.0

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

This typically happens when an incompatible combination of bitRate and sampleRate is passed to startRecording(...). The AAC encoder accepts the settings without error at start, but silently fails to encode, producing an empty file and triggering the recordingError event on stop.

For example, requesting bitRate: 256000 with sampleRate: 16000 (mono AAC) is invalid, because the requested bitrate is far higher than what the encoder can produce from the given sample rate. As a rule of thumb, AAC requires roughly bitRate <= sampleRate * channels * 6. Either lower the bitRate or raise the sampleRate (the default is 44100 Hz, which works with bitrates up to ~256 kbps):

await AudioRecorder.startRecording({
  bitRate: 256_000,
  sampleRate: 44_100,
});

The plugin records audio in AAC format. You can configure the bitrate (default: 192000 bytes per second) and sample rate (default: 44100 Hz) via the options of the startRecording(...) method on Android and iOS.

Yes, the plugin supports background recording. On iOS, you need to enable the Background Modes capability with Audio, AirPlay, and Picture in Picture in your Xcode project, as described in the Installation section.

The plugin needs access to the device's microphone, which you can check and request using the checkPermissions() and requestPermissions() methods. On iOS, you also need to add the NSMicrophoneUsageDescription key to your Info.plist file as described in the Installation section.

This typically happens when an incompatible combination of bitRate and sampleRate is passed to startRecording(...). The AAC encoder silently fails to encode, producing an empty file and triggering the recordingError event. Either lower the bitRate or raise the sampleRate. See the Troubleshooting section for more details.

By default, the recording is saved to a temporary location in the cache directory on Android and iOS, and its URI is returned by the stopRecording() method. You can save the recording to a custom location instead by passing the uri option to startRecording(...). On Web, the recorded audio is returned as a Blob.

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

• Audio Player: Play back recorded audio with background support.
• Speech Recognition: Transcribe speech into text (speech-to-text).
• Speech Synthesis: Synthesize speech from text (text-to-speech).

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

See CHANGELOG.md.

See BREAKING.md.

See LICENSE.