Installation

npm install --save @independo/capacitor-voice-recorder
npx cap sync

Configuration

Using with Android

Add the following to your AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Using with iOS

Add the following to your Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone to record audio.</string>

Overview

The @independo/capacitor-voice-recorder plugin allows you to record audio on Android, iOS, and Web platforms.

API

Below is an index of all available methods. Run npm run docgen after updating any JSDoc comments to refresh this section.

• canDeviceVoiceRecord()
• requestAudioRecordingPermission()
• hasAudioRecordingPermission()
• startRecording(...)
• stopRecording()
• pauseRecording()
• resumeRecording()
• getCurrentStatus()
• Interfaces
• Type Aliases
• Enums

Interface for the VoiceRecorderPlugin which provides methods to record audio.

canDeviceVoiceRecord()

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: Promise<GenericResponse>

requestAudioRecordingPermission()

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: Promise<GenericResponse>

hasAudioRecordingPermission()

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: Promise<GenericResponse>

startRecording(...)

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 | RecordingOptions | The options for the recording. |

Returns: Promise<GenericResponse>

stopRecording()

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. In case of success, the promise resolves to RecordingData containing the recording in base-64, the duration of the recording in milliseconds, and the MIME type.

Returns: Promise<RecordingData>

pauseRecording()

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: Promise<GenericResponse>

resumeRecording()

resumeRecording() => Promise<GenericResponse>

Resumes a paused 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: Promise<GenericResponse>

getCurrentStatus()

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.

Returns: Promise<CurrentRecordingStatus>

Interfaces

GenericResponse

Interface representing a generic response with a boolean value.

| Prop | Type | Description | | ----------- | -------------------- | ----------------------------------------------- | | value | boolean | The result of the operation as a boolean value. |

RecordingOptions

Can be used to specify options for the recording.

| Prop | Type | Description | | ------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | directory | Directory | 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 RecordingData object. | | subDirectory | string | An optional subdirectory in the specified directory where the recording should be saved. |

RecordingData

Interface representing the data of a recording.

| Prop | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------- | | value | { recordDataBase64: string; msDuration: number; mimeType: string; uri?: string; } | The value containing the recording details. |

CurrentRecordingStatus

Interface representing the current status of the voice recorder.

| Prop | Type | Description | | ------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | status | 'RECORDING' | 'PAUSED' | 'NONE' | The current status of the recorder, which can be one of the following values: 'RECORDING', 'PAUSED', 'NONE'. |

Type Aliases

Base64String

Represents a Base64 encoded string.

string

Enums

Directory

| Members | Value | Description | Since | | --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | Documents | "DOCUMENTS" | 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 | "DATA" | 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 | "LIBRARY" | 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 | "CACHE" | 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 | "EXTERNAL" | 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 | "EXTERNAL_STORAGE" | 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 | "EXTERNAL_CACHE" | 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 | "LIBRARY_NO_CLOUD" | The Library directory without cloud backup. Used in iOS. On Android it's the directory holding application files. | 7.1.0 | | Temporary | "TEMPORARY" | A temporary directory for iOS. On Android it's the directory holding the application cache. | 7.1.0 |

Format and Mime type

The plugin will return the recording in one of several possible formats. the format is dependent on the os / web browser that the user uses. on android and ios the mime type will be audio/aac, while on chrome and firefox it will be audio/webm;codecs=opus and on safari it will be audio/mp4. note that these 3 browsers has been tested on. the plugin should still work on other browsers, as there is a list of mime types that the plugin checks against the user's browser.

Note that this fact might cause unexpected behavior in case you'll try to play recordings between several devices or browsers - as they not all support the same set of audio formats. it is recommended to convert the recordings to a format that all your target devices supports. as this plugin focuses on the recording aspect, it does not provide any conversion between formats.

Playback

To play the recorded file you can use plain javascript:

const base64Sound = '...' // from plugin
const mimeType = '...'  // from plugin
const audioRef = new Audio(`data:${mimeType};base64,${base64Sound}`)
audioRef.oncanplaythrough = () => audioRef.play()
audioRef.load()

Compatibility

Versioning follows Capacitor versioning. Major versions of the plugin are compatible with major versions of Capacitor.

| Plugin Version | Capacitor Version | |----------------|-------------------| | 5.* | 5 | | 6.* | 6 | | 7.* | 7 |

Collaborators

| Collaborators | | GitHub | Donation | |--------------------|-------------------------------------------------------------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | Avihu Harush | Original Author | tchvu3 | | | Konstantin Strümpf | Contributor for Independo GmbH | kstruempf | |