soundcraft-ui-connection

Library for controlling the Soundcraft Ui series audio mixers

Usage no npm install needed!

<script type="module">
  import soundcraftUiConnection from 'https://cdn.skypack.dev/soundcraft-ui-connection';
</script>

README

soundcraft-ui-connection

npm

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

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:

Message Description
OPENING Connecting to the mixer
OPEN Successfully connected to the mixer
CLOSING Disconnecting from the mixer
CLOSE Disconnected from the mixer
ERROR Connection error occured. The error object can be accessed through the payload property of the message.
RECONNECTING After an error, trying reconnection

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

Call Description
conn.master.setFaderLevel(value) Set the master fader level (between 0 and 1)
conn.master.setFaderLevelDB(dbValue) Set the master fader level in dB (between -Infinity and 10)
conn.master.changeFaderLevelDB(dbValue) Change the master fader level relatively by adding a given value (in dB)
conn.master.fadeTo(value, fadeTime) Fade master to value (between 0 and 1)
conn.master.fadeToDB(value, fadeTime) Fade master to dB value (between -Infinity and 10)
conn.master.pan(value) Set the master pan (between 0 and 1)
conn.master.dim() Dim master
conn.master.undim() Undim master
conn.master.toggleDim() Toggle master dim
conn.master.setDim(value) Set master dim (0 or 1)
conn.master.faderLevel$ Get master fader level (between 0 and 1)
conn.master.faderLevelDB$ Get master fader level in dB (between -Infinity and 10)
conn.master.pan$ Get master pan value (between 0 and 1)
conn.master.dim$ Get master dim status (0 or 1)

Generic channel operations

These operations apply for any sort of channel like MasterChannel, FxChannel or AuxChannel.

Call Description
setFaderLevel(value) Set fader level (between 0 and 1)
setFaderLevelDB(dbValue) Set fader level in dB (between -Infinity and 10)
changeFaderLevelDB(dbValue) Change fader level relatively by adding a given value (in dB)
fadeTo(value, fadeTime) Fade channel to value (between 0 and 1)
fadeToDB(value, fadeTime) Fade channel to dB value (between -Infinity and 10)
setMute(value) Set mute for channel (0 or 1)
mute() Mute channel
unmute() Unmute channel
toggleMute() Toggle mute status
faderLevel$ Get fader level (between 0 and 1)
faderLevelDB$ Get fader level in dB (between -Infinity and 10)
mute$ Get mute status (0 or 1)

Master bus

Get access to a MasterChannel object first:

Call Description
conn.master.input(2) Input 2 on master bus
conn.master.line(1) Line Input 1 on master bus
conn.master.player(1) Player channel 1 on master bus
conn.master.aux(2) AUX channel 2 on master bus
conn.master.fx(3) FX channel 3 on master bus
conn.master.sub(3) Sub group 3 on master bus
conn.master.vca(4) VCA 4 on master bus

The MasterChannel exposes the following operations:

Call on master channel Description
all generic channel operations
pan(value) Set pan for channel (between 0 and 1)
setSolo(value) Set solo for channel (0 or 1)
solo() Enable solo
unsolo() Disable solo
toggleSolo() Toggle solo status
solo$ Get solo status (0 or 1)
pan$ Get pan value (between 0 and 1)

AUX buses

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

Call Description
conn.aux(3).input(2) Input 2 on AUX bus 3
conn.aux(3).line(1) Line Input 1 on AUX bus 3
conn.aux(3).player(1) Player channel 1 on AUX bus 3
conn.aux(3).fx(3) FX channel 3 on AUX bus 3

An AuxChannel supports the following operations:

Call on AUX channel Description
all generic channel operations
pan(value) Set pan for channel (between 0 and 1). Not possible for mono AUX!
pre() Set channel to PRE
post() Set channel to POST
togglePost() Toggle PRE/POST status
setPost(value) Set POST (1) or PRE (0)
preProc() Set channel to PRE PROC
postProc() Set channel to POST PROC
setPostProc(value) Set POST PROC (1) or PRE PROC (0)
post$ Get POST status (0 for PRE, 1 for POST)
pan$ Get pan value (between 0 and 1)

FX buses

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

Call Description
conn.fx(2).input(2) Input 2 on FX bus 2
conn.fx(2).line(1) Line Input 1 on FX bus 2
conn.fx(2).player(1) Player channel 1 on FX bus 2
conn.fx(2).sub(3) Sub group 3 on FX bus 2

