Numa X Piano with MIDI Controller Map

WORK IN PROGRESS

The algrotihm below is implemented and tested in a gig. It works 😀

I need a week or two to:

Get the Bome implementation documented and published
Clean up the node.js version and try to address latency
Clean up this page and get the "Download and Use It" part to the top

What Numa X Piano does in MIDI Controller mode:

Many of the knobs send different CC numbers depending upon the zone selected (1-4) and/or the parameter number selected (1-3)
Changing the zone, muting an instrument and other action will cause unexpected jumps in the knob value
Causes headaches

The MIDI mapper on this page works on the principle that live performance needs predictable behaviour with tight synchronisation to the host’s performance software. I use Gig Performance and expect it would apply to other tools. The solution…

Numa X operating as a MIDI Controller
Mapping software between the piano and the performance tool that makes it look like each knob/button/action corresponds to a single MIDI CC number
The performance software and Numa X remain synchronised even with changes in songs and patches
It should work reliably and with minimal thought and attention when performing!

[If there’s a computer issue I can quickly switch over to Numa’s built-in sounds which are OK.]

Point 2 is the key. In controller mode, the Numa X knobs / buttons send different CC numbers depending upon the current Zone selection and the choice parameter select for FX A, FX B, delay and reverb.

Basic Rig

Fig 1: Basic Rig

The basic rig used for development and testing:

Studiologic Numa X Piano 73 (73 keys) as a MIDI controller
Sustain and expression pedals
Mac running MacOS Sequoia 15.2 (Mac Mini M4 with 24gb memory, 2TB SSD)
Gig Performer 5.x as the Performance Tool (variety of plugin instruments and effects)
Studiologic Numa X Piano 73 (73 keys) also used as the USB audio device for output

Enable MIDI Controller Mode

The “Local Control” settings puts the Numa X Piano into a MIDI Controller Mode. (There are other settings but they are not needed for the simplest setup.)

Click the gear button (⚙️) to open Numa’s Global Settings
Turn “Local Control” to “OFF”

Fig 2: Global Setting for Local Control

MIDI Controllers (knobs)

Most of the buttons and knobs on the control surface trigger MIDI events. I focussed on 2 of the 5 panels (short explanation below).

Fig 3: MIDI Controller knobs and buttons

Instrument Knobs

These 4 knobs noramlly control the 4 layers of the current Program. They each have press and rotate capability. The press control is for enable / disable of each (i.e. mute / unmute). The rotate control normally sets the volume of each zone.

Note 1: for reasons that will become clear, these 4 knobs don’t need mapping. It’s useful to keep them in as a comparison for what we want to achieve from all the knobs.

Note 2: The Select / Zoom buttons below do not generate MIDI but we’ll see below that they affect the MIDI generated by other controls.

Effects Knobs (top 4)

There a 8 knobs (2 rows of 4 knobs) that normally control the audio effects for the current Program and are labelled FX A, FX-B, Delay and Reverb. Each has press and rotate capability but each sends different MIDI according to the current Zone with focus (4 zones means 4 different MIDI CC for each press and rotate control).

Note: the press to enable/disable Delay and Reverb has different MIDI CC behavior. Detail below.

For the “What I need” setup, we want a single MIDI CC number for both press and rotate on these 4 knobs effectively ignoring the Zone.

Effects Parameters Knobs (bottom 4)

For each of FX A, FX-B, Delay and Reverb there is a parameter knob. Pressing these knobs does NOT send a MIDI CC value but instead changes the state of the knob on the Numa X to control the next of 3 parameters.

Rotating these 4 knobs send a MIDI CC. The CC number is different for each of the 4 Zones when selected AND different for each parameter. That’s 12 different MIDI CC numbers - I want one.

Assignable knob

Rotating this knob sends MIDI CC but also changes the USB audio volume. These 2 controls can’t be distinguished so I choose not to use the Assignable knob to avoid volume issues.

Main dial and Sound Bank / Favourites

These controls send MIDI message like Program Change (PC). Because of the risk of side effects, I don’t use them for MIDI control.

Other Controls

We don’t need to do anything with these because they are not affected by the state of the Numa X. I list them for completeness and because they need to be tested to ensure the mapper passes them through and doesn’t break anything.

The piano keybed: note on/off, channel pressure
The modulation and XY controller (dedicated CC numbers)
The pedal and expression controllers (if connected)
MIDI IN

The Problem

So I’m playing a song with a mix of rock organ and piano. I’m using plugins in Gig Performer to provide those sounds. I have the Zone 1 knob rotation controlling the volume of the organ and the Zone 1 press for mute/unmute. It’s the same for the piano except it’s Zone 2. I have expression pedal and sustain pedal for drive and sustain.

