@supertiger/native-sound-mixer

Native Sound Mixer

Introduction

Native cross-platform sound mixer

This node.js project is a sound mixer for node desktop apps providing control over volume for each render/capture device (I/O devices) and for each audio session in an audio device separately.

The native c++ code is provided in cppsrc/ and compiled using node-addon-api

postinstall scripts will automatically build bin files

Install

This is a Node js package available through npm registry.

prerequisites

Linux

• install pulseaudio server (already installed on most user-friendly distros)

Windows

• no prerequisites are required for windows.

Install

> npm install native-sound-mixer

or using yarn :

> yarn add native-sound-mixer

Features

• Per-device volume control and monitoring
• Per-audio session volume control and monitoring within each device
• Fully compatible with TypeScript

DOCUMENTATION

Summary :

• SoundMixer: factory, default export

  • (static Attribute) devices: readonly
  • (static Method) getDefaulDevice

• Device: Represents a physical/virtual device with channels and volume controls

  • (Attribute) sessions: readonly
  • (Attribute) mute: read-write
  • (Attribute) volume: read-write
  • (Attribute) balance: read-write

• AudioSession: Represents an app-linked audio channel with volume controls

  • (Attribute) mute: read-write
  • (Attribute) volume: read-write
  • (Attribute) balance: read-write

• Data Structures

  • Volume Scalar
  • Volume Balance
  • AudioSessionState
  • DeviceType

1) SoundMixer

• get devices

this function returns all the devices found by the system.

import SoundMixer, {Device} from "native-sound-mixer";

const devices: Device[] = SoundMixer.devices;

• getDefaultDevice

returns the default device for the specified DeviceType, if none found returns undefined.

import SoundMixer, {Device, DeviceType} from "native-sound-mixer";

const device: Device | undefined = SoundMixer.getDefaultDevice(DeviceType.RENDER);

2) Device

class Device {
	private constructor(); // Device instantiation is disallowed
	public volume: VolumeScalar;
	public mute: boolean;
	public readonly name: string;
	public readonly type: DeviceType;
	public readonly sessions: AudioSession[];
}

• get sessions

returns all the AudioSessions linked to the Device.

// import ...

let device: Device;
// set device to any valid Device object.

const sessions: AudioSession[] = device.sessions;

• device mute

gets and sets mute value for the device.

// import ...

// retrieving the mute flag 
const mute: boolean = device.mute;

// toggling mute
device.mute = !mute;

• device volume

gets and sets the volume scalar for the device.

// import ...

// retrieving the volume 
const volume: VolumeScalar = device.volume;

// adding 10% to volume
device.volume += .1;

• device balance

gets and sets the volume balance for the device.

// import ...

// retrieving the volume 
const balance: VolumeBalance = device.balance;

// sets right VolumeScalar to 1 and left VolumeScalar to .5
// by default, left and right are equal to the VolumeScalar of the device
device.balance = {right: 1, left: .5};

3) AudioSession

// class declaration
class AudioSession {
	private constructor(); // AudioSession instantiation is disallowed

	public volume: VolumeScalar;
	public mute: boolean;
	public readonly name: string;
	public readonly appName: string;
}

• session mute

sets and gets the mute flag for the AudioSession.

// import ...

let session: AudioSession;
// set session to a valid session object
const mute: boolean = session.mute;
// toggling mute 
session.mute = !mute;

• session volume

sets and gets the VolumeScalar for the AudioSession.

// import ...

let session: AudioSession;
// set session to a valid session object
const volume: VolumeScalar = session.volume;
// adding 10% to volume
session.volume += .1;

• device balance

gets and sets the volume balance for the device.

// import ...

// retrieving the volume
let session: AudioSession;
const balance: VolumeBalance = session.balance;

// sets right VolumeScalar to 1 and left VolumeScalar to .5
// by default, left and right are equal to the VolumeScalar of the session
session.balance = {right: 1, left: .5};

4) Data Structures

• VolumeScalar

a clamped float betwen 0 and 1 representing the power of the volume, 1 is max power and 0 is no output.

• VolumeBalance

a structure representing the stereo balance for a device and an audio session

interface VolumeBalance {
	right: Number; // float
	left: Number; // float
	stereo: Boolean; // only for Device::balance
}

• AudioSessionState

an enumeration representing the state of the audio session. Possible values are

import {AudioSessionState} from "native-sound-mixer";

AudioSessionState.INACTIVE; // session is incative but valid
AudioSessionState.ACTIVE; // session is active
AudioSessionState.EXPIRED; // session no longer exists or is no longer available

• DeviceType

an enumeration representing the type of the device. Possible values are :

import {DeviceType} from "native-sound-mixer";

DeviceType.RENDER; // device type is output
DeviceType.CAPTURE; // device type is input
DeviceType.ALL; // device type is both input and output

Contributing

As an open-source project, every one is free to modify the codebase. Feel free to open any discussion or issue or PR to improve this project.

License

This project is under MIT license