@independo/capacitor-voice-recorder 8.0.2-dev.1 → 8.1.0-dev.2

package/README.md

@@ -11,6 +11,7 @@
 <br>
   <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/main"><img src="https://codecov.io/gh/independo-gmbh/capacitor-voice-recorder/branch/main/graph/badge.svg" alt="Coverage Badge: main" /></a>
 </p>
 
 ## Installation
@@ -24,8 +25,8 @@ npx cap sync
 
 - Capacitor 8+
 - iOS 15+
-- Android minSdk 24+
-- Android 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).
+- 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
 
@@ -41,7 +42,7 @@ This plugin supports both CocoaPods and Swift Package Manager (SPM) on iOS.
 Add the following to your `AndroidManifest.xml`:
 
 ```xml
-<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.RECORD_AUDIO"/>
 ```
 
 ### Using with iOS
@@ -49,7 +50,6 @@ Add the following to your `AndroidManifest.xml`:
 Add the following to your `Info.plist`:
 
 ```xml
-
 <key>NSMicrophoneUsageDescription</key>
 <string>This app uses the microphone to record audio.</string>
 ```
@@ -60,7 +60,8 @@ The `@independo/capacitor-voice-recorder` plugin allows you to record audio on A
 
 ## API
 
-Below is an index of all available methods. Run `npm run docgen` after updating any JSDoc comments to refresh this section.
+Below is an index of all available methods. Run `npm run docgen` after updating any JSDoc comments to refresh this
+section.
 
 <docgen-index>
 
