capacitor-audio-manager

Manage device ringer mode, volume levels, and audio settings for Capacitor apps.

Features

• 🔔 Ringer Mode Control - Get and set device ringer mode (normal, vibrate, silent)
• 🔊 Volume Control - Get and set volume levels for different audio streams
• 🔕 Mute Detection - Check if the device is muted
• 🌙 DND Detection - Check if Do Not Disturb mode is enabled
• 📡 Event Listeners - Listen for ringer mode and volume changes in real-time

Platform Support

| Feature | Android | iOS | Web | | ---------------------- | ------- | -------------- | ------- | | getRingerMode | ✅ Real | ⚠️ Best-effort | ❌ | | setRingerMode | ✅ | ❌ | ❌ | | getVolume | ✅ Real | ✅ Real | ⚠️ Mock | | setVolume | ✅ | ❌ | ❌ | | isMuted | ✅ Real | ⚠️ Best-effort | ❌ | | getDndMode | ✅ | ❌ | ❌ | | ringerModeChange event | ✅ Real | ⚠️ Inferred | ❌ | | volumeChange event | ✅ | ✅ | ❌ |

Legend:

• ✅ Real - Native API provides accurate data
• ⚠️ Best-effort - Inferred from available data, may not reflect actual state
• ⚠️ Mock - Returns placeholder values
• ❌ - Not supported

Install

npm install capacitor-audio-manager
npx cap sync

Android Setup

Do Not Disturb Permission

To change ringer mode on Android 7.0+ (API 24+), your app needs Do Not Disturb access permission:

1. The user must manually grant this permission in device settings
2. If permission is not granted, setRingerMode() will reject with an error

// Check if permission is needed and prompt user
import { AudioManager } from 'capacitor-audio-manager';

try {
  await AudioManager.setRingerMode({ mode: 'silent' });
} catch (error) {
  // Permission denied - direct user to settings
  console.log('Please grant Do Not Disturb access in Settings');
}

Volume Change Events

On Android, the volumeChange event currently reports changes to the music stream only. Changes to ring, notification, or alarm streams are not individually tracked.

Muted Definition

On Android, isMuted() returns true when the ringer mode is silent or vibrate (i.e., the ringer is not audible).

Web Limitations

Web platform has very limited audio control capabilities:

• getRingerMode() - Always returns "normal" (no ringer concept on web)
• getVolume() - Returns { volume: 0, maxVolume: 0 } (system volume not accessible)
• isMuted() - Always returns false
• getDndMode() - Always returns false
• setRingerMode() / setVolume() - Throws "not supported" error
• Events - Not fired on web platform

⚠️ These values are placeholders and should not be relied upon for application logic. Web platform is provided for development convenience only.

iOS Limitations

iOS does not expose APIs to reliably detect or control:

• Ringer mode (physical mute switch state)
• Do Not Disturb status
• System volume programmatically

Unsupported Features

