https://github.com/tchvu3/capacitor-voice-recorder
Capacitor plugin for voice recording
https://github.com/tchvu3/capacitor-voice-recorder
Last synced: about 1 month ago
JSON representation
Capacitor plugin for voice recording
- Host: GitHub
- URL: https://github.com/tchvu3/capacitor-voice-recorder
- Owner: tchvu3
- License: mit
- Created: 2020-11-07T02:37:53.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-11-04T19:14:38.000Z (about 1 year ago)
- Last Synced: 2025-01-11T09:13:16.903Z (10 months ago)
- Language: Java
- Size: 4.96 MB
- Stars: 79
- Watchers: 5
- Forks: 64
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-capacitor - Capacitor voice recorder - A plugin for simple voice recording. (Other plugins)
- trackawesomelist - Capacitor voice recorder (⭐82) - A plugin for simple voice recording. (Recently Updated / [Who Wants to Be a Millionare](https://www.boardgamecapital.com/who-wants-to-be-a-millionaire-rules.htm))
README
Capacitor Voice Recorder
tchvu3/capacitor-voice-recorder
Capacitor plugin for simple voice recording
## Maintainers
| Maintainer | GitHub |
|--------------|-------------------------------------|
| Avihu Harush | [tchvu3](https://github.com/tchvu3) |
## Installation
```
npm install --save capacitor-voice-recorder
npx cap sync
```
## Configuration
### Using with Android
Add the following to your `AndroidManifest.xml`:
```xml
```
### Using with iOS
Add the following to your `Info.plist`:
```xml
NSMicrophoneUsageDescription
This app uses the microphone to record audio.
```
## Supported methods
| Name | Android | iOS | Web |
|:--------------------------------|:--------|:----|:----|
| canDeviceVoiceRecord | ✅ | ✅ | ✅ |
| requestAudioRecordingPermission | ✅ | ✅ | ✅ |
| hasAudioRecordingPermission | ✅ | ✅ | ✅ |
| startRecording | ✅ | ✅ | ✅ |
| stopRecording | ✅ | ✅ | ✅ |
| pauseRecording | ✅ | ✅ | ✅ |
| resumeRecording | ✅ | ✅ | ✅ |
| getCurrentStatus | ✅ | ✅ | ✅ |
## Overview
The `capacitor-voice-recorder` plugin allows you to record audio on Android, iOS, and Web platforms.
Below is a summary
of the key methods and how to use them.
### Checking Device Capabilities and Permissions
#### canDeviceVoiceRecord
Check if the device/browser can record audio.
```typescript
VoiceRecorder.canDeviceVoiceRecord().then((result: GenericResponse) => console.log(result.value));
```
| Return Value | Description |
|--------------------|----------------------------------------------------------------------------------------|
| `{ value: true }` | The device/browser can record audio. |
| `{ value: false }` | The browser cannot record audio. Note: On mobile, it always returns `{ value: true }`. |
#### requestAudioRecordingPermission
Request audio recording permission from the user.
```typescript
VoiceRecorder.requestAudioRecordingPermission().then((result: GenericResponse) => console.log(result.value));
```
| Return Value | Description |
|--------------------|---------------------|
| `{ value: true }` | Permission granted. |
| `{ value: false }` | Permission denied. |
#### hasAudioRecordingPermission
Check if the audio recording permission has been granted.
```typescript
VoiceRecorder.hasAudioRecordingPermission().then((result: GenericResponse) => console.log(result.value));
```
| Return Value | Description |
|--------------------|---------------------|
| `{ value: true }` | Permission granted. |
| `{ value: false }` | Permission denied. |
| Error Code | Description |
|-------------------------------------|------------------------------------|
| `COULD_NOT_QUERY_PERMISSION_STATUS` | Failed to query permission status. |
### Managing Recording
#### startRecording
Start the audio recording.
Optional options can be used with this method to save the file in the device's filesystem and return a path to that file instead of a base64 string.
This greatly increases performance for large files.
```typescript
VoiceRecorder.startRecording(options?: RecordingOptions)
.then((result: GenericResponse) => console.log(result.value))
.catch(error => console.log(error));
```
| Option | Description |
|-------------------|------------------------------------------------------------------------------------------------------|
| directory | Specifies a Capacitor Filesystem [Directory](https://capacitorjs.com/docs/apis/filesystem#directory) |
| subDirectory | Specifies a custom sub-directory (optional) |
| Return Value | Description |
|-------------------|---------------------------------|
| `{ value: true }` | Recording started successfully. |
| Error Code | Description |
|------------------------------|------------------------------------------|
| `MISSING_PERMISSION` | Required permission is missing. |
| `DEVICE_CANNOT_VOICE_RECORD` | Device/browser cannot record audio. |
| `ALREADY_RECORDING` | A recording is already in progress. |
| `MICROPHONE_BEING_USED` | Microphone is being used by another app. |
| `FAILED_TO_RECORD` | Unknown error occurred during recording. |
#### stopRecording
Stops the audio recording and returns the recording data.
When a `directory` option has been passed to the `VoiceRecorder.startRecording` method the data will include a `path` instead of a `recordDataBase64`
```typescript
VoiceRecorder.stopRecording()
.then((result: RecordingData) => console.log(result.value))
.catch(error => console.log(error));
```
| Return Value | Description |
|--------------------|------------------------------------------------|
| `recordDataBase64` | The recorded audio data in Base64 format. |
| `msDuration` | The duration of the recording in milliseconds. |
| `mimeType` | The MIME type of the recorded audio. |
| `path` | The path to the audio file |
| Error Code | Description |
|-----------------------------|------------------------------------------------------|
| `RECORDING_HAS_NOT_STARTED` | No recording in progress. |
| `EMPTY_RECORDING` | Recording stopped immediately after starting. |
| `FAILED_TO_FETCH_RECORDING` | Unknown error occurred while fetching the recording. |
#### pauseRecording
Pause the ongoing audio recording.
```typescript
VoiceRecorder.pauseRecording()
.then((result: GenericResponse) => console.log(result.value))
.catch(error => console.log(error));
```
| Return Value | Description |
|--------------------|--------------------------------|
| `{ value: true }` | Recording paused successfully. |
| `{ value: false }` | Recording is already paused. |
| Error Code | Description |
|-----------------------------|----------------------------------------------------|
| `RECORDING_HAS_NOT_STARTED` | No recording in progress. |
| `NOT_SUPPORTED_OS_VERSION` | Operation not supported on the current OS version. |
#### resumeRecording
Resumes a paused audio recording.
```typescript
VoiceRecorder.resumeRecording()
.then((result: GenericResponse) => console.log(result.value))
.catch(error => console.log(error));
```
| Return Value | Description |
|--------------------|---------------------------------|
| `{ value: true }` | Recording resumed successfully. |
| `{ value: false }` | Recording is already running. |
| Error Code | Description |
|-----------------------------|----------------------------------------------------|
| `RECORDING_HAS_NOT_STARTED` | No recording in progress. |
| `NOT_SUPPORTED_OS_VERSION` | Operation not supported on the current OS version. |
#### getCurrentStatus
Retrieves the current status of the recorder.
```typescript
VoiceRecorder.getCurrentStatus()
.then((result: CurrentRecordingStatus) => console.log(result.status))
.catch(error => console.log(error));
```
| Status Code | Description |
|-------------|------------------------------------------------------|
| `NONE` | Plugin is idle and waiting to start a new recording. |
| `RECORDING` | Plugin is currently recording. |
| `PAUSED` | Recording is paused. |
## 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 three browsers have 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 do not all support the same set of audio formats.
It is recommended to convert the recordings to a format that all your target devices support.
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:
### With Base64 string
```typescript
const base64Sound = '...' // from plugin
const mimeType = '...' // from plugin
const audioRef = new Audio(`data:${mimeType};base64,${base64Sound}`)
audioRef.oncanplaythrough = () => audioRef.play()
audioRef.load()
```
### With Blob
```typescript
import { Capacitor } from '@capacitor/core'
import { Directory, Filesystem } from '@capacitor/filesystem'
const PATH = '...' // from plugin
/** Generate a URL to the blob file with @capacitor/core and @capacitor/filesystem */
const getBlobURL = async (path: string) => {
const directory = Directory.Data // Same Directory as the one you used with VoiceRecorder.startRecording
if (config.public.platform === 'web') {
const { data } = await Filesystem.readFile({ directory, path })
return URL.createObjectURL(data)
}
const { uri } = await Filesystem.getUri({ directory, path })
return Capacitor.convertFileSrc(uri)
}
/** Read the audio file */
const play = async () => {
const url = await getBlobURL(PATH)
const audioRef = new Audio(url)
audioRef.onended = () => { URL.revokeObjectUrl(url) }
audioRef.play()
}
/** Load the audio file (ie: to send to a Cloud Storage service) */
const load = async () => {
const url = await getBlobURL(PATH)
const response = await fetch(url)
return response.blob()
}
```
## Compatibility
Versioning follows Capacitor versioning.
Major versions of the plugin are compatible with major versions of Capacitor.
You can find each version in its own dedicated branch.
| Plugin Version | Capacitor Version |
|----------------|-------------------|
| 5.* | 5 |
| 6.* | 6 |
| 7.* | 7 |
## Donation
If you enjoy my work and find it useful, feel free to invite me to a cup of coffee :)
[](https://www.buymeacoffee.com/tchvu3)
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
### Credit
Thanks to independo-gmbh for the readme update.