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

$3

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

$3

| 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

$3

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

$3

1. Install the plugin:

``bash
npm install capacitor-audio-engine


or

pnpm add capacitor-audio-engine

or

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
NSMicrophoneUsageDescription
We need access to your microphone to record audio
`

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

📖 API Documentation

$3

#### 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
}
`

$3

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

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

🛠️ Technical Details

$3

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!