Skip to content

Commit

Permalink
chore: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@hirbod
hirbod committed Jun 4, 2022
1 parent d871ff6 commit 4d04bff
Show file tree
Hide file tree
Showing 3 changed files with 77 additions and 16 deletions.
93 changes: 77 additions & 16 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,14 @@

# react-native-volume-manager

This native package adds the ability to change the system volume on iOS and Android, listen to volume changes and suppress the native volume UI to build your own volume slider and UX. It also provides a simple API to get the current volume level.
This native package adds the ability to change the system volume on iOS and Android, listen to volume changes and suppress the native volume UI to build your own volume slider and UX. It also provides a simple API to get the current volume level. On iOS, you can check if the silent switch is enabled and listen to changes. On Android, you can set and listen for ringer mode changes.

| ![React Native Volume Manager](ios-preview.gif) | ![React Native Volume Manager](android-preview.gif) |
| ----------------------------------------------- | --------------------------------------------------- |

## Notice

This library does **not work** in a **Simulator** or **Emulator**. It is only working on a real device.

## Installation

Expand All @@ -20,14 +27,18 @@ Linking the package manually is not required anymore with [Autolinking](https://

## Expo

---

This library adds native code. It does not work with _Expo Go_ but you can easily install it using a [custom dev client](https://docs.expo.dev/development/getting-started/). Thats how it should be done in 2022 :).

**No config plugin required.**

---

## Usage 🚀

```tsx
import VolumeManager from 'react-native-volume-manager';
import { VolumeManager } from 'react-native-volume-manager';

// ...

Expand All @@ -38,7 +49,7 @@ await VolumeManager.setVolume(0.5); // float value between 0 and 1
await VolumeManager.setVolume(0.5, {
type: 'system', // defaults to "music" (Android only)
showUI: true, // defaults to false, can surpress the native UI Volume Toast (iOS & Android)
playSound: false, // defaults to false (when pushing hardware buttons) (Android only)
playSound: false, // defaults to false (Android only)
});

// get volume async, type defaults to "music" (Android only)
Expand All @@ -47,27 +58,41 @@ await VolumeManager.setVolume(0.5, {
const { volume } = await VolumeManager.getVolume(type: 'music');

// or the oldschool way
VolumeManager.getVolume.then((result) => {
console.log(result.volume); // returns the current volume as a float (0-1)
VolumeManager.getVolume('music').then((result) => {
console.log(result); // returns the current volume as a float (0-1)

// NOTE: if you don't supply a type to getVolume on Android, you will receive the VolumeResult object:
/*
{
volume: number, // these are the same
music: number, // these are the same
system: number, // these are the same
ring: number,
alarm: number,
notification: number,
}
*/
// iOS will always return only the volume as float
});

// listen to volume changes
useEffect(() => {
const volumeListener = VolumeManager.addListener((result) => {
const volumeListener = VolumeManager.addVolumeListener((result) => {
console.log(result.volume); // returns the current volume as a float (0-1)
// on android, the result object will also have the keys music, system, ring, alarm, notification
});

// clean up function
return function () {
// remove listener
volumeListener.remove();
// remove listener, just call .remove on the volumeListener EventSubscription
volumeListener.remove();
}
}, []);

// or with useFocusEffect from react-navigation
useFocusEffect(
React.useCallback(() => {
const volumeListener = VolumeManager.addListener(async (data) => {
const volumeListener = VolumeManager.addVolumeListener(async (result) => {
if (Platform.OS === 'ios') {
try {
// once we detected a user on iOS triggered volume change,
Expand All @@ -81,21 +106,57 @@ useFocusEffect(
}
});
return function blur() {
// remove listener, just call .remove on the emitter
volumeListener.remove();
};
}, [])
);
```

## iOS mute switch listener

---

There is no native iOS API to detect if the mute switch is enabled/disabled on a device.

The general principle to check if the device is muted is to play a short sound without audio and detect the length it took to play. Has a trigger rate of 1 second.

**Note: The check is performed on the native main thread, not the JS thread.**
You can increase or decrease how often the check is performed by changing the `VolumeManager.setNativeSilenceCheckInterval(1)` property. Minimum value is `0.5`, default is `2`. The default value is usually enough.

```tsx
import { VolumeManager } from 'react-native-volume-manager';
const [isSilent, setIsSilent] = useState<boolean>();

VolumeManager.setNativeSilenceCheckInterval(1); // min 0.5, default 2

// ....
// ....

useEffect(() => {
const silentListener = VolumeManager.addSilentListener((status) => {
setIsSilent(status); // status is a boolean
});

return () => {
// remove listener, just call .remove on the emitter
// never forget to clean up
silentListener.remove();
};
}, []);
```

## API

| Method | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Volume** |
| getVolume(type:string) => Promise | Get the system volume. <br><br>`type` must be one of `music`, `call`, `system`, `ring`, `alarm`, `notification`, default is `music`. (Android only, iOS will always report the system volume) |
| setVolume(value:float, config:object) | Set the system volume by specified value, from 0 to 1. 0 for mute, and 1 for the max volume.<br><br> `config` can be `{type: 'music', playSound:true, showUI:true}`<br><br> `type` : must be one of `music`, `call`, `system`, `ring`, `alarm`, `notification`, default is `music`. (Android only) <br>`playSound`: Whether to play a sound when changing the volume, default is `false` (Android only)<br>`showUI`: Show the native system volume UI, default is `false` (Android & iOS) |
| addListener(callback) | Listen to volume changes (soft- and hardware. addListener will return the listener which is needed for cleanup. Result passed to callback contains `volume` as key. |
| `listener.remove()` | Remove the listener when you don't need it anymore. Store the return of `const listener = VolumeManager.addListener()` in a variable and call it with `.remove()`. See the example above. |
| Method | Description |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Volume** |
| getVolume(type?:string) => Promise | Get the system volume. <br><br>`type` must be one of `music`, `call`, `system`, `ring`, `alarm`, `notification`, default is `music`. (Android only, iOS will always report the system volume) |
| setVolume(value:float, config?:object) | Set the system volume by specified value, from 0 to 1. 0 for mute, and 1 for the max volume.<br><br> `config` can be `{type: 'music', playSound:true, showUI:true}`<br><br> `type` : must be one of `music`, `call`, `system`, `ring`, `alarm`, `notification`, default is `music`. (Android only) <br>`playSound`: Whether to play a sound when changing the volume, default is `false` (Android only)<br>`showUI`: Show the native system volume UI, default is `false` (Android & iOS) |
| addVolumeListener(callback) | Listen to volume changes (soft- and hardware. addListener will return the listener which is needed for cleanup. Result passed to callback contains `volume` as key. |
| `listener.remove()` | Remove the listener when you don't need it anymore. Store the return of `const listener = VolumeManager.addListener()` in a variable and call it with `.remove()`. See the example above. |
| addRingerListener(callback): RingerSilentStatus => void | **Android only:** Listen to ringer mode changes. Returns object with type `RingerSilentStatus` |
| removeRingerListener(listener) => void | **Android only:** Unlike `addVolumeListener`, you need to call a separate method and pass the return of `addRingerListener`. |

## Contributing

Expand Down
Binary file added android-preview.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added ios-preview.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 4d04bff

Please sign in to comment.