An FxChannel supports the following operations:

Call on FX channel Description
all generic channel operations
pre() Set channel to PRE
post() Set channel to POST
setPost(value) Set POST (1) or PRE (0)
post$ Get POST status (0 for PRE, 1 for POST)

Hardware Channels (Phantom Power)

A HwChannel represents a hardware input on the mixer. At the moment, hardware channels can only be used to switch the phantom power for an input.

Since hardware inputs can be patched to different channels, 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).

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

Call on HwChannel Description
phantomOn() Switch ON phantom power
phantomOff() Switch OFF phantom power
togglePhantom() Toggle phantom power status
setPhantom(value) Set phantom power status (0 or 1)
phantom$ Get phantom power status (0 or 1)

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:

Call Description
conn.volume.solo SOLO bus
conn.volume.headphone(1) Headphone 1 Volume
conn.volume.headphone(2) Headphone 2 Volume

A VolumeBus supports the following operations (which are quite the same as for all other fadeable channels):

Call Description
setFaderLevel(value) Set fader level (between 0 and 1)
setFaderLevelDB(dbValue) Set fader level in dB (between -Infinity and 10)
changeFaderLevelDB(dbValue) Change fader level relatively by adding a given value (in dB)
fadeTo(value, fadeTime) Fade channel to value (between 0 and 1)
fadeToDB(value, fadeTime) Fade channel to dB value (between -Infinity and 10)
faderLevel$ Get fader level (between 0 and 1)
faderLevelDB$ Get fader level in dB (between -Infinity and 10)

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:

Call Description
conn.muteGroup(1) Mute Group 1
conn.muteGroup(2) Mute Group 2
conn.muteGroup('fx') Group for "MUTE FX"
conn.muteGroup('all') Group for "MUTE ALL"

MuteGroup supports the following operations:

Call on MuteGroup Description
state$ Get MUTE status (0 or 1)
mute() Mute the group
unmute() Unmute the group
toggle() Toggle mute group

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.

Media Player

Call Description
conn.player.state$ Current state (playing, stopped, paused) as a value of the PlayerState enum
conn.player.playlist$ Current playlist name
conn.player.track$ Current track name
conn.player.length$ Current track length in seconds
conn.player.elapsedTime$ Elapsed time of current track in seconds
conn.player.remainingTime$ Remaining time of current track in seconds
conn.player.shuffle$ Shuffle setting (0 or 1)
conn.player.play() Play
conn.player.pause() Pause
conn.player.stop() Stop
conn.player.next() Next track
conn.player.prev() Previous track
conn.player.loadPlaylist(playlist) Load a playlist by name
conn.player.loadTrack(track, playlist) Load a track from a given playlist
conn.player.setShuffle(value) Set player shuffle setting (0 or 1)
conn.player.toggleShuffle() Toggle player shuffle setting
conn.player.setPlayMode(value) Set player mode like manual or auto. Values are rather internal, please use convenience functions below.
conn.player.setManual() Enable manual mode
conn.player.setAuto() Enable automatic mode

2-Track USB Recorder

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

Call Description
conn.recorderDualTrack.recording$ Recording state (0 or 1)
conn.recorderDualTrack.busy$ Recording busy state (0 or 1)
conn.recorderDualTrack.recordToggle() Toggle recording

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.

Call Description
conn.shows.loadShow(showName) Load a show by its name
conn.shows.loadSnapshot(showName, snapshotName) Load a snapshot in a show by its name
conn.shows.loadCue(showName, cueName) Load a cue in a show by its name

Transitions

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

Parameter Description
targetValue Value to fade to. The method fadeTo takes a linear value between 0 and 1, the fadeToDB method takes the value in dB between -Infinity and 10.
fadeTime Fade time in milliseconds (ms)
easing optional: easing characteristic. This needs to be an entry of the Easings enum, see below. Defaults to linear (= no easing).
fps optional: frames/ticks per second, defaults to 25. Usually, you don't need to change this.
// 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:

Links Action Result
CH 3/4 MUTE CH 3 MUTE CH 3/4
AUX 1/2 Fader level change CH 5 on AUX 1 Fader level change CH 5 on AUX 1/2
CH 3/4 and AUX 1/2 MUTE CH 3 on AUX 1 MUTE CH 3/4 on AUX 1/2

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

Retrieving raw messages or 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

Please prefer the human-readable interface over reading the raw state! 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 are not checked or sanitized in any way! Be sure to call the functions with valid values only.

License

MIT