• setRingerMode - Apple doesn't allow apps to change ringer mode
• setVolume - Apple restricts programmatic volume control
• getDndMode - Always returns false (Apple doesn't expose DND status)

Best-Effort Detection

The following methods use best-effort detection based on output volume:

• getRingerMode() - Returns "silent" when output volume is 0, otherwise "normal". This does not detect the physical mute switch state.
• isMuted() - Returns true when output volume is 0. This means "audio output is zero" not necessarily "mute switch is on".
• ringerModeChange event - Inferred from volume changes, does not represent physical mute switch state.
• volumeChange event - Reflects system output volume changes only (music stream).

⚠️ Important: These values may not reflect the actual device state. iOS intentionally restricts access to ringer/mute information for privacy reasons.

API

• getRingerMode()
• setRingerMode(...)
• getVolume(...)
• setVolume(...)
• isMuted()
• getDndMode()
• checkDndPermission()
• openDndSettings()
• addListener('ringerModeChange', ...)
• addListener('volumeChange', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

Audio Manager Plugin interface Provides methods to manage device ringer mode, volume levels, and audio settings

getRingerMode()

getRingerMode() => Promise<GetRingerModeResult>

Get the current ringer mode

Returns: Promise<GetRingerModeResult>

Since: 1.0.0

setRingerMode(...)

setRingerMode(options: SetRingerModeOptions) => Promise<void>

Set the ringer mode Note: On some Android devices, this requires Do Not Disturb access permission

| Param | Type | Description | | ------------- | --------------------------------------------------------------------- | ------------------------ | | options | SetRingerModeOptions | - The ringer mode to set |

Since: 1.0.0

getVolume(...)

getVolume(options: GetVolumeOptions) => Promise<GetVolumeResult>

Get the current volume for a specific audio stream

| Param | Type | Description | | ------------- | ------------------------------------------------------------- | ------------------------------------ | | options | GetVolumeOptions | - The audio stream to get volume for |

Returns: Promise<GetVolumeResult>

Since: 1.0.0

setVolume(...)

setVolume(options: SetVolumeOptions) => Promise<void>

Set the volume for a specific audio stream

| Param | Type | Description | | ------------- | ------------------------------------------------------------- | ------------------------------------------ | | options | SetVolumeOptions | - The audio stream and volume level to set |

Since: 1.0.0

isMuted()

isMuted() => Promise<IsMutedResult>

Check if the device is currently muted

Returns: Promise<IsMutedResult>

Since: 1.0.0

getDndMode()

getDndMode() => Promise<GetDndModeResult>

Check if Do Not Disturb mode is enabled

Returns: Promise<GetDndModeResult>

Since: 1.0.0

checkDndPermission()

checkDndPermission() => Promise<CheckDndPermissionResult>

Check if DND access permission is granted Required on Android 7.0+ to change ringer mode

Returns: Promise<CheckDndPermissionResult>

Since: 1.0.0

openDndSettings()

openDndSettings() => Promise<void>

Open the system settings to grant DND access permission Only available on Android

Since: 1.0.0

addListener('ringerModeChange', ...)

addListener(eventName: 'ringerModeChange', listenerFunc: (event: RingerModeChangeEvent) => void) => Promise<PluginListenerHandle>

Add a listener for ringer mode changes

| Param | Type | Description | | ------------------ | ------------------------------------------------------------------------------------------- | ----------------------- | | eventName | 'ringerModeChange' | - The event name | | listenerFunc | (event: RingerModeChangeEvent) => void | - The listener function |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

addListener('volumeChange', ...)

addListener(eventName: 'volumeChange', listenerFunc: (event: VolumeChangeEvent) => void) => Promise<PluginListenerHandle>

Add a listener for volume changes

| Param | Type | Description | | ------------------ | ----------------------------------------------------------------------------------- | ----------------------- | | eventName | 'volumeChange' | - The event name | | listenerFunc | (event: VolumeChangeEvent) => void | - The listener function |

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin

Since: 1.0.0

Interfaces

GetRingerModeResult

Result of getting ringer mode

| Prop | Type | Description | | ---------- | ------------------------------------------------- | ------------------- | | mode | RingerMode | Current ringer mode |

SetRingerModeOptions

Options for setting ringer mode

| Prop | Type | Description | | ---------- | ------------------------------------------------- | ---------------------- | | mode | RingerMode | The ringer mode to set |

GetVolumeResult

Result of getting volume

| Prop | Type | Description | | --------------- | ------------------- | ------------------------------------- | | volume | number | Current volume level (0 to maxVolume) | | maxVolume | number | Maximum volume level for this stream |

GetVolumeOptions

Options for getting volume

| Prop | Type | Description | | ------------ | --------------------------------------------------- | --------------------------------------- | | stream | AudioStream | The audio stream type to get volume for |

SetVolumeOptions

Options for setting volume

| Prop | Type | Description | | ------------ | --------------------------------------------------- | ------------------------------------------------------------------------------ | | stream | AudioStream | The audio stream type to set volume for | | volume | number | Volume level to set (0 to maxVolume) | | showUI | boolean | Whether to show the system volume UI (default: true) Only supported on Android |

IsMutedResult

Result of checking mute status

| Prop | Type | Description | | ----------- | -------------------- | --------------------------- | | muted | boolean | Whether the device is muted |

GetDndModeResult

Result of checking DND status

| Prop | Type | Description | | ------------- | -------------------- | -------------------------------------- | | enabled | boolean | Whether Do Not Disturb mode is enabled |

CheckDndPermissionResult

Result of checking DND permission

| Prop | Type | Description | | ------------- | -------------------- | ---------------------------------------- | | granted | boolean | Whether DND access permission is granted |

PluginListenerHandle

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

RingerModeChangeEvent

Event fired when ringer mode changes

| Prop | Type | Description | | ---------- | ------------------------------------------------- | ------------------- | | mode | RingerMode | The new ringer mode |

VolumeChangeEvent

Event fired when volume changes

| Prop | Type | Description | | --------------- | --------------------------------------------------- | ------------------------------------ | | stream | AudioStream | The audio stream that changed | | volume | number | The new volume level | | maxVolume | number | Maximum volume level for this stream |

Type Aliases

RingerMode

Ringer mode types

• normal: Normal mode with sound
• vibrate: Vibrate only mode
• silent: Silent mode (no sound, no vibration)

'normal' | 'vibrate' | 'silent'

AudioStream

Audio stream types

• music: Media/music playback
• ring: Ringtone
• notification: Notification sounds
• alarm: Alarm sounds
• system: System sounds
• voiceCall: Voice call audio

'music' | 'ring' | 'notification' | 'alarm' | 'system' | 'voiceCall'

Example App

import { AudioManager } from 'capacitor-audio-manager';

// Get current state
const { mode } = await AudioManager.getRingerMode();
const { volume, maxVolume } = await AudioManager.getVolume({ stream: 'music' });
const { muted } = await AudioManager.isMuted();
const { enabled: dndEnabled } = await AudioManager.getDndMode();

console.log(`Mode: ${mode}, Volume: ${volume}/${maxVolume}, Muted: ${muted}, DND: ${dndEnabled}`);

// Set ringer mode (Android only)
await AudioManager.setRingerMode({ mode: 'vibrate' });

// Set volume (Android only)
await AudioManager.setVolume({ stream: 'music', volume: 8 });

// Listen for changes
AudioManager.addListener('ringerModeChange', (event) => {
  console.log('Ringer mode changed:', event.mode);
});

AudioManager.addListener('volumeChange', (event) => {
  console.log(`Volume changed: ${event.stream} = ${event.volume}`);
});

Contributing

See CONTRIBUTING.md for details on how to contribute to this project.

License

MIT

Author

Selman Yasin Aktaş (@selmanyasinaktas)