Skip to content

m1dugh/native-sound-mixer

Repository files navigation

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
  • stereo volume control for session and device
  • Fully compatible with TypeScript

DOCUMENTATION

Summary :

  1. SoundMixer: factory, default export

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

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

  4. Data Structures

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;
  • session balance

gets and sets the volume balance for the session.

// 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};
  • session state

gets the AudioSessionState for the session.

// import ...

// retrieving the state
let session: AudioSession;
const state: AudioSessionState = session.state;

if (state === AudioSessionState.ACTIVE) {
    // do something...
}

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

See CONTRIBUTING.md


License

This project is under MIT license