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

• 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 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:

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

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