@independo/capacitor-voice-recorder 8.1.2 → 8.1.3-dev.1

package/README.md

@@ -14,6 +14,10 @@
   <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>
 </p>
 
+## Overview
+
+The `@independo/capacitor-voice-recorder` plugin allows you to record audio on Android, iOS, and Web platforms.
+
 ## Installation
 
 ```
@@ -21,43 +25,72 @@ npm install --save @independo/capacitor-voice-recorder
 npx cap sync
 ```
 
-## Requirements
+### 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). `npm run verify:android` requires a Java version supported
   by the bundled Gradle wrapper (currently Java 21–24, with Java 21 recommended).
 
-## iOS Package Manager Support
+### 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`
 
-## Configuration
-
-### Using with Android
+## Quick start
 
-Add the following to your `AndroidManifest.xml`:
+Minimal flow for starting and stopping a recording:
 
-```xml
-<uses-permission android:name="android.permission.RECORD_AUDIO"/>
-```
+```typescript
+import {VoiceRecorder} from '@independo/capacitor-voice-recorder';
 
-### Using with iOS
+export const startRecording = async () => {
+    const permission = await VoiceRecorder.requestAudioRecordingPermission();
+    if (!permission.value) {
+        throw new Error('Microphone permission not granted');
+    }
 
-Add the following to your `Info.plist`:
+    await VoiceRecorder.startRecording();
+};
 
-```xml
-<key>NSMicrophoneUsageDescription</key>
-<string>This app uses the microphone to record audio.</string>
+export const stopRecording = async () => {
+    const {value} = await VoiceRecorder.stopRecording();
+    return value;
+};
 ```
 
-## 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
@@ -370,7 +403,9 @@ Event payload for voiceRecordingInterruptionEnded event (empty - no data).
 
 </docgen-api>
 
-## Audio interruption handling
+## 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`
@@ -380,6 +415,32 @@ event fires. When the interruption ends, the `voiceRecordingInterruptionEnded` e
 If interruptions occur on iOS, recordings are segmented and merged when you stop. The merged file is M4A with MIME type
 `audio/mp4`. Recordings without interruptions remain AAC with MIME type `audio/aac`.
 
+### 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.
+
+## 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
@@ -412,16 +473,26 @@ audioRef.oncanplaythrough = () => audioRef.play();
 audioRef.load();
 ```
 
-## Compatibility
+## Troubleshooting
 
-Versioning follows Capacitor versioning. Major versions of the plugin are compatible with major versions of Capacitor.
+### Common error codes
+
+The plugin rejects with error codes; check `error.code` (native) or `error.message` (web). Not all codes apply to every
+platform.
 
-| Plugin Version | Capacitor Version |
-|----------------|-------------------|
-| 5.*            | 5                 |
-| 6.*            | 6                 |
-| 7.*            | 7                 |
-| 8.*            | 8                 |
+| 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
 
@@ -430,3 +501,4 @@ This project started as a fork of [
 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/).

package/package.json

@@ -13,7 +13,7 @@
     "url": "https://github.com/independo-gmbh/capacitor-voice-recorder.git"
   },
   "description": "Capacitor plugin for voice recording",
-  "version": "8.1.2",
+  "version": "8.1.3-dev.1",
   "devDependencies": {
     "@capacitor/android": "^8.0.0",
     "conventional-changelog-conventionalcommits": "^9.1.0",