Wrapper for the Behringer X-Touch control surface over MIDI. Currently supports all features except the scribble strips. X-Touch needs to be in Mackie Control over USB.
Simple use example, this will initialize the controller and make the 'SCRUB' button blink when it is pressed:
var xt = require('jw-xtouch');
xt.on('action', (action) => {
if (action.name === 'SCRUB' &&
action.state === 'up') {
xt.setButtonLight('SCRUB', 'blink');
}
});
xt.start();
There are two intended ways of working with the X-Touch:
You can use both methods simultaneously. If you handle the same control both ways both things will happen. In other words the controlMap does not stop the emitter from firing. So for example if you want to use the controlMap for everything but the faders and use the emitter to set the faders that is perfectly reasonable, though as you'll see from the below examples you can actually use the controlMap to pass all the faders to your own function with a similar amount of code as would be needed to use the emitter. Feel free to mix and match as you see fit.
Here is an example written in both ways that will illuminate several buttons after they are pressed:
//Emitter mode:
xt.on('action', (action) => {
if (action.control === 'button') {
if (action.state === 'up') {
if (action.name === 'SCRUB') { xt.setButtonLight('SCRUB', 'on'); }
else if (action.name === 'FLIP') { xt.setButtonLight('FLIP', 'on'); }
else if (action.name === 'MARKER') { xt.setButtonLight('MARKER', 'on'); }
else if (action.name === 'NUDGE') { xt.setButtonLight('NUDGE', 'on'); }
}
}
});
//vs controlMap mode:
xt.controlMap({
'button': {
'up': {
'SCRUB': function() { xt.setButtonLight('SCRUB', 'on'); },
'FLIP': function() { xt.setButtonLight('FLIP', 'on'); },
'MARKER': function() { xt.setButtonLight('MARKER', 'on'); },
'NUDGE': function() { xt.setButtonLight('NUDGE', 'on'); },
}
}
});
Either method is fine for simple and similar actions, but when you want to do different things with different buttons emitter mode starts to become unwieldy. In this next example we are going to add only one extra button behavior and one knob behavior, but you can start to see how complex it starts to get using the emitter mode:
//Emitter mode:
xt.on('action', (action) => {
if (action.control === 'button') {
if (action.state === 'up') {
if (action.name === 'SCRUB') { xt.setButtonLight('SCRUB', 'on'); }
else if (action.name === 'FLIP') { xt.setButtonLight('FLIP', 'on'); }
else if (action.name === 'MARKER') { xt.setButtonLight('MARKER', 'on'); }
else if (action.name === 'NUDGE') { xt.setButtonLight('NUDGE', 'on'); }
} else if (action.state === 'down' && action.name === 'SCRUB') {
xt.setButtonLight('SCRUB', 'blink');
}
} else if (action.control == 'knob') {
if (action.name === 'CH1') {
if (action.state === 'right' ) { myPanVar += 1; }
else { myPanVar -=1; }
}
}
});
//vs controlMap mode:
xt.controlMap({
'button': {
'up': {
'SCRUB': function() { xt.setButtonLight('SCRUB', 'on'); },
'FLIP': function() { xt.setButtonLight('FLIP', 'on'); },
'MARKER': function() { xt.setButtonLight('MARKER', 'on'); },
'NUDGE': function() { xt.setButtonLight('NUDGE', 'on'); },
},
'down': {
'SCRUB': function() { xt.setButtonLight('SCRUB', 'blink'); }
}
},
'knob': {
'CH1': {
'right': { myPanVar += 1; },
'left': { myPanVar -=1; }
}
}
});
As you can see with this small example that only used 4 buttons and 1 knob how much simpler and more readable the controlMap method is. Don't forget: the X-Touch has over 90 buttons, 8 knobs, 9 faders and a jog/shuttle wheel, imagine how complex and unreadable your nested conditionals will become!
You can use various structures to organize the controlMap to set it up in the most readable way for your needs. The software will find your function regardless. Ex:
xt.controlMap({
button: {
//first by the name, then the state
//useful when each control does multiple things
'SCRUB': {
'down': function() { xt.setButtonLight('SCRUB', 'on'); }
'up': function() { xt.setButtonLight('SCRUB', 'off'); }
},
//now by the state, then the name
//useful when you only want to respond to one state
'up': {
'SHIFT': function() { doMyShiftFunc(); },
'OPTION': function() { doMyOptionFunc(); }
}
},
//now just by the type and the name, passing the state to the function
//this is basically required for faders since they emit 100s of different states
fader: {
'CH1': function() { updateLeftSpeaker(state); },
'CH2': function() { updateRightSpeaker(state); },
}
//now just by the control type, passing the name and the state
//useful when you want to take care of everything inside your own function
knob: function() { updatePan(name, state); }
});
In fact even if you want to handle 100% of the controls inside your own function you can still use the controlMap. While this may be more verbose, it does allow for different modes (see below)
//emitter mode:
xt.on('action', (action) => {
processAction(action);
});
//controlMap mode:
xt.controlMap({
'button': function() { processButtons(name, state); },
'knob': function() { processKnobs(name, state); },
'fader': function() { processFaders(name, state); },
'jog/shuttle': function() { processJog(name, state); }
});
The other advantage of the controlMap method is that there is built-in support for different modes, so for example if we wanted the SCRUB and FLIP buttons to blink only while in 'edit' mode but have the same behavior as the other buttons otherwise we can do it like this:
xt.controlMap({
'button': {
'up': {
'SCRUB': function() { xt.setButtonLight('SCRUB', 'on'); },
'FLIP': function() { xt.setButtonLight('FLIP', 'on'); },
'MARKER': function() { xt.setButtonLight('MARKER', 'on'); },
'NUDGE': function() { xt.setButtonLight('NUDGE', 'on'); },
}
}
});
xt.modeMap({
'edit': { //this is the mode
'button': {
'up': {
'SCRUB': function() { xt.setButtonLight('SCRUB', 'blink'); },
'FLIP': function() { xt.setButtonLight('FLIP', 'blink'); },
}
}
}
});
xt.setMode('edit');
The software will check the modeMap before the control map and use that action if one is found.
There are also a few 'convenience' functions that create virtual controls:
When you assign buttons and knobs to toggles/groups/knob modes they no longer emit their standard actions, instead they will emit what is appropriate for the virtual control. For toggles and groups their type also becomes 'toggle' or 'group'. So for toggles they emit 'activate'/'deactivate', for groups they emit the name of the button pressed and for knob modes they emit various numbers representing their value. See detailed information below.
Naming: CH1 - CH8, MAIN
States: touch/release/a number representing the value of the fader
Naming: CH1 - CH8
States: up/down/left/right/a number representing the value of the knob based on its mode (right is clockwise)
Naming:
With some exceptions the name of the button is exactly what is printed under the button on the X-Touch. So for example the buttons in the "Encoder Assign" section are: 'TRACK', 'PAN/SURROUND', 'EQ', 'SEND', 'PLUG-IN', 'INST'. If the button text has a space or a newline then the button name will also have a space: 'GLOBAL VIEW', 'MIDI TRACKS', etc.
Exceptions:
States:
up/down
Note that the control is type jog/shuttle and it's name is JOG/SHUTTLE for case consistency with other controls/names
States:
right/left
Naming: You can use the labels on the top or bottom, so the second display section can be referred to as either 'HOURS' or 'BARS' for example.
{
control: 'button/knob/fader',
name: 'the name of the control',
state: 'up/down/left/right' || 'value{number}'
}
NOTES: Floating point numbers do not use up a display slot, so 4.7 will only take up 2 slots. If you send an array you have full control of what goes in each space. So if you send ['A','OFF,'B] it will display 'A_B' where the underscore represents a blank. To send a decimal manually do it like this: ['3.',2] which will display '3.2'. To just send a dot/decimal send it as a string: '.' Here is an example where the individual elements are separated by | in the output comments
xt.setDisplay('full', 3.2 , true, 1);
//Output: | | | | | | | | |3.|2|
xt.setDisplay('full', '3.2' , false, 1);
//Output: |3.|2| | | | | | | | |
xt.setDisplay('full', [3,'.',2] ,false);
//Output: |3|.|2| | | | | | | | -note the extra space taken up by the .
XT.setDisplay('full', 'foo bar');
//Output: |f|o|o| |b|a|r| | | |
xt.sendRaw([144, 101, 127]);
//Turns the light in the 'SWAP' button on
{
state: 'on/off', //the initial state
blink: true //this toggle should blink when it's pressed
}
setToggle(name, state, noCallback):
Sets the state of an existing toggle
-name{string} - the name of the button
-state{string} - 'on/off'
-noCallback{boolean} - by default setting the state via code will execute the callback (only on change), set this true and the callback wont run.
NOTES: you can set a normal toggle to a blink toggle by sending 'blink' as the state. If the toggle was previously on this isn't considered a change.
addGroup(name, group):
Adds a group, a series of buttons where only one can active at any time.
-group{object} - information about the group
Example:
xt.addGroup('mode',{
members: ['F1','F2','F3'],
activeButton: 'F1'
});
NOTES:
-this will setup the first 3 "F" buttons as a group for changing a hypothetical mode.
-name: the name of the group
-members: the buttons that are part of the group
-activeButton: 'F1' sets F1 active when you declare the group, this is optional.
setGroup(name, button, noCallback):
Sets the state of an existing group
-name{string} - the name of the group to modify
-button{string} - the new button to be active
-noCallback{bool} - if true then the onChange callback wont run
clearDisplay(force): Clears the entire display -force{boolean} by default the display keeps track of what is in each element and only updates them if they change. If force=true then each element will be reset to blank even if it is already blank. This should in theory never be necessary.
removeToggle(name):
Removes an existing toggle
-name{string} - the name of the button to remove the toggle from
removeGroup(name): Removes an existing group -name{string} - the name of the existing group
setFader(fader, value):
Sets the position of a fader based on its mode and resolution
-fader{string} - the name of the fader
-value{number} - the new value/position of the fader
NOTES:
This is not super-accurate and needs improvement. In decibel mode near unity it works fine but if you send -30 in decibel mode and then touch the fader it will probably register that it's at -29 or -31 or something like that. Since it's not that accurate to begin with when you are in position mode it only uses 7-bit precision regardless of how high you set the resolution.
setKnobLight(knob, mode, value, showSideLights): Turns on the lights that ring the knobs. Uses the same names and values from the knob modes. -knob{string} - the name of the knob -mode{string} - the mode of the lights, normal/sequence/level/fill -value{number} - the value associated with the mode -showSideLights{boolean} - if true the leftmost and rightmost lights will also illuminate
setKnobMode(knob, mode, sideLights, value): Set the mode for a knob and it's initial value. When set to a mode the knob's lights change automatically based on their value and they emit appropriate values. -knob{string} - the name of the knob -mode{string} - the mode, see notes for explanation -sideLights{boolean} - if true the leftmost and rightmost lights will also illuminate while the knob is in a mode -value{number} - the initial value
Modes:
clearKnobModes: Resets the knobs to their normal functionality, emitting just left/right/up/down and no lights lighting. To reset a signal knob set its mode to "normal".
setDisplayLight(name, state): Turns on/off/blink the lights in the display area -name{string} - the name of the light SOLO/SMPTE/BEATS -state{string} - the state of the light on/off/blink
setAllDisplayLights(state): Set all the display indicator lights on/off/blink -state{string} - the new state
resetFaders(unity): Moves all fader to either -infinity (-100) or unity (0) regardless of their mode or resolution -unity{boolean} - if true then sets to unity otherwise to -infinity (all the way down)
setFaderMode(fader, mode, resolution):
Set the mode (decibel/position) and resolution of an individual fader
-fader{string} - the name of the fader
-mode{string} - the mode decibel/position
-resolution{number} - the resolution, see notes
NOTES:
In position mode the resolution should be a whole number representing the min-max value the fader will return when it's moved from the bottom to the top. In decibel mode the resolution is a fraction or whole number, such as 0.5 to return half-decibel changes. Decibel mode always returns the values printed on the fader.
As best I can determine the physical faders theoretically output in 14-bit resolution but in practice it's closer to 10 bits (1024) and really only consistently accurate to 7 bits (128). I'd recommend setting the position resolution to 100, 128, 256 or at most 512 (there's no technical reason to use powers of two honestly, 500 or 398 or 7 are all perfectly fine resolution values).
In decibel mode the scale isn't linear, with much more physical space near unity (0) then there is closer to -infinity so if you set the resolution to 0.125 or something very precise like that you will only get those small fractions near unity. I'd recommend not using precision below 0.5 but you may use: 0.1, 0.125, 0.25, 0.5, 1, 5, or 10. If you do use a more precise resolution then 0.5 you wont get each value in sequence (0.125, 0.25. 0.375, etc.) instead it will almost always skip since it isn't really that accurate.
It should also be noted that depending on the mode/resolution the fader may return a higher number then your max. This has to do with the analog nature of the physical fader, so program your solution accordingly.
setSignalLevel(channel, level):
Set the signal level indicator for a channel. By default the X-Touch will only light the signal for a moment and then show it dropping off.
-channel{string} - the channel name
-level{number} - the level, 0-8. 8 will illuminate the clip light until you set the signal to 0.
clearSignalBars(): If you send the max value to a signal bar it will illuminate the "clip" light permanently. This will clear all of those indicators. To clear a single signal use setSignalLevel(channel, 0)
holdSignalLevel(channel, level):
This will hold the signal level for the given value. It does this by sending the signal level several times a second, so it is recommended not to use this for more then one or two channels at a time because it will saturate the midi communication. Quite frankly you probable shouldn't use it at all.
-channel{string} - the channel
-level{number} - the level, 1-8
clearSignalHold(channel): Will stop a signal hold for the given channel -channel{string} - the channel
setAutoButtonLights(shouldAutoLight, buttonNames): Another convenience feature, this will cause the named buttons to illuminate only while they are pressed down. It doesn't change any other behavior. Useful when you just want to let the user know that the button was pressed. It actually leaves the button illuminated for a very short time after it is released to help give better visual feedback. -shouldAutoLight{boolean} - false will clear a previously set light -buttonNames{string} - 'all' will make every button auto-light. May also send a single button name or a list of button names Example:
//make the FLIP button light when pressed
xt.setAutoButtonLight(true, 'FLIP');
//make the "d-pad" next to the jog/shuttle wheel light when pressed
xt.setAutoButtonLight(true, 'UP', 'DOWN', 'LEFT', 'RIGHT', 'ENTER');
showTempMessage(message, delay): Will show a temporary message on the display for a given time. Afterwords the display will show what it did before. Useful when you want to communicate an event to the user. It only uses the contiguous ("full") display elements. -message{string} - the message to display (10 chars) -delay{number} - number of milliseconds to display the message, default=1000
controlMap(map): Used to set or return the control map -map{object} - the map
modeMap(map): Used to set or return the mode map -map{object} - the map
mode(mode): Used to set or return the mode used by the mode map. -mode{string} - the new mode
FAQs
Wrapper for communicating with the Behringer X-Touch via midi
We found that jw-xtouch demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.