All is good as I play the organ.

But I’m also using FX A knob to control effects through Gig Performer. When Zone 1 is selected the Numa sends FX A rotation as MIDI CC 68 (x44). I switch from organ to piano by pressing Zone 1 (to mute) and Zone 2 (to unmute). Now, FX A rotation is sent as MIDI CC 73 (x49).

Worse, it has a different value which causes my effects to go crazy.

Worse, when I switch songs or patches on the computer it sends a MIDI CC to 68 but that doesn’t affevct 73, 78 or 83 which are CC numbers for Zone 2, 3 and 4.

Worse, if I use any of the FX parameter knob there are 12 different CC values which can all be different.

The Solution - The MIDI Mapper

I’ve implemented the MIDI Mapper for Numa X Piano a few ways. The algorithm is the same for all.

Node.js / Javascript: Functional but had latency issues that affected the notes (but didn’t matter for the controllers)
Bome MIDI Translator Pro: paid software which a free trial. This is what I am using at time of writing
MIDI Mapping in Gig Performer: I could map messages coming from the keyboard to GP but the mapping of return messages was complex and messy. (I might try again another day.)

#	Requirement	What the mapper does	Detail
1	The performance software will not need to deal with the Zones and Parameter variation.	Map all MIDI variations from a knob press or rotation to a single MIDI CC	I use the MIDI CC for Zone 1 & param 1 for consistency
2	Changes to a knob’s value (press or rotate) will be updated for all zone & parameter variation of that same knob	A change to press or rotation on a knob will be instantly be passed back for all Zone and Parameter variations of that same knob	-
3	MIDI CC from the performance software to the Numa must affect all variations	A MIDI CC must be mapped to all zone and parameter variations at the same time	-

Fig 4: Logical Design

(my) MIDI Specification for NUMA X Piano in MIDI Controller Mode

This is not the official Numa X MIDI specification. We’re interested in the subset of the Control Channel in the section on “CC table Common Channel” starting from page 4 (it’s not obviuos). The first 5 columns in the table below match the CC numbers from the Numa X MIDI specification.

Group	Controller	Action	CC Number (Group)	CC Value	CC Number (Single)	CC Value Map	Note
Assignable	Assignable	Rotate	3	0 - 127	pass	pass
		Press	-	-	-	-	(a)
Instrument Knobs	Zone 1	Rotate	33	0 - 127	pass	pass
	Zone 2	Rotate	34	0 - 127	pass	pass
	Zone 3	Rotate	35	0 - 127	pass	pass
	Zone 4	Rotate	36	0 - 127	pass	pass
	Zone 1	Press	12	Off=0 On=1 Mute=2	pass	On=127 Off/Mute=0	(b, c)
	Zone 2	Press	13	Off=0 On=1 Mute=2	pass	On=127 Off/Mute=0	(b, c)
	Zone 3	Press	14	Off=0 On=1 Mute=2	pass	On=127 Off/Mute=0	(b, c)
	Zone 4	Press	15	Off=0 On=1 Mute=2	pass	On=127 Off/Mute=0	(b, c)
FX Knobs (top row)	FX A	Rotate	68, 73, 78, 83	0 - 127	68	pass
	FX B	Rotate	100, 105, 110, 115	0 - 127	100	pass
	Delay	Rotate	24, 25, 26, 27	0 - 127	24	pass
	Reverb	Rotate	28, 29, 30, 31	0 - 127	28	pass
	FX A	Press	69, 74, 79, 84	On > 0 Off=0	69	On=127 Off=0	(d)
	FX B	Press	101, 106, 111, 116	On > 0 Off=0	101	On=127 Off=0	(d)
	Delay	Press	-	-	-	-	(a)
	Reverb	Press	-	-	-	-	(a)
FX Knobs (parameter row)	FX A Param	Rotate	70, 75, 80, 85, 71, 76, 81, 86, 72, 77, 82, 87	0 - 127	70	pass
	FX B	Rotate	102, 107, 112, 117, 103, 108, 113, 118, 104, 109, 114, 119	0 - 127	102	pass
	Delay	Rotate	57, 58, 59	0 - 127	57	pass
	Reverb	Rotate	61, 62, 63	0 - 127	61	pass
	FX A	Press	-	-	-	-	(a)
	FX B	Press	-	-	-	-	(a)
	Delay	Press	-	-	-	-	(a)
	Reverb	Press	-	-	-	-	(a)

Table Notes

(a) No MIDI CC message for pressing this knob.

