High-quality audio recording Capacitor plugin with native iOS & Android support. Features pause/resume, microphone management, real-time monitoring, audio trimming, and comprehensive mobile audio recording capabilities.
npm install capacitor-audio-engineA powerful Capacitor plugin for audio recording and playback on mobile devices. This plugin provides high-quality audio recording with real-time monitoring and flexible playback controls for iOS and Android platforms.
> đĄ Note: This plugin is designed for native mobile platforms (Android and iOS). Web platform is not supported.
| Method Name | Description |
| -------------------------------------------------------------------------- | ------------------------------------------------------- |
| checkPermissions | Check all audio-related permissions. |
| checkPermissionMicrophone | Check microphone permission. |
| checkPermissionNotifications | Check notification permission. |
| requestPermissions | Request all permissions with optional configuration. |
| requestPermissionMicrophone | Request microphone permission only. |
| requestPermissionNotifications | Request notification permission only. |
| openSettings | Open device settings for manual permission management. |
| startRecording | Start recording with specified output path. |
| stopRecording | Stop recording and get file information. |
| pauseRecording | Pause the current recording. |
| resumeRecording | Resume a paused recording. |
| resetRecording | Reset the current recording session without finalizing. |
| getRecordingStatus | Get current recording status. |
| preloadTracks | Preload audio tracks for optimized playback. |
| playAudio | Play current track or specific track by URL. |
| pauseAudio | Pause current track or specific track. |
| resumeAudio | Resume paused playback. |
| stopAudio | Stop playback and reset to beginning. |
| seekAudio | Seek to specific position in track. |
| skipToNext | Skip to next track in playlist. |
| skipToPrevious | Skip to previous track in playlist. |
| skipToIndex | Jump to specific track by index. |
| getPlaybackInfo | Get current playback information. |
| configureWaveform | Configure real-time audio level monitoring. |
| destroyWaveform | Clean up waveform resources. |
| trimAudio | Trim audio file to specific time range. |
| getAudioInfo | Get detailed audio file information. |
| addListener | Listen for recording and playback events. |
| removeAllListeners | Remove all event listeners. |
| Name | Description |
| --------------------------------------------------------------- | ----------------------------------------------- |
| AudioFileInfo | Complete information about an audio file. |
| PermissionStatusResults | Simplified permission status. |
| PermissionStatus | Enum for detailed permission statuses. |
| AudioPermissionType | Enum for audio permission types. |
| RecordingStatusInfo | Current recording state. |
| RecordingStatus | Type for recording statuses. |
| PlaybackInfo | Current playback state. |
| PlaybackStatus | Type for playback statuses. |
| WaveLevelConfiguration | Waveform monitoring configuration. |
| WaveLevelEmissionInterval | Enum for waveform emission intervals. |
| PermissionRequestOptions | Options for requesting permissions. |
| PreloadTracksOptions | Options for preloading audio tracks. |
| PreloadTracksResult | Result of preloading tracks. |
| PreloadedTrackInfo | Information about preloaded tracks. |
| PlayAudioOptions | Options for playing audio. |
| PauseAudioOptions | Options for pausing audio. |
| ResumeAudioOptions | Options for resuming audio. |
| StopAudioOptions | Options for stopping audio. |
| SeekOptions | Options for seeking audio. |
| SkipToIndexOptions | Options for skipping to a specific track index. |
| WaveLevelConfigurationResult | Result of waveform configuration. |
| TrimAudioOptions | Options for trimming audio. |
| DurationChangeData | Event data for duration changes. |
| WaveLevelData | Event data for waveform levels. |
| ErrorEventData | Event data for errors. |
| PermissionStatusChangedData | Event data for permission status changes. |
| RecordingStatusChangedData | Event data for recording status changes. |
| PlaybackStartedData | Event data for playback started. |
| PlaybackPausedData | Event data for playback paused. |
| PlaybackStoppedData | Event data for playback stopped. |
| PlaybackErrorData | Event data for playback errors. |
| PlaybackProgressData | Event data for playback progress. |
---
- Capacitor 7.0.0+
- Android: Minimum API 29 (Android 10) or higher
- iOS: Minimum iOS 13.0 or higher
1. Install the plugin:
``bash`
npm install capacitor-audio-engineor
pnpm add capacitor-audio-engineor
yarn add capacitor-audio-engine
2. Sync your project:
`bash`
npx cap sync
3. Add required permissions:
#### iOS
Add these to your Info.plist:
`xml`
#### Android
Add this to your AndroidManifest.xml:
`xml`
> âšī¸ AndroidX Compatibility: This package is fully AndroidX-compatible and does not require Jetifier. If you see Jetifier warnings during installation, they can be safely ignored. The package uses modern AndroidX libraries and doesn't depend on legacy Android support libraries.
#### AudioFileInfo
Complete information about an audio file:
`typescript`
interface AudioFileInfo {
path: string; // File system path
webPath: string; // Web accessible path
uri: string; // URI for file access
mimeType: string; // MIME type (audio/m4a)
size: number; // File size in bytes
duration: number; // Duration in seconds
sampleRate: number; // Sample rate in Hz
channels: number; // Number of audio channels
bitrate: number; // Bitrate in bps
createdAt: number; // Creation timestamp
filename: string; // File name
}
#### PermissionStatusResults
Simplified permission status:
`typescript
interface PermissionStatusResults {
granted: boolean; // Overall permission status
status: PermissionStatus; // Detailed status
}
enum PermissionStatus {
GRANTED = 'granted',
DENIED = 'denied',
DENIED_PERMANENTLY = 'denied_permanently',
NOT_DETERMINED = 'not_determined',
LIMITED = 'limited',
RESTRICTED = 'restricted',
REQUESTING = 'requesting',
UNSUPPORTED = 'unsupported',
}
enum AudioPermissionType {
MICROPHONE = 'microphone',
NOTIFICATIONS = 'notifications',
}
`
#### RecordingStatusInfo
Current recording state:
`typescript
interface RecordingStatusInfo {
status: RecordingStatus;
duration: number;
path?: string;
}
type RecordingStatus = 'recording' | 'paused' | 'stopped' | 'idle';
`
#### PlaybackInfo
Current playback state:
`typescript
interface PlaybackInfo {
currentTrack: {
id: string;
url: string;
} | null;
currentIndex: number;
currentPosition: number;
duration: number;
isPlaying: boolean;
}
type PlaybackStatus = 'idle' | 'loading' | 'playing' | 'paused' | 'stopped';
`
#### WaveLevelConfiguration
Waveform monitoring configuration:
`typescript
interface WaveLevelConfiguration {
emissionInterval?: WaveLevelEmissionInterval | number;
}
enum WaveLevelEmissionInterval {
REALTIME = 50, // 50ms - real-time
VERY_FAST = 100, // 100ms - very fast
FAST = 200, // 200ms - fast
MEDIUM = 500, // 500ms - medium
DEFAULT = 1000, // 1000ms - default
}
`
#### Permission Management
##### checkPermissions()
Check all audio-related permissions:
`typescript`
checkPermissions(): Promise
##### checkPermissionMicrophone()
Check microphone permission:
`typescript`
checkPermissionMicrophone(): Promise
##### checkPermissionNotifications()
Check notification permission:
`typescript`
checkPermissionNotifications(): Promise
##### requestPermissions(options?)
Request all permissions with optional configuration:
`typescript
requestPermissions(options?: PermissionRequestOptions): Promise
interface PermissionRequestOptions {
showRationale?: boolean; // Show rationale before requesting (Android)
rationaleMessage?: string; // Custom rationale message
forceRequest?: boolean; // Force request even if denied permanently
}
`
##### requestPermissionMicrophone(options?)
Request microphone permission only:
`typescript
requestPermissionMicrophone(options?: PermissionRequestOptions): Promise
interface PermissionRequestOptions {
showRationale?: boolean; // Show rationale before requesting (Android)
rationaleMessage?: string; // Custom rationale message
forceRequest?: boolean; // Force request even if denied permanently
}
`
Example:
`typescript`
// Request only microphone permission
const micResult = await CapacitorAudioEngine.requestPermissionMicrophone();
if (micResult.granted) {
console.log('Microphone permission granted');
} else {
console.log('Microphone permission status:', micResult.status);
}
##### requestPermissionNotifications(options?)
Request notification permission only:
`typescript
requestPermissionNotifications(options?: PermissionRequestOptions): Promise
interface PermissionRequestOptions {
showRationale?: boolean; // Show rationale before requesting (Android)
rationaleMessage?: string; // Custom rationale message
forceRequest?: boolean; // Force request even if denied permanently
}
`
Example:
`typescript`
// Request only notification permission
const notifResult = await CapacitorAudioEngine.requestPermissionNotifications();
if (notifResult.granted) {
console.log('Notification permission granted');
} else {
console.log('Notification permission status:', notifResult.status);
}
##### openSettings()
Open device settings for manual permission management:
`typescript`
openSettings(): Promise
#### Recording Control
##### startRecording(options)
Start recording with specified output path:
`typescript`
startRecording(options: { path: string }): Promise
##### stopRecording()
Stop recording and get file information:
`typescript`
stopRecording(): Promise
##### pauseRecording()
Pause the current recording:
`typescript`
pauseRecording(): Promise
##### resumeRecording()
Resume a paused recording:
`typescript`
resumeRecording(): Promise
##### resetRecording()
Reset the current recording session without finalizing:
`typescript`
resetRecording(): Promise
##### getRecordingStatus()
Get current recording status:
`typescript`
getRecordingStatus(): Promise
#### Playback Control
##### preloadTracks(options)
Preload audio tracks for optimized playback:
`typescript
preloadTracks(options: PreloadTracksOptions): Promise
interface PreloadTracksOptions {
tracks: string[]; // Array of track URLs or file paths
}
interface PreloadTracksResult {
tracks: PreloadedTrackInfo[];
}
interface PreloadedTrackInfo {
url: string;
loaded: boolean;
mimeType?: string;
duration?: number;
size?: number;
}
`
##### playAudio(options?)
Play current track or specific track by URL:
`typescript
playAudio(options?: PlayAudioOptions): Promise
interface PlayAudioOptions {
url?: string; // Optional URL to play specific track
}
`
##### pauseAudio(options?)
Pause current track or specific track:
`typescript
pauseAudio(options?: PauseAudioOptions): Promise
interface PauseAudioOptions {
url?: string;
}
`
##### resumeAudio(options?)
Resume paused playback:
`typescript
resumeAudio(options?: ResumeAudioOptions): Promise
interface ResumeAudioOptions {
url?: string;
}
`
##### stopAudio(options?)
Stop playback and reset to beginning:
`typescript
stopAudio(options?: StopAudioOptions): Promise
interface StopAudioOptions {
url?: string;
}
`
##### seekAudio(options)
Seek to specific position in track:
`typescript
seekAudio(options: SeekOptions): Promise
interface SeekOptions {
seconds: number;
url?: string;
}
`
##### skipToNext()
Skip to next track in playlist:
`typescript`
skipToNext(): Promise
##### skipToPrevious()
Skip to previous track in playlist:
`typescript`
skipToPrevious(): Promise
##### skipToIndex(options)
Jump to specific track by index:
`typescript
skipToIndex(options: SkipToIndexOptions): Promise
interface SkipToIndexOptions {
index: number;
}
`
##### getPlaybackInfo()
Get current playback information:
`typescript`
getPlaybackInfo(): Promise
#### Waveform Monitoring
##### configureWaveform(options?)
Configure real-time audio level monitoring:
`typescript
configureWaveform(options?: { EmissionInterval?: number }): Promise
interface WaveLevelConfigurationResult {
success: boolean;
configuration: {
emissionInterval: number;
};
}
`
##### destroyWaveform()
Clean up waveform resources:
`typescript`
destroyWaveform(): Promise
#### Audio Processing
##### trimAudio(options)
Trim audio file to specific time range:
`typescript
trimAudio(options: TrimAudioOptions): Promise
interface TrimAudioOptions {
uri: string; // URI or file path
startTime: number; // Start time in seconds
endTime: number; // End time in seconds
}
`
##### getAudioInfo(options)
Get detailed audio file information:
`typescript`
getAudioInfo(options: { uri: string }): Promise
#### Event Handling
##### addListener(eventName, callback)
Listen for recording and playback events:
`typescript`
addListener
eventName: T,
callback: (event: AudioEventMap[T]) => void
): Promise
Recording Events:
- durationChange - Duration updates during recordingerror
- - Recording errorswaveLevel
- - Real-time audio level data (requires configureWaveform)waveLevelInit
- - Waveform initialization statuswaveLevelDestroy
- - Waveform cleanup statuswaveLevelError
- - Waveform errorspermissionStatusChanged
- - Permission status changesrecordingStatusChanged
- - Recording status changes
Playback Events:
- playbackStarted - Playback startedplaybackPaused
- - Playback pausedplaybackStopped
- - Playback stoppedplaybackError
- - Playback errorsplaybackProgress
- - Progress updates during playback
Event Data Structures:
`typescript
interface DurationChangeData {
duration: number;
}
interface WaveLevelData {
level: number; // Normalized 0.0-1.0
timestamp: number;
}
interface ErrorEventData {
message: string;
code?: string | number;
details?: any;
}
interface PermissionStatusChangedData {
permissionType: AudioPermissionType;
status: PermissionStatus;
previousStatus?: PermissionStatus;
message?: string;
}
interface RecordingStatusChangedData {
status: RecordingStatus;
}
interface PlaybackStartedData {
trackId: string;
url: string;
}
interface PlaybackPausedData {
trackId: string;
url: string;
position: number;
}
interface PlaybackStoppedData {
trackId: string;
url: string;
}
interface PlaybackErrorData {
trackId: string;
message: string;
}
interface PlaybackProgressData {
trackId: string;
url: string;
currentPosition: number;
duration: number;
isPlaying: boolean;
}
`
##### removeAllListeners()
Remove all event listeners:
`typescript`
removeAllListeners(): Promise
Android:
- Recording: MediaRecorder with AAC codec
- Playback: MediaPlayer for individual track management
- Format: M4A/AAC (audio/m4a)
- Sample Rate: 48kHz, Mono, 128kbps
iOS:
- Recording: AVAudioRecorder with AAC codec
- Playback: AVPlayer for individual track management
- Format: M4A/AAC (audio/m4a)
- Sample Rate: 48kHz, Mono, 128kbps
Web:
- Not supported - designed for native mobile platforms only
We love contributions! Whether it's fixing bugs, adding features, or improving docs, your help makes this plugin better for everyone. Here's how to help:
1. Fork the repo
2. Create your feature branch (git checkout -b feature/feature-name)git commit -m 'Add amazing feature'
3. Commit your changes ()git push origin feature/feature-name`)
4. Push to the branch (
5. Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Found a bug? Have a feature request? Just want to chat? Open an issue on GitHub and we'll help you out!