--- description: Capacitor plugin to get and set the volume level and observe hardware volume button presses on Android and iOS. title: Capacitor Volume Plugin for Android & iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/volume.png --- [Skip to content ](#capacitor-volume-plugin) [πŸ“² Introducing **Build Sharing** β€” get your builds onto testers' devices with a link & QR code. No account required. ](/blog/share-mobile-app-builds-with-testers/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * Volume [ Volume ](/docs/sdks/capacitor/volume/) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ Volume Control ](#volume-control) * [ Volume Button Watching ](#volume-button-watching) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Notifications * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ Volume Control ](#volume-control) * [ Volume Button Watching ](#volume-button-watching) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) # Capacitor Volume Plugin[ΒΆ](#capacitor-volume-plugin "Permanent link") Capacitor plugin to control the volume and observe hardware volume button presses. [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[ΒΆ](#features "Permanent link") * πŸ”Š **Volume control**: Get and set the volume level. * 🎚️ **Audio streams**: Control individual audio streams (music, ring, alarm and more) on Android. * πŸ”˜ **Volume buttons**: Listen for hardware volume button presses. * 🀫 **Suppression**: Keep the volume unchanged and hide the system volume indicator while watching. * πŸ‘‚ **Change events**: Listen for changes to the volume level. * 🀝 **Compatibility**: Works alongside the [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/), [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/) and [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/) plugins. * πŸ“¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. * πŸ” **Up-to-date**: Always supports the latest Capacitor version. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases[ΒΆ](#use-cases "Permanent link") The Volume plugin is typically used whenever an app needs to control the volume or react to the hardware volume buttons, for example: * **Media apps**: Read and adjust the media volume from your own player UI. * **Camera apps**: Use the hardware volume buttons as a shutter trigger while keeping the volume unchanged. * **Remote control apps**: Map the volume buttons to custom actions, for example to control external devices. * **Audio guidance**: Warn users when the volume is too low to hear important audio cues. ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | \>=8.x.x | Active support | ## Installation[ΒΆ](#installation "Permanent link") You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-1-1) Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-volume` plugin in my project. `` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: `[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-volume [](#%5F%5Fcodelineno-2-2)npx cap sync ` This plugin is only available on **Android** and **iOS**. On the Web, all methods reject as unimplemented. ## Configuration[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") The following examples show how to get and set the current volume, watch the hardware volume buttons, listen for volume button presses and volume changes, and remove all listeners. ### Get the current volume[ΒΆ](#get-the-current-volume "Permanent link") Read the current volume level as a value between `0` and `1`. On Android, you can select the audio stream (for example the ring stream) with the `stream` option. On iOS, this always returns the media volume: `[](#%5F%5Fcodelineno-3-1)import { Volume, VolumeStream } from '@capawesome/capacitor-volume'; [](#%5F%5Fcodelineno-3-2) [](#%5F%5Fcodelineno-3-3)const getVolume = async () => { [](#%5F%5Fcodelineno-3-4) const { volume } = await Volume.getVolume(); [](#%5F%5Fcodelineno-3-5) return volume; [](#%5F%5Fcodelineno-3-6)}; [](#%5F%5Fcodelineno-3-7) [](#%5F%5Fcodelineno-3-8)const getRingVolume = async () => { [](#%5F%5Fcodelineno-3-9) const { volume } = await Volume.getVolume({ stream: VolumeStream.Ring }); [](#%5F%5Fcodelineno-3-10) return volume; [](#%5F%5Fcodelineno-3-11)}; ` ### Set the volume[ΒΆ](#set-the-volume "Permanent link") Set the volume level as a value between `0` and `1`. On Android, you can select the audio stream with the `stream` option. On iOS, this always sets the media volume: `[](#%5F%5Fcodelineno-4-1)import { Volume } from '@capawesome/capacitor-volume'; [](#%5F%5Fcodelineno-4-2) [](#%5F%5Fcodelineno-4-3)const setVolume = async () => { [](#%5F%5Fcodelineno-4-4) await Volume.setVolume({ volume: 0.5 }); [](#%5F%5Fcodelineno-4-5)}; ` ### Watch the hardware volume buttons[ΒΆ](#watch-the-hardware-volume-buttons "Permanent link") Start watching the hardware volume buttons to receive the `volumeButtonPressed` and `volumeChange` events. With the `suppressVolumeChange` option enabled, the volume level is kept unchanged and the system volume indicator is hidden while watching: `[](#%5F%5Fcodelineno-5-1)import { Volume } from '@capawesome/capacitor-volume'; [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3)const startWatching = async () => { [](#%5F%5Fcodelineno-5-4) await Volume.startWatching({ suppressVolumeChange: true }); [](#%5F%5Fcodelineno-5-5)}; [](#%5F%5Fcodelineno-5-6) [](#%5F%5Fcodelineno-5-7)const stopWatching = async () => { [](#%5F%5Fcodelineno-5-8) await Volume.stopWatching(); [](#%5F%5Fcodelineno-5-9)}; [](#%5F%5Fcodelineno-5-10) [](#%5F%5Fcodelineno-5-11)const isWatching = async () => { [](#%5F%5Fcodelineno-5-12) const { watching } = await Volume.isWatching(); [](#%5F%5Fcodelineno-5-13) return watching; [](#%5F%5Fcodelineno-5-14)}; ` ### Listen for volume button presses[ΒΆ](#listen-for-volume-button-presses "Permanent link") Get notified when a hardware volume button is pressed. The event is only emitted while watching (see above): `[](#%5F%5Fcodelineno-6-1)import { Volume } from '@capawesome/capacitor-volume'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)const addVolumeButtonPressedListener = async () => { [](#%5F%5Fcodelineno-6-4) await Volume.addListener('volumeButtonPressed', event => { [](#%5F%5Fcodelineno-6-5) console.log('Volume button pressed:', event.direction); [](#%5F%5Fcodelineno-6-6) }); [](#%5F%5Fcodelineno-6-7)}; ` ### Listen for volume changes[ΒΆ](#listen-for-volume-changes "Permanent link") Get notified when the volume level changes. The event is only emitted while watching (see above): `[](#%5F%5Fcodelineno-7-1)import { Volume } from '@capawesome/capacitor-volume'; [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)const addVolumeChangeListener = async () => { [](#%5F%5Fcodelineno-7-4) await Volume.addListener('volumeChange', event => { [](#%5F%5Fcodelineno-7-5) console.log('Volume changed:', event.volume); [](#%5F%5Fcodelineno-7-6) }); [](#%5F%5Fcodelineno-7-7)}; ` ### Remove all listeners[ΒΆ](#remove-all-listeners "Permanent link") Remove all listeners for this plugin when they are no longer needed: `[](#%5F%5Fcodelineno-8-1)import { Volume } from '@capawesome/capacitor-volume'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const removeAllListeners = async () => { [](#%5F%5Fcodelineno-8-4) await Volume.removeAllListeners(); [](#%5F%5Fcodelineno-8-5)}; ` ## API[ΒΆ](#api "Permanent link") * [getVolume(...)](#getvolume) * [isWatching()](#iswatching) * [setVolume(...)](#setvolume) * [startWatching(...)](#startwatching) * [stopWatching()](#stopwatching) * [addListener('volumeButtonPressed', ...)](#addlistenervolumebuttonpressed-) * [addListener('volumeButtonReleased', ...)](#addlistenervolumebuttonreleased-) * [addListener('volumeChange', ...)](#addlistenervolumechange-) * [removeAllListeners()](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### getVolume(...)[ΒΆ](#getvolume "Permanent link") `[](#%5F%5Fcodelineno-9-1)getVolume(options?: GetVolumeOptions | undefined) => Promise ` Get the current volume level. On iOS, this always returns the media volume. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------- | | **options** | [GetVolumeOptions](#getvolumeoptions) | **Returns:** `Promise<[GetVolumeResult](#getvolumeresult)>` **Since:** 0.1.0 --- ### isWatching()[ΒΆ](#iswatching "Permanent link") `[](#%5F%5Fcodelineno-10-1)isWatching() => Promise ` Check whether the hardware volume buttons are currently being watched. Only available on Android and iOS. **Returns:** `Promise<[IsWatchingResult](#iswatchingresult)>` **Since:** 0.1.0 --- ### setVolume(...)[ΒΆ](#setvolume "Permanent link") `[](#%5F%5Fcodelineno-11-1)setVolume(options: SetVolumeOptions) => Promise ` Set the volume level. On iOS, this always sets the media volume. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------- | | **options** | [SetVolumeOptions](#setvolumeoptions) | **Since:** 0.1.0 --- ### startWatching(...)[ΒΆ](#startwatching "Permanent link") `[](#%5F%5Fcodelineno-12-1)startWatching(options?: StartWatchingOptions | undefined) => Promise ` Start watching the hardware volume buttons. The `volumeButtonPressed`, `volumeButtonReleased` and `volumeChange`events are only emitted while watching. If the volume buttons are already being watched, this call has no effect. Call `stopWatching()` first to change the options. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------------------- | | **options** | [StartWatchingOptions](#startwatchingoptions) | **Since:** 0.1.0 --- ### stopWatching()[ΒΆ](#stopwatching "Permanent link") `[](#%5F%5Fcodelineno-13-1)stopWatching() => Promise ` Stop watching the hardware volume buttons. On iOS, this also restores the volume level that was set when watching started if the `suppressVolumeChange` option was enabled. Only available on Android and iOS. **Since:** 0.1.0 --- ### addListener('volumeButtonPressed', ...)[ΒΆ](#addlistenervolumebuttonpressed "Permanent link") `[](#%5F%5Fcodelineno-14-1)addListener(eventName: 'volumeButtonPressed', listenerFunc: (event: VolumeButtonPressedEvent) => void) => Promise ` Called when a hardware volume button is pressed while watching. Only available on Android and iOS. | Param | Type | | ---------------- | ---------------------------------------------------------------------- | | **eventName** | 'volumeButtonPressed' | | **listenerFunc** | (event: [VolumeButtonPressedEvent](#volumebuttonpressedevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.1.0 --- ### addListener('volumeButtonReleased', ...)[ΒΆ](#addlistenervolumebuttonreleased "Permanent link") `[](#%5F%5Fcodelineno-15-1)addListener(eventName: 'volumeButtonReleased', listenerFunc: (event: VolumeButtonReleasedEvent) => void) => Promise ` Called when a hardware volume button is released while watching. Only available on Android. | Param | Type | | ---------------- | ------------------------------------------------------------------------ | | **eventName** | 'volumeButtonReleased' | | **listenerFunc** | (event: [VolumeButtonReleasedEvent](#volumebuttonreleasedevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.2.0 --- ### addListener('volumeChange', ...)[ΒΆ](#addlistenervolumechange "Permanent link") `[](#%5F%5Fcodelineno-16-1)addListener(eventName: 'volumeChange', listenerFunc: (event: VolumeChangeEvent) => void) => Promise ` Called when the volume level changes while watching. On Android, this is called for changes to the music stream. On iOS, this is called for changes to the media volume and is not called while the `suppressVolumeChange` option is enabled. Only available on Android and iOS. | Param | Type | | ---------------- | -------------------------------------------------------- | | **eventName** | 'volumeChange' | | **listenerFunc** | (event: [VolumeChangeEvent](#volumechangeevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.1.0 --- ### removeAllListeners()[ΒΆ](#removealllisteners "Permanent link") `[](#%5F%5Fcodelineno-17-1)removeAllListeners() => Promise ` Remove all listeners for this plugin. **Since:** 0.1.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### GetVolumeResult[ΒΆ](#getvolumeresult "Permanent link") | Prop | Type | Description | Since | | ---------- | ------ | ---------------------------------------------------- | ----- | | **volume** | number | The current volume level as a value between 0 and 1. | 0.1.0 | #### GetVolumeOptions[ΒΆ](#getvolumeoptions "Permanent link") | Prop | Type | Description | Default | Since | | ---------- | ----------------------------- | ------------------------------------------------------------------ | ------------------ | ----- | | **stream** | [VolumeStream](#volumestream) | The audio stream to get the volume for. Only available on Android. | VolumeStream.Music | 0.1.0 | #### IsWatchingResult[ΒΆ](#iswatchingresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ------- | ---------------------------------------------------------------- | ----- | | **watching** | boolean | Whether the hardware volume buttons are currently being watched. | 0.1.0 | #### SetVolumeOptions[ΒΆ](#setvolumeoptions "Permanent link") | Prop | Type | Description | Default | Since | | ---------- | ----------------------------- | ------------------------------------------------------------------ | ------------------ | ----- | | **stream** | [VolumeStream](#volumestream) | The audio stream to set the volume for. Only available on Android. | VolumeStream.Music | 0.1.0 | | **volume** | number | The volume level to set as a value between 0 and 1. | | 0.1.0 | #### StartWatchingOptions[ΒΆ](#startwatchingoptions "Permanent link") | Prop | Type | Description | Default | Since | | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | | **suppressVolumeChange** | boolean | Whether to keep the volume level unchanged when a hardware volume button is pressed while watching. On Android, the volume key events are consumed so that the system does not apply the volume change or display the volume panel. On iOS, the volume level is reset immediately after each button press and the system volume indicator is hidden. If the volume level is close to the minimum or maximum, it is nudged to a value from which both buttons can still be detected. The original volume level is restored when watching stops. | false | 0.1.0 | #### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link") | Prop | Type | | ---------- | ------------------- | | **remove** | () => Promise | #### VolumeButtonPressedEvent[ΒΆ](#volumebuttonpressedevent "Permanent link") | Prop | Type | Description | Since | | ------------- | ----------------------- | ---------------------------------------------------- | ----- | | **direction** | [Direction](#direction) | The direction of the pressed hardware volume button. | 0.1.0 | #### VolumeButtonReleasedEvent[ΒΆ](#volumebuttonreleasedevent "Permanent link") | Prop | Type | Description | Since | | ------------- | ----------------------- | ----------------------------------------------------- | ----- | | **direction** | [Direction](#direction) | The direction of the released hardware volume button. | 0.2.0 | #### VolumeChangeEvent[ΒΆ](#volumechangeevent "Permanent link") | Prop | Type | Description | Since | | ---------- | ------ | ------------------------------------------------ | ----- | | **volume** | number | The new volume level as a value between 0 and 1. | 0.1.0 | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### Direction[ΒΆ](#direction "Permanent link") The direction of a hardware volume button. * `up`: The volume up button. * `down`: The volume down button. `'down' | 'up'` ### Enums[ΒΆ](#enums "Permanent link") #### VolumeStream[ΒΆ](#volumestream "Permanent link") | Members | Value | Description | Since | | ---------------- | -------------- | ---------------------------------------------- | ----- | | **Alarm** | 'ALARM' | The audio stream for alarms. | 0.1.0 | | **Music** | 'MUSIC' | The audio stream for music and media playback. | 0.1.0 | | **Notification** | 'NOTIFICATION' | The audio stream for notifications. | 0.1.0 | | **Ring** | 'RING' | The audio stream for the phone ring. | 0.1.0 | | **System** | 'SYSTEM' | The audio stream for system sounds. | 0.1.0 | | **VoiceCall** | 'VOICE\_CALL' | The audio stream for phone calls. | 0.1.0 | ## Volume Control[ΒΆ](#volume-control "Permanent link") Keep the following platform differences in mind when getting and setting the volume: * **Android**: The volume can be read and set per audio stream (see the `stream` option). If Do Not Disturb is active, changing the volume of the ring, notification or system stream requires Do Not Disturb access. Without this access, the call is rejected with the `DO_NOT_DISTURB_ACCESS_REQUIRED` error code. You can direct the user to the corresponding settings screen using the [ACTION\_NOTIFICATION\_POLICY\_ACCESS\_SETTINGS](https://developer.android.com/reference/android/provider/Settings#ACTION%5FNOTIFICATION%5FPOLICY%5FACCESS%5FSETTINGS) intent, for example with the [App Launcher](https://capacitorjs.com/docs/apis/app-launcher) plugin. * **iOS**: There is no public API to set the system volume directly. The plugin therefore uses a hidden system volume view to change the media volume, which is the only volume that can be read and set. The `stream` option is ignored. ## Volume Button Watching[ΒΆ](#volume-button-watching "Permanent link") Keep the following platform differences in mind when watching the hardware volume buttons: * **Android**: The volume key events are intercepted by the web view, so button presses are only detected while the app is in the foreground. With the `suppressVolumeChange` option enabled, the key events are consumed, which keeps the volume unchanged and prevents the system volume panel from appearing. * **iOS**: Button presses are derived from changes to the media volume, so button presses are only detected while the app is in the foreground. Without the `suppressVolumeChange` option, presses can not be detected once the volume has reached its minimum or maximum. With the option enabled, the volume is reset immediately after each press (nudged away from the edges if needed), the system volume indicator is hidden, and the original volume is restored when watching stops. Note that volume changes from other sources (for example Control Center) are also reported while watching. ## FAQ[ΒΆ](#faq "Permanent link") ### How is this plugin different from other similar plugins?[ΒΆ](#how-is-this-plugin-different-from-other-similar-plugins "Permanent link") It combines volume control and hardware button events in one unified API β€” a natural fit on iOS, where both rely on the same underlying system machinery. It adds per-stream control on Android and handles iOS volume-indicator suppression, all through a fully typed, actively maintained package, so a single dependency covers the whole volume story. ### Which platforms are supported by this plugin?[ΒΆ](#which-platforms-are-supported-by-this-plugin "Permanent link") The plugin is available on Android and iOS. On the Web, all methods reject as unimplemented. ### Why is the `stream` option ignored on iOS?[ΒΆ](#why-is-the-stream-option-ignored-on-ios "Permanent link") On iOS, there is no public API to set the system volume directly. The plugin therefore uses a hidden system volume view to change the media volume, which is the only volume that can be read and set on iOS. The `stream` option is only supported on Android, see [Volume Control](#volume-control) for details. ### Why is `setVolume` rejected with the `DO_NOT_DISTURB_ACCESS_REQUIRED` error code?[ΒΆ](#why-is-setvolume-rejected-with-the-do%5Fnot%5Fdisturb%5Faccess%5Frequired-error-code "Permanent link") On Android, changing the volume of the ring, notification or system stream while Do Not Disturb is active requires Do Not Disturb access. You can direct the user to the corresponding settings screen using the `ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS` intent, for example with the App Launcher plugin, see [Volume Control](#volume-control) for details. ### Why are volume button presses not detected?[ΒΆ](#why-are-volume-button-presses-not-detected "Permanent link") The `volumeButtonPressed` event is only emitted while watching, so make sure you have called `startWatching(...)` first. On both platforms, button presses are only detected while the app is in the foreground. On iOS, presses can also not be detected once the volume has reached its minimum or maximum unless the `suppressVolumeChange` option is enabled, see [Volume Button Watching](#volume-button-watching) for details. ### What does the `suppressVolumeChange` option do?[ΒΆ](#what-does-the-suppressvolumechange-option-do "Permanent link") With this option enabled, pressing a hardware volume button while watching does not change the volume and the system volume indicator stays hidden. On Android, the volume key events are consumed. On iOS, the volume level is reset immediately after each button press and the original volume level is restored when watching stops. ### Can I use this plugin with Ionic, React, Vue or Angular?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins[ΒΆ](#related-plugins "Permanent link") * [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/): Configure and observe the iOS audio session. * [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/): Interact with media controllers, volume keys and media buttons. * [Silent Mode](https://capawesome.io/docs/sdks/capacitor/silent-mode/): Detect whether the device is in silent mode. ## Newsletter[ΒΆ](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/volume/CHANGELOG.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/volume/LICENSE). July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/volume/#article", "headline": "Capacitor Volume Plugin for Android & iOS", "name": "Capacitor Volume Plugin for Android & iOS", "description": "Capacitor plugin to get and set the volume level and observe hardware volume button presses on Android and iOS.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/volume/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/volume/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/volume/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/volume/#software", "name": "Capacitor Volume Plugin for Android & iOS", "description": "Capacitor plugin to get and set the volume level and observe hardware volume button presses on Android and iOS.", "url": "https://capawesome.io/docs/sdks/capacitor/volume/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How is this plugin different from other similar plugins?", "acceptedAnswer": {"@type": "Answer", "text": "It combines volume control and hardware button events in one unified API β€” a natural fit on iOS, where both rely on the same underlying system machinery. It adds per-stream control on Android and handles iOS volume-indicator suppression, all through a fully typed, actively maintained package, so a single dependency covers the whole volume story."}}, {"@type": "Question", "name": "Which platforms are supported by this plugin?", "acceptedAnswer": {"@type": "Answer", "text": "The plugin is available on Android and iOS. On the Web, all methods reject as unimplemented."}}, {"@type": "Question", "name": "Why is the stream option ignored on iOS?", "acceptedAnswer": {"@type": "Answer", "text": "On iOS, there is no public API to set the system volume directly. The plugin therefore uses a hidden system volume view to change the media volume, which is the only volume that can be read and set on iOS. The stream option is only supported on Android, see Volume Control for details."}}, {"@type": "Question", "name": "Why is setVolume rejected with the DO_NOT_DISTURB_ACCESS_REQUIRED error code?", "acceptedAnswer": {"@type": "Answer", "text": "On Android, changing the volume of the ring, notification or system stream while Do Not Disturb is active requires Do Not Disturb access. You can direct the user to the corresponding settings screen using the ACTION_NOTIFICATION_POLICY_ACCESS_SETTINGS intent, for example with the App Launcher plugin, see Volume Control for details."}}, {"@type": "Question", "name": "Why are volume button presses not detected?", "acceptedAnswer": {"@type": "Answer", "text": "The volumeButtonPressed event is only emitted while watching, so make sure you have called startWatching(...) first. On both platforms, button presses are only detected while the app is in the foreground. On iOS, presses can also not be detected once the volume has reached its minimum or maximum unless the suppressVolumeChange option is enabled, see Volume Button Watching for details."}}, {"@type": "Question", "name": "What does the suppressVolumeChange option do?", "acceptedAnswer": {"@type": "Answer", "text": "With this option enabled, pressing a hardware volume button while watching does not change the volume and the system volume indicator stays hidden. On Android, the volume key events are consumed. On iOS, the volume level is reset immediately after each button press and the original volume level is restored when watching stops."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects."}}], "url": "https://capawesome.io/docs/sdks/capacitor/volume/"} ```