@independo/capacitor-voice-recorder 8.1.8 → 8.1.9-dev.2

package/README.md

@@ -21,8 +21,8 @@ The `@independo/capacitor-voice-recorder` plugin allows you to record audio on A
 ## Installation
 
 ```
-npm install --save @independo/capacitor-voice-recorder
-npx cap sync
+pnpm add @independo/capacitor-voice-recorder
+pnpm exec cap sync
 ```
 
 ### Configuration
@@ -48,7 +48,7 @@ Add the following to your `Info.plist`:
 
 - Capacitor 8+
 - iOS 15+
-- Android minSdk 24+; builds require Java 21 (recommended). `npm run verify:android` requires a Java version supported
+- Android minSdk 24+; builds require Java 21 (recommended). `pnpm verify:android` requires a Java version supported
   by the bundled Gradle wrapper (currently Java 21–24, with Java 21 recommended).
 
 ### Compatibility
@@ -93,7 +93,7 @@ export const stopRecording = async () => {
 
 ## API
 
-Below is an index of all available methods. Run `npm run docgen` after updating any JSDoc comments to refresh this
+Below is an index of all available methods. Run `pnpm docgen` after updating any JSDoc comments to refresh this
 section.
 
 <docgen-index>
@@ -322,10 +322,11 @@ Interface representing a generic response with a boolean value.
 
 Can be used to specify options for the recording.
 
-| Prop               | Type                                            | Description                                                                                                                                                                                                        |
-| ------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **`directory`**    | <code><a href="#directory">Directory</a></code> | The capacitor filesystem directory where the recording should be saved. If not specified, the recording will be stored in a base64 string and returned in the <a href="#recordingdata">`RecordingData`</a> object. |
-| **`subDirectory`** | <code>string</code>                             | An optional subdirectory in the specified directory where the recording should be saved.                                                                                                                           |
+| Prop                         | Type                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ---------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`directory`**              | <code><a href="#directory">Directory</a></code> | The capacitor filesystem directory where the recording should be saved. If not specified, the recording will be stored in a base64 string and returned in the <a href="#recordingdata">`RecordingData`</a> object.                                                                                                                                                                                               |
+| **`subDirectory`**           | <code>string</code>                             | An optional subdirectory in the specified directory where the recording should be saved.                                                                                                                                                                                                                                                                                                                         |
+| **`requirePlaybackSupport`** | <code>boolean</code>                            | Whether the web implementation should require the selected recording MIME type to also be playable by the browser's native HTML `&lt;audio&gt;` element. Defaults to `true` on web to reduce cases where `MediaRecorder` reports support for a format but the recorded file cannot be played back in the same browser (observed on some Safari/iOS/WKWebView combinations). Native platforms ignore this option. |
 
 
 #### RecordingData
@@ -412,8 +413,8 @@ an interruption begins, the recording is paused, the status becomes `INTERRUPTED
 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. iOS recordings are normalized to an
+M4A container with MIME type `audio/mp4` for consistent output across interrupted and non-interrupted sessions.
 
 ### Web constraints
 
@@ -422,6 +423,9 @@ If interruptions occur on iOS, recordings are segmented and merged when you stop
 - 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.
+- By default, the web implementation picks a MIME type that is supported for both recording (`MediaRecorder`) and
+  playback (`<audio>`). You can disable the playback probe with `RecordingOptions.requirePlaybackSupport = false` if
+  you prefer recorder-only MIME selection.
 
 ## Recording options and storage
 
@@ -447,9 +451,9 @@ The plugin returns the recording in one of several possible formats. The actual
 browser capabilities.
 
 - 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`
+- iOS: `audio/mp4` (M4A container)
+- Web: first supported MIME type from the plugin's ordered list, with a default preference for formats that are
+  reported as playable by the browser `<audio>` element (in addition to `MediaRecorder` support)
 
 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

package/dist/docs.json

@@ -315,6 +315,13 @@
           "docs": "An optional subdirectory in the specified directory where the recording should be saved.",
           "complexTypes": [],
           "type": "string | undefined"
+        },
+        {
+          "name": "requirePlaybackSupport",
+          "tags": [],
+          "docs": "Whether the web implementation should require the selected recording MIME type\nto also be playable by the browser's native HTML `<audio>` element.\n\nDefaults to `true` on web to reduce cases where `MediaRecorder` reports support\nfor a format but the recorded file cannot be played back in the same browser\n(observed on some Safari/iOS/WKWebView combinations).\n\nNative platforms ignore this option.",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -19,6 +19,17 @@ export interface RecordingOptions {
      * An optional subdirectory in the specified directory where the recording should be saved.
      */
     subDirectory?: string;
+    /**
+     * Whether the web implementation should require the selected recording MIME type
+     * to also be playable by the browser's native HTML `<audio>` element.
+     *
+     * Defaults to `true` on web to reduce cases where `MediaRecorder` reports support
+     * for a format but the recorded file cannot be played back in the same browser
+     * (observed on some Safari/iOS/WKWebView combinations).
+     *
+     * Native platforms ignore this option.
+     */
+    requirePlaybackSupport?: boolean;
 }
 /**
  * Interface representing the data of a recording.

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type {PluginListenerHandle} from \"@capacitor/core\";\nimport type {Directory} from \"@capacitor/filesystem\";\n\n/**\n * Represents a Base64 encoded string.\n */\nexport type Base64String = string;\n\n/**\n * Can be used to specify options for the recording.\n */\nexport interface RecordingOptions {\n    /**\n     * The capacitor filesystem directory where the recording should be saved.\n     *\n     * If not specified, the recording will be stored in a base64 string and returned in the `RecordingData` object.\n     * @see RecordingData\n     */\n    directory?: Directory;\n\n    /**\n     * An optional subdirectory in the specified directory where the recording should be saved.\n     */\n    subDirectory?: string;\n}\n\n/**\n * Interface representing the data of a recording.\n */\nexport interface RecordingData {\n    /**\n     * The value containing the recording details.\n     */\n    value: {\n        /**\n         * The recorded data as a Base64 encoded string.\n         */\n        recordDataBase64: Base64String;\n        /**\n         * The duration of the recording in milliseconds.\n         */\n        msDuration: number;\n        /**\n         * The MIME type of the recorded file.\n         */\n        mimeType: string;\n\n        /**\n         * The URI of the recording file.\n         */\n        uri?: string;\n    };\n}\n\n/**\n * Interface representing a generic response with a boolean value.\n */\nexport interface GenericResponse {\n    /**\n     * The result of the operation as a boolean value.\n     */\n    value: boolean;\n}\n\n/**\n * Interface representing the current status of the voice recorder.\n */\nexport interface CurrentRecordingStatus {\n    /**\n     * The current status of the recorder, which can be one of the following values: 'RECORDING', 'PAUSED', 'INTERRUPTED', 'NONE'.\n     */\n    status: 'RECORDING' | 'PAUSED' | 'INTERRUPTED' | 'NONE';\n}\n\n/**\n * Event payload for voiceRecordingInterrupted event (empty - no data).\n */\nexport type VoiceRecordingInterruptedEvent = Record<string, never>;\n\n/**\n * Event payload for voiceRecordingInterruptionEnded event (empty - no data).\n */\nexport type VoiceRecordingInterruptionEndedEvent = Record<string, never>;\n\n/**\n * Interface for the VoiceRecorderPlugin which provides methods to record audio.\n */\nexport interface VoiceRecorderPlugin {\n    /**\n     * Checks if the current device can record audio.\n     * On mobile, this function will always resolve to `{ value: true }`.\n     * In a browser, it will resolve to `{ value: true }` or `{ value: false }` based on the browser's ability to record.\n     * This method does not take into account the permission status, only if the browser itself is capable of recording at all.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with code \"COULD_NOT_QUERY_PERMISSION_STATUS\" if the device cannot query the permission status.\n     */\n    canDeviceVoiceRecord(): Promise<GenericResponse>;\n\n    /**\n     * Requests audio recording permission from the user.\n     * If the permission has already been provided, the promise will resolve with `{ value: true }`.\n     * Otherwise, the promise will resolve to `{ value: true }` or `{ value: false }` based on the user's response.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error if the permission request fails.\n     */\n    requestAudioRecordingPermission(): Promise<GenericResponse>;\n\n    /**\n     * Checks if audio recording permission has been granted.\n     * Will resolve to `{ value: true }` or `{ value: false }` based on the status of the permission.\n     * The web implementation of this plugin uses the Permissions API, which is not widespread.\n     * If the status of the permission cannot be checked, the promise will reject with `COULD_NOT_QUERY_PERMISSION_STATUS`.\n     * In that case, use `requestAudioRecordingPermission` or `startRecording` and capture any exception that is thrown.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with code \"COULD_NOT_QUERY_PERMISSION_STATUS\" if the device cannot query the permission status.\n     */\n    hasAudioRecordingPermission(): Promise<GenericResponse>;\n\n    /**\n     * Starts audio recording.\n     * On success, the promise will resolve to { value: true }.\n     * On error, the promise will reject with one of the following error codes:\n     * \"MISSING_PERMISSION\", \"ALREADY_RECORDING\", \"MICROPHONE_BEING_USED\", \"DEVICE_CANNOT_VOICE_RECORD\", or \"FAILED_TO_RECORD\".\n     * @param options The options for the recording.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with one of the specified error codes if the recording cannot be started.\n     */\n    startRecording(options?: RecordingOptions): Promise<GenericResponse>;\n\n    /**\n     * Stops audio recording.\n     * Will stop the recording that has been previously started.\n     * If the function `startRecording` has not been called beforehand, the promise will reject with `RECORDING_HAS_NOT_STARTED`.\n     * If the recording has been stopped immediately after it has been started, the promise will reject with `EMPTY_RECORDING`.\n     * In a case of unknown error, the promise will reject with `FAILED_TO_FETCH_RECORDING`.\n     * On iOS, if a recording interrupted by the system cannot be merged, the promise will reject with `FAILED_TO_MERGE_RECORDING`.\n     * In case of success, the promise resolves to RecordingData containing the recording in base-64, the duration of the recording in milliseconds, and the MIME type.\n     * @returns A promise that resolves to RecordingData.\n     * @throws Error with one of the specified error codes if the recording cannot be stopped.\n     */\n    stopRecording(): Promise<RecordingData>;\n\n    /**\n     * Pauses the ongoing audio recording.\n     * If the recording has not started yet, the promise will reject with an error code `RECORDING_HAS_NOT_STARTED`.\n     * On success, the promise will resolve to { value: true } if the pause was successful or { value: false } if the recording is already paused.\n     * On certain mobile OS versions, this function is not supported and will reject with `NOT_SUPPORTED_OS_VERSION`.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with one of the specified error codes if the recording cannot be paused.\n     */\n    pauseRecording(): Promise<GenericResponse>;\n\n    /**\n     * Resumes a paused or interrupted audio recording.\n     * If the recording has not started yet, the promise will reject with an error code `RECORDING_HAS_NOT_STARTED`.\n     * On success, the promise will resolve to { value: true } if the resume was successful or { value: false } if the recording is already running.\n     * On certain mobile OS versions, this function is not supported and will reject with `NOT_SUPPORTED_OS_VERSION`.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with one of the specified error codes if the recording cannot be resumed.\n     */\n    resumeRecording(): Promise<GenericResponse>;\n\n    /**\n     * Gets the current status of the voice recorder.\n     * Will resolve with one of the following values:\n     * `{ status: \"NONE\" }` if the plugin is idle and waiting to start a new recording.\n     * `{ status: \"RECORDING\" }` if the plugin is in the middle of recording.\n     * `{ status: \"PAUSED\" }` if the recording is paused.\n     * `{ status: \"INTERRUPTED\" }` if the recording was paused due to a system interruption.\n     * @returns A promise that resolves to a CurrentRecordingStatus.\n     * @throws Error if the status cannot be fetched.\n     */\n    getCurrentStatus(): Promise<CurrentRecordingStatus>;\n\n    /**\n     * Listen for audio recording interruptions (e.g., phone calls, other apps using microphone).\n     * Available on iOS and Android only.\n     *\n     * @param eventName The name of the event to listen for.\n     * @param listenerFunc The callback function to invoke when the event occurs.\n     * @returns A promise that resolves to a PluginListenerHandle.\n     */\n    addListener(\n        eventName: 'voiceRecordingInterrupted',\n        listenerFunc: (event: VoiceRecordingInterruptedEvent) => void,\n    ): Promise<PluginListenerHandle>;\n\n    /**\n     * Listen for audio recording interruption end events.\n     * Available on iOS and Android only.\n     *\n     * @param eventName The name of the event to listen for.\n     * @param listenerFunc The callback function to invoke when the event occurs.\n     * @returns A promise that resolves to a PluginListenerHandle.\n     */\n    addListener(\n        eventName: 'voiceRecordingInterruptionEnded',\n        listenerFunc: (event: VoiceRecordingInterruptionEndedEvent) => void,\n    ): Promise<PluginListenerHandle>;\n\n    /**\n     * Remove all listeners for this plugin.\n     */\n    removeAllListeners(): Promise<void>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type {PluginListenerHandle} from \"@capacitor/core\";\nimport type {Directory} from \"@capacitor/filesystem\";\n\n/**\n * Represents a Base64 encoded string.\n */\nexport type Base64String = string;\n\n/**\n * Can be used to specify options for the recording.\n */\nexport interface RecordingOptions {\n    /**\n     * The capacitor filesystem directory where the recording should be saved.\n     *\n     * If not specified, the recording will be stored in a base64 string and returned in the `RecordingData` object.\n     * @see RecordingData\n     */\n    directory?: Directory;\n\n    /**\n     * An optional subdirectory in the specified directory where the recording should be saved.\n     */\n    subDirectory?: string;\n\n    /**\n     * Whether the web implementation should require the selected recording MIME type\n     * to also be playable by the browser's native HTML `<audio>` element.\n     *\n     * Defaults to `true` on web to reduce cases where `MediaRecorder` reports support\n     * for a format but the recorded file cannot be played back in the same browser\n     * (observed on some Safari/iOS/WKWebView combinations).\n     *\n     * Native platforms ignore this option.\n     */\n    requirePlaybackSupport?: boolean;\n}\n\n/**\n * Interface representing the data of a recording.\n */\nexport interface RecordingData {\n    /**\n     * The value containing the recording details.\n     */\n    value: {\n        /**\n         * The recorded data as a Base64 encoded string.\n         */\n        recordDataBase64: Base64String;\n        /**\n         * The duration of the recording in milliseconds.\n         */\n        msDuration: number;\n        /**\n         * The MIME type of the recorded file.\n         */\n        mimeType: string;\n\n        /**\n         * The URI of the recording file.\n         */\n        uri?: string;\n    };\n}\n\n/**\n * Interface representing a generic response with a boolean value.\n */\nexport interface GenericResponse {\n    /**\n     * The result of the operation as a boolean value.\n     */\n    value: boolean;\n}\n\n/**\n * Interface representing the current status of the voice recorder.\n */\nexport interface CurrentRecordingStatus {\n    /**\n     * The current status of the recorder, which can be one of the following values: 'RECORDING', 'PAUSED', 'INTERRUPTED', 'NONE'.\n     */\n    status: 'RECORDING' | 'PAUSED' | 'INTERRUPTED' | 'NONE';\n}\n\n/**\n * Event payload for voiceRecordingInterrupted event (empty - no data).\n */\nexport type VoiceRecordingInterruptedEvent = Record<string, never>;\n\n/**\n * Event payload for voiceRecordingInterruptionEnded event (empty - no data).\n */\nexport type VoiceRecordingInterruptionEndedEvent = Record<string, never>;\n\n/**\n * Interface for the VoiceRecorderPlugin which provides methods to record audio.\n */\nexport interface VoiceRecorderPlugin {\n    /**\n     * Checks if the current device can record audio.\n     * On mobile, this function will always resolve to `{ value: true }`.\n     * In a browser, it will resolve to `{ value: true }` or `{ value: false }` based on the browser's ability to record.\n     * This method does not take into account the permission status, only if the browser itself is capable of recording at all.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with code \"COULD_NOT_QUERY_PERMISSION_STATUS\" if the device cannot query the permission status.\n     */\n    canDeviceVoiceRecord(): Promise<GenericResponse>;\n\n    /**\n     * Requests audio recording permission from the user.\n     * If the permission has already been provided, the promise will resolve with `{ value: true }`.\n     * Otherwise, the promise will resolve to `{ value: true }` or `{ value: false }` based on the user's response.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error if the permission request fails.\n     */\n    requestAudioRecordingPermission(): Promise<GenericResponse>;\n\n    /**\n     * Checks if audio recording permission has been granted.\n     * Will resolve to `{ value: true }` or `{ value: false }` based on the status of the permission.\n     * The web implementation of this plugin uses the Permissions API, which is not widespread.\n     * If the status of the permission cannot be checked, the promise will reject with `COULD_NOT_QUERY_PERMISSION_STATUS`.\n     * In that case, use `requestAudioRecordingPermission` or `startRecording` and capture any exception that is thrown.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with code \"COULD_NOT_QUERY_PERMISSION_STATUS\" if the device cannot query the permission status.\n     */\n    hasAudioRecordingPermission(): Promise<GenericResponse>;\n\n    /**\n     * Starts audio recording.\n     * On success, the promise will resolve to { value: true }.\n     * On error, the promise will reject with one of the following error codes:\n     * \"MISSING_PERMISSION\", \"ALREADY_RECORDING\", \"MICROPHONE_BEING_USED\", \"DEVICE_CANNOT_VOICE_RECORD\", or \"FAILED_TO_RECORD\".\n     * @param options The options for the recording.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with one of the specified error codes if the recording cannot be started.\n     */\n    startRecording(options?: RecordingOptions): Promise<GenericResponse>;\n\n    /**\n     * Stops audio recording.\n     * Will stop the recording that has been previously started.\n     * If the function `startRecording` has not been called beforehand, the promise will reject with `RECORDING_HAS_NOT_STARTED`.\n     * If the recording has been stopped immediately after it has been started, the promise will reject with `EMPTY_RECORDING`.\n     * In a case of unknown error, the promise will reject with `FAILED_TO_FETCH_RECORDING`.\n     * On iOS, if a recording interrupted by the system cannot be merged, the promise will reject with `FAILED_TO_MERGE_RECORDING`.\n     * In case of success, the promise resolves to RecordingData containing the recording in base-64, the duration of the recording in milliseconds, and the MIME type.\n     * @returns A promise that resolves to RecordingData.\n     * @throws Error with one of the specified error codes if the recording cannot be stopped.\n     */\n    stopRecording(): Promise<RecordingData>;\n\n    /**\n     * Pauses the ongoing audio recording.\n     * If the recording has not started yet, the promise will reject with an error code `RECORDING_HAS_NOT_STARTED`.\n     * On success, the promise will resolve to { value: true } if the pause was successful or { value: false } if the recording is already paused.\n     * On certain mobile OS versions, this function is not supported and will reject with `NOT_SUPPORTED_OS_VERSION`.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with one of the specified error codes if the recording cannot be paused.\n     */\n    pauseRecording(): Promise<GenericResponse>;\n\n    /**\n     * Resumes a paused or interrupted audio recording.\n     * If the recording has not started yet, the promise will reject with an error code `RECORDING_HAS_NOT_STARTED`.\n     * On success, the promise will resolve to { value: true } if the resume was successful or { value: false } if the recording is already running.\n     * On certain mobile OS versions, this function is not supported and will reject with `NOT_SUPPORTED_OS_VERSION`.\n     * @returns A promise that resolves to a GenericResponse.\n     * @throws Error with one of the specified error codes if the recording cannot be resumed.\n     */\n    resumeRecording(): Promise<GenericResponse>;\n\n    /**\n     * Gets the current status of the voice recorder.\n     * Will resolve with one of the following values:\n     * `{ status: \"NONE\" }` if the plugin is idle and waiting to start a new recording.\n     * `{ status: \"RECORDING\" }` if the plugin is in the middle of recording.\n     * `{ status: \"PAUSED\" }` if the recording is paused.\n     * `{ status: \"INTERRUPTED\" }` if the recording was paused due to a system interruption.\n     * @returns A promise that resolves to a CurrentRecordingStatus.\n     * @throws Error if the status cannot be fetched.\n     */\n    getCurrentStatus(): Promise<CurrentRecordingStatus>;\n\n    /**\n     * Listen for audio recording interruptions (e.g., phone calls, other apps using microphone).\n     * Available on iOS and Android only.\n     *\n     * @param eventName The name of the event to listen for.\n     * @param listenerFunc The callback function to invoke when the event occurs.\n     * @returns A promise that resolves to a PluginListenerHandle.\n     */\n    addListener(\n        eventName: 'voiceRecordingInterrupted',\n        listenerFunc: (event: VoiceRecordingInterruptedEvent) => void,\n    ): Promise<PluginListenerHandle>;\n\n    /**\n     * Listen for audio recording interruption end events.\n     * Available on iOS and Android only.\n     *\n     * @param eventName The name of the event to listen for.\n     * @param listenerFunc The callback function to invoke when the event occurs.\n     * @returns A promise that resolves to a PluginListenerHandle.\n     */\n    addListener(\n        eventName: 'voiceRecordingInterruptionEnded',\n        listenerFunc: (event: VoiceRecordingInterruptionEndedEvent) => void,\n    ): Promise<PluginListenerHandle>;\n\n    /**\n     * Remove all listeners for this plugin.\n     */\n    removeAllListeners(): Promise<void>;\n}\n"]}

