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++.

• On the Mac, you can use TextEdit to edit MIDI controller files, but you MUST set it to plain-text mode.
• On Windows, DO NOT use WordPad. Use Notepad or Notepad++, or any “programming editor”.
• On any platform, NEVER copy/paste text from outside the editor, unless you are VERY sure of what you are doing. You may end up importing the wrong character-codes, and your file won't work, even though it may look fine.

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.

nanoKontrol mix and enable.txt

# 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

• The CC numbers 16 to 23 are the default assignments for the eight knobs along the top of the nanoKONTROL2.
• The parameter paths have been chosen to control the AUX1 send values for the eight INST layers

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.
  • In its factory-default setup, the Korg nanoKontrol 2 controller outputs a CC value of 127 when an “S” button is pressed, and a CC value of 0 when it is released; this is sufficient for these functions.
• 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.
  • In its factory-default setup, the Korg nanoKontrol 2 controller outputs a CC value of 127 when a “M” button is pressed, and a CC value of 0 when it is released; this is sufficient for these functions.
• 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.
  • The factory-default setup of the Korg nanoKontrol 2 controller is NOT sufficient for these functions.
  • It is necessary to use the Korg Kontrol Editor app to CHANGE the controller configuration, setting all the “R” buttons to Button Behavior = Toggle. A setup file for this purpose is provided below.

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:

1. Close Korg Kontrol Editor (or any other program using the nanoKontrol), if necessary.
2. Disconnect the USB cable from the nanoKontrol 2.
3. Hold down the PREV TRACK, NEXT TRACK, and CYCLE buttons while re-connecting the USB cable from the computer. The transport buttons (except CYCLE) will blink when the factory-set default state has been restored.

To set up your nanoKontrol 2 for use with the MIDI Controller File shown above:

1. Quit Unify (or any other program using the nanoKontrol 2) if already running.
2. Download and unzip this file: nk2_unifymixenable.zip. It unzips to a “scene data” file called NK2_UnifyMixEnable.nktrl2_data.
3. Double-click the NK2_UnifyMixEnable.nktrl2_data; the Korg Kontrol Editor should run automatically. If it does not, run Korg Kontrol Editor manually, and use the File > Open menu item to load the scene-data file.
4. Use the Communication > Write scene data function to upload the scene data to your nanoKontrol 2. This may take a moment; wait until the program indicates that it is done.
5. Quit the Korg Kontrol Editor program.
6. Make sure the nanoKontrol mix and enable.txt file (shown above) is saved into a folder called MIDI Controller Files under the main Unify data folder.
7. Run the Unify stand-alone app, load any patch with several INST layers, and test the “R” buttons to check that they enable/disable layers.

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.txt

  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.

• The macro/* OSC paths control the Macro parameters directly.
• If a Macro knob which is controlled in this direct way happens to have a MIDI CC assignment, turning the knob will send corresponding MIDI CC messages into Unify.
• If the Macro knob does not have any MIDI CC assignment, the knob will turn, and any linked parameters will adjust accordingly, but no MIDI CC messages will be seen by any Unify layers.

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.

Akai MPD218.txt

# 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.

• Tapping pad 13 sets the knob value to 0.0 (all the way to the left)
• Pad 14 sets it to 0.35, about the ten o'clock position, and
• Pad 15 sets it to 0.67, about two o'clock.

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 six “no” lines at the bottom of the MPD218 example file illustrate how Unify v1.6.2 and later allow you to use MIDI note-on events to control things like layer MIDI-enable and Patch Variations.

The example refers to a drum-pad controller, but you can do the same thing using any MIDI keyboard in a live-performance setup.

• Maybe you don't have a pad controller, but you do have a small secondary MIDI keyboard. You could set up a MIDI controller file to allow you to switch layers on and off (or mute/solo layers, etc.) using keys on that little keyboard.
• If you have just one 88-key master keyboard, you might want to set up a handful of notes at the very bottom or top end (which you don't expect to actually use to play notes) to trigger other functions in Unify.

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.

• Note that you can deactivate a MIDI controller file by moving it to another folder.
• A common practice is to create a sub-folder called e.g. INACTIVE inside the MIDI Controller Files folder itself, and move files in and out of there as you require.
• Because Unify scans the MIDI controller files only when starting up, any editing changes you make will only take effect the next time Unify starts.

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.

• If there is no match, it passes the MIDI message along to be seen by the layers and Transport.
• If there is a match, Unify checks the specific message against the “rules” for that specific controller.
  • If there is no match, it passes the MIDI message along.
  • If there is a match, it interprets the message according to the appropriate rule and DOES NOT pass the MIDI message along to the layers and Transport.

The suppression of MIDI messages which match controller-file rules has two important benefits:

1. Two or more MIDI controllers may generate identical CC or Note messages, which are interpreted differently for each.
2. Some devices (the KORG nanoKONTROL2 is a major example) generate MIDI CC messages which are normally reserved for special purposes, e.g. CC#0 (default assignment for the first slider) would normally be interpreted by Unify and most other MIDI instruments as MIDI Bank Select. With MIDI controller files, you can effectively intercept such messages, and specify exactly how they are to be interpreted, knowing they will be suppressed at the early stages of Unify's MIDI processing, and won't go on to trigger their more conventional functions.

As of Unify v1.9, you can put the word suppress in place of a normal command-path, to entirely suppress (filter out) a specific CC message.

This was added in response to feedback from a user who found that a Roland D-50, used as a MIDI controller, sends a MIDI CC#123 (all notes off) message when the last key is released, and this can cause problems with some plug-ins. Adding the line

cc 123 suppress

to the active MIDI Controller file will cause this message to be suppressed (filtered out).