/native-sound-mixer

Primary LanguageC++MIT LicenseMIT

Windows Sound Mixer

Introduction

Native cross-platform sound mixer

NB: Note that native integration with linux is under development and macos integration is not yet under development

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

What's new in v3

  • the node.js logic is now fully written in TypeScript
  • old functional architecture turned to modern object-oriented architecture

Install

This is a Node js package available through npm registry.

prerequisites

Linux (currently under development)

  • install pulseaudio lib

Windows

  • no prerequisites are required for windows.

Once Node.js and platform-specific prerequisites are installed, you can install native-sound-mixer with npm. In order to compile files, you have to run npm run build or npm install in node_modules/native-sound-mixer. :

> npm install native-sound-mixer
> cd node_modules/native-sound-mixer && npm run build

or using yarn :

> yarn add native-sound-mixer
> cd node_modules/native-sound-mixer && npm run build

Features

  • Per-device volume control and monitoring
  • Per-audio session volume control and monitoring within each 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);

  • getDeviceById

returns the device corresponding to the given id, if none, returns undefined.

// import ...

const id = "<any id of device here>";
const device: Device | undefined = SoundMixer.getDeviceById(id);

2) Device

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

  • getSessionById

returns the AudioSession linked to the given id. If not found, returns undefined.

// import ...

const id: string = "<any audio session id>";
const session: AudioSession | undefined = device.getSessionById(id);

3) AudioSession

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

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.

  • 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. The TODO file provides all future features with their current development state. Please test your code before committing to this repository.

License

This project is under MIT license