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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Independo GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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>
 
@@ -371,36 +372,44 @@ Event payload for voiceRecordingInterruptionEnded event (empty - no data).
 
 ## 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.
+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`.
+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 returns the recording in one of several possible formats. The actual MIME type depends on the platform and
+browser capabilities.
 
-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.
+- 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`
 
-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.
+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
@@ -414,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", 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";

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

@@ -1,12 +1,17 @@
-package com.tchvu3.capacitorvoicerecorder;
+package app.independo.capacitorvoicerecorder.core;
 
 import com.getcapacitor.JSObject;
 
+/** Recording payload returned to the bridge layer. */
 public class RecordData {
 
+    /** File URI when returning recordings by reference. */
     private String uri;
+    /** Base64 payload for inline recording data. */
     private String recordDataBase64;
+    /** MIME type of the audio payload. */
     private String mimeType;
+    /** Recording duration in milliseconds. */
     private int msDuration;
 
     public RecordData() {}
@@ -18,6 +23,7 @@ public class RecordData {
         this.uri = uri;
     }
 
+    /** Returns the base64 payload, if present. */
     public String getRecordDataBase64() {
         return recordDataBase64;
     }
@@ -26,6 +32,7 @@ public class RecordData {
         this.recordDataBase64 = recordDataBase64;
     }
 
+    /** Returns the recording duration in milliseconds. */
     public int getMsDuration() {
         return msDuration;
     }
@@ -34,6 +41,7 @@ public class RecordData {
         this.msDuration = msDuration;
     }
 
+    /** Returns the MIME type of the recording. */
     public String getMimeType() {
         return mimeType;
     }
@@ -42,6 +50,12 @@ public class RecordData {
         this.mimeType = mimeType;
     }
 
+    /** Returns the file URI, if present. */
+    public String getUri() {
+        return uri;
+    }
+
+    /** Serializes the record data into the legacy JS payload shape. */
     public JSObject toJSObject() {
         JSObject toReturn = new JSObject();
         toReturn.put("recordDataBase64", recordDataBase64);

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

@@ -0,0 +1,4 @@
+package app.independo.capacitorvoicerecorder.core;
+
+/** Optional output configuration for recordings. */
+public record RecordOptions(String directory, String subDirectory) {}

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

@@ -0,0 +1,18 @@
+package app.independo.capacitorvoicerecorder.core;
+
+import com.getcapacitor.PluginConfig;
+
+/** Supported response payload shapes. */
+public enum ResponseFormat {
+    LEGACY,
+    NORMALIZED;
+
+    /** Reads the response format from plugin configuration. */
+    public static ResponseFormat fromConfig(PluginConfig config) {
+        String value = config.getString("responseFormat", "legacy");
+        if ("normalized".equalsIgnoreCase(value)) {
+            return NORMALIZED;
+        }
+        return LEGACY;
+    }
+}

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

@@ -1,34 +1,40 @@
-package com.tchvu3.capacitorvoicerecorder;
+package app.independo.capacitorvoicerecorder.core;
 
 import com.getcapacitor.JSObject;
 
+/** Helper for building JS payloads in the legacy response shape. */
 public class ResponseGenerator {
 
     private static final String VALUE_RESPONSE_KEY = "value";
     private static final String STATUS_RESPONSE_KEY = "status";
 
+    /** Wraps a boolean value into the response shape. */
     public static JSObject fromBoolean(boolean value) {
         return value ? successResponse() : failResponse();
     }
 
+    /** Returns a success response with value=true. */
     public static JSObject successResponse() {
         JSObject success = new JSObject();
         success.put(VALUE_RESPONSE_KEY, true);
         return success;
     }
 
+    /** Returns a failure response with value=false. */
     public static JSObject failResponse() {
         JSObject success = new JSObject();
         success.put(VALUE_RESPONSE_KEY, false);
         return success;
     }
 
+    /** Wraps arbitrary data into the response shape. */
     public static JSObject dataResponse(Object data) {
         JSObject success = new JSObject();
         success.put(VALUE_RESPONSE_KEY, data);
         return success;
     }
 
+    /** Wraps the recording status into the response shape. */
     public static JSObject statusResponse(CurrentRecordingStatus status) {
         JSObject success = new JSObject();
         success.put(STATUS_RESPONSE_KEY, status.name());