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.
This version of the page is valid for Unify v1.4.x only.
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 nanoKONTROL2
.
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
The 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/1
refers 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/1
refers 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/1
will 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 highly 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 KOMPLETE KONTROL
.
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) 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.
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: