Capacitor Volume Control Plugin

A Capacitor plugin for advanced volume control with native Android and iOS implementations. This plugin provides comprehensive volume management capabilities including volume level control, volume change monitoring, and platform-specific features.

Features

🔊 Volume Level Control: Get and set volume levels for different audio streams
👂 Volume Change Monitoring: Watch for volume changes in real-time
📱 Platform-Specific Features:
- Android: Suppress volume indicator, control different volume types
- iOS: Disable system volume handler, voice call volume control
🎯 Type Safety: Full TypeScript support with comprehensive type definitions
🔧 Easy Integration: Simple API that works seamlessly with Capacitor apps

⚠️ Migration Notice

v2.0+ Breaking Change:

The callback parameter in watchVolume(options, callback) is no longer supported.
Use the event listener pattern addListener('volumeButtonPressed', callback) instead.
The callback receives { direction: 'up' | 'down' }.

Installation

npm install @odion-cloud/capacitor-volume-control
npx cap sync

✅ No MainActivity Integration Required!

This plugin uses @capacitor-community/volume-buttons for hardware button detection, which means no MainActivity code changes needed. Just install and use!

Setup

Install dependencies:

npm install

Add the plugin:

npm install @odion-cloud/capacitor-volume-control

Sync with native platforms:

npx cap sync

Usage Examples

Basic Volume Control

import { VolumeControl, VolumeType } from '@odion-cloud/capacitor-volume-control';

// Get current volume
const volume = await VolumeControl.getVolumeLevel();
console.log('Current volume:', volume.value);

// Set volume to 50%
await VolumeControl.setVolumeLevel({ value: 0.5 });

Volume Watching

// First, add the event listener
await VolumeControl.addListener('volumeButtonPressed', (event) => {
  console.log('Volume button pressed:', event.direction); // 'up' or 'down'
});

// Then start watching
await VolumeControl.watchVolume({
  disableSystemVolumeHandler: true, // iOS only
  suppressVolumeIndicator: true,    // Android only
});

// Stop watching when done
await VolumeControl.clearWatch();

Advanced Usage

import { VolumeControl, VolumeType } from '@odion-cloud/capacitor-volume-control';

class VolumeService {
  private isWatching = false;

  async initializeVolume() {
    try {
      // Get current music volume
      const musicVolume = await VolumeControl.getVolumeLevel({
        type: VolumeType.MUSIC
      });
      
      console.log('Music volume:', musicVolume.value);
      
      // Set system volume
      await VolumeControl.setVolumeLevel({
        value: 0.8,
        type: VolumeType.SYSTEM
      });
      
    } catch (error) {
      console.error('Volume initialization error:', error);
    }
  }

  async startWatching() {
    if (this.isWatching) return;

    try {
      // Add listener first
      await VolumeControl.addListener('volumeButtonPressed', this.handleVolumeChange.bind(this));
      
      // Then start watching
      await VolumeControl.watchVolume({
        disableSystemVolumeHandler: true,
        suppressVolumeIndicator: true
      });
      
      this.isWatching = true;
      console.log('Started volume watching');
      
    } catch (error) {
      console.error('Volume watching error:', error);
    }
  }

  async stopWatching() {
    try {
      await VolumeControl.clearWatch();
      this.isWatching = false;
      console.log('Stopped volume watching');
      
    } catch (error) {
      console.error('Stop watching error:', error);
    }
  }

  private handleVolumeChange(event: { direction: 'up' | 'down' }) {
    console.log(`Volume ${event.direction}`);
    // Custom volume handling logic
  }

  async getWatchStatus() {
    const status = await VolumeControl.isWatching();
    return status.value;
  }
}

// Usage
const volumeService = new VolumeService();

// Initialize
await volumeService.initializeVolume();

// Start watching
await volumeService.startWatching();

// Check status
const isWatching = await volumeService.getWatchStatus();
console.log('Is watching:', isWatching);

// Stop watching
await volumeService.stopWatching();

Platform-Specific Examples

Android Specific

// Add listener
await VolumeControl.addListener('volumeButtonPressed', (event) => {
  console.log('Volume button pressed:', event.direction);
});

// Suppress volume indicator on Android
await VolumeControl.watchVolume({
  suppressVolumeIndicator: true
});

// Control different volume types
await VolumeControl.setVolumeLevel({
  value: 0.7,
  type: VolumeType.NOTIFICATION
});

iOS Specific

// Add listener
await VolumeControl.addListener('volumeButtonPressed', (event) => {
  console.log('Volume button pressed:', event.direction);
});

// Disable system volume handler on iOS
await VolumeControl.watchVolume({
  disableSystemVolumeHandler: true
});

// Control voice call volume
await VolumeControl.setVolumeLevel({
  value: 0.9,
  type: VolumeType.VOICE_CALL
});

Error Handling

try {
  await VolumeControl.setVolumeLevel({ value: 1.5 });
} catch (error) {
  if (error.message.includes('between 0.0 and 1.0')) {
    console.error('Invalid volume value');
  } else {
    console.error('Unexpected error:', error);
  }
}

try {
  await VolumeControl.watchVolume({});
  await VolumeControl.watchVolume({}); // This will fail
} catch (error) {
  if (error.message.includes('already been watched')) {
    console.error('Volume watching is already active');
  }
}

React Hook Example

import { useEffect, useState } from 'react';
import { VolumeControl } from '@odion-cloud/capacitor-volume-control';

export function useVolumeControl() {
  const [volume, setVolume] = useState(0.5);
  const [isWatching, setIsWatching] = useState(false);

  useEffect(() => {
    // Get initial volume
    VolumeControl.getVolumeLevel().then(result => {
      setVolume(result.value);
    });

    // Cleanup on unmount
    return () => {
      VolumeControl.clearWatch();
    };
  }, []);

  const startWatching = async () => {
    if (isWatching) return;

    try {
      // Add listener first
      await VolumeControl.addListener('volumeButtonPressed', (event) => {
        console.log('Volume button pressed:', event.direction);
        // You may want to update UI or state here
      });
      
      // Then start watching
      await VolumeControl.watchVolume({
        disableSystemVolumeHandler: true,
        suppressVolumeIndicator: true
      });
      
      setIsWatching(true);
    } catch (error) {
      console.error('Failed to start watching:', error);
    }
  };

  const stopWatching = async () => {
    try {
      await VolumeControl.clearWatch();
      setIsWatching(false);
    } catch (error) {
      console.error('Failed to stop watching:', error);
    }
  };

  const setVolumeLevel = async (value: number) => {
    try {
      await VolumeControl.setVolumeLevel({ value });
      setVolume(value);
    } catch (error) {
      console.error('Failed to set volume:', error);
    }
  };

  return {
    volume,
    isWatching,
    startWatching,
    stopWatching,
    setVolumeLevel
  };
}

Vue Composition API Example

import { ref, onMounted, onUnmounted } from 'vue';
import { VolumeControl } from '@odion-cloud/capacitor-volume-control';

export function useVolumeControl() {
  const volume = ref(0.5);
  const isWatching = ref(false);

  onMounted(async () => {
    // Get initial volume
    try {
      const result = await VolumeControl.getVolumeLevel();
      volume.value = result.value;
    } catch (error) {
      console.error('Failed to get initial volume:', error);
    }
  });

  onUnmounted(async () => {
    await stopWatching();
  });

  const startWatching = async () => {
    if (isWatching.value) return;

    try {
      // Add listener first
      await VolumeControl.addListener('volumeButtonPressed', (event) => {
        console.log('Volume button pressed:', event.direction);
      });
      
      // Then start watching
      await VolumeControl.watchVolume({
        disableSystemVolumeHandler: true,
        suppressVolumeIndicator: true
      });
      
      isWatching.value = true;
    } catch (error) {
      console.error('Failed to start watching:', error);
    }
  };

  const stopWatching = async () => {
    try {
      await VolumeControl.clearWatch();
      isWatching.value = false;
    } catch (error) {
      console.error('Failed to stop watching:', error);
    }
  };

  const setVolumeLevel = async (value: number) => {
    try {
      await VolumeControl.setVolumeLevel({ value });
      volume.value = value;
    } catch (error) {
      console.error('Failed to set volume:', error);
    }
  };

  return {
    volume,
    isWatching,
    startWatching,
    stopWatching,
    setVolumeLevel
  };
}

Angular Service Example

import { Injectable } from '@angular/core';
import { BehaviorSubject } from 'rxjs';
import { VolumeControl } from '@odion-cloud/capacitor-volume-control';

@Injectable({
  providedIn: 'root'
})
export class VolumeService {
  private volumeSubject = new BehaviorSubject<number>(0.5);
  private isWatchingSubject = new BehaviorSubject<boolean>(false);

  public volume$ = this.volumeSubject.asObservable();
  public isWatching$ = this.isWatchingSubject.asObservable();

  constructor() {
    this.initializeVolume();
  }

  private async initializeVolume() {
    try {
      const result = await VolumeControl.getVolumeLevel();
      this.volumeSubject.next(result.value);
    } catch (error) {
      console.error('Failed to get initial volume:', error);
    }
  }

  async startWatching(): Promise<void> {
    if (this.isWatchingSubject.value) return;

    try {
      // Add listener first
      await VolumeControl.addListener('volumeButtonPressed', (event) => {
        console.log('Volume button pressed:', event.direction);
        // You may want to update with actual logic
      });
      
      // Then start watching
      await VolumeControl.watchVolume({
        disableSystemVolumeHandler: true,
        suppressVolumeIndicator: true
      });
      
      this.isWatchingSubject.next(true);
    } catch (error) {
      console.error('Failed to start watching:', error);
      throw error;
    }
  }

  async stopWatching(): Promise<void> {
    try {
      await VolumeControl.clearWatch();
      this.isWatchingSubject.next(false);
    } catch (error) {
      console.error('Failed to stop watching:', error);
      throw error;
    }
  }

  async setVolumeLevel(value: number): Promise<void> {
    try {
      await VolumeControl.setVolumeLevel({ value });
      this.volumeSubject.next(value);
    } catch (error) {
      console.error('Failed to set volume:', error);
      throw error;
    }
  }
}

Testing

Run the example:

npm start

Build for production:

npm run build

Test on device:

npx cap run android
npx cap run ios

Platform Support

📱 Supported Devices

Platform	Support Level	Minimum Version	Features
Android	✅ Full Support	Android 6.0+ (API 23+)	All volume types, hardware buttons, real-time monitoring
iOS	✅ Full Support	iOS 13.0+	Volume control, hardware buttons, audio session management
Web	⚠️ Development Only	All modern browsers	Mock implementation for testing

🏆 Android Version Compatibility

Android Version	API Level	Support Level	Features
Android 14+	API 34+	✅ Full	All features, visual media permissions
Android 13	API 33	✅ Full	Granular media permissions
Android 10-12	API 29-32	✅ Full	Scoped storage, external volumes
Android 6-9	API 23-28	✅ Full	Runtime permissions, SD card access
Android 5	API 21-22	⚠️ Basic	Limited external storage access

🎯 Volume Types Support

Volume Type	Android	iOS	Description
`VolumeType.MUSIC`	✅	✅	Music, videos, games, and other media
`VolumeType.SYSTEM`	✅	❌	System sounds and notifications
`VolumeType.RING`	✅	❌	Phone ringtone volume
`VolumeType.NOTIFICATION`	✅	❌	Notification sounds
`VolumeType.ALARM`	✅	❌	Alarm clock volume
`VolumeType.VOICE_CALL`	✅	✅	Voice call volume
`VolumeType.DTMF`	✅	❌	DTMF tones

API Reference

Methods

`getVolumeLevel(options?)`

Get the current volume level for a specific audio stream.

getVolumeLevel({
  type?: VolumeType;        // Volume type to get (default: 'music')
}): Promise<VolumeResult>

// Returns: { value: number } (0.0 to 1.0)

`setVolumeLevel(options)`

Set the volume level for a specific audio stream.

setVolumeLevel({
  value: number;            // Volume level (0.0 to 1.0)
  type?: VolumeType;        // Volume type to set (default: 'music')
}): Promise<VolumeResult>

// Returns: { value: number } (the new volume level)

`watchVolume(options)`

Start watching for volume button presses.

watchVolume({
  disableSystemVolumeHandler?: boolean;  // iOS: disable system UI
  suppressVolumeIndicator?: boolean;     // Android: hide volume UI
}): Promise<void>

`addListener(eventName, callback)`

Listen for volume button press events.

addListener(
  'volumeButtonPressed',
  callback: (event: { direction: 'up' | 'down' }) => void
): Promise<PluginListenerHandle>

// Event data: { direction: 'up' | 'down' }

`clearWatch()`

Stop watching for volume changes.

clearWatch(): Promise<void>

`isWatching()`

Check if volume watching is currently active.

isWatching(): Promise<{ value: boolean }>

Configuration Options

Option	Platform	Description
`suppressVolumeIndicator`	Android	Hide system volume UI when changing volume
`disableSystemVolumeHandler`	iOS	Disable system volume UI and intercept hardware buttons
`type`	Both	Specify volume type (MUSIC, SYSTEM, RING, etc.)
`value`	Both	Volume level between 0.0 and 1.0

Error Handling

Common errors and their solutions:

Error Message	Cause	Solution
`Volume value must be between 0.0 and 1.0`	Invalid volume level	Ensure volume is between 0.0 and 1.0
`Volume buttons has already been watched`	Multiple watch calls	Call `clearWatch()` before starting new watch
`Volume slider not available`	iOS setup issue	Check audio session configuration
`Failed to get volume level`	Permission or system error	Verify permissions and device compatibility
`Volume observer registration failed`	Android system issue	Restart app or check system permissions
`Audio session setup failed`	iOS audio session issue	Check audio session category and options

Best Practices

Always clean up listeners: Remove event listeners when components unmount with removeAllListeners()
Add listener before watching: Call addListener() before watchVolume() to ensure events are captured
Handle errors gracefully: Wrap volume operations in try-catch blocks
Check watch status: Use isWatching() to avoid duplicate watch calls
Test on real devices: Volume watching requires physical hardware

Support This Project

Help me improve this plugin and build better tools for the community!

🤝 GitHub Sponsors

Support through GitHub's official sponsorship program:

GitHub Sponsors - Most transparent and developer-friendly way to support

₿ Cryptocurrency Support

Support via crypto donations across multiple networks:

Network	Address
Bitcoin (BTC)	`bc1q2k0ftm2fgst22kzj683e8gpau3spfa23ttkg26`
USDT (Ethereum)	`0xd6f4d8733c8C23e7bEC8Aeba37F4b3D2e93172d1`
USDT (BNB Chain)	`0xd6f4d8733c8C23e7bEC8Aeba37F4b3D2e93172d1`
USDT (TRON/TRC20)	`TXVy781mQ2tCuQ1BrattXWueUHp1wB5fwt`
USDT (Solana)	`GZ8jmSUUzc4dQF7Cthj2atomvpBZWqccR81N9DL4o1Be`
USDT (TON)	`UQAthXSNIlauj3SrzpDAU4VYxgEVV3niOSmeTPCtMBKGfEAE`

