@capacitor-community/volume-buttons

Capacitor Volume Buttons Plugin

@capacitor-community/volume-buttons

Capacitor community plugin to listen to hardware volume button presses

Table of Contents

• Maintainers
• About
• Plugin versions
• Supported Platforms
• Installation
• API
• Troubleshooting

Maintainers

Maintainer	GitHub	Active
ryaa	ryaa	yes

About

This plugins allows to listen for the events fired when the user presses the hardware volume up or down button of the device. An object that contains only one property is passed to the callback - see VolumeButtonsResult. This plugin contains code derived from or inspired by https://github.com/CipherBitCorp/VolumeButtonHandler and https://github.com/thiagobrez/capacitor-volume-buttons plugins.

Features:

• support receiving events when the volume is max or min (make sure to use disableSystemVolumeHandler on iOS platform - see VolumeButtonsOptions)
• keep receiving events after the application sent to and returns from the background
• supports Android and iOS platforms

NOTE: The plugin version 7.0.0 is compatible with Capacitor 7

Plugin versions

Capacitor version	Plugin version
7.x	7.x
6.x	6.x
5.x	1.x

Supported Platforms

• iOS
• Android

Installation

npm install @capacitor-community/volume-buttons
npx cap sync

API

• isWatching()
• watchVolume(...)
• clearWatch()
• Interfaces
• Type Aliases

isWatching()

isWatching() => Promise<GetIsWatchingResult>

Get the watch status of the volume buttons.

Returns: Promise<GetIsWatchingResult>

Since: 1.0.1

watchVolume(...)

watchVolume(options: VolumeButtonsOptions, callback: VolumeButtonsCallback) => Promise<CallbackID>

Set up a watch for he hardware volume buttons changes

Param	Type
options	VolumeButtonsOptions
callback	VolumeButtonsCallback

Returns: Promise<string>

Since: 1.0.0

clearWatch()

clearWatch() => Promise<void>

Clear the existing watch

Since: 1.0.0

Interfaces

GetIsWatchingResult

Prop	Type	Description	Since
value	boolean	If the volume buttons are being watched.	1.0.1

VolumeButtonsOptions

Prop	Type	Description	Since
disableSystemVolumeHandler	boolean	This parameter can be used to disable the system volume handler (iOS only). If this is true, when up or down volume button is tapped, the system volume will always be reset to either the initial volume (the volume which was current when the volume buttons are started to be tracked/listened) or to 0.05 if the initial volume is less then 0.05 or to 0.95 if the initial volume is greater then 0.95.	1.0.0
suppressVolumeIndicator	boolean	This parameter can be used to suppress/hide the system volume indicator (Android only, it is never shown on iOS already). If this is true, when up or down volume button is tapped, the system volume indicator will not be shown. The default value is false.	1.0.2

VolumeButtonsResult

Prop	Type	Description	Since
direction	'up' | 'down'	This indicates either the volume up or volume down button was pressed.	1.0.0

Type Aliases

VolumeButtonsCallback

(result: VolumeButtonsResult, err?: any): void

CallbackID

string

Usage

Please also see example-app for a complete example.

Add volume button listener in the app

import { VolumeButtons } from '@capacitor-community/volume-buttons';

const options: VolumeButtonsOptions = {};
const callback: VolumeButtonsCallback = (result: VolumeButtonsResult, err?: any) => {
  console.log('result', result);
};
if (this.platform.is('ios')) {
  options.disableSystemVolumeHandler = true;
} else if (this.platform.is('android')) {
  options.suppressVolumeIndicator = true;
}
await VolumeButtons.watchVolume(options, callback);

Remove volume button listener in the app

import { VolumeButtons } from '@capacitor-community/volume-buttons';

await VolumeButtons.clearWatch();