soundcraft-ui-connection v2.2.1

soundcraft-ui-connection

This library provides a generic connection interface for the Soundcraft Ui series audio mixers (Ui12, Ui16 and Ui24R).

Installation

npm i soundcraft-ui-connection

Usage

Initialization and connection

import { SoundcraftUI } from 'soundcraft-ui-connection';

const conn = new SoundcraftUI(mixerIP);
conn.connect();

conn.disconnect(); // close connection
conn.reconnect(); // close connection and reconnect after timeout

All three methods return a Promise that resolves when the operation has finished. This is useful when you want to wait for the connection to be open before you start using the mixer. Please note that these Promises will not reject on errors. If you want to receive errors, use the status$ Observable instead.

Receive status

Status messages of the connection are exposed as an observable stream:

conn.status$.subscribe(status => {
  // ...
});

All messages have a type property with one of the following values:

Use commands and feedback

The SoundcraftUI object exposes commands and feedback in a human-readable and object-oriented structure. Feedback is published as streams that you can subscribe to. This uses the Observable object from RxJS. See a list of all available commands and feedback streams below.

conn.master.setFaderLavel(0.5);
conn.master.input(5).solo();
conn.aux(3).input(2).mute();

conn.master.faderLevel$.subscribe(value => {
  // ...
});

Commands and Feedback

Master

The following operations can be used to interact with the global master fader.

Generic channel operations

All channels on all buses have similar behavior. Therefore, these operations are available for any channel like MasterChannel, FxChannel or AuxChannel:

Master bus

Get access to a MasterChannel object first:

The MasterChannel exposes the following operations:

For input, line and aux master channels, the bus returns a DelayableMasterChannel object which is a subtype of MasterChannel. It contains the following members:

AUX buses

Get access to a AuxBus object with conn.aux(busNumber). Then pick one of the available AuxChannel objects:

An AuxChannel supports the following operations:

FX buses

Get access to a FxBus object with conn.fx(busNumber). Then pick one of the available FxChannels:

An FxChannel supports the following operations:

Hardware Channels (Phantom Power)

A HwChannel represents a hardware input on the mixer.

On the Ui24R, hardware inputs can be patched to different channels. This is why a hardware channel is not always the same as an input. This distinction is also visible in the original protocol of the mixer as well as in the UI (Phantom Power/Gain are on another page than the input faders). For Ui16 and Ui12, those hardware settings are part of the input channels internally. To keep the library surface clean, this library considers the mixer model in the background and offers all options through the HwChannel class.

First, get a HwChannel by calling conn.hw(inputNumber), e.g. conn.hw(1) for the first input.

Please note that the value conversion for gain dB values in the original Web UI is not exact. Values emitted by gain$ may differ from the values visible in the UI.

SOLO and Headphone Buses

SOLO and Headphone Outputs live on separate internal buses that have individual volume faders in the settings section of the web app. Get access to a VolumeBus object through conn.volume:

A VolumeBus supports the following operations (which are quite similar to all other fadeable channels):

MUTE Groups

The mixer supports up to 6 MUTE groups. Functions "MUTE ALL" and "MUTE FX" are also expressed as logical MUTE groups, internally.

First, get access to a MuteGroup object:

MuteGroup supports the following operations:

Call conn.clearMuteGroups() to disable all MUTE groups. This behaves differently from the "CLEAR MUTE" button in the Soundcraft Web App which also clears channel mutes.

Shows, Snapshots and Cues

Shows and their snapshots/cues can be loaded by providing their names to the following method calls. Please be aware that there will be no check whether a show with the given name actually exists. Information about the currently loaded show, snapshot or cue is also available.

Recording and playback

Media Player

2-Track USB Recorder

The following commands control the dual-track USB recorder in the media player section of the Soundcraft Web App:

Multitrack Recording (Ui24R only)

The Ui24R features multi-track recording. The MultiTackRecorder object can be retrieved via conn.recorderMultiTrack. It supports the following operations:

Transitions

All channels can perform timed transitions to a given value. Channel and MasterBus contain two methods fadeTo and fadeToDB with the following parameters:

Both methods return a Promise object that resolves when the transition time is finished. You can use this signal to wait for the transition before starting another operation. Please note that this signal is just implemented as a simple timer. If the transition stops for other reasons (interrupt by another transition or terminated connection), the timer will still run.

// Example:
// Fade input 1 on master bus to 0 dB within 2 seconds
// using the "ease out" characteristic
conn.master.input(1).fadeToDB(0, 2000, Easings.EaseOut);

A transition stops when a new transition is started on the same channel. When the connection is closed, all running transitions will be stopped.

The library supports the following built-in easing characteristics:

import { Easings } from 'soundcraft-ui-connection';

Easings.Linear; // no easing
Easings.EaseIn; // acceleration from zero velocity (slow start)
Easings.EaseOut; // deceleration from zero velocity (slow end)
Easings.EaseInOut; // acceleration until halfway, then deceleration (slow start and end)

Stereo Link

All commands respect the stereo link settings: If a channel is linked, all actions like fader level, mute, solo, etc. will be mirrored to the linked channel. This also applies to stereo-linked AUX buses so that the corresponding channel on a linked AUX bus mirrors the actions.

Examples:

This behavior matches the way the original web app handles stereo-linking.

Device Info

The mixer exposes the following information about the device:

Working with raw messages and state

The MixerStore object exposes raw streams with messages and state data. You can use them for debugging purposes or for integration in other services:

• conn.store.messages$: Stream of all raw SETD and SETS messages (inbound and outbound)
• conn.store.state$: Stream of state objects, derived from the messages

In much the same way you can send raw messages to the mixer:

conn.conn.sendMessage('SETD^m.mix^0.4');
conn.conn.sendMessage('SETD^i.2.mute^0');

Please prefer the human-readable interface over using the raw format! If you're missing any features, please file an issue or PR.

Additional useful information

• All channel objects are cached and treated as singletons. If you call conn.master.input(3) multiple times, each call returns the exact same object.
• Input values for fader levels and pan are restricted to the range of 0..1. All other values are not checked or sanitized in any way! Be sure to call the functions with valid values only.

License

MIT