💻 Why Support?

Your contributions help me:

Upgrade to better development hardware
Improve workspace and productivity
Dedicate more time to open source projects
Add new features faster
Provide better documentation and examples

🤝 Other Ways to Help

⭐ Star the Project - Give us a star on GitHub to show your support!
🐛 Report Issues - Help improve the plugin by reporting bugs and suggesting features
📖 Improve Docs - Contribute to documentation, examples, and tutorials
💬 Spread the Word - Share the plugin with other developers who might find it useful

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Troubleshooting

Android: Kotlin Version Incompatibility

If you encounter the error:

Module was compiled with an incompatible version of Kotlin. The binary version of its metadata is 1.9.0, expected version is 1.7.1

Solution: Update your project's Kotlin version in android/build.gradle:

buildscript {
    ext.kotlin_version = '1.9.10'  // Update from older version
    dependencies {
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
    }
}

This plugin requires Kotlin 1.9.0+ and Android Gradle Plugin 7.4.2+.

iOS: Pod Name Mismatch

If you're using the scoped npm package name and encounter pod installation issues:

Symptom: Pod name in Podfile (OdionCloudCapacitorVolumeControl) doesn't match the podspec file name (CapacitorVolumeControl)

Solution: Reference the package with an alias in package.json:

{
  "dependencies": {
    "capacitor-volume-control": "npm:@odion-cloud/capacitor-volume-control@^1.0.13"
  }
}

Then run:

npm install
npx cap sync ios

Other Common Issues

Volume watching not working on emulators/simulators

Volume watching requires physical hardware buttons
Test on real devices for volume button detection

Permission denied errors

Ensure you've added the required permissions to your AndroidManifest.xml or Info.plist
Request permissions at runtime before calling volume control methods

Build errors after updating

Clean your build folders:

cd android && ./gradlew clean
# or
cd ios && rm -rf Pods && pod install

Invalidate caches in Android Studio: File → Invalidate Caches → Restart

Changelog

See CHANGELOG.md for a list of changes and version history.

Name		Name	Last commit message	Last commit date
Latest commit History 60 Commits
.github		.github
android		android
attached_assets		attached_assets
docs		docs
ios/Plugin		ios/Plugin
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.replit		.replit
CHANGELOG.md		CHANGELOG.md
CapacitorVolumeControl.podspec		CapacitorVolumeControl.podspec
MAINACTIVITY_INTEGRATION.md		MAINACTIVITY_INTEGRATION.md
PUBLISH_TO_NPM.md		PUBLISH_TO_NPM.md
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
replit.md		replit.md
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Uh oh!

odion-cloud/capacitor-volume-control

Folders and files

Latest commit

History

Repository files navigation

Capacitor Volume Control Plugin

Features

⚠️ Migration Notice

Installation

✅ No MainActivity Integration Required!

Setup

Usage Examples

Basic Volume Control

Volume Watching

Advanced Usage

Platform-Specific Examples

Android Specific

iOS Specific

Error Handling

React Hook Example

Vue Composition API Example

Angular Service Example

Testing

Platform Support

📱 Supported Devices

🏆 Android Version Compatibility

🎯 Volume Types Support

API Reference

Methods

getVolumeLevel(options?)

setVolumeLevel(options)

watchVolume(options)

addListener(eventName, callback)

clearWatch()

isWatching()

Configuration Options

Error Handling

Best Practices

Support This Project

🤝 GitHub Sponsors

₿ Cryptocurrency Support

💻 Why Support?

🤝 Other Ways to Help

Contributing

License

Troubleshooting

Android: Kotlin Version Incompatibility

iOS: Pod Name Mismatch

Other Common Issues

Changelog

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 15

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Languages

`getVolumeLevel(options?)`

`setVolumeLevel(options)`

`watchVolume(options)`

`addListener(eventName, callback)`

`clearWatch()`

`isWatching()`

Packages