Skip to content

selmanyasinaktas/capacitor-audio-manager

BranchesTags

Repository files navigation

capacitor-audio-manager

npm version npm downloads license

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

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)

About

Manage device ringer mode, volume levels, and audio settings

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 Latest
Dec 23, 2025

Packages

 
 
 

Contributors

Languages