This page describes a Unify feature which is both ADVANCED and EXPERIMENTAL. Limited support will be provided. Please do not attempt to follow these instructions unless you are sure you understand them.
The stand-alone Unify app can make use of plain-text files containing instructions for how to interpret MIDI data coming from a specific MIDI controller device. These “MIDI controller files” must be placed in a folder called MIDI Controller Files located in the Unify Content Folder (beside Libraries, Presets, etc.; see Unify's files and folders). You can easily open your Unify Content Folder from within Unify, by clicking the gear icon to open the Settings View, and clicking the “Open…” button.
So-called “plain text” file formats use a standard set of single- or multi-byte codes to represent characters, plus a few basic non-character entities such as the end of a line. This is distinct from “word processing” formats, which tend to be proprietary and specific to one word-processing program, but are able to represent not only characters, but all sorts of display-oriented details like fonts and spacing. Word-processing file formats (even simple ones like Microsoft's Rich Text Format (RTF) have become so common, that many people don't even realize that “plain text” formats still exist, but they do, and they are tremendously important.
On the Macintosh, the built-in TextEdit app can work with either plain-text or RTF. On Windows, the built-in Notepad app is used for plain-text files, while WordPad is used for RTF. A great many third-party text editing apps are available for both platforms; one of the best for Windows is called Notepad++.
The following is an example of a MIDI controller file to set up a KORG nanoKONTROL2 MIDI device to control mix and effect-send levels and MIDI enablement for up to eight layers. We'll look at its various parts individually in the sections below.
# This is a comment, and blank lines are also ignored # Active lines can begin with "cc" or "no". # "cc" lines have a MIDI CC number followed by an OSC control path, # optionally followed by a maximum value, e.g. 0.8 = 80% of full range. # "no" lines have a MIDI note number followed by an OSC control path. # The first non-blank, non-comment line must be the MIDI controller name # or any prefix thereof nanoKONTROL2 # Sliders control mix-levels of 1st 8 layers, up to 80% (0 dB) cc 0 inst/1/mixLevel 0.8 cc 1 inst/2/mixLevel 0.8 cc 2 inst/3/mixLevel 0.8 cc 3 inst/4/mixLevel 0.8 cc 4 inst/5/mixLevel 0.8 cc 5 inst/6/mixLevel 0.8 cc 6 inst/7/mixLevel 0.8 cc 7 inst/8/mixLevel 0.8 # Knobs control AUX1-send levels of 1st 8 layers, up to 80% (0 dB) cc 16 inst/1/auxSend/1 0.8 cc 17 inst/2/auxSend/1 0.8 cc 18 inst/3/auxSend/1 0.8 cc 19 inst/4/auxSend/1 0.8 cc 20 inst/5/auxSend/1 0.8 cc 21 inst/6/auxSend/1 0.8 cc 22 inst/7/auxSend/1 0.8 cc 23 inst/8/auxSend/1 0.8 # "S" buttons toggle the SOLO state of individual layers cc 32 unify/solo/1 cc 33 unify/solo/2 cc 34 unify/solo/3 cc 35 unify/solo/4 cc 36 unify/solo/5 cc 37 unify/solo/6 cc 38 unify/solo/7 cc 39 unify/solo/8 # "M" buttons toggle the MUTE state of individual layers cc 48 unify/mute/1 cc 49 unify/mute/2 cc 50 unify/mute/3 cc 51 unify/mute/4 cc 52 unify/mute/5 cc 53 unify/mute/6 cc 54 unify/mute/7 cc 55 unify/mute/8 # "R" buttons enable/disable individual layers at the MIDI level. # NOTE THIS WILL ONLY WORK IF THE NANOKONTROL 2 IS CORRECTLY SET UP. # IT WILL NOT WORK WITH THE DEFAULT/FACTORY SETUP! cc 64 unify/midiEnable/1 cc 65 unify/midiEnable/2 cc 66 unify/midiEnable/3 cc 67 unify/midiEnable/4 cc 68 unify/midiEnable/5 cc 69 unify/midiEnable/6 cc 70 unify/midiEnable/7 cc 71 unify/midiEnable/8
The first eight lines of the file are comments. As it says in the file, any lines which are blank, or begin with a # symbol, are ignored by Unify, and are only there to provide some documentation of the syntax used for these files.
The ninth line (as indicated, the first non-comment line) is assumed to contain either the full name or some prefix of a MIDI controller device. (Device names are listed in the Active MIDI inputs are of the Audio/MIDI settings view (see this page for details.) In this case, the full name
nanoKONTROL2 1 SLIDER/KNOB has been shortened to the prefix
It's critical that the controller name (or prefix) match the name of the MIDI controller as it appears on your system. Different device-drivers may assign slightly different names for the same device, so you have to check carefully, and edit the file accordingly.
The KORG nanoKONTROL2 features eight vertical sliders and eight rotary knobs, each of which generates MIDI CC messages using a different CC number. This example uses the nanoKONTROL2's default CC assignments. If you have used the KORG Kontrol Editor app to change these assignments, you will have to edit the CC numbers in the file to match.
MIDI continuous controllers (CC's) send out messages with associated values between 0 and 127. Unify interprets the value range 0-127 as a fraction 0.0-1.0, and each of the lines in these sections indicates what it does with these fractional CC values. Let's examine the first line:
cc 0 inst/1/mixLevel 0.8
cc 0 part identifies MIDI CC#0, which is sent by the nanoKONTROL2's leftmost slider by default. The
0.8 indicates that the fractional value will be scaled to the range 0.0-0.8 before being used. The rest of the line is a parameter path, the same as you would use for parameters linked to Unify's Macro knobs.
So this first line indicates that when you move the first of the nanoKONTROL2's sliders, the MIDI CC#0 message which results is interpreted as a value between 0.0 (slider all the way down) and 0.8 (all the way up), which is then assigned to the linked parameter 'inst/1/mixLevel'. As a result, the mix-level control for the INST1 layer will move, but only up as high as 80% (0.8) of the maximum, which corresponds to exactly 0 dB. (If you were to remove the
0.8 scale factor, or change it to
1.0, the level would go all the way to +10 dB.)
Because Unify safely ignores “invalid” linked parameter-paths, this mapping of eight sliders will work just fine even for patches where you have fewer than eight INST layers. Any parameter paths which don't correspond to actual layers simply won't do anything.
The “knobs” section which follows is structured the same way as the “sliders” section, but
This could be useful in a typical live-performance setup, where you have a single AUX effects layer, and would like the ability to define the effect send-level for each INST layer in real-time. If you were doing straight-ahead mixing, you might want the knobs to control pan-positions instead; the first line might instead read:
cc 16 inst/1/panPos
Note there is no scale factor, because the panPos parameters naturally accept values from 0.0 (hard left) through 0.5 (balanced) to 1.0 (hard right).
You might have noticed that the comments at the top of this file mention “OSC parameter paths” rather than “linked parameter paths”. The parameter-paths available for linking to Macro knobs are just a subset of the total set of parameters available for real-time control in Unify. The path syntax used is borrowed from a network remote-control standard called Open Sound Control (OSC).
The final three sections of this MIDI controller file use some of these extra parameters to control whether or not each INST layer (up to INST8) will listen to MIDI from any controller, or will ignore it. Each of these parameters is binary in nature, treating any CC value less than 64 as “off” and any higher values as “on”.
unify/solo/1refers to the INST1 layer, and when it receives a CC value of 64 or higher, it will toggle the “solo” state of INST1.
unify/mute/1refers to the INST1 layer, and when it receives a CC value of 64 or higher, it will toggle the “mute” state of INST1.
unify/midiEnable/1will enable MIDI input to INST1 when it receives a CC value of 64 or higher, and disable it when it receives a CC value less than 63.
These new parameters are still experimental and should not be considered “ideal” in any way, nor should they be treated as final. We expect to refine the list of MIDI-related OSC parameters over time, and user comments/suggestions are welcome.
To set up a Korg nanoKontrol 2 controller for controlling the MIDI enable/disable state of layers using the “R” buttons, you will need to use the Korg Kontrol Editor app. USE AT YOUR OWN RISK. PlugInGuru, Inc. is not responsible for any mistakes you make.
Note that you can always reset your nanoKontrol 2 to its original factory settings as follows:
To set up your nanoKontrol 2 for use with the MIDI Controller File shown above:
NOTE When Unify loads a patch, all INST layers will normally be enabled (not darkened and responsive to MIDI), but some of the “R” buttons on your nanoKontrol 2 may not be toggled “on” (lit red). Press any that are off, to toggle them on.
At this time, Unify does not do two-way communication with MIDI controllers, so it has no way of knowing that the state of INST layers may not match the on/off state of your nanoKontrol 2's “R” buttons. You may simply need to press the buttons one or more times, to bring their states into sync with Unify's layers.
Here is an example (minus the initial comments) of a MIDI control file for use with a keyboard controller such as one of the Native Instruments Komplete Kontrol series.
KOMPLETE KONTROL # If a "convChannel" line is included, convert MIDI channel as indicated convChannel 12 # knobs page 1 cc 14 macro/1 cc 15 macro/2 cc 16 macro/3 cc 17 macro/4 cc 18 macro/5 cc 19 macro/6 cc 20 macro/7 cc 21 macro/8 # knobs page 2 cc 22 midi/cc/18 cc 23 midi/cc/19 # A1 is panic no 21 midi/panic
The Komplete Kontrol M32 keyboard, for example, enumerates on a Windows system as “KOMPLETE KONTROL M32 MIDI”, so in this case we simply use the prefix
The convChannel line is optional. It allows you to specify a MIDI channel which ALL incoming messages from the specific controller are to be converted to on their way into Unify. If you have two or more keyboards, for example, you could create a MIDI controller file for each, putting one on MIDI channel 1, another on MIDI channel 2, etc., regardless of what MIDI channel the device is actually sending on. This can often be much easier than actually setting the hardware unit to a specific MIDI channel.
The Komplete Kontrol series all provide eight rotary encoder knobs, and a pair of “page buttons” to set the CC-assignments of all eight as a group. By default, page 1 assigns CC numbers 14 through 21, page 2 is 22 through 29, etc. In this example, the first page of eight knobs is assigned to control the first eight of Unify's Macro knobs.
macro/*OSC paths control the Macro parameters directly.
You may have noticed that the comments in the first example mentioned “no” lines. Lines beginning with “no” (Note On) and not ending with a number can be used to specify that certain MIDI note-on messages be used to activate binary OSC parameters. In this example, we specify that pressing the A1 key (MIDI note 21, lowest note on a standard 88-key keyboard) should trigger the “MIDI Panic” or “stop all notes” function, instead of triggering a note. This can be quite useful for pianists, who rarely actually play the A1 key, and may be using a simple digital piano which has no extra controls which could be used to generate MIDI CC messages.
The next example illustrates “no” lines with a numeric value at the end, support for which was added in Unify v1.6.2.
The Akai MPD218 is a USB MIDI controller featuring sixteen drum-pads (each of which sends a MIDI note-on with a distinct note-number) and six knobs (each of which sends MIDI CC data with a distinct CC number). The following MIDI Controller file illustrates some possible techniques for using this device and other controllers like it.
# First non-blank, non-comment line is the MIDI controller name (or a prefix thereof) MPD218 # Knobs bank A cc 3 macro/1 cc 9 macro/2 cc 12 macro/3 cc 13 macro/4 cc 14 macro/5 cc 15 macro/6 # Knobs bank B cc 16 macro/7 cc 17 macro/8 cc 18 macro/9 cc 19 macro/10 cc 20 macro/11 cc 21 macro/12 # Knobs bank C cc 22 macro/13 cc 23 macro/14 cc 24 macro/15 cc 25 macro/16 cc 26 macro/17 cc 27 macro/18 # Pads bank A: first three pads on top row no 48 macro/8 0.0 no 49 macro/8 0.35 no 50 macro/8 0.7 # Pads bank A: first three pads on second-from-top row no 44 inst/1/midiToggle no 45 inst/2/midiToggle no 46 inst/3/midiToggle
The MPD218 has six physical knobs, but also has a button allowing you to select any of three different sets of CC-number assignments for them (called “banks”), so there are actually eighteen “logical” knobs. Akai provides an editor program which allows you to see all these assignments, and edit them if you wish. The file above was made by simply using the editor to check the default CC-number assignments for each of banks A, B, and C.
The knobs are set up to control the first eighteen of Unify's Macro Knobs. Note that the special parameter-paths starting with “macro” will always work to refer to Unify's macro-knobs, even if these have been given custom names in Unify v1.6.0 and later.
The MPD2018 also supports three banks of MIDI-command assignments for the sixteen physical pads, yielding a total of 48 logical pads, but as this is only a partial tutorial example, there are only six “no” lines, all for pad bank A. These are divided into two groups of three lines.
The first three “no” lines are for the first three pads along the top row of the MPD218 (designated 13, 14, and 15) on the front panel). All three pads are set up to send a specific fractional value (range 0.0 to 1.0) to Unify's Macro8 knob, setting it to a specific position.
These values were experimentally chosen, to correspond to three different Patch Variations defined using new features added in Unify 1.6.0 and refined in later versions. See the Patch Variations page for more details. The upshot of all this is that tapping pad 13 activates the INST1 layer of the patch, pad 14 switches to the INST2 layer only, and pad 15 to the INST3 layer.
The next three “no” lines are for pads 9, 10, and 11, on the second row of the MPD218's pads array. These allow toggling (switching on and off) the MIDI-enable state of the INST1, INST2, and INST3 layers individually. Tapping these buttons thus allows you to switch each of these layers on and off in any combination, separately from the three specific combinations set up by the Macro8 knob.
These last three “no” lines don't have a numeric value at the end, so Unify internally uses the default value 1.0, which is ideal for triggering binary and toggle-type parameters. This matches the behavior of “no” lines in Unify versions prior to v1.6.2, when support for numeric values was added.
The example refers to a drum-pad controller, but you can do the same thing using any MIDI keyboard in a live-performance setup.
When the Unify stand-alone app (NOT the plug-ins) starts up, it looks for a MIDI Controller Files folder at the root of the Unify Content folder, and if such a folder exists, Unify scans its contents and attempts to interpret any .txt files as controller files, according to the syntax described above, building up a table of “rules” in memory according to the contents of each file.
When the Unify stand-alone app receives MIDI input, each message is tagged with the name of the MIDI controller device which generated it. It checks for a match with any of the controller name prefixes specified in the MIDI controller files.
The suppression of MIDI messages which match controller-file rules has two important benefits: