Capacitor Audio Engine 🎙️

A 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.

📋 Overview of Methods and Types

Methods

| 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. |

Interfaces, Enums, and Types

| 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. |

🚀 Installation

Prerequisites

• Capacitor 7.0.0+
• Android: Minimum API 29 (Android 10) or higher
• iOS: Minimum iOS 13.0 or higher

Setup

1. Install the plugin:

npm install capacitor-audio-engine
# or
pnpm add capacitor-audio-engine
# or
yarn add capacitor-audio-engine

2. Sync your project:

npx cap sync

3. Add required permissions:

iOS

Add these to your Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>We need access to your microphone to record audio</string>

Android

Add this to your AndroidManifest.xml:

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

ℹ️ 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.

📖 API Documentation

Core Interfaces

AudioFileInfo

Complete information about an audio file:

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:

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:

interface RecordingStatusInfo {
  status: RecordingStatus;
  duration: number;
  path?: string;
}

type RecordingStatus = 'recording' | 'paused' | 'stopped' | 'idle';

PlaybackInfo

Current playback state:

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:

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
}

Methods

Permission Management

checkPermissions()

Check all audio-related permissions:

checkPermissions(): Promise<PermissionStatusResults>

checkPermissionMicrophone()

Check microphone permission:

checkPermissionMicrophone(): Promise<PermissionStatusResults>

checkPermissionNotifications()

Check notification permission:

checkPermissionNotifications(): Promise<PermissionStatusResults>

requestPermissions(options?)

Request all permissions with optional configuration:

requestPermissions(options?: PermissionRequestOptions): Promise<PermissionStatusResults>

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:

requestPermissionMicrophone(options?: PermissionRequestOptions): Promise<PermissionStatusResults>

interface PermissionRequestOptions {
  showRationale?: boolean;      // Show rationale before requesting (Android)
  rationaleMessage?: string;    // Custom rationale message
  forceRequest?: boolean;       // Force request even if denied permanently
}

Example:

// 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:

requestPermissionNotifications(options?: PermissionRequestOptions): Promise<PermissionStatusResults>

interface PermissionRequestOptions {
  showRationale?: boolean;      // Show rationale before requesting (Android)
  rationaleMessage?: string;    // Custom rationale message
  forceRequest?: boolean;       // Force request even if denied permanently
}

Example:

// 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:

openSettings(): Promise<void>

Recording Control

startRecording(options)

Start recording with specified output path:

startRecording(options: { path: string }): Promise<void>

stopRecording()

Stop recording and get file information:

stopRecording(): Promise<AudioFileInfo>

pauseRecording()

Pause the current recording:

pauseRecording(): Promise<void>

resumeRecording()

Resume a paused recording:

resumeRecording(): Promise<void>

resetRecording()

Reset the current recording session without finalizing:

resetRecording(): Promise<void>

getRecordingStatus()

Get current recording status:

getRecordingStatus(): Promise<RecordingStatusInfo>

Playback Control

preloadTracks(options)

Preload audio tracks for optimized playback:

preloadTracks(options: PreloadTracksOptions): Promise<PreloadTracksResult>

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:

playAudio(options?: PlayAudioOptions): Promise<void>

interface PlayAudioOptions {
  url?: string;  // Optional URL to play specific track
}

pauseAudio(options?)

Pause current track or specific track:

pauseAudio(options?: PauseAudioOptions): Promise<void>

interface PauseAudioOptions {
  url?: string;
}

resumeAudio(options?)

Resume paused playback:

resumeAudio(options?: ResumeAudioOptions): Promise<void>

interface ResumeAudioOptions {
  url?: string;
}

stopAudio(options?)

Stop playback and reset to beginning:

stopAudio(options?: StopAudioOptions): Promise<void>

interface StopAudioOptions {
  url?: string;
}

seekAudio(options)

Seek to specific position in track:

seekAudio(options: SeekOptions): Promise<void>

interface SeekOptions {
  seconds: number;
  url?: string;
}

skipToNext()

Skip to next track in playlist:

skipToNext(): Promise<void>

skipToPrevious()

Skip to previous track in playlist:

skipToPrevious(): Promise<void>

skipToIndex(options)

Jump to specific track by index:

skipToIndex(options: SkipToIndexOptions): Promise<void>

interface SkipToIndexOptions {
  index: number;
}

getPlaybackInfo()

Get current playback information:

getPlaybackInfo(): Promise<PlaybackInfo>

Waveform Monitoring

configureWaveform(options?)

Configure real-time audio level monitoring:

configureWaveform(options?: { EmissionInterval?: number }): Promise<WaveLevelConfigurationResult>

interface WaveLevelConfigurationResult {
  success: boolean;
  configuration: {
    emissionInterval: number;
  };
}

destroyWaveform()

Clean up waveform resources:

destroyWaveform(): Promise<void>

Audio Processing

trimAudio(options)

Trim audio file to specific time range:

trimAudio(options: TrimAudioOptions): Promise<AudioFileInfo>

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:

getAudioInfo(options: { uri: string }): Promise<AudioFileInfo>

Event Handling

addListener(eventName, callback)

Listen for recording and playback events:

addListener<T extends AudioEventName>(
  eventName: T,
  callback: (event: AudioEventMap[T]) => void
): Promise<PluginListenerHandle>

Recording Events:

• durationChange - Duration updates during recording
• error - Recording errors
• waveLevel - Real-time audio level data (requires configureWaveform)
• waveLevelInit - Waveform initialization status
• waveLevelDestroy - Waveform cleanup status
• waveLevelError - Waveform errors
• permissionStatusChanged - Permission status changes
• recordingStatusChanged - Recording status changes

Playback Events:

• playbackStarted - Playback started
• playbackPaused - Playback paused
• playbackStopped - Playback stopped
• playbackError - Playback errors
• playbackProgress - Progress updates during playback

Event Data Structures:

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:

removeAllListeners(): Promise<void>

🛠️ Technical Details

Platform-Specific Implementations

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

🤝 Contributing

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)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/feature-name)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Need Help?

Found a bug? Have a feature request? Just want to chat? Open an issue on GitHub and we'll help you out!