@@ -72,6 +73,9 @@ Below is an index of all available methods. Run `npm run docgen` after updating
 * [`pauseRecording()`](#pauserecording)
 * [`resumeRecording()`](#resumerecording)
 * [`getCurrentStatus()`](#getcurrentstatus)
+* [`addListener('voiceRecordingInterrupted', ...)`](#addlistenervoicerecordinginterrupted-)
+* [`addListener('voiceRecordingInterruptionEnded', ...)`](#addlistenervoicerecordinginterruptionended-)
+* [`removeAllListeners()`](#removealllisteners)
 * [Interfaces](#interfaces)
 * [Type Aliases](#type-aliases)
 * [Enums](#enums)
@@ -162,6 +166,7 @@ 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&lt;<a href="#recordingdata">RecordingData</a>&gt;</code>
@@ -191,7 +196,7 @@ On certain mobile OS versions, this function is not supported and will reject wi
 resumeRecording() => Promise<GenericResponse>
 ```
 
-Resumes a paused audio recording.
+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`.
@@ -212,12 +217,62 @@ 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&lt;<a href="#currentrecordingstatus">CurrentRecordingStatus</a>&gt;</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>) =&gt; void</code> | The callback function to invoke when the event occurs. |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</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>) =&gt; void</code> | The callback function to invoke when the event occurs. |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### removeAllListeners()
+
+```typescript
+removeAllListeners() => Promise<void>
+```
+
+Remove all listeners for this plugin.
+
+--------------------
+
+
 ### Interfaces
 
 
@@ -253,9 +308,16 @@ Interface representing the data of a recording.
 
 Interface representing the current status of the voice recorder.
 
-| Prop         | Type                                           | Description                                                                                                  |
-| ------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| **`status`** | <code>'NONE' \| 'RECORDING' \| 'PAUSED'</code> | The current status of the recorder, which can be one of the following values: 'RECORDING', 'PAUSED', 'NONE'. |
+| 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>() =&gt; Promise&lt;void&gt;</code> |
 
 
 ### Type Aliases
@@ -268,6 +330,27 @@ Represents a Base64 encoded string.
 <code>string</code>
 
 
+#### VoiceRecordingInterruptedEvent
+
+Event payload for voiceRecordingInterrupted event (empty - no data).
+
+<code><a href="#record">Record</a>&lt;string, never&gt;</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>&lt;string, never&gt;</code>
+
+
 ### Enums
 
 
@@ -287,32 +370,46 @@ Represents a Base64 encoded string.
 
 </docgen-api>
 
+## Audio interruption handling
+
+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. The merged file is M4A with MIME type
+`audio/mp4`. Recordings without interruptions remain AAC with MIME type `audio/aac`.
 
-## Format and Mime type
+## 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.
+The plugin returns the recording in one of several possible formats. The actual MIME type depends on the platform and
+browser capabilities.
 
-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.
+- Android: `audio/aac`
+- iOS: `audio/aac` (or `audio/mp4` when interrupted recordings are merged)
+- Web: first supported type from `audio/aac`, `audio/webm;codecs=opus`, `audio/ogg;codecs=opus`, `audio/webm`,
+  `audio/mp4`
+
+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 the recorded file you can use plain javascript:
+To play a recording, prefer `uri` when available. On native platforms, pass it through
+`Capacitor.convertFileSrc` before using it in the web view.
 
 ```typescript
-const base64Sound = '...' // from plugin
-const mimeType = '...'  // from plugin
-const audioRef = new Audio(`data:${mimeType};base64,${base64Sound}`)
-audioRef.oncanplaythrough = () => audioRef.play()
-audioRef.load()
+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();
 ```
 
 ## Compatibility
@@ -326,9 +423,10 @@ Versioning follows Capacitor versioning. Major versions of the plugin are compat
 | 7.*            | 7                 |
 | 8.*            | 8                 |
 
-## Collaborators
+## Origins and credit
 
-| Collaborators      |                                                             | GitHub                                    | Donation                                                                                                                          |
-|--------------------|-------------------------------------------------------------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| Avihu Harush       | Original Author                                             | [tchvu3](https://github.com/tchvu3)       | [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/tchvu3) |
-| Konstantin Strümpf | Contributor for [Independo GmbH](https://www.independo.app) | [kstruempf](https://github.com/kstruempf) |                                                                                                                                   |
+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.

package/android/build.gradle

@@ -16,9 +16,10 @@ buildscript {
 }
 
 apply plugin: 'com.android.library'
+apply plugin: 'jacoco'
 
 android {
-    namespace = "com.tchvu3.capacitorvoicerecorder"
+    namespace = "app.independo.capacitorvoicerecorder"
     compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
     defaultConfig {
         minSdk = project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
@@ -33,6 +34,14 @@ android {
             proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
         }
     }
+    testOptions {
+        unitTests.all {
+            jacoco {
+                includeNoLocationClasses = true
+                excludes = ['jdk.internal.*']
+            }
+        }
+    }
     lint {
         abortOnError = false
     }
@@ -42,6 +51,10 @@ android {
     }
 }
 
+jacoco {
+    toolVersion = '0.8.11'
+}
+
 repositories {
     google()
     mavenCentral()
@@ -53,6 +66,36 @@ dependencies {
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     testImplementation "junit:junit:$junitVersion"
+    testImplementation "org.json:json:20240303"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
 }
+
+tasks.register('jacocoTestReport', JacocoReport) {
+    dependsOn tasks.named('testDebugUnitTest')
+
+    def fileFilter = [
+        '**/R.class',
+        '**/R$*.class',
+        '**/BuildConfig.*',
+        '**/Manifest*.*',
+        '**/*Test*.*',
+        'android/**/*.*',
+    ]
+    def javaClasses = fileTree(dir: "$buildDir/intermediates/javac/debug/classes", excludes: fileFilter)
+    def kotlinClasses = fileTree(dir: "$buildDir/tmp/kotlin-classes/debug", excludes: fileFilter)
+    classDirectories.setFrom(files([javaClasses, kotlinClasses]))
+    sourceDirectories.setFrom(files(['src/main/java', 'src/main/kotlin']))
+    executionData.setFrom(
+        fileTree(dir: buildDir, includes: [
+            'jacoco/testDebugUnitTest.exec',
+            'outputs/unit_test_code_coverage/debugUnitTest/testDebugUnitTest.exec',
+        ]),
+    )
+
+    reports {
+        xml.required = true
+        html.required = true
+        csv.required = false
+    }
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/VoiceRecorder.java

@@ -0,0 +1,146 @@
+package app.independo.capacitorvoicerecorder;
+
+import android.Manifest;
+import app.independo.capacitorvoicerecorder.adapters.PermissionChecker;
+import app.independo.capacitorvoicerecorder.adapters.RecordDataMapper;
+import app.independo.capacitorvoicerecorder.adapters.RecorderPlatform;
+import app.independo.capacitorvoicerecorder.core.ErrorCodes;
+import app.independo.capacitorvoicerecorder.core.Messages;
+import app.independo.capacitorvoicerecorder.core.RecordData;
+import app.independo.capacitorvoicerecorder.core.RecordOptions;
+import app.independo.capacitorvoicerecorder.core.ResponseFormat;
+import app.independo.capacitorvoicerecorder.core.ResponseGenerator;
+import app.independo.capacitorvoicerecorder.platform.DefaultRecorderPlatform;
+import app.independo.capacitorvoicerecorder.service.VoiceRecorderService;
+import app.independo.capacitorvoicerecorder.service.VoiceRecorderServiceException;
+import com.getcapacitor.PermissionState;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import com.getcapacitor.annotation.Permission;
+import com.getcapacitor.annotation.PermissionCallback;
+
+@CapacitorPlugin(
+    name = "VoiceRecorder",
+    permissions = { @Permission(alias = VoiceRecorder.RECORD_AUDIO_ALIAS, strings = { Manifest.permission.RECORD_AUDIO }) }
+)
+/** Capacitor bridge for the VoiceRecorder plugin. */
+public class VoiceRecorder extends Plugin {
+
+    /** Permission alias used by the Capacitor permission API. */
+    static final String RECORD_AUDIO_ALIAS = "voice recording";
+    /** Service layer that owns recording flows and validation. */
+    private VoiceRecorderService service;
+    /** Response format derived from plugin configuration. */
+    private ResponseFormat responseFormat;
+
+    @Override
+    public void load() {
+        super.load();
+        responseFormat = ResponseFormat.fromConfig(getConfig());
+        RecorderPlatform platform = new DefaultRecorderPlatform(getContext());
+        PermissionChecker permissionChecker = this::doesUserGaveAudioRecordingPermission;
+        service = new VoiceRecorderService(platform, permissionChecker);
+    }
+
+    /** Checks whether the device can record audio. */
+    @PluginMethod
+    public void canDeviceVoiceRecord(PluginCall call) {
+        call.resolve(ResponseGenerator.fromBoolean(service.canDeviceVoiceRecord()));
+    }
+
+    /** Requests microphone permission or returns success if already granted. */
+    @PluginMethod
+    public void requestAudioRecordingPermission(PluginCall call) {
+        if (service.hasAudioRecordingPermission()) {
+            call.resolve(ResponseGenerator.successResponse());
+        } else {
+            requestPermissionForAlias(RECORD_AUDIO_ALIAS, call, "recordAudioPermissionCallback");
+        }
+    }
+
+    /** Forwards permission results back to the JS call. */
+    @PermissionCallback
+    private void recordAudioPermissionCallback(PluginCall call) {
+        this.hasAudioRecordingPermission(call);
+    }
+
+    /** Returns whether the app has microphone permission. */
+    @PluginMethod
+    public void hasAudioRecordingPermission(PluginCall call) {
+        call.resolve(ResponseGenerator.fromBoolean(service.hasAudioRecordingPermission()));
+    }
+
+    /** Starts a recording session. */
+    @PluginMethod
+    public void startRecording(PluginCall call) {
+        try {
+            String directory = call.getString("directory");
+            String subDirectory = call.getString("subDirectory");
+            RecordOptions options = new RecordOptions(directory, subDirectory);
+            service.startRecording(
+                options,
+                () -> notifyListeners("voiceRecordingInterrupted", null),
+                () -> notifyListeners("voiceRecordingInterruptionEnded", null)
+            );
+            call.resolve(ResponseGenerator.successResponse());
+        } catch (VoiceRecorderServiceException exp) {
+            call.reject(toLegacyMessage(exp.getCode()), exp.getCode(), exp);
+        }
+    }
+
+    /** Stops recording and returns the recording payload. */
+    @PluginMethod
+    public void stopRecording(PluginCall call) {
+        try {
+            RecordData recordData = service.stopRecording();
+            if (responseFormat == ResponseFormat.NORMALIZED) {
+                call.resolve(ResponseGenerator.dataResponse(RecordDataMapper.toNormalizedJSObject(recordData)));
+            } else {
+                call.resolve(ResponseGenerator.dataResponse(RecordDataMapper.toLegacyJSObject(recordData)));
+            }
+        } catch (VoiceRecorderServiceException exp) {
+            call.reject(toLegacyMessage(exp.getCode()), exp.getCode(), exp);
+        }
+    }
+
+    /** Pauses an active recording session if supported. */
+    @PluginMethod
+    public void pauseRecording(PluginCall call) {
+        try {
+            call.resolve(ResponseGenerator.fromBoolean(service.pauseRecording()));
+        } catch (VoiceRecorderServiceException exception) {
+            call.reject(toLegacyMessage(exception.getCode()), exception.getCode(), exception);
+        }
+    }
+
+    /** Resumes a paused recording session if supported. */
+    @PluginMethod
+    public void resumeRecording(PluginCall call) {
+        try {
+            call.resolve(ResponseGenerator.fromBoolean(service.resumeRecording()));
+        } catch (VoiceRecorderServiceException exception) {
+            call.reject(toLegacyMessage(exception.getCode()), exception.getCode(), exception);
+        }
+    }
+
+    /** Returns the current recording status. */
+    @PluginMethod
+    public void getCurrentStatus(PluginCall call) {
+        call.resolve(ResponseGenerator.statusResponse(service.getCurrentStatus()));
+    }
+
+    /** Checks whether the app has the RECORD_AUDIO permission. */
+    private boolean doesUserGaveAudioRecordingPermission() {
+        return getPermissionState(VoiceRecorder.RECORD_AUDIO_ALIAS).equals(PermissionState.GRANTED);
+    }
+
+    /** Maps canonical error codes back to legacy error messages. */
+    private String toLegacyMessage(String canonicalCode) {
+        if (ErrorCodes.DEVICE_CANNOT_VOICE_RECORD.equals(canonicalCode)) {
+            return Messages.CANNOT_RECORD_ON_THIS_PHONE;
+        }
+        return canonicalCode;
+    }
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/adapters/PermissionChecker.java

@@ -0,0 +1,8 @@
+package app.independo.capacitorvoicerecorder.adapters;
+
+/** Functional interface used to check microphone permission. */
+@FunctionalInterface
+public interface PermissionChecker {
+    /** Returns whether the app currently has microphone permission. */
+    boolean hasAudioPermission();
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/adapters/RecordDataMapper.java

@@ -0,0 +1,32 @@
+package app.independo.capacitorvoicerecorder.adapters;
+
+import app.independo.capacitorvoicerecorder.core.RecordData;
+import com.getcapacitor.JSObject;
+
+/** Maps internal record data into legacy or normalized JS payloads. */
+public final class RecordDataMapper {
+
+    private RecordDataMapper() {}
+
+    /** Converts record data to the legacy payload shape. */
+    public static JSObject toLegacyJSObject(RecordData recordData) {
+        return recordData.toJSObject();
+    }
+
+    /** Converts record data to the normalized payload shape. */
+    public static JSObject toNormalizedJSObject(RecordData recordData) {
+        JSObject normalized = new JSObject();
+        normalized.put("msDuration", recordData.getMsDuration());
+        normalized.put("mimeType", recordData.getMimeType());
+
+        String uri = recordData.getUri();
+        String recordDataBase64 = recordData.getRecordDataBase64();
+        if (uri != null && !uri.isEmpty()) {
+            normalized.put("uri", uri);
+        } else if (recordDataBase64 != null && !recordDataBase64.isEmpty()) {
+            normalized.put("recordDataBase64", recordDataBase64);
+        }
+
+        return normalized;
+    }
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/adapters/RecorderAdapter.java

@@ -0,0 +1,39 @@
+package app.independo.capacitorvoicerecorder.adapters;
+
+import app.independo.capacitorvoicerecorder.core.CurrentRecordingStatus;
+import app.independo.capacitorvoicerecorder.core.RecordOptions;
+import app.independo.capacitorvoicerecorder.platform.NotSupportedOsVersion;
+import java.io.File;
+
+/** Recorder abstraction used by the service layer. */
+public interface RecorderAdapter {
+    /** Sets a callback invoked when interruptions begin. */
+    void setOnInterruptionBegan(Runnable callback);
+
+    /** Sets a callback invoked when interruptions end. */
+    void setOnInterruptionEnded(Runnable callback);
+
+    /** Starts recording audio. */
+    void startRecording();
+
+    /** Stops recording audio. */
+    void stopRecording();
+
+    /** Pauses recording if supported. */
+    boolean pauseRecording() throws NotSupportedOsVersion;
+
+    /** Resumes recording if supported. */
+    boolean resumeRecording() throws NotSupportedOsVersion;
+
+    /** Returns the current recording status. */
+    CurrentRecordingStatus getCurrentStatus();
+
+    /** Returns the output file for the recording. */
+    File getOutputFile();
+
+    /** Returns the options used to start recording. */
+    RecordOptions getRecordOptions();
+
+    /** Deletes the output file from disk. */
+    boolean deleteOutputFile();
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/adapters/RecorderPlatform.java

@@ -0,0 +1,25 @@
+package app.independo.capacitorvoicerecorder.adapters;
+
+import app.independo.capacitorvoicerecorder.core.RecordOptions;
+import java.io.File;
+
+/** Platform abstraction for device and file operations. */
+public interface RecorderPlatform {
+    /** Returns whether the device can record audio. */
+    boolean canDeviceVoiceRecord();
+
+    /** Returns true when the microphone is in use elsewhere. */
+    boolean isMicrophoneOccupied();
+
+    /** Creates a recorder instance for the given options. */
+    RecorderAdapter createRecorder(RecordOptions options) throws Exception;
+
+    /** Reads the recording file as base64, or null on failure. */
+    String readFileAsBase64(File recordedFile);
+
+    /** Returns the recording duration in milliseconds. */
+    int getDurationMs(File recordedFile);
+
+    /** Returns the URI for the recording file. */
+    String toUri(File recordedFile);
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/core/CurrentRecordingStatus.java

@@ -0,0 +1,9 @@
+package app.independo.capacitorvoicerecorder.core;
+
+/** Represents the current recording state. */
+public enum CurrentRecordingStatus {
+    RECORDING,
+    PAUSED,
+    INTERRUPTED,
+    NONE
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/core/ErrorCodes.java

@@ -0,0 +1,19 @@
+package app.independo.capacitorvoicerecorder.core;
+
+/** Canonical error codes returned by the plugin. */
+public final class ErrorCodes {
+
+    public static final String MISSING_PERMISSION = "MISSING_PERMISSION";
+    public static final String ALREADY_RECORDING = "ALREADY_RECORDING";
+    public static final String MICROPHONE_BEING_USED = "MICROPHONE_BEING_USED";
+    public static final String DEVICE_CANNOT_VOICE_RECORD = "DEVICE_CANNOT_VOICE_RECORD";
+    public static final String FAILED_TO_RECORD = "FAILED_TO_RECORD";
+    public static final String EMPTY_RECORDING = "EMPTY_RECORDING";
+    public static final String RECORDING_HAS_NOT_STARTED = "RECORDING_HAS_NOT_STARTED";
+    public static final String FAILED_TO_FETCH_RECORDING = "FAILED_TO_FETCH_RECORDING";
+    public static final String FAILED_TO_MERGE_RECORDING = "FAILED_TO_MERGE_RECORDING";
+    public static final String NOT_SUPPORTED_OS_VERSION = "NOT_SUPPORTED_OS_VERSION";
+    public static final String COULD_NOT_QUERY_PERMISSION_STATUS = "COULD_NOT_QUERY_PERMISSION_STATUS";
+
+    private ErrorCodes() {}
+}

package/android/src/main/java/{com/tchvu3/capacitorvoicerecorder → app/independo/capacitorvoicerecorder/core}/Messages.java

@@ -1,5 +1,6 @@
-package com.tchvu3.capacitorvoicerecorder;
+package app.independo.capacitorvoicerecorder.core;
 
+/** Legacy error messages preserved for backward compatibility. */
 public abstract class Messages {
 
     public static final String MISSING_PERMISSION = "MISSING_PERMISSION";