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

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());

package/android/src/main/java/app/independo/capacitorvoicerecorder/platform/CustomMediaRecorder.java

@@ -0,0 +1,281 @@
+package app.independo.capacitorvoicerecorder.platform;
+
+import android.content.Context;
+import android.media.AudioAttributes;
+import android.media.AudioFocusRequest;
+import android.media.AudioManager;
+import android.media.MediaRecorder;
+import android.os.Build;
+import android.os.Environment;
+import app.independo.capacitorvoicerecorder.adapters.RecorderAdapter;
+import app.independo.capacitorvoicerecorder.core.CurrentRecordingStatus;
+import app.independo.capacitorvoicerecorder.core.RecordOptions;
+import java.io.File;
+import java.io.IOException;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/** MediaRecorder wrapper that manages audio focus and interruptions. */
+public class CustomMediaRecorder implements AudioManager.OnAudioFocusChangeListener, RecorderAdapter {
+
+    /** Android context for file paths and system services. */
+    private final Context context;
+    /** Recording options passed from the service layer. */
+    private final RecordOptions options;
+    /** Active MediaRecorder instance for the session. */
+    private MediaRecorder mediaRecorder;
+    /** Output file for the current recording session. */
+    private File outputFile;
+    /** Current session status tracked locally. */
+    private CurrentRecordingStatus currentRecordingStatus = CurrentRecordingStatus.NONE;
+    /** Audio manager for focus changes. */
+    private AudioManager audioManager;
+    /** Focus request for Android O and above. */
+    private AudioFocusRequest audioFocusRequest;
+    /** Callback invoked when an interruption begins. */
+    private Runnable onInterruptionBegan;
+    /** Callback invoked when an interruption ends. */
+    private Runnable onInterruptionEnded;
+
+    public CustomMediaRecorder(Context context, RecordOptions options) throws IOException {
+        this.context = context;
+        this.options = options;
+        this.audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
+        generateMediaRecorder();
+    }
+
+    /** Sets the callback for interruption begin events. */
+    public void setOnInterruptionBegan(Runnable callback) {
+        this.onInterruptionBegan = callback;
+    }
+
+    /** Sets the callback for interruption end events. */
+    public void setOnInterruptionEnded(Runnable callback) {
+        this.onInterruptionEnded = callback;
+    }
+
+    /** Configures the MediaRecorder with audio settings. */
+    private void generateMediaRecorder() throws IOException {
+        mediaRecorder = new MediaRecorder();
+        mediaRecorder.setAudioSource(MediaRecorder.AudioSource.MIC);
+        mediaRecorder.setOutputFormat(MediaRecorder.OutputFormat.AAC_ADTS);
+        mediaRecorder.setAudioEncoder(MediaRecorder.AudioEncoder.AAC);
+        mediaRecorder.setAudioEncodingBitRate(96000);
+        mediaRecorder.setAudioSamplingRate(44100);
+        setRecorderOutputFile();
+        mediaRecorder.prepare();
+    }
+
+    /** Picks a directory and allocates the output file for this session. */
+    private void setRecorderOutputFile() throws IOException {
+        File outputDir = context.getCacheDir();
+
+        String directory = options.directory();
+        String subDirectory = options.subDirectory();
+
+        if (directory != null) {
+            outputDir = this.getDirectory(directory);
+            if (subDirectory != null) {
+                Pattern pattern = Pattern.compile("^/?(.+[^/])/?$");
+                Matcher matcher = pattern.matcher(subDirectory);
+                if (matcher.matches()) {
+                    outputDir = new File(outputDir, matcher.group(1));
+                    if (!outputDir.exists()) {
+                        outputDir.mkdirs();
+                    }
+                }
+            }
+        }
+
+        outputFile = File.createTempFile(String.format("recording-%d", System.currentTimeMillis()), ".aac", outputDir);
+
+        if (directory == null) {
+            outputFile.deleteOnExit();
+        }
+
+        mediaRecorder.setOutputFile(outputFile.getAbsolutePath());
+    }
+
+    /** Maps directory strings to Android file locations. */
+    private File getDirectory(String directory) {
+        return switch (directory) {
+            case "DOCUMENTS" -> Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOCUMENTS);
+            case "DATA", "LIBRARY" -> context.getFilesDir();
+            case "CACHE" -> context.getCacheDir();
+            case "EXTERNAL" -> context.getExternalFilesDir(null);
+            case "EXTERNAL_STORAGE" -> Environment.getExternalStorageDirectory();
+            default -> null;
+        };
+    }
+
+    /** Starts recording and requests audio focus. */
+    public void startRecording() {
+        requestAudioFocus();
+        mediaRecorder.start();
+        currentRecordingStatus = CurrentRecordingStatus.RECORDING;
+    }
+
+    /** Stops recording and releases audio resources. */
+    public void stopRecording() {
+        if (mediaRecorder == null) {
+            abandonAudioFocus();
+            currentRecordingStatus = CurrentRecordingStatus.NONE;
+            return;
+        }
+
+        try {
+            if (currentRecordingStatus == CurrentRecordingStatus.RECORDING
+                || currentRecordingStatus == CurrentRecordingStatus.PAUSED
+                || currentRecordingStatus == CurrentRecordingStatus.INTERRUPTED) {
+                mediaRecorder.stop();
+            }
+        } catch (IllegalStateException ignore) {
+        } finally {
+            mediaRecorder.release();
+            mediaRecorder = null;
+            abandonAudioFocus();
+            currentRecordingStatus = CurrentRecordingStatus.NONE;
+        }
+    }
+
+    /** Returns the output file for the current session. */
+    public File getOutputFile() {
+        return outputFile;
+    }
+
+    /** Returns the options provided at start time. */
+    public RecordOptions getRecordOptions() {
+        return options;
+    }
+
+    /** Pauses recording when supported by the OS version. */
+    public boolean pauseRecording() throws NotSupportedOsVersion {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.N) {
+            throw new NotSupportedOsVersion();
+        }
+
+        if (currentRecordingStatus == CurrentRecordingStatus.RECORDING) {
+            mediaRecorder.pause();
+            currentRecordingStatus = CurrentRecordingStatus.PAUSED;
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    /** Resumes a paused or interrupted recording session. */
+    public boolean resumeRecording() throws NotSupportedOsVersion {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.N) {
+            throw new NotSupportedOsVersion();
+        }
+
+        if (currentRecordingStatus == CurrentRecordingStatus.PAUSED || currentRecordingStatus == CurrentRecordingStatus.INTERRUPTED) {
+            requestAudioFocus();
+            mediaRecorder.resume();
+            currentRecordingStatus = CurrentRecordingStatus.RECORDING;
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    /** Returns the current recording status. */
+    public CurrentRecordingStatus getCurrentStatus() {
+        return currentRecordingStatus;
+    }
+
+    /** Deletes the output file from disk. */
+    public boolean deleteOutputFile() {
+        return outputFile.delete();
+    }
+
+    /** Simple capability check used for device validation. */
+    public static boolean canPhoneCreateMediaRecorder(Context context) {
+        return true;
+    }
+
+    /** Attempts to record a short sample to validate permission and hardware. */
+    private static boolean canPhoneCreateMediaRecorderWhileHavingPermission(Context context) {
+        CustomMediaRecorder tempMediaRecorder = null;
+        try {
+            tempMediaRecorder = new CustomMediaRecorder(context, new RecordOptions(null, null));
+            tempMediaRecorder.startRecording();
+            tempMediaRecorder.stopRecording();
+            return true;
+        } catch (Exception exp) {
+            return exp.getMessage().startsWith("stop failed");
+        } finally {
+            if (tempMediaRecorder != null) tempMediaRecorder.deleteOutputFile();
+        }
+    }
+
+    /** Requests audio focus for the recording session. */
+    private void requestAudioFocus() {
+        if (audioManager == null) {
+            return;
+        }
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            AudioAttributes audioAttributes = new AudioAttributes.Builder()
+                .setUsage(AudioAttributes.USAGE_MEDIA)
+                .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+                .build();
+
+            audioFocusRequest = new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
+                .setAudioAttributes(audioAttributes)
+                .setOnAudioFocusChangeListener(this)
+                .build();
+
+            audioManager.requestAudioFocus(audioFocusRequest);
+        } else {
+            audioManager.requestAudioFocus(this, AudioManager.STREAM_MUSIC, AudioManager.AUDIOFOCUS_GAIN);
+        }
+    }
+
+    /** Releases audio focus when recording completes. */
+    private void abandonAudioFocus() {
+        if (audioManager == null) {
+            return;
+        }
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && audioFocusRequest != null) {
+            audioManager.abandonAudioFocusRequest(audioFocusRequest);
+            audioFocusRequest = null;
+        } else {
+            audioManager.abandonAudioFocus(this);
+        }
+    }
+
+    /** Handles audio focus changes as recording interruptions. */
+    @Override
+    public void onAudioFocusChange(int focusChange) {
+        switch (focusChange) {
+            case AudioManager.AUDIOFOCUS_LOSS:
+            case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT:
+            case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK:
+                // For voice recording, ducking still degrades captured audio, so treat all loss types as interruptions.
+                if (currentRecordingStatus == CurrentRecordingStatus.RECORDING) {
+                    try {
+                        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+                            mediaRecorder.pause();
+                            currentRecordingStatus = CurrentRecordingStatus.INTERRUPTED;
+                            if (onInterruptionBegan != null) {
+                                onInterruptionBegan.run();
+                            }
+                        }
+                    } catch (Exception ignore) {
+                    }
+                }
+                break;
+            case AudioManager.AUDIOFOCUS_GAIN:
+                if (currentRecordingStatus == CurrentRecordingStatus.INTERRUPTED) {
+                    if (onInterruptionEnded != null) {
+                        onInterruptionEnded.run();
+                    }
+                }
+                break;
+            default:
+                break;
+        }
+    }
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/platform/DefaultRecorderPlatform.java

