Volume Control

import { PulseAudio } from 'pulseaudio.js';

const pa = new PulseAudio();
await pa.connect();

Volume Conversion Functions

In PulseAudio volumes are represented with integer values. The value 0 represents silence. The value 65536 represents a "normal" maximum value. For hardware sinks/sources, this usually refers to the maximum hardware volume. For software (virtual) objects, the value 65536 indicates no volume adjustment (software amplification). Values above 65536 indicate that some level of software amplification is desired. The PulseAudio volume value is opaque. It is designed to make 32768 feel roughly half as loud as 65536. The mapping to hardware volumes is complex and internal to PulseAudio. All Pulseaudio.js volume control methods expect PulseAudio volume values. Please refer to the PulseAudio wiki for more information on PulseAudio volumes.

The Pulseaudio.js library provides convenience functions to convert PulseAudio volumes to and from percentage (%) and decibel (dB) values.

import { percentToVolume, volumeToPercent, dBToVolume, volumeTodB } from 'pulseaudio.js';

• percentToVolume: converts a percentage (%) volume to a PulseAudio volume (e.g., percentToVolume(100) returns 65536)
• volumeToPercent: converts a PulseAudio volume to a percentage (%) volume
• dBToVolume: converts a decibel (dB) volume to a PulseAudio volume (e.g., dBToVolume(0) returns 65536)
• volumeTodB: converts a PulseAudio volume to a decibel (dB) volume

Additionally, the library provides two functions to convert between percentage and decibel volumes.

import { percentTodB, dBToPercent } from 'pulseaudio.js';

• percentTodB: converts a percentage (%) volume to a decibel (dB) volume
• dBToPercent: converts a decibel (dB) volume to a percentage (%) volume

Playback Volume Control

The methods setSinkVolume and setSinkInputVolume can be used to control playback volume. The former method controls the volume of the output device (sound card). The latter controls the volume of a particular output stream connected to the sink. setSinkVolume takes the volume to be set as the first argument. The optional second argument can provide the index (number) or name of the sink to control. The default sink will be used if left unspecified.

// Set the output volume of the default output device to 50%
await pa.setSinkVolume(percentToVolume(50));

If you wish to control the volume of each sink channel individually, provide an array of volumes in the first argument.

// Set left channel volume to 75% and right channel volume to 50%
await pa.setSinkVolume([percentToVolume(75), percentToVolume(50)], 'default_card');

Note that setSinkInputVolume takes the index (number) of the playback stream in the first argument and the volume(s) in the second argument. The index of the playback stream is returned by the method createPlaybackStream.

The methods setSinkMute and setSinkInputMute can be used to mute or unmute an output device or a playback stream.

await pa.setSinkMute(true);

Like setSinkInputVolume, setSinkInputMute takes the index of the playback stream in the first argument.

Record Volume Control

The methods setSourceVolume and setSourceOutputVolume can be used to control recording volume. The former method controls the volume of the input device (sound card). The latter controls the volume of a particular record stream connected to the source. setSourceVolume takes the volume to be set as the first argument. The optional second argument can provide the index (number) or name of the source to control. The default source will be used if left unspecified.

// Set the recording volume of the default input device to 50%
await pa.setSourceVolume(percentToVolume(50));

If you wish to control the volume of each source channel individually, provide an array of volumes in the first argument.

// Set left channel volume to 75% and right channel volume to 50%
await pa.setSourceVolume([percentToVolume(75), percentToVolume(50)], 'default_card');

Note that setSourceOutputVolume takes the index (number) of the record stream in the first argument and the volume(s) in the second argument. The index of the record stream is returned by the method createRecordStream.

The methods setSourceMute and setSourceOutputMute can be used to mute or unmute an input device or a record stream.

await pa.setSourceMute(true);

Like setSourceOutputVolume, setSourceOutputMute takes the index of the record stream in the first argument.