Hacking Remote Files In Reason

If Remote support has not been added for your favourite MIDI controller, consider doing it yourself.

Propellerhead's 'Remote' technology allows intelligent and fluid control of Reason 's devices, but only for specifically supported MIDI controllers. Many of the latest MIDI keyboards and controllers have had Remote support developed by their manufacturers. However, with a little time and patience you can add support for older or more obscure devices yourself, or even customise the controller mapping of supported devices.

A Remote codec file defines all the available controls on your device, and determines what data they send to Reason.

We covered Remote in detail last year ('Using Hardware Controllers with Reason 3 ', SOS April 2006) but, to recap, it's a protocol developed by Propellerheads to allow MIDI controllers to work with no configuration or control mapping by the user. All you have to do is tell Reason what hardware is connected and the rest is taken care of by Remote. Once a controller is 'on-line', its controls are mapped to the most relevant parameters of whichever Reason device is the current MIDI target. You can also lock a controller to any rack device, and use multiple controllers. Multiple banks of controls can be accessed via keyboard shortcuts or buttons on the controller.

Old Dog, New Tricks

So what if you are, for example, a humble sound engineer/writer who can't afford to splash out on the latest controller keyboard, and are still using, say, your battered-but-still-loved Yamaha CS1x as a master keyboard? Luckily, I have some experience of this demographic. My 10-year-old CS1x is still capable of controlling Reason with its six assignable knobs, pitch and mod wheels, and a couple of foot-controller inputs, but it's not supported by Remote. Until recently, I've used the ubiquitous (and Remote-supported) M-Audio Oxygen 8 alongside the CS1x, providing me with eight knobs for controlling Reason devices. However, I wanted to be able to take my gear out live without the Oxygen 8, so I decided to try to hack some Remote support for the CS1x.

Before we get too carried away, it should be said that any MIDI controllers or keyboards that lack Remote support can be used with Reason, just as they could prior to version 3. To do this, you need to open the Preferences, choose the Control Surfaces and Keyboards page, and click 'Add'. Then set the Manufacturer to 'Other' and select from the list of generic device types such as 'Basic MIDI Keyboard', 'MIDI Controller', and 'MIDI Keyboard w Controls'. As well as providing basic keyboard support, these selections will give any knobs, buttons and so forth a degree of functionality in Reason — albeit without the intelligent assignments and multiple banks that you get with Remote. Each device in Reason is programmed to respond to MIDI CC (Continuous Controller) messages in set ways. Your controllers may therefore move knobs on whichever device is the MIDI target, although they might be mapped in quite a random order. You can also, of course, use Reason 's Remote Override mode to lock any of your hardware controls to particular parameters.

You may be able to use this older functionality to achieve what you need without resorting to Remote file editing. For example, I might want to get my CS1x's knobs to control the four knobs on any Combinator, and that may be enough to run a live set. To do this I'd need to program the controls on the keyboard to transmit the default CC values that Combinator is wired for. All the default Controller assignments are listed in the MIDI Implementation Chart PDF file in Reason 's Documents folder (Combinator 's knobs are listed as CCs 71-74). To test this scenario, I set the first four knobs on my keyboard to transmit these controller numbers and, sure enough, any targeted Combi could now be controlled by the knobs. However, having chosen to map to Combinator 's knobs, I can't choose how the knobs map to any other device. With Remote support, I could switch to the mixer and the same knobs would control channel faders. Without Remote, you're at the mercy of the default MIDI assignments, which are channel EQ bass controls.

Remote Hack

So how does Remote intelligently assign your controls to the most useful parameters on each device, and manage banks of assignments? Remote references two files that are provided for each supported device. The first, the MIDI codec file, tells Reason what physical controls are on the controller. It may also contain a data dump that Reason can send to the device to configure it. The second is called a Remote Map file and lists all the assignments of each control for every Reason device, including multiple bank assignments.

The directory stucture for custom Remote files in Mac OS X. Their Windows location is described in the main text.In Mac OS X the files are kept in the root library at Macintosh HD/Library/Application Support/Propellerhead Software/Remote. On Windows XP computers the files are hidden, so you need to open the Folder Options Control Panel, switch to the View tab, and enable the 'Show hidden files and folders' option. You will then find the files at C:/Documents and Settings/All Users/Application Data/Propellerhead Software/Remote. The Remote directory contains two folders: Codecs and Maps. The Codecs folder contains a folder called MIDI Codecs, where the codec files we are interested in are stored. There are also other files for the devices that support two-way communication, and Lua codecs which use the Lua scripting language and are basically off-limits. All the codec files are in a single folder, but the map files are divided by manufacturer. You will need to observe this convention if you create your own files.