@@ -0,0 +1,86 @@
+package app.independo.capacitorvoicerecorder.platform;
+
+import android.content.Context;
+import android.media.AudioManager;
+import android.media.MediaPlayer;
+import android.net.Uri;
+import android.util.Base64;
+import app.independo.capacitorvoicerecorder.adapters.RecorderAdapter;
+import app.independo.capacitorvoicerecorder.adapters.RecorderPlatform;
+import app.independo.capacitorvoicerecorder.core.RecordOptions;
+import java.io.BufferedInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.IOException;
+
+/** Default Android platform adapter for recording and file IO. */
+public class DefaultRecorderPlatform implements RecorderPlatform {
+
+    /** Android context used to access system services. */
+    private final Context context;
+
+    public DefaultRecorderPlatform(Context context) {
+        this.context = context;
+    }
+
+    /** Returns whether the device can create a MediaRecorder instance. */
+    @Override
+    public boolean canDeviceVoiceRecord() {
+        return CustomMediaRecorder.canPhoneCreateMediaRecorder(context);
+    }
+
+    /** Returns true when the system audio mode indicates another recorder. */
+    @Override
+    public boolean isMicrophoneOccupied() {
+        AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
+        if (audioManager == null) return true;
+        return audioManager.getMode() != AudioManager.MODE_NORMAL;
+    }
+
+    /** Creates the recorder adapter for the provided options. */
+    @Override
+    public RecorderAdapter createRecorder(RecordOptions options) throws Exception {
+        return new CustomMediaRecorder(context, options);
+    }
+
+    /** Reads the recorded file as base64, returning null on failure. */
+    @Override
+    public String readFileAsBase64(File recordedFile) {
+        try (BufferedInputStream bufferedInputStream = new BufferedInputStream(new FileInputStream(recordedFile))) {
+            ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
+            byte[] buffer = new byte[8192];
+            int bytesRead;
+            while ((bytesRead = bufferedInputStream.read(buffer)) != -1) {
+                outputStream.write(buffer, 0, bytesRead);
+            }
+            return Base64.encodeToString(outputStream.toByteArray(), Base64.DEFAULT);
+        } catch (IOException exp) {
+            return null;
+        }
+    }
+
+    /** Returns the file duration in milliseconds, or -1 on failure. */
+    @Override
+    public int getDurationMs(File recordedFile) {
+        MediaPlayer mediaPlayer = null;
+        try {
+            mediaPlayer = new MediaPlayer();
+            mediaPlayer.setDataSource(recordedFile.getAbsolutePath());
+            mediaPlayer.prepare();
+            return mediaPlayer.getDuration();
+        } catch (Exception ignore) {
+            return -1;
+        } finally {
+            if (mediaPlayer != null) {
+                mediaPlayer.release();
+            }
+        }
+    }
+
+    /** Returns a file:// URI for the given recording. */
+    @Override
+    public String toUri(File recordedFile) {
+        return Uri.fromFile(recordedFile).toString();
+    }
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/platform/NotSupportedOsVersion.java

@@ -0,0 +1,4 @@
+package app.independo.capacitorvoicerecorder.platform;
+
+/** Signals that a feature is not supported on the current OS version. */
+public class NotSupportedOsVersion extends Exception {}

package/android/src/main/java/app/independo/capacitorvoicerecorder/service/VoiceRecorderService.java

@@ -0,0 +1,144 @@
+package app.independo.capacitorvoicerecorder.service;
+
+import app.independo.capacitorvoicerecorder.adapters.PermissionChecker;
+import app.independo.capacitorvoicerecorder.adapters.RecorderAdapter;
+import app.independo.capacitorvoicerecorder.adapters.RecorderPlatform;
+import app.independo.capacitorvoicerecorder.core.CurrentRecordingStatus;
+import app.independo.capacitorvoicerecorder.core.ErrorCodes;
+import app.independo.capacitorvoicerecorder.core.RecordData;
+import app.independo.capacitorvoicerecorder.core.RecordOptions;
+import app.independo.capacitorvoicerecorder.platform.NotSupportedOsVersion;
+import java.io.File;
+
+/** Service layer that orchestrates recording operations. */
+public class VoiceRecorderService {
+
+    /** Platform adapter that owns file and recorder creation. */
+    private final RecorderPlatform platform;
+    /** Permission checker injected from the bridge layer. */
+    private final PermissionChecker permissionChecker;
+    /** Current recorder instance for an active session. */
+    private RecorderAdapter recorder;
+
+    public VoiceRecorderService(RecorderPlatform platform, PermissionChecker permissionChecker) {
+        this.platform = platform;
+        this.permissionChecker = permissionChecker;
+    }
+
+    /** Returns whether the device can record audio. */
+    public boolean canDeviceVoiceRecord() {
+        return platform.canDeviceVoiceRecord();
+    }
+
+    /** Returns whether the app has microphone permission. */
+    public boolean hasAudioRecordingPermission() {
+        return permissionChecker.hasAudioPermission();
+    }
+
+    /** Starts a recording session or throws a service exception. */
+    public void startRecording(
+        RecordOptions options,
+        Runnable onInterruptionBegan,
+        Runnable onInterruptionEnded
+    ) throws VoiceRecorderServiceException {
+        if (!platform.canDeviceVoiceRecord()) {
+            throw new VoiceRecorderServiceException(ErrorCodes.DEVICE_CANNOT_VOICE_RECORD);
+        }
+
+        if (!permissionChecker.hasAudioPermission()) {
+            throw new VoiceRecorderServiceException(ErrorCodes.MISSING_PERMISSION);
+        }
+
+        if (platform.isMicrophoneOccupied()) {
+            throw new VoiceRecorderServiceException(ErrorCodes.MICROPHONE_BEING_USED);
+        }
+
+        if (recorder != null) {
+            throw new VoiceRecorderServiceException(ErrorCodes.ALREADY_RECORDING);
+        }
+
+        try {
+            recorder = platform.createRecorder(options);
+            recorder.setOnInterruptionBegan(onInterruptionBegan);
+            recorder.setOnInterruptionEnded(onInterruptionEnded);
+            recorder.startRecording();
+        } catch (Exception exp) {
+            recorder = null;
+            throw new VoiceRecorderServiceException(ErrorCodes.FAILED_TO_RECORD, exp);
+        }
+    }
+
+    /** Stops the active recording session and returns the payload. */
+    public RecordData stopRecording() throws VoiceRecorderServiceException {
+        if (recorder == null) {
+            throw new VoiceRecorderServiceException(ErrorCodes.RECORDING_HAS_NOT_STARTED);
+        }
+
+        RecordOptions options = recorder.getRecordOptions();
+
+        try {
+            recorder.stopRecording();
+            File recordedFile = recorder.getOutputFile();
+            if (recordedFile == null) {
+                throw new VoiceRecorderServiceException(ErrorCodes.FAILED_TO_FETCH_RECORDING);
+            }
+
+            String recordDataBase64 = null;
+            String uri = null;
+            if (options.directory() != null) {
+                uri = platform.toUri(recordedFile);
+            } else {
+                recordDataBase64 = platform.readFileAsBase64(recordedFile);
+            }
+
+            int duration = platform.getDurationMs(recordedFile);
+            RecordData recordData = new RecordData(recordDataBase64, duration, "audio/aac", uri);
+            if ((recordDataBase64 == null && uri == null) || recordData.getMsDuration() < 0) {
+                throw new VoiceRecorderServiceException(ErrorCodes.EMPTY_RECORDING);
+            }
+
+            return recordData;
+        } catch (VoiceRecorderServiceException exp) {
+            throw exp;
+        } catch (Exception exp) {
+            throw new VoiceRecorderServiceException(ErrorCodes.FAILED_TO_FETCH_RECORDING, exp);
+        } finally {
+            if (options.directory() == null && recorder != null) {
+                recorder.deleteOutputFile();
+            }
+            recorder = null;
+        }
+    }
+
+    /** Pauses the active recording session. */
+    public boolean pauseRecording() throws VoiceRecorderServiceException {
+        if (recorder == null) {
+            throw new VoiceRecorderServiceException(ErrorCodes.RECORDING_HAS_NOT_STARTED);
+        }
+        try {
+            return recorder.pauseRecording();
+        } catch (NotSupportedOsVersion exception) {
+            throw new VoiceRecorderServiceException(ErrorCodes.NOT_SUPPORTED_OS_VERSION, exception);
+        }
+    }
+
+    /** Resumes a paused recording session. */
+    public boolean resumeRecording() throws VoiceRecorderServiceException {
+        if (recorder == null) {
+            throw new VoiceRecorderServiceException(ErrorCodes.RECORDING_HAS_NOT_STARTED);
+        }
+        try {
+            return recorder.resumeRecording();
+        } catch (NotSupportedOsVersion exception) {
+            throw new VoiceRecorderServiceException(ErrorCodes.NOT_SUPPORTED_OS_VERSION, exception);
+        }
+    }
+
+    /** Returns the current recording status. */
+    public CurrentRecordingStatus getCurrentStatus() {
+        if (recorder == null) {
+            return CurrentRecordingStatus.NONE;
+        }
+        return recorder.getCurrentStatus();
+    }
+}

package/android/src/main/java/app/independo/capacitorvoicerecorder/service/VoiceRecorderServiceException.java

@@ -0,0 +1,23 @@
+package app.independo.capacitorvoicerecorder.service;
+
+/** Exception wrapper that carries a canonical error code. */
+public class VoiceRecorderServiceException extends Exception {
+
+    /** Canonical error code mapped to plugin responses. */
+    private final String code;
+
+    public VoiceRecorderServiceException(String code) {
+        super(code);
+        this.code = code;
+    }
+
+    public VoiceRecorderServiceException(String code, Exception cause) {
+        super(code, cause);
+        this.code = code;
+    }
+
+    /** Returns the canonical error code for this failure. */
+    public String getCode() {
+        return code;
+    }
+}