Volume Supervisor

Volume Supervisor is a Node.js library that allows you to control system and application volume. It provides a simple and intuitive API to get and set the global volume, mute and unmute the system, and get the status of the system. The project is inspired by easy-volume by Arciiix.

This is in a really early stage of development, so expect bugs and missing features. The API is also subject to consequential changes.

Installation

You can install Volume Supervisor using npm:

$ npm install volume_supervisor
$ yarn add volume_supervisor
$ pnpm add volume_supervisor

Compatibility

Currently, Volume Supervisor only fully supports Linux and basic function on windows. The windows support is planned to be expended in the near future. If you are a Mac user and would like to contribute to this project, feel free to fork the repository and make a merge request.

Functions Compatibility

The compatibility of features on linux depends on whether amixer, wireplumber or pulseaudio is installed on your Linux system. Here is a table that outlines the compatibility:

Feature	Amixer	Wireplumber	Pulseaudio	Windows
Global volume features	Yes	Yes	Yes	Yes
Audio status	No	Yes	Yes	Yes
List streams	No	Yes	Yes	Yes
List sinks	No	Yes	Yes	Yes
List sources	No	Yes	Yes	Yes
Stream volume features	No	Yes	Yes	Yes
Sink volume features	No	Yes	Yes	Yes
Source volume features	No	Yes	Yes	Yes
Get stream destination	No	No	Yes	Yes
Set stream destination	No	No	Yes	No

Priority for linux: pulseaudio (pactl) > wireplumber (wpctl) > amixer

Volume features correspond to get/set volume and mute/unmute.

Usage

Here is a basic example of how to use Volume Supervisor:

import { volumeControl } from 'volume_supervisor';

// Get the global volume
volumeControl.getGlobalVolume().then(volume => {
  console.log(`Current volume is ${volume}`);
});

// Set the global volume
volumeControl.setGlobalVolume(50).then(() => {
  console.log('Volume has been set to 50');
});

// Mute the system
volumeControl.setGlobalMuted(true).then(() => {
  console.log('System has been muted');
});

Per node volume

Volume Supervisor also allows you to get and set the volume of individual nodes. Here is an example:

import { volumeControl } from 'volume_supervisor';

// Get the status of the system
volumeControl.getStatus().then(async status => {
  // Get the first stream
  const stream = status.streams[0];
  if (!stream) {
    console.log('No streams found');
    return;
  }

  // Display the stream's name
  console.log(`Stream name: ${stream.name}`); // e.g. 'Firefox'

  // Get the stream's volume
  const volume = (await volumeControl.getNodeVolumeInfoById(stream.id)).volume;
  console.log(`Stream volume: ${volume}`); // e.g. 50

  // Increase the stream's volume by 10%
  await volumeControl.setNodeVolumeById(stream.id, volume + 10);
  
  // Set new destination for the stream
  await volumeControl.setStreamDestination(stream.id, status.sinks[0].id);
});

Types

All the types used in the API are defined in the types.ts file. Here is a list of the types: Here are some of the types used in the API:

export type VolumeInfo = {
  volume: number;
  muted: boolean;
};

export type VsNodeTypes = 'sink' | 'source' | 'stream';

export type VsNode = {
  type: VsNodeTypes;
  id: string;
  name: string;
  isDefault: boolean;
} & VolumeInfo;

export type VsStreamNode = VsNode & {
  type: 'stream';
  destinationId?: string;
};

export type SinkStatus = {
  sinks: VsNode[];
  defaultSink?: string;
};

export type SourceStatus = {
  sources: VsNode[];
  defaultSource?: string;
};

export type StreamStatus = {
  streams: VsStreamNode[];
};

export type Status = SinkStatus & SourceStatus & StreamStatus;

License

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