https://github.com/cap-go/capacitor-audio-recorder
Capacitor plugin to record audio on iOS and Android, keep active in background
https://github.com/cap-go/capacitor-audio-recorder
Last synced: 3 months ago
JSON representation
Capacitor plugin to record audio on iOS and Android, keep active in background
- Host: GitHub
- URL: https://github.com/cap-go/capacitor-audio-recorder
- Owner: Cap-go
- License: mpl-2.0
- Created: 2025-10-27T04:52:41.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-20T03:11:39.000Z (4 months ago)
- Last Synced: 2026-02-20T06:47:23.569Z (4 months ago)
- Language: Swift
- Size: 822 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# @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
```bash
npm install @capgo/capacitor-audio-recorder
npx cap sync
```
## API
* [`startRecording(...)`](#startrecording)
* [`pauseRecording()`](#pauserecording)
* [`resumeRecording()`](#resumerecording)
* [`stopRecording()`](#stoprecording)
* [`cancelRecording()`](#cancelrecording)
* [`getRecordingStatus()`](#getrecordingstatus)
* [`checkPermissions()`](#checkpermissions)
* [`requestPermissions()`](#requestpermissions)
* [`addListener('recordingError', ...)`](#addlistenerrecordingerror-)
* [`addListener('recordingPaused', ...)`](#addlistenerrecordingpaused-)
* [`addListener('recordingStopped', ...)`](#addlistenerrecordingstopped-)
* [`removeAllListeners()`](#removealllisteners)
* [`getPluginVersion()`](#getpluginversion)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
* [Enums](#enums)
Capacitor plugin contract for recording audio.
### startRecording(...)
```typescript
startRecording(options?: StartRecordingOptions | undefined) => Promise
```
Start recording audio using the device microphone.
| Param | Type | Description |
| ------------- | ----------------------------------------------------------------------- | -------------------------------- |
| **`options`** | StartRecordingOptions | Recording configuration options. |
**Since:** 1.0.0
--------------------
### pauseRecording()
```typescript
pauseRecording() => Promise
```
Pause the ongoing recording. Only available on Android (API 24+), iOS, and Web.
**Since:** 1.0.0
--------------------
### resumeRecording()
```typescript
resumeRecording() => Promise
```
Resume a previously paused recording.
**Since:** 1.0.0
--------------------
### stopRecording()
```typescript
stopRecording() => Promise
```
Stop the current recording and persist the recorded audio.
**Returns:** Promise<StopRecordingResult>
**Since:** 1.0.0
--------------------
### cancelRecording()
```typescript
cancelRecording() => Promise
```
Cancel the current recording and discard any captured audio.
**Since:** 1.0.0
--------------------
### getRecordingStatus()
```typescript
getRecordingStatus() => Promise
```
Retrieve the current recording status.
**Returns:** Promise<GetRecordingStatusResult>
**Since:** 1.0.0
--------------------
### checkPermissions()
```typescript
checkPermissions() => Promise
```
Return the current permission state for accessing the microphone.
**Returns:** Promise<PermissionStatus>
**Since:** 1.0.0
--------------------
### requestPermissions()
```typescript
requestPermissions() => Promise
```
Request permission to access the microphone.
**Returns:** Promise<PermissionStatus>
**Since:** 1.0.0
--------------------
### addListener('recordingError', ...)
```typescript
addListener(eventName: 'recordingError', listenerFunc: (event: RecordingErrorEvent) => void) => Promise
```
Listen for recording errors.
| Param | Type |
| ------------------ | --------------------------------------------------------------------------------------- |
| **`eventName`** | 'recordingError' |
| **`listenerFunc`** | (event: RecordingErrorEvent) => void |
**Returns:** Promise<PluginListenerHandle>
**Since:** 1.0.0
--------------------
### addListener('recordingPaused', ...)
```typescript
addListener(eventName: 'recordingPaused', listenerFunc: () => void) => Promise
```
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', ...)
```typescript
addListener(eventName: 'recordingStopped', listenerFunc: (event: RecordingStoppedEvent) => void) => Promise
```
Listen for recording completion events.
| Param | Type |
| ------------------ | --------------------------------------------------------------------------------------- |
| **`eventName`** | 'recordingStopped' |
| **`listenerFunc`** | (event: StopRecordingResult) => void |
**Returns:** Promise<PluginListenerHandle>
**Since:** 1.0.0
--------------------
### removeAllListeners()
```typescript
removeAllListeners() => Promise
```
Remove all registered listeners.
**Since:** 1.0.0
--------------------
### getPluginVersion()
```typescript
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 |
#### 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.
### 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