@independo/capacitor-voice-recorder

<img src="https://user-images.githubusercontent.com/236501/85893648-1c92e880-b7a8-11ea-926d-95355b8175c7.png" width="128" height="128" alt="CapacitorJS Logo" /> <h3 align="center">Capacitor Voice Recorder</h3> <code>@independo/capacitor-voice-recorder</code> Capacitor plugin for audio recording <img src="https://img.shields.io/maintenance/yes/2026" alt="Maintenance Badge: until 2026" /> <a href="https://www.npmjs.com/package/@independo/capacitor-voice-recorder"><img src="https://img.shields.io/npm/l/@independo/capacitor-voice-recorder" alt="License Badge: MIT" /></a> <a href="https://www.npmjs.com/package/@independo/capacitor-voice-recorder"><img src="https://img.shields.io/npm/dw/@independo/capacitor-voice-recorder" alt="" role="presentation" /></a> <a href="https://www.npmjs.com/package/@independo/capacitor-voice-recorder"><img src="https://img.shields.io/npm/v/@independo/capacitor-voice-recorder" alt="" role="presentation" /></a> <a href="https://codecov.io/gh/independo-gmbh/capacitor-voice-recorder/branch/master"><img src="https://codecov.io/gh/independo-gmbh/capacitor-voice-recorder/branch/master/graph/badge.svg" alt="Coverage Badge: master" /></a> ## Overview The `@independo/capacitor-voice-recorder` plugin allows you to record audio on Android, iOS, and Web platforms. ## Installation ``` pnpm add @independo/capacitor-voice-recorder pnpm exec cap sync ``` ### Configuration #### Using with Android Add the following to your `AndroidManifest.xml`: ```xml <uses-permission android:name="android.permission.RECORD_AUDIO"/> ``` #### Using with iOS Add the following to your `Info.plist`: ```xml <key>NSMicrophoneUsageDescription</key> <string>This app uses the microphone to record audio.</string> ``` ### Requirements - Capacitor 8+ - iOS 15+ - Android minSdk 24+; builds require Java 21 (recommended). `pnpm verify:android` requires a Java version supported by the bundled Gradle wrapper (currently Java 21–24, with Java 21 recommended). ### Compatibility Versioning follows Capacitor versioning. Major versions of the plugin are compatible with major versions of Capacitor. | Plugin Version | Capacitor Version | Status | |----------------|-------------------|------------| | 8.* | 8 | Active | | 7.* | 7 | Deprecated | | 6.* | 6 | Deprecated | | 5.* | 5 | Deprecated | ### iOS Package Manager Support This plugin supports both CocoaPods and Swift Package Manager (SPM) on iOS. - CocoaPods (default Capacitor iOS template): `npx cap sync ios` - Swift Package Manager (SPM): migrate/create your iOS app to use SPM, then run `npx cap sync ios` ## Quick start Minimal flow for starting and stopping a recording: ```typescript import {VoiceRecorder} from '@independo/capacitor-voice-recorder'; export const startRecording = async () => { const permission = await VoiceRecorder.requestAudioRecordingPermission(); if (!permission.value) { throw new Error('Microphone permission not granted'); } await VoiceRecorder.startRecording(); }; export const stopRecording = async () => { const {value} = await VoiceRecorder.stopRecording(); return value; }; ``` ## API Below is an index of all available methods. Run `pnpm docgen` after updating any JSDoc comments to refresh this section. <docgen-index> * [`canDeviceVoiceRecord()`](#candevicevoicerecord) * [`requestAudioRecordingPermission()`](#requestaudiorecordingpermission) * [`hasAudioRecordingPermission()`](#hasaudiorecordingpermission) * [`startRecording(...)`](#startrecording) * [`stopRecording()`](#stoprecording) * [`pauseRecording()`](#pauserecording) * [`resumeRecording()`](#resumerecording) * [`getCurrentStatus()`](#getcurrentstatus) * [`addListener('voiceRecordingInterrupted', ...)`](#addlistenervoicerecordinginterrupted-) * [`addListener('voiceRecordingInterruptionEnded', ...)`](#addlistenervoicerecordinginterruptionended-) * [`removeAllListeners()`](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) </docgen-index> <docgen-api>  Interface for the VoiceRecorderPlugin which provides methods to record audio. ### canDeviceVoiceRecord() ```typescript canDeviceVoiceRecord() => Promise<GenericResponse> ``` Checks if the current device can record audio. On mobile, this function will always resolve to `{ value: true }`. In a browser, it will resolve to `{ value: true }` or `{ value: false }` based on the browser's ability to record. This method does not take into account the permission status, only if the browser itself is capable of recording at all. **Returns:** <code>Promise<<a href="#genericresponse">GenericResponse</a>></code> -------------------- ### requestAudioRecordingPermission() ```typescript requestAudioRecordingPermission() => Promise<GenericResponse> ``` Requests audio recording permission from the user. If the permission has already been provided, the promise will resolve with `{ value: true }`. Otherwise, the promise will resolve to `{ value: true }` or `{ value: false }` based on the user's response. **Returns:** <code>Promise<<a href="#genericresponse">GenericResponse</a>></code> -------------------- ### hasAudioRecordingPermission() ```typescript hasAudioRecordingPermission() => Promise<GenericResponse> ``` Checks if audio recording permission has been granted. Will resolve to `{ value: true }` or `{ value: false }` based on the status of the permission. The web implementation of this plugin uses the Permissions API, which is not widespread. If the status of the permission cannot be checked, the promise will reject with `COULD_NOT_QUERY_PERMISSION_STATUS`. In that case, use `requestAudioRecordingPermission` or `startRecording` and capture any exception that is thrown. **Returns:** <code>Promise<<a href="#genericresponse">GenericResponse</a>></code> -------------------- ### startRecording(...) ```typescript startRecording(options?: RecordingOptions | undefined) => Promise<GenericResponse> ``` Starts audio recording. On success, the promise will resolve to { value: true }. On error, the promise will reject with one of the following error codes: "MISSING_PERMISSION", "ALREADY_RECORDING", "MICROPHONE_BEING_USED", "DEVICE_CANNOT_VOICE_RECORD", or "FAILED_TO_RECORD". | Param | Type | Description | | ------------- | ------------------------------------------------------------- | ------------------------------ | | **`options`** | <code><a href="#recordingoptions">RecordingOptions</a></code> | The options for the recording. | **Returns:** <code>Promise<<a href="#genericresponse">GenericResponse</a>></code> -------------------- ### stopRecording() ```typescript stopRecording() => Promise<RecordingData> ``` Stops audio recording. Will stop the recording that has been previously started. If the function `startRecording` has not been called beforehand, the promise will reject with `RECORDING_HAS_NOT_STARTED`. If the recording has been stopped immediately after it has been started, the promise will reject with `EMPTY_RECORDING`. In a case of unknown error, the promise will reject with `FAILED_TO_FETCH_RECORDING`. On iOS, if a recording interrupted by the system cannot be merged, the promise will reject with `FAILED_TO_MERGE_RECORDING`. In case of success, the promise resolves to <a href="#recordingdata">RecordingData</a> containing the recording in base-64, the duration of the recording in milliseconds, and the MIME type. **Returns:** <code>Promise<<a href="#recordingdata">RecordingData</a>></code> -------------------- ### pauseRecording() ```typescript pauseRecording() => Promise<GenericResponse> ``` Pauses the ongoing audio recording. If the recording has not started yet, the promise will reject with an error code `RECORDING_HAS_NOT_STARTED`. On success, the promise will resolve to { value: true } if the pause was successful or { value: false } if the recording is already paused. On certain mobile OS versions, this function is not supported and will reject with `NOT_SUPPORTED_OS_VERSION`. **Returns:** <code>Promise<<a href="#genericresponse">GenericResponse</a>></code> -------------------- ### resumeRecording() ```typescript resumeRecording() => Promise<GenericResponse> ``` Resumes a paused or interrupted audio recording. If the recording has not started yet, the promise will reject with an error code `RECORDING_HAS_NOT_STARTED`. On success, the promise will resolve to { value: true } if the resume was successful or { value: false } if the recording is already running. On certain mobile OS versions, this function is not supported and will reject with `NOT_SUPPORTED_OS_VERSION`. **Returns:** <code>Promise<<a href="#genericresponse">GenericResponse</a>></code> -------------------- ### getCurrentStatus() ```typescript getCurrentStatus() => Promise<CurrentRecordingStatus> ``` Gets the current status of the voice recorder. Will resolve with one of the following values: `{ status: "NONE" }` if the plugin is idle and waiting to start a new recording. `{ status: "RECORDING" }` if the plugin is in the middle of recording. `{ status: "PAUSED" }` if the recording is paused. `{ status: "INTERRUPTED" }` if the recording was paused due to a system interruption. **Returns:** <code>Promise<<a href="#currentrecordingstatus">CurrentRecordingStatus</a>></code> -------------------- ### addListener('voiceRecordingInterrupted', ...) ```typescript addListener(eventName: 'voiceRecordingInterrupted', listenerFunc: (event: VoiceRecordingInterruptedEvent) => void) => Promise<PluginListenerHandle> ``` Listen for audio recording interruptions (e.g., phone calls, other apps using microphone). Available on iOS and Android only. | Param | Type | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | **`eventName`** | <code>'voiceRecordingInterrupted'</code> | The name of the event to listen for. | | **`listenerFunc`** | <code>(event: <a href="#voicerecordinginterruptedevent">VoiceRecordingInterruptedEvent</a>) => void</code> | The callback function to invoke when the event occurs. | **Returns:** <code>Promise<<a href="#pluginlistenerhandle">PluginListenerHandle</a>></code> -------------------- ### addListener('voiceRecordingInterruptionEnded', ...) ```typescript addListener(eventName: 'voiceRecordingInterruptionEnded', listenerFunc: (event: VoiceRecordingInterruptionEndedEvent) => void) => Promise<PluginListenerHandle> ``` Listen for audio recording interruption end events. Available on iOS and Android only. | Param | Type | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | **`eventName`** | <code>'voiceRecordingInterruptionEnded'</code> | The name of the event to listen for. | | **`listenerFunc`** | <code>(event: <a href="#voicerecordinginterruptionendedevent">VoiceRecordingInterruptionEndedEvent</a>) => void</code> | The callback function to invoke when the event occurs. | **Returns:** <code>Promise<<a href="#pluginlistenerhandle">PluginListenerHandle</a>></code> -------------------- ### removeAllListeners() ```typescript removeAllListeners() => Promise<void> ``` Remove all listeners for this plugin. -------------------- ### Interfaces #### GenericResponse Interface representing a generic response with a boolean value. | Prop | Type | Description | | ----------- | -------------------- | ----------------------------------------------- | | **`value`** | <code>boolean</code> | The result of the operation as a boolean value. | #### RecordingOptions Can be used to specify options for the recording. | Prop | Type | Description | | ---------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`directory`** | <code><a href="#directory">Directory</a></code> | The capacitor filesystem directory where the recording should be saved. If not specified, the recording will be stored in a base64 string and returned in the <a href="#recordingdata">`RecordingData`</a> object. | | **`subDirectory`** | <code>string</code> | An optional subdirectory in the specified directory where the recording should be saved. | | **`requirePlaybackSupport`** | <code>boolean</code> | Whether the web implementation should require the selected recording MIME type to also be playable by the browser's native HTML `<audio>` element. Defaults to `true` on web to reduce cases where `MediaRecorder` reports support for a format but the recorded file cannot be played back in the same browser (observed on some Safari/iOS/WKWebView combinations). Native platforms ignore this option. | #### RecordingData Interface representing the data of a recording. | Prop | Type | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | **`value`** | <code>{ recordDataBase64: string; msDuration: number; mimeType: string; fileExtension: string; uri?: string; }</code> | The value containing the recording details. | #### CurrentRecordingStatus Interface representing the current status of the voice recorder. | Prop | Type | Description | | ------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | **`status`** | <code>'NONE' \| 'RECORDING' \| 'PAUSED' \| 'INTERRUPTED'</code> | The current status of the recorder, which can be one of the following values: 'RECORDING', 'PAUSED', 'INTERRUPTED', 'NONE'. | #### PluginListenerHandle | Prop | Type | | ------------ | ----------------------------------------- | | **`remove`** | <code>() => Promise<void></code> | ### Type Aliases #### Base64String Represents a Base64 encoded string. <code>string</code> #### VoiceRecordingInterruptedEvent Event payload for voiceRecordingInterrupted event (empty - no data). <code><a href="#record">Record</a><string, never></code> #### Record Construct a type with a set of properties K of type T <code>{ [P in K]: T; }</code> #### VoiceRecordingInterruptionEndedEvent Event payload for voiceRecordingInterruptionEnded event (empty - no data). <code><a href="#record">Record</a><string, never></code> ### Enums #### Directory | Members | Value | Description | Since | | --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | **`Documents`** | <code>"DOCUMENTS"</code> | The Documents directory. On iOS it's the app's documents directory. Use this directory to store user-generated content. On Android it's the Public Documents folder, so it's accessible from other apps. It's not accessible on Android 10 unless the app enables legacy External Storage by adding `android:requestLegacyExternalStorage="true"` in the `application` tag in the `AndroidManifest.xml`. On Android 11 or newer the app can only access the files/folders the app created. | 1.0.0 | | **`Data`** | <code>"DATA"</code> | The Data directory. On iOS it will use the Documents directory. On Android it's the directory holding application files. Files will be deleted when the application is uninstalled. | 1.0.0 | | **`Library`** | <code>"LIBRARY"</code> | The Library directory. On iOS it will use the Library directory. On Android it's the directory holding application files. Files will be deleted when the application is uninstalled. | 1.1.0 | | **`Cache`** | <code>"CACHE"</code> | The Cache directory. Can be deleted in cases of low memory, so use this directory to write app-specific files. that your app can re-create easily. | 1.0.0 | | **`External`** | <code>"EXTERNAL"</code> | The external directory. On iOS it will use the Documents directory. On Android it's the directory on the primary shared/external storage device where the application can place persistent files it owns. These files are internal to the applications, and not typically visible to the user as media. Files will be deleted when the application is uninstalled. | 1.0.0 | | **`ExternalStorage`** | <code>"EXTERNAL_STORAGE"</code> | The external storage directory. On iOS it will use the Documents directory. On Android it's the primary shared/external storage directory. It's not accessible on Android 10 unless the app enables legacy External Storage by adding `android:requestLegacyExternalStorage="true"` in the `application` tag in the `AndroidManifest.xml`. It's not accessible on Android 11 or newer. | 1.0.0 | | **`ExternalCache`** | <code>"EXTERNAL_CACHE"</code> | The external cache directory. On iOS it will use the Documents directory. On Android it's the primary shared/external cache. | 7.1.0 | | **`LibraryNoCloud`** | <code>"LIBRARY_NO_CLOUD"</code> | The Library directory without cloud backup. Used in iOS. On Android it's the directory holding application files. | 7.1.0 | | **`Temporary`** | <code>"TEMPORARY"</code> | A temporary directory for iOS. On Android it's the directory holding the application cache. | 7.1.0 | </docgen-api> ## Platform behaviors ### Interruption handling (iOS and Android) On iOS and Android, the plugin listens for system audio interruptions (phone calls, other apps taking audio focus). When an interruption begins, the recording is paused, the status becomes `INTERRUPTED`, and the `voiceRecordingInterrupted` event fires. When the interruption ends, the `voiceRecordingInterruptionEnded` event fires, and the status stays `INTERRUPTED` until you call `resumeRecording()` or `stopRecording()`. Web does not provide interruption handling. If interruptions occur on iOS, recordings are segmented and merged when you stop. iOS recordings are normalized to an M4A container with MIME type `audio/mp4` for consistent output across interrupted and non-interrupted sessions. ### Web constraints - `getUserMedia` requires a secure context (HTTPS or localhost). - Most browsers require a user gesture to start recording; call `startRecording()` from a click/tap handler. - The Permissions API is not consistently supported; `hasAudioRecordingPermission()` can reject with `COULD_NOT_QUERY_PERMISSION_STATUS`. In that case, use `requestAudioRecordingPermission()` or `startRecording()` and handle errors. - By default, the web implementation picks a MIME type that is supported for both recording (`MediaRecorder`) and playback (`<audio>`). You can disable the playback probe with `RecordingOptions.requirePlaybackSupport = false` if you prefer recorder-only MIME selection. ## Recording options and storage When you set `RecordingOptions.directory`, recordings are written to the Capacitor filesystem and `stopRecording()` returns a `uri`. This avoids large base64 payloads and is recommended for long recordings. When `directory` is not set, the data is returned in `recordDataBase64`. When a `uri` is present, `recordDataBase64` may be empty or omitted, so prefer `uri` when available. ```typescript import {Directory} from '@capacitor/filesystem'; import {VoiceRecorder} from '@independo/capacitor-voice-recorder'; await VoiceRecorder.startRecording({ directory: Directory.Cache, subDirectory: 'voice', }); ``` ## Format and MIME type The plugin returns the recording in one of several possible formats. The actual MIME type depends on the platform and browser capabilities. - Android: `audio/aac` - iOS: `audio/mp4` (M4A container) - Web: first supported MIME type from the plugin's ordered list, with a default preference for formats that are reported as playable by the browser `<audio>` element (in addition to `MediaRecorder` support) Because not all devices and browsers support the same formats, recordings may not be playable everywhere. If you need consistent playback across targets, convert recordings to a single format outside this plugin. The plugin focuses on recording only and does not perform format conversion. ## Playback To play a recording, prefer `uri` when available. On native platforms, pass it through `Capacitor.convertFileSrc` before using it in the web view. ```typescript import {Capacitor} from '@capacitor/core'; const {recordDataBase64, mimeType, uri} = result.value; const source = uri ? Capacitor.convertFileSrc(uri) : `data:${mimeType};base64,${recordDataBase64}`; const audioRef = new Audio(source); audioRef.oncanplaythrough = () => audioRef.play(); audioRef.load(); ``` ## Troubleshooting ### Common error codes The plugin rejects with error codes; check `error.code` (native) or `error.message` (web). Not all codes apply to every platform. | Code | Platform(s) | Typical cause | |-------------------------------------|-------------------|---------------------------------------------------------------------------------| | `MISSING_PERMISSION` | iOS, Android, Web | Microphone permission is not granted. | | `ALREADY_RECORDING` | iOS, Android, Web | `startRecording()` called while already recording. | | `DEVICE_CANNOT_VOICE_RECORD` | iOS, Android, Web | The device or browser cannot record audio. | | `FAILED_TO_RECORD` | iOS, Android, Web | Recording failed to start or continue. | | `RECORDING_HAS_NOT_STARTED` | iOS, Android, Web | `stopRecording()`, `pauseRecording()`, or `resumeRecording()` called too early. | | `EMPTY_RECORDING` | iOS, Android, Web | Recording stopped too quickly or produced no data. | | `FAILED_TO_FETCH_RECORDING` | iOS, Android, Web | The recording could not be read back. | | `FAILED_TO_MERGE_RECORDING` | iOS | Interrupted recording segments failed to merge. | | `MICROPHONE_BEING_USED` | Android | The microphone is busy or held by another app. | | `NOT_SUPPORTED_OS_VERSION` | Android | Pause/resume is not supported on the current OS version. | | `COULD_NOT_QUERY_PERMISSION_STATUS` | Web | Permissions API is unavailable. | ## Origins and credit This project started as a fork of [ `tchvu3/capacitor-voice-recorder`](https://github.com/tchvu3/capacitor-voice-recorder). Thanks to Avihu Harush for the original implementation and community groundwork. Since then, the plugin has been re-architected for improved performance, reliability, and testability (service/adapters split, contract tests, and a normalized response path). The codebase now diverges substantially, which is why this repo left the fork network. This plugin is maintained by [Independo GmbH](https://www.independo.app/).