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

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

2. 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

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

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

4. 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

```Typescript
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`](#volumescalar) for the device. 
```TypeScript
// 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 : 

```TypeScript
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