package/dist/esm/platform/web/VoiceRecorderImpl.d.ts

@@ -1,23 +1,64 @@
 import type { CurrentRecordingStatus, GenericResponse, RecordingData, RecordingOptions } from '../../definitions';
-/** Preferred MIME types to probe in order of fallback. */
-declare const POSSIBLE_MIME_TYPES: {
-    'audio/aac': string;
-    'audio/webm;codecs=opus': string;
-    'audio/mp4': string;
-    'audio/webm': string;
-    'audio/ogg;codecs=opus': string;
-};
+/**
+ * Ordered MIME types to probe for audio recording via `MediaRecorder.isTypeSupported()`.
+ *
+ * ⚠️ The order is intentional and MUST remain stable unless you also update the
+ * selection policy in code and test on Safari/iOS + WebViews.
+ *
+ * ✅ What this list is used for
+ * - Selecting a `mimeType` for `new MediaRecorder(stream, { mimeType })`.
+ *
+ * ❌ What this list does NOT guarantee
+ * - It does NOT guarantee that the recorded output will be playable via the
+ *   HTML `<audio>` element in the same browser.
+ *
+ * Real-world caveat (important):
+ * - We have observed cases where `MediaRecorder.isTypeSupported('audio/webm;codecs=opus')`
+ *   returned `true`, the recorder produced a Blob, but `<audio>` could not play it.
+ *   This can happen due to container/codec playback support differences, platform
+ *   quirks (especially Safari/iOS / WKWebView), or incomplete WebM playback support.
+ *
+ * Current selection behavior in this implementation:
+ * - By default, MIME selection treats recorder support and playback support as separate
+ *   capabilities and probes both:
+ *   - Recorder capability: `MediaRecorder.isTypeSupported(type)`
+ *   - Playback capability: `audio.canPlayType(type)`
+ * - This default can be disabled via `RecordingOptions.requirePlaybackSupport = false`
+ *   to fall back to recorder-only probing.
+ *
+ * Keeping legacy keys:
+ * - Some entries are kept even if they overlap (e.g. `audio/mp4` and explicit codec),
+ *   to maximize compatibility across differing browser implementations.
+ */
+declare const POSSIBLE_MIME_TYPES: Record<string, string>;
 /** Browser implementation backed by MediaRecorder and Capacitor Filesystem. */
 export declare class VoiceRecorderImpl {
+    /** Default behavior for web MIME selection: require recorder + playback support. */
+    private static readonly DEFAULT_REQUIRE_PLAYBACK_SUPPORT;
     /** Active MediaRecorder instance, if recording. */
     private mediaRecorder;
     /** Collected data chunks from MediaRecorder. */
     private chunks;
     /** Promise resolved when the recorder stops and payload is ready. */
     private pendingResult;
-    /** Returns whether the browser can start a recording session. */
-    static canDeviceVoiceRecord(): Promise<GenericResponse>;
-    /** Starts a recording session using MediaRecorder. */
+    /**
+     * Returns whether the browser can start a recording session.
+     *
+     * On web this checks:
+     * - `navigator.mediaDevices.getUserMedia`
+     * - at least one supported recording MIME type using {@link getSupportedMimeType}
+     *
+     * The optional `requirePlaybackSupport` flag is forwarded to MIME selection and defaults
+     * to `true` when omitted.
+     */
+    static canDeviceVoiceRecord(options?: Pick<RecordingOptions, 'requirePlaybackSupport'>): Promise<GenericResponse>;
+    /**
+     * Starts a recording session using `MediaRecorder`.
+     *
+     * The selected MIME type is resolved once at start time (using the optional
+     * `requirePlaybackSupport` flag from `RecordingOptions`) and reused for the final Blob
+     * and file extension to keep the recording payload internally consistent.
+     */
     startRecording(options?: RecordingOptions): Promise<GenericResponse>;
     /** Stops the current recording and resolves the pending payload. */
     stopRecording(): Promise<RecordingData>;
@@ -31,8 +72,41 @@ export declare class VoiceRecorderImpl {
     resumeRecording(): Promise<GenericResponse>;
     /** Returns the current recording status from MediaRecorder. */
     getCurrentStatus(): Promise<CurrentRecordingStatus>;
-    /** Returns the first supported MIME type, if any. */
-    static getSupportedMimeType<T extends keyof typeof POSSIBLE_MIME_TYPES>(): T | null;
+    /**
+     * Returns the first MIME type (key of {@link POSSIBLE_MIME_TYPES}) that the current
+     * environment reports as supported for recording via `MediaRecorder.isTypeSupported()`,
+     * optionally requiring native HTML `<audio>` playback support too.
+     *
+     * The search order is the iteration order of {@link POSSIBLE_MIME_TYPES}.
+     *
+     * @typeParam T - A MIME type string that exists as a key in {@link POSSIBLE_MIME_TYPES}.
+     *
+     * @returns The first supported MIME type for `MediaRecorder`, or `null` if:
+     * - `MediaRecorder` is unavailable, or
+     * - no configured MIME types are supported.
+     *
+     * ⚠️ Important: `MediaRecorder` support ≠ `<audio>` playback support
+     *
+     * Some browsers/platforms can claim support for recording a format (notably WebM/Opus)
+     * but still fail to play the resulting Blob through the native HTML audio pipeline.
+     * This mismatch is especially likely on Safari/iOS / WKWebView variants, so the default
+     * behavior also probes `HTMLAudioElement.canPlayType(type)` when available.
+     *
+     * Selection policy when playback probing is enabled:
+     * - keep the global priority order from {@link POSSIBLE_MIME_TYPES}
+     * - among recordable types, prefer the first `"probably"` playable candidate
+     * - otherwise return the first `"maybe"` playable candidate
+     * - treat `""` as not playable
+     *
+     * Note: The <audio> element is never attached to the DOM, so it won't appear to users or assistive tech.
+     *
+     * Fallback behavior:
+     * - If `document` / `audio.canPlayType` is unavailable (e.g. SSR-like environments),
+     *   this falls back to record-only probing.
+     */
+    static getSupportedMimeType<T extends keyof typeof POSSIBLE_MIME_TYPES>(options?: {
+        requirePlaybackSupport?: boolean;
+    }): T | null;
     /** Initializes MediaRecorder and wires up handlers. */
     private onSuccessfullyStartedRecording;
     /** Handles failures from getUserMedia. */

package/dist/esm/platform/web/VoiceRecorderImpl.js

@@ -2,13 +2,51 @@ import { Filesystem } from '@capacitor/filesystem';
 import write_blob from 'capacitor-blob-writer';
 import getBlobDuration from './get-blob-duration';
 import { alreadyRecordingError, couldNotQueryPermissionStatusError, deviceCannotVoiceRecordError, emptyRecordingError, failedToFetchRecordingError, failedToRecordError, failureResponse, missingPermissionError, recordingHasNotStartedError, successResponse, } from './predefined-web-responses';
-/** Preferred MIME types to probe in order of fallback. */
+/**
+ * Ordered MIME types to probe for audio recording via `MediaRecorder.isTypeSupported()`.
+ *
+ * ⚠️ The order is intentional and MUST remain stable unless you also update the
+ * selection policy in code and test on Safari/iOS + WebViews.
+ *
+ * ✅ What this list is used for
+ * - Selecting a `mimeType` for `new MediaRecorder(stream, { mimeType })`.
+ *
+ * ❌ What this list does NOT guarantee
+ * - It does NOT guarantee that the recorded output will be playable via the
+ *   HTML `<audio>` element in the same browser.
+ *
+ * Real-world caveat (important):
+ * - We have observed cases where `MediaRecorder.isTypeSupported('audio/webm;codecs=opus')`
+ *   returned `true`, the recorder produced a Blob, but `<audio>` could not play it.
+ *   This can happen due to container/codec playback support differences, platform
+ *   quirks (especially Safari/iOS / WKWebView), or incomplete WebM playback support.
+ *
+ * Current selection behavior in this implementation:
+ * - By default, MIME selection treats recorder support and playback support as separate
+ *   capabilities and probes both:
+ *   - Recorder capability: `MediaRecorder.isTypeSupported(type)`
+ *   - Playback capability: `audio.canPlayType(type)`
+ * - This default can be disabled via `RecordingOptions.requirePlaybackSupport = false`
+ *   to fall back to recorder-only probing.
+ *
+ * Keeping legacy keys:
+ * - Some entries are kept even if they overlap (e.g. `audio/mp4` and explicit codec),
+ *   to maximize compatibility across differing browser implementations.
+ */
 const POSSIBLE_MIME_TYPES = {
-    'audio/aac': '.aac',
-    'audio/webm;codecs=opus': '.ogg',
-    'audio/mp4': '.mp3',
-    'audio/webm': '.ogg',
-    'audio/ogg;codecs=opus': '.ogg',
+    // ✅ Most universal
+    'audio/mp4;codecs="mp4a.40.2"': '.m4a', // AAC in MP4 (explicit codec helps detection)
+    'audio/mp4': '.m4a', // (legacy key kept; broad support)
+    'audio/aac': '.aac', // (legacy key kept; less common in the wild)
+    'audio/mpeg': '.mp3', // MP3 (universal)
+    'audio/wav': '.wav', // WAV (universal, big files)
+    // ✅ Modern high-quality (very widely supported, but slightly less “universal” than MP3/AAC)
+    'audio/webm;codecs="opus"': '.webm', // Opus in WebM (explicit codec helps detection)
+    'audio/webm;codecs=opus': '.webm', // (legacy key kept)
+    'audio/webm': '.webm', // (legacy key kept; container-only, codec-dependent)
+    // ⚠️ Least universal (Safari/iOS historically the limiting factor)
+    'audio/ogg;codecs=opus': '.ogg', // (legacy key kept)
+    'audio/ogg;codecs=vorbis': '.ogg', // Ogg Vorbis (weakest mainstream support)
 };
 /** Creates a promise that never resolves. */
 const neverResolvingPromise = () => new Promise(() => undefined);
@@ -22,22 +60,40 @@ export class VoiceRecorderImpl {
         /** Promise resolved when the recorder stops and payload is ready. */
         this.pendingResult = neverResolvingPromise();
     }
-    /** Returns whether the browser can start a recording session. */
-    static async canDeviceVoiceRecord() {
+    /**
+     * Returns whether the browser can start a recording session.
+     *
+     * On web this checks:
+     * - `navigator.mediaDevices.getUserMedia`
+     * - at least one supported recording MIME type using {@link getSupportedMimeType}
+     *
+     * The optional `requirePlaybackSupport` flag is forwarded to MIME selection and defaults
+     * to `true` when omitted.
+     */
+    static async canDeviceVoiceRecord(options) {
         var _a;
-        if (((_a = navigator === null || navigator === void 0 ? void 0 : navigator.mediaDevices) === null || _a === void 0 ? void 0 : _a.getUserMedia) == null || VoiceRecorderImpl.getSupportedMimeType() == null) {
+        if (((_a = navigator === null || navigator === void 0 ? void 0 : navigator.mediaDevices) === null || _a === void 0 ? void 0 : _a.getUserMedia) == null ||
+            VoiceRecorderImpl.getSupportedMimeType({
+                requirePlaybackSupport: options === null || options === void 0 ? void 0 : options.requirePlaybackSupport,
+            }) == null) {
             return failureResponse();
         }
         else {
             return successResponse();
         }
     }
-    /** Starts a recording session using MediaRecorder. */
+    /**
+     * Starts a recording session using `MediaRecorder`.
+     *
+     * The selected MIME type is resolved once at start time (using the optional
+     * `requirePlaybackSupport` flag from `RecordingOptions`) and reused for the final Blob
+     * and file extension to keep the recording payload internally consistent.
+     */
     async startRecording(options) {
         if (this.mediaRecorder != null) {
             throw alreadyRecordingError();
         }
-        const deviceCanRecord = await VoiceRecorderImpl.canDeviceVoiceRecord();
+        const deviceCanRecord = await VoiceRecorderImpl.canDeviceVoiceRecord(options);
         if (!deviceCanRecord.value) {
             throw deviceCannotVoiceRecordError();
         }
@@ -139,30 +195,91 @@ export class VoiceRecorderImpl {
             return Promise.resolve({ status: 'NONE' });
         }
     }
-    /** Returns the first supported MIME type, if any. */
-    static getSupportedMimeType() {
+    /**
+     * Returns the first MIME type (key of {@link POSSIBLE_MIME_TYPES}) that the current
+     * environment reports as supported for recording via `MediaRecorder.isTypeSupported()`,
+     * optionally requiring native HTML `<audio>` playback support too.
+     *
+     * The search order is the iteration order of {@link POSSIBLE_MIME_TYPES}.
+     *
+     * @typeParam T - A MIME type string that exists as a key in {@link POSSIBLE_MIME_TYPES}.
+     *
+     * @returns The first supported MIME type for `MediaRecorder`, or `null` if:
+     * - `MediaRecorder` is unavailable, or
+     * - no configured MIME types are supported.
+     *
+     * ⚠️ Important: `MediaRecorder` support ≠ `<audio>` playback support
+     *
+     * Some browsers/platforms can claim support for recording a format (notably WebM/Opus)
+     * but still fail to play the resulting Blob through the native HTML audio pipeline.
+     * This mismatch is especially likely on Safari/iOS / WKWebView variants, so the default
+     * behavior also probes `HTMLAudioElement.canPlayType(type)` when available.
+     *
+     * Selection policy when playback probing is enabled:
+     * - keep the global priority order from {@link POSSIBLE_MIME_TYPES}
+     * - among recordable types, prefer the first `"probably"` playable candidate
+     * - otherwise return the first `"maybe"` playable candidate
+     * - treat `""` as not playable
+     *
+     * Note: The <audio> element is never attached to the DOM, so it won't appear to users or assistive tech.
+     *
+     * Fallback behavior:
+     * - If `document` / `audio.canPlayType` is unavailable (e.g. SSR-like environments),
+     *   this falls back to record-only probing.
+     */
+    static getSupportedMimeType(options) {
+        var _a, _b, _c, _d, _e;
         if ((MediaRecorder === null || MediaRecorder === void 0 ? void 0 : MediaRecorder.isTypeSupported) == null)
             return null;
-        const foundSupportedType = Object.keys(POSSIBLE_MIME_TYPES).find((type) => MediaRecorder.isTypeSupported(type));
-        return foundSupportedType !== null && foundSupportedType !== void 0 ? foundSupportedType : null;
+        const orderedTypes = Object.keys(POSSIBLE_MIME_TYPES);
+        const recordSupportedTypes = orderedTypes.filter((type) => MediaRecorder.isTypeSupported(type));
+        if (recordSupportedTypes.length === 0)
+            return null;
+        const requirePlaybackSupport = (_a = options === null || options === void 0 ? void 0 : options.requirePlaybackSupport) !== null && _a !== void 0 ? _a : VoiceRecorderImpl.DEFAULT_REQUIRE_PLAYBACK_SUPPORT;
+        if (!requirePlaybackSupport) {
+            return (_b = recordSupportedTypes[0]) !== null && _b !== void 0 ? _b : null;
+        }
+        if (typeof document === 'undefined' || typeof document.createElement !== 'function') {
+            return (_c = recordSupportedTypes[0]) !== null && _c !== void 0 ? _c : null;
+        }
+        const audioElement = document.createElement('audio');
+        if (typeof audioElement.canPlayType !== 'function') {
+            return (_d = recordSupportedTypes[0]) !== null && _d !== void 0 ? _d : null;
+        }
+        let firstProbably = null;
+        let firstMaybe = null;
+        for (const type of recordSupportedTypes) {
+            const playbackSupport = audioElement.canPlayType(type);
+            if (playbackSupport === 'probably') {
+                firstProbably = type;
+                break;
+            }
+            if (playbackSupport === 'maybe' && firstMaybe == null) {
+                firstMaybe = type;
+            }
+        }
+        return (_e = firstProbably !== null && firstProbably !== void 0 ? firstProbably : firstMaybe) !== null && _e !== void 0 ? _e : null;
     }
     /** Initializes MediaRecorder and wires up handlers. */
     onSuccessfullyStartedRecording(stream, options) {
         this.pendingResult = new Promise((resolve, reject) => {
-            this.mediaRecorder = new MediaRecorder(stream);
+            const mimeType = VoiceRecorderImpl.getSupportedMimeType({
+                requirePlaybackSupport: options === null || options === void 0 ? void 0 : options.requirePlaybackSupport,
+            });
+            if (mimeType == null) {
+                this.prepareInstanceForNextOperation();
+                reject(failedToRecordError());
+                return;
+            }
+            this.mediaRecorder = new MediaRecorder(stream, { mimeType });
             this.mediaRecorder.onerror = () => {
                 this.prepareInstanceForNextOperation();
                 reject(failedToRecordError());
             };
             this.mediaRecorder.onstop = async () => {
-                var _a, _b, _c;
-                const mimeType = VoiceRecorderImpl.getSupportedMimeType();
-                if (mimeType == null) {
-                    this.prepareInstanceForNextOperation();
-                    reject(failedToFetchRecordingError());
-                    return;
-                }
-                const blobVoiceRecording = new Blob(this.chunks, { type: mimeType });
+                var _a, _b, _c, _d, _e;
+                const mt = (_b = (_a = this.mediaRecorder) === null || _a === void 0 ? void 0 : _a.mimeType) !== null && _b !== void 0 ? _b : mimeType;
+                const blobVoiceRecording = new Blob(this.chunks, { type: mt });
                 if (blobVoiceRecording.size <= 0) {
                     this.prepareInstanceForNextOperation();
                     reject(emptyRecordingError());
@@ -171,8 +288,8 @@ export class VoiceRecorderImpl {
                 let uri = undefined;
                 let recordDataBase64 = '';
                 if (options === null || options === void 0 ? void 0 : options.directory) {
-                    const subDirectory = (_c = (_b = (_a = options.subDirectory) === null || _a === void 0 ? void 0 : _a.match(/^\/?(.+[^/])\/?$/)) === null || _b === void 0 ? void 0 : _b[1]) !== null && _c !== void 0 ? _c : '';
-                    const path = `${subDirectory}/recording-${new Date().getTime()}${POSSIBLE_MIME_TYPES[mimeType]}`;
+                    const subDirectory = (_e = (_d = (_c = options.subDirectory) === null || _c === void 0 ? void 0 : _c.match(/^\/?(.+[^/])\/?$/)) === null || _d === void 0 ? void 0 : _d[1]) !== null && _e !== void 0 ? _e : '';
+                    const path = `${subDirectory}/recording-${new Date().getTime()}${POSSIBLE_MIME_TYPES[mt]}`;
                     await write_blob({
                         blob: blobVoiceRecording,
                         directory: options.directory,
@@ -187,7 +304,14 @@ export class VoiceRecorderImpl {
                 }
                 const recordingDuration = await getBlobDuration(blobVoiceRecording);
                 this.prepareInstanceForNextOperation();
-                resolve({ value: { recordDataBase64, mimeType, msDuration: recordingDuration * 1000, uri } });
+                resolve({
+                    value: {
+                        recordDataBase64,
+                        mimeType: mt,
+                        msDuration: recordingDuration * 1000,
+                        uri
+                    }
+                });
             };
             this.mediaRecorder.ondataavailable = (event) => this.chunks.push(event.data);
             this.mediaRecorder.start();
@@ -227,4 +351,6 @@ export class VoiceRecorderImpl {
         this.chunks = [];
     }
 }
+/** Default behavior for web MIME selection: require recorder + playback support. */
+VoiceRecorderImpl.DEFAULT_REQUIRE_PLAYBACK_SUPPORT = true;
 //# sourceMappingURL=VoiceRecorderImpl.js.map