A Capacitor plugin for microphone audio recording with pause/resume support, real-time status events, and cross-platform compatibility.

Lire en Français

About

This plugin is a fork of @mozartec/capacitor-microphone originally created by Mozart. We are grateful for the solid foundation provided by the original project.

This fork was created to add advanced recording control needed for long-form audio recording use cases (meetings, interviews, lectures, etc.):

• Pause & Resume — Full control over the recording flow without losing data
• Status Tracking — Query the current recording state at any time
• Native Events — Real-time status change notifications via event listeners
• Full cross-platform support: iOS, Android, and Web

Platform Support

| | iOS | Android | Web | | ------------ | -------------------- | -------------------- | -------------------- | | Availability | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Encoding | kAudioFormatMPEG4AAC (audio/aac) | MPEG_4 / AAC (audio/aac) | audio/webm or audio/mp4 or audio/ogg or audio/wav | | Extension | .m4a | .m4a | .webm or .mp4 or .ogg or .wav |

Installation

npm install @dimer47/capacitor-microphone
npx cap sync

iOS Setup

Add the following usage description to your app's Info.plist:

• NSMicrophoneUsageDescription (Privacy - Microphone Usage Description)

Read about Configuring Info.plist in the iOS Guide for more information.

Android Setup

Add the following permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Note: Pause/Resume requires Android API 24+ (Android 7.0 Nougat).

Read about Setting Permissions in the Android Guide for more information.

Usage

import { Microphone } from '@dimer47/capacitor-microphone';

// Request permissions
const { microphone } = await Microphone.requestPermissions();

// Start recording
await Microphone.startRecording();

// Pause / Resume
await Microphone.pauseRecording();
await Microphone.resumeRecording();

// Check status
const { status } = await Microphone.getCurrentStatus();

// Listen to status changes
await Microphone.addListener('status', ({ status }) => {
  console.log('Recording status:', status);
});

// Stop and get the audio file
const recording = await Microphone.stopRecording();
console.log(recording.path, recording.duration, recording.mimeType);

API

• checkPermissions()
• requestPermissions()
• startRecording()
• pauseRecording()
• resumeRecording()
• getCurrentStatus()
• addListener('status', ...)
• removeStatusListener(...)
• removeAllListeners()
• stopRecording()
• Interfaces
• Type Aliases

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Checks microphone permission

Returns: Promise<PermissionStatus>

Since: 0.0.3

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Requests microphone permission

Returns: Promise<PermissionStatus>

Since: 0.0.3

startRecording()

startRecording() => Promise<{ status: string; }>

Starts recoding session if no session is in progress

Returns: Promise<{ status: string; }>

Since: 0.0.3

pauseRecording()

pauseRecording() => Promise<{ status: string; }>

Pauses recoding session if one is in progress

Returns: Promise<{ status: string; }>

Since: 0.0.3

resumeRecording()

resumeRecording() => Promise<{ status: string; }>

Resumes recoding session if one is paused

Returns: Promise<{ status: string; }>

Since: 0.0.3

getCurrentStatus()

getCurrentStatus() => Promise<{ status: string; }>

Gets current recording status

Returns: Promise<{ status: string; }>

Since: 0.0.3

addListener('status', ...)

addListener(eventName: 'status', listenerFunc: (status: { status: string; }) => void) => Promise<PluginListenerHandle>

Adds a listener to microphone status updates

| Param | Type | Description | | ------------------ | ----------------------------------------------------- | -------------------------------- | | eventName | 'status' | status | | listenerFunc | (status: { status: string; }) => void | function to be executed on event |

Returns: Promise<PluginListenerHandle>

Since: 0.0.4

removeStatusListener(...)

removeStatusListener(eventName: 'status', listenerFunc: (status: { status: string; }) => void) => Promise<void>

Removes a specific listener from microphone status updates

| Param | Type | Description | | ------------------ | ----------------------------------------------------- | ---------------------- | | eventName | 'status' | status | | listenerFunc | (status: { status: string; }) => void | function to be removed |

Since: 0.0.4

removeAllListeners()

removeAllListeners() => Promise<void>

Removes all listeners from microphone status updates

Since: 0.0.4

stopRecording()

stopRecording() => Promise<AudioRecording>

Stops recoding session if one is in progress

Returns: Promise<AudioRecording>

Since: 0.0.3

Interfaces

PermissionStatus

| Prop | Type | | ---------------- | ------------------------------------------------------------------------------- | | microphone | MicrophonePermissionState |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

AudioRecording

| Prop | Type | Description | Since | | -------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | path | string | Platform-specific file URL that can be read later using the Filesystem API. | 0.0.3 | | webPath | string | webPath returns a path that can be used to set the src attribute of an audio element and can be useful for testing. | 0.0.3 | | duration | number | recoding duration in milliseconds | 0.0.3 | | format | string | file extension: ".m4a" for (iOS and Android) and ".webm" | ".mp4" | ".ogg" | ".wav" for Web based on compatibility | 0.0.3 | | mimeType | string | file encoding: "audio/aac" for (iOS and Android) and "audio/webm | "audio/mp4" | "audio/ogg" | "audio/wav" for Web based on compatibility | 0.0.3 |

Type Aliases

MicrophonePermissionState

PermissionState | 'limited'

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

Status Messages

The following status strings are returned by the API methods and emitted through status events:

| Status | Description | | ---------------------------------- | ------------------------------------------ | | recording stared | Recording has started successfully | | recording in progress | A recording is currently in progress | | recording paused | Recording has been paused | | recording resumed | Recording has been resumed | | no recording in progress | No active recording session | | microphone permission not granted| Microphone permission was not granted | | cannot record on this phone | Device does not support audio recording | | recording failed | An error occurred during recording | | failed to fetch recording | Could not retrieve the recorded audio file | | microphone is busy | Microphone is already in use |

Acknowledgments

This project is a fork of @mozartec/capacitor-microphone by Mozart. Thank you for creating and maintaining the original plugin that made this work possible.

License

MIT - See LICENSE for details.