The quickest way to understand how the files work is to study the existing ones. In fact, the easiest way to add support for a new device is to use the files for a similar device as a template. You may also be interested in opening up files for a device you own and customising the mapping. Let's have a look at the Oxygen 8's files, as this is a simple device with eight knobs, a keyboard and a slider. You should be able to add basic Remote support to most devices or keyboards that have eight knobs, by making a few simple changes to the Oxygen 8's files. In the MIDI Codecs folder, find the 'Oxygen 8 old.midicodec' file, right-click it and choose Open With. On a Mac, open with Text Edit, and on XP use Notepad. The screen on the previous page shows the contents, which are just standard text.

Codec Files

The top section of the codec file has some basic file information and entries for the make and model of the device. Reason uses this information to list the device in the Control Surface Preferences. The next few lines all begin 'Setup Info Text', and contain the information text that appears in Reason when you add the device. Next is the list of controls and data-generating devices on your hardware. Each line begins with 'Item', followed by the name of the control (which can be whatever you like), followed by the control type. Any ranged controller, such as a knob, fader, pitch wheel, mod wheel, or either axis of a joystick or touchpad, is listed as a 'value'. Other types are 'button', 'keyboard' and 'delta'. After the type, Min and Max values are listed.

The next block of data is a list that defines the messages that are sent by each of the controls. Each line begins with 'Map', followed by the MIDI data format of the control written in hex format (see the box below for more on this). Following this is the name of the control, and three further values. For example, knob 1 of the Oxygen 8 is listed as:

Map b? 0a xx Knob 1 x 0 0

The three hex MIDI data entries represent the MIDI Channel, Control number, and Control value from knob one. The '?' is a wildcard value, and in this case tells Reason to ignore the MIDI channel. The second value (0a) is the controller number, telling Reason that the knob transmits Controller 10 (the decimal equivalent of 0a). The third value is the value representing the knob's position. This has been written as 'xx', because it is a variable: ie. this value will change from one message to the next as you turn the knob. The next entry in the line is, obviously, the name of the hardware control. The final three values determine what is going to be sent to Reason. In the example, we have a single value 'x', which simply means that the 'xx' value in the message is passed on to Reason. You could have Remote pass on something different, such as a constant (for example,1), or a function (for example, try 128 ­ x), but a simple 'x' is the most common case for knobs and faders. Buttons are normally set up to send a message of '1' whenever they are pressed, as Reason only needs to know that it's been pressed and doesn't care if it puts out different values. Keyboard messages (Note On/Note Off) have two variables: note number and velocity. There are some differences between the way keyboards handle these messages, but the three lines listed for 'keyboard' in the Oxygen 8 map cover all eventualities, so can be use for all codecs.

Modifying A Remote Codec

We're going to use the Oxygen 8 file as the basis for my CS1x codec. The first thing to do is make a copy of the file and rename it Yamaha CS1x.midicodec (or whatever is appropriate for your own controller, so long as it ends in .midicodec). You can leave the file in this directory, but Propellerheads recommend putting it in the equivalent place in your home directory. This means that if you migrate your user account to another computer, your personal remote maps will come with you. The files paths are Macintosh HD/<user name>/Library:Application Support/Propellerhead Software/Remote or C:/Documents and Settings/<user name>/Application Data/Propellerhead Software/Remote/. The Codecs and Maps folders do not exist in your home location at first; you can either create them or just copy the whole lot over from the root directory and delete what you don't need. I elected to do the latter and copied my Yamaha CS1x.midicodec file to my home Codecs folder.

