---
title: Exploring the Capacitor Audio Recorder API
description: "Practical guide to the Capacitor Audio Recorder API: record audio with silence detection in your Ionic and Capacitor apps."
date: 
  created: 2025-07-12
  updated: 2026-07-17
authors:
  - robingenz
categories:
  - Capacitor
  - Guides
  - SDKs
links:
  - Capacitor Audio Recorder: sdks/capacitor/audio-recorder.md
faq: true
---

# Exploring the Capacitor Audio Recorder API

Audio recording has become a fundamental feature in modern mobile applications, enabling users to capture voice memos, create audio content, and implement voice-driven functionality. With the [Capacitor Audio Recorder plugin](../../sdks/capacitor/audio-recorder.md) from Capawesome, developers can integrate comprehensive audio recording capabilities into their Ionic and Capacitor applications, providing high-performance recording features across Android, iOS, and Web platforms through a unified API that simplifies the complexity of platform-specific audio implementations.

<!-- more -->

## Installation

To install the Capacitor Audio Recorder plugin, please refer to the [Installation](../../sdks/capacitor/audio-recorder.md/#installation) section in the plugin documentation.

## Usage

Let's explore the key features of the Capacitor Audio Recorder API and how to implement them in your Ionic applications.

### Start Recording

To begin recording audio, use the [`startRecording(...)`](../../sdks/capacitor/audio-recorder.md#startrecording) method. This method initializes the recording session and begins capturing audio from the device's microphone:

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

const startRecording = async () => {
  try {
    await AudioRecorder.startRecording();
    console.log('Recording started successfully');
  } catch (error) {
    console.error('Failed to start recording:', error);
  }
};
```

The recording will begin immediately when this method is called. Make sure to handle any errors that may occur during the recording initialization, such as permission issues or device compatibility problems.

### Pause and Resume Recording

The Capacitor Audio Recorder API provides full control over recording sessions with pause and resume functionality. Use the [`pauseRecording(...)`](../../sdks/capacitor/audio-recorder.md#pauserecording) method to temporarily pause the recording without stopping it completely:

```ts
const pauseRecording = async () => {
  try {
    await AudioRecorder.pauseRecording();
    console.log('Recording paused');
  } catch (error) {
    console.error('Failed to pause recording:', error);
  }
};
```

To resume a paused recording, use the [`resumeRecording(...)`](../../sdks/capacitor/audio-recorder.md#resumerecording) method:

```ts
const resumeRecording = async () => {
  try {
    await AudioRecorder.resumeRecording();
    console.log('Recording resumed');
  } catch (error) {
    console.error('Failed to resume recording:', error);
  }
};
```

This pause and resume functionality allows users to have more control over their recording sessions without losing previous audio content.

### Stop Recording

To complete the recording session and retrieve the recorded audio, use the [`stopRecording(...)`](../../sdks/capacitor/audio-recorder.md#stoprecording) method:

```ts
const stopRecording = async () => {
  try {
    const result = await AudioRecorder.stopRecording();
    console.log('Recording stopped');
    console.log('Audio blob:', result.blob); // Only available on web
    console.log('Audio URI:', result.uri); // Only available on Android and iOS
  } catch (error) {
    console.error('Failed to stop recording:', error);
  }
};
```

The `stopRecording(...)` method returns an object containing both a blob and URI representation of the recorded audio. The blob can be used for web-based operations, while the URI provides a file path for native platform operations.

### Event Handling

The Capacitor Audio Recorder API provides event listeners to handle various recording states and errors. Proper event handling is crucial for creating a robust recording experience.

#### `recordingError` Event

The `recordingError` event is triggered when an error occurs during the recording process. It's important to handle this event to provide appropriate feedback to users:

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

const addErrorListener = () => {
  AudioRecorder.addListener('recordingError', (error) => {
    console.error('Recording error occurred:', error);
    alert('Recording failed. Please try again.');
  });
};
```

Always implement error handling to ensure users are informed when recording issues occur and can take appropriate action.

#### `recordingStopped` Event

The `recordingStopped` event is triggered when the recording session ends, either by user action or system interruption:

```ts
const addStoppedListener = () => {
  AudioRecorder.addListener('recordingStopped', (result) => {
    console.log('Recording stopped:', result);
  });
};
```

This event is useful for handling recording completion and updating your application's state accordingly.

### Permission Handling

Before using any recording functionality, ensure your application has the necessary microphone permissions. The Capacitor Audio Recorder API provides methods to check and request permissions:

```ts
const checkPermissions = async () => {
  try {
    const permissions = await AudioRecorder.checkPermissions();
    if (permissions.microphone !== 'granted') {
      console.log('Microphone permission not granted');
      return false;
    }
    return true;
  } catch (error) {
    console.error('Failed to check permissions:', error);
    return false;
  }
};

const requestPermissions = async () => {
  try {
    const permissions = await AudioRecorder.requestPermissions();
    if (permissions.microphone === 'granted') {
      console.log('Microphone permission granted');
      return true;
    } else {
      console.log('Microphone permission denied');
      return false;
    }
  } catch (error) {
    console.error('Failed to request permissions:', error);
    return false;
  }
};
```

Always check for permissions before attempting to record audio, and provide clear feedback to users about why permissions are needed.

## Best Practices

When implementing audio recording with the Capacitor Audio Recorder API, consider these best practices:

1. **Handle permissions proactively**: Always check and request microphone permissions before starting recording operations. Use the [`checkPermissions(...)`](../../sdks/capacitor/audio-recorder.md#checkpermissions) and [`requestPermissions(...)`](../../sdks/capacitor/audio-recorder.md#requestpermissions) methods to ensure your application has the necessary access. Provide clear explanations to users about why audio permissions are required.

2. **Implement comprehensive error handling**: Use the [`recordingError`](../../sdks/capacitor/audio-recorder.md#addlistenerrecordingerror) event listener to handle recording failures gracefully. Provide meaningful error messages to users and implement fallback mechanisms when recording fails. This ensures a smooth user experience even when technical issues occur.

3. **Manage recording state properly**: Keep track of recording states (recording, paused, stopped) in your application and provide appropriate UI feedback. Use the [`recordingStopped`](../../sdks/capacitor/audio-recorder.md#addlistenerrecordingstopped) event to update your interface and handle the completion of recording sessions. This helps users understand the current recording status and available actions.

## FAQ

### Is pause and resume supported on every platform?

Not universally on older Android. Pausing and resuming a recording works on Android SDK 24+, iOS, and web — on older Android versions, the underlying `MediaRecorder` API doesn't expose a pause/resume capability, so those two methods aren't available there.

### What happens to the recorded audio if I call `cancelRecording()` instead of `stopRecording()`?

The audio is discarded rather than returned. `cancelRecording()` stops the session without producing a blob or URI, so it's the right call when a user backs out of a recording mid-way rather than wanting the partial audio saved.

### Does the `recordingStopped` event fire if the recording is cancelled or errors out?

No. The event only fires when a recording completes via `stopRecording()` — it's explicitly documented not to fire if the recording is cancelled, paused, or if an error interrupts it. If you need to react to those other outcomes, you have to handle `cancelRecording()`'s return and the `recordingError` event separately.

### Can a recording resume automatically after a phone call interrupts it?

Yes on iOS, if you opt in. Setting `autoResumeAfterInterruption: true` in `startRecording()`'s options tells the plugin to resume automatically once an audio session interruption (like an incoming call) ends — though the system only does this if it determines resuming is actually appropriate for that interruption type. This option has no effect on Android or web.

### Is the `recordingError` event available on every platform?

No — it's iOS-only. On Android and web, recording failures surface as a rejected promise from the method call itself (`startRecording`, `stopRecording`, etc.) rather than through this event listener, so your error handling needs to cover both paths if you're targeting all three platforms.

## Conclusion

The Capacitor Audio Recorder Plugin from Capawesome provides a comprehensive solution for integrating audio recording capabilities into Ionic applications. By offering a unified API across multiple platforms, it enables developers to create powerful audio-enabled applications without the complexity of platform-specific implementations.

Recording is often only half of the feature: to play recordings back, including in the background with lock screen media controls, read [How to Play Audio in the Background in a Capacitor App](./how-to-play-audio-in-the-background-in-capacitor.md).

To stay updated with the latest updates, features, and news about the Capawesome, Capacitor, and Ionic ecosystem, subscribe to the [Capawesome newsletter](/newsletter/){:target="_blank"} and follow us on [X (formerly Twitter)](https://x.com/capawesomeio){:target="_blank"}.

If you have any questions or need assistance with the Capacitor Audio Recorder Plugin, feel free to reach out to the Capawesome team. We're here to help you implement robust audio recording features in your Ionic applications.