(b) Most MIDI on/off values are On=127 (or >= 64) and Off=0 (or <64) but Numa X does On=1 and Off=2. If, however, you are mapping to a mute or bypass contoller in the performance tool then the value needs to be inverted. For CC messages back to the Numa X the CC values must be exactly 2 or 1.

(c) Long press sets the zone to solo (value=2) with the other zones off (value=1). That’s 4 MIDI control messages in quick sequence.

(d) TODO - I need to confirm that the interpretation should be Off=0 and On>0 where the value is the current setting for the FX (e.g. FX A Overdrive=49). In MIDI Controller mode we need On=127 and Off=0.

MIDI Mapping for messages from Numa X

This sequence shows the MIDI messages fired by the Mapper in response to a CC event from Numa X.

Receive a MIDI message
If it is a CC message in one of the groups from table then
1. Send forward a CC message as-if the Numa X had Zone 1 selected and Parameter 1 for all effects (first in group by design)
  1. CC channel unchanged
  2. CC number is the first CC number in the group
  3. See below for the CC value (usually unchanged)
2. For each CC number in the group (except the CC number received) send a CC message back to the Numa X with
  1. CC channel unchanged
  2. CC number from the group (except the CC number received)
  3. CC valie unchanged
Otherwise, for all other MIDI messages (including CC numbers not shown in the table) pass them forward without change.

Fig 5: Sequence Diagram for MIDI Messages from Numa X Piano

MIDI Mapping for messages from Performance Tool

Receive a MIDI message
If it is a CC message in one of the groups from table then for every CC number in the group send a CC message to the Numa X with:
1. CC channel unchanged
2. CC number from the group
3. CC valie unchanged
Otherwise, for all other MIDI messages (including CC numbers not shown in the table) pass them on without change.

Fig 6: Sequence Diagram for MIDI Messages from the Performance Tool

Example for FX B Rotation

Say the player turns the FX B Effects level knob…

Fig 5: MIDI Messages for FX B rotation

If the piano has Zone 1 selected, the Numa X will send MIDI CC number 100 (x64). For Zones 2, 3, 4 the MIDI numbers are 105, 110, 115. We need the mapper to

Receive the MIDI CC as 100, 105, 110 or 115 with its value
Send forward that CC value to the performance tool as CC number 100 (x64)
And, send back the value as the other 3 CC numbers from 100, 105, 110 and 115 so that the knob has the same value across all Zones (in case the player changes Zone)

Implementation with BOME MIDI Translator Pro

The Bome MIDI Translator Pro is a paid product. I am using it because it is built for this kind of MIDI mapping and performs with low latency.

NOTE: It's working and I've used it in rehearsals. Some minor issues to sort out then publish. Check the `javascript` directory in the numaxpiano-midi-controller for the JS source to convert the algorithm to a BOME script. I need to get the full BOME script finalised.

Implementation with NodeJS / JavaScript

NOTE: This implementation is functional but has noticeable latency on pass-through of MIDI messages making playing keys. It was about 15-20msec but I didn't do proper measurement or determine the specific source of the latency.

A rough measurement with MIDI Monitor showed delays around 20msec (unsatisfactory is above 2-5msaec). It might be possible to interface directly to the Node Task Queue to reduce that latency A task queue is a mechanism that helps in organizing and executing tasks in a prioritized manner. The process.nextTick() could prioritize sending of MIDI messages. This matters most of NoteOn/NoteOff messages but maintain

Notes:

This is a work in progress. The Studiologic doc is sparse so there may be errors. Please submit comments in issues page on the Github project.
The documentation and images is from a NUMA X Piano 73. It is likely that the 88 and 88 HD will be similar but this needs to be confirmed. Unfortunately, I have no idea about the Compact series. Use the issues or submit a pull request if you can help.
This work was done on a Mac. It shouldn’t be that different for Windows or Linux.

Numa X Docs

All the relevant Numa X documentation that I could find is on the Numa X Piano support page including:

Verifying MIDI Messages

Install a MIDI monitor on your computer to verify that the NUMA X Piano is sending MIDI messages.

For Mac, I use MIDI Monitor. There are many alternatives.

First, verify connectivity by playing some notes on the keyboard. You should see Note On/Off MIDI messages in the monitor. If not, check your cabling and MIDI settings.

Now, turn the Zone 1 knob. You should see CC messages in the monitor. Specifically, the CC number should match the Knob 1 CC setting in the Program settings for Zone 1 (it’s CC 22 in the image above). If not, check that the configuration is completed.

Mapper MIDI for Numa X Piano Controller

Better way to use a Numa X Piano as a MIDI controller