Remote Map files set how your physical controls map to the parameters in each Reason device, with provision for multiple pages or banks.Open the file in your text editor and change the Manufacturer and Model entries. Next, edit the list of Items to reflect your hardware. For example, if you just have a simple eight-knob controller with no keyboard, you can remove the Keyboard Items from the file. The CS1x has no data-entry fader, so I removed that. I also removed the lines referring to knobs 7 and 8, but having those extra two knobs would make life much easier, as you'll see when we get to the mapping stage. The next step is the most important: you need to make sure that the messages sent by your actual knobs match those declared in the codec file. There are two approaches: change the file to match the messages sent by your knobs, or change the messages sent by your knobs to match the file. On the CS1x, editing the control values sent by the knobs is easy, so I did that. The Control Surface Details guide lists the knob values used in some of the supported devices, including the Oxygen 8 (10-17 decimal). If you can't edit the knobs on your controller, you will need to change the values in the file. The first step is to find out what controller numbers your knobs send. This should be listed in the manual, but if not you can use a MIDI monitor utility (or Logic) to see the values (see the box on the previous page). You should be able to display the values in hex and save yourself the job of converting them. Now enter the controller numbers into the Map list in the file, replacing the middle of the three hex values (0a in the example above).

Remote Maps

Codec files describe what controls are present and what messages are sent, but Reason also needs to know what to do with these controls: this is where map files come in. Open the Maps folder in the root Remote directory, and find the map for the remote implementation you are modifying (in this example, the 'Oxygen 8 old' map). Now, in your home Maps folder, create a folder for the Manufacturer and make a copy of the file here. Rename it with the <model name>.remotemap, and open it in your text editor. The screen above shows the first page of the file. The file is quite long, as it needs to list the mapping for every Reason device supporting MIDI control.

How my custom Remote device shows up in the Control Surfaces Preferences.As with the codec, you need to change the Manufacturer and Model entries, or Reason will not be able to match the files up when it tries to set up Remote. How much you need to do next depends on how closely the device you are trying to set up resembles the file you are using as a template. For example, if your device is a simple keyboard with eight knobs, it is so close to an Oxygen 8 that you can just use the Oxygen 8 map without further editing. All you would need to do is save the Map file, restart Reason, and choose your device in the Preferences (see the screen at the top of the next page). However, if you have had to make some changes to the codec file, such as removing two knobs, as I did for the CS1x, you will need to decide how the controls are remapped. This is also the case if you are attempting to modify the mapping behaviour of an existing supported device. As with the codec, if you study how the file works you should be able to make changes that do what you need.

The map is divided into sections for Reason 's devices, with each section called a Scope. For example, if the device includes a keyboard, the first section starts 'Scope Propellerheads Master Keyboard'. Each following line is in this format:

Map <physical control name> <item controlled in Reason>

My custom map, with the six available controls assigned using additional banks.The line 'Map Keyboard Keyboard' should, therefore, be self-explanatory. The names of the physical controls are those declared in the codec file. The names of the Reason parameters are fixed. As you can see in the screen on the previous page, the next block of text is for the Combinator, and is a simple mapping of the eight declared knobs to the Combi 's eight controls. Things get more complicated when there are more parameters than controllers and you need to create multiple banks. This can be seen in the next section in the file for the 14:2 Mixer. The mixer parameters have been divided into groups of eight or less, and an extra entry has been added to each line of text to specify a bank. These banks, or groups, have been declared at the beginning of the section with the text 'Define Group Keyboard Shortcut Variations' and then the bank names. Banks are selected in Reason by holding Command + Option (Mac) or Ctrl + Alt (Windows) and pressing number keys on the main keyboard.

The screen to the right is the start of my map for the CS1x, and shows how you can create or edit new banks/groups, and also how six knobs are not really enough for Reason! In order to control all the parameters on Combinator, I've had to split the controls across two groups, which I've called Bank1 and Bank2. In the mixer section, I've had to re-allocate the knobs across three groups just for the faders. The main thing to be aware of when making larger changes like this is that the file format is sensitive to how the text and values are spaced. Each entry must be divided by a Tab, and you must be aware of values that aren't being used and insert an extra Tab as a place-holder. For example, there are headings for Key and Scale parameters in each Map entry, which are not used in the Oxygen 8 implementation. The only way to be sure any additions you make will work is to copy and paste lines from elsewhere in the file to use as templates. If you enter anything in a format Reason doesn't like, a red cross appears in Control Surfaces Preferences. Click the cross and you'll see a list of the problems in the file.

Taking It Further

Remote file editing is not for the faint-hearted, but it is very rewarding when you get an unsupported controller working, or open up new possibilities by customising a map to do exactly what you want. You'll soon be experimenting with assignment ideas to see if you can map MIDI keys to buttons, or reverse a controller's polarity. Enjoy!