DEALING WITH ENDLESS ROTARY ENCODERS IN CSOUND - WITH ADDENDA FOR THE NICHE AUTOMATION STATION AND DIGIDESIGN R1 REMOTE CONTROLLER Art Hunkins - December 2005 abhunkin AT uncg DOT edu http://www.arthunkins.com THE PROBLEM MIDI hardware control surfaces consist of assortments of rotary knobs and sliders. They are very useful for real time performance of Csound, especially in conjunction with the ctrl7 opcode. In most cases, the control surfaces implement continuous controllers (CCs) with an absolute range (normally 0-127), and a tactile beginning and end point to the knob or slider. However, rotary encoders exhibit the physical problem of having no tactile or visible beginning and end points. (Since the controls are endless, they cannot have such points; this is a good reason generally not to use encoders with live-performance Csound except as a last resort.) However, a related issue *can* be addressed - that of "travel." That is, to cover the required data range (normally 0-127) the control should turn the expected amount, typically one full turn or less. In addition, some of these encoders use *relative* rather than absolute values - including several with *three or more varieties* of relative! (Thankfully, most of those that provide relative also offer absolute mode as default.) Among control surfaces that incorporate endless encoders are the Behringer BCF/BCR2000 (best because of their red "guide LEDs") and Nano, Doepfer Pocket Dial, Korg microKONTROL, Niche Automation Station, Native Instruments 4Control, Novation Remote 25, and Digidesign R1 Remote Controller. These and similar units are the subject of this article. The Behringer and Doepfer units offer both absolute and three types of relative data; the Niche, Korg and Novation present absolute only, while the 4Control outputs a single kind of relative. The Digidesign implements a unique absolute/relative hybrid; for anyone wanting to design his own MIDIOx conversion utility, the addendum below, as well as the conversion file itself, should prove particularly instructive. The Peavey StudioMix is a very special case: it presents *proprietary NRPN* data rather than the usual CC values and note on/offs - as well as a unique type of relative rather than absolute data. Solutions to these challenges are dealt with in two companion articles: "The Peavey StudioMix as Standard MIDI Controller for Csound," and "Converting StudioMix Endless Rotary Encoder Data for Use in Csound." So, the problem: endless encoders normally have way too much "travel." Many of them have tactile "stops" (steps) as they turn, typically 24 per rotation. Each of these stops is +/-1; to get the full 0-127 range, more than six complete rotations are required! Even the Behringer units, which have no stops, require 1.25+ rotations to cover the range - which is, from the tactile standpoint, still much too far. (On the other hand, the Digidesign is problematic in that it covers the complete range in less than one-half rotation - though then it begins to repeat!) THE SOLUTION The solution to the "travel" issue is to run a special VBscript in MIDIOx, a free utility for Windows only, found at http://www.midiox.com. Actually, there are four scripts - one for the usual absolute data format, and one for each of the three relative data formats. The names for these custom scripts are AbsoluteEncoderFix.vbs and RelativeEncoderFix1-3.vbs (all are found in RotaryEncoders.zip). RelativeEncoderFix1 is for twos complement mode. This is one of the options for the Behringer units as well as Doepfer's Pocket Dial, and is Behringer's Relative 3 mode. RelativeEncoderFix2 is for binary offset mode. It too is an option for the Behringer units and Pocket Dial, and is Behringer's Relative 2 mode. More importantly, it is the sole output mode of the Native Instruments 4Control. Lastly, RelativeEncoderFix3 is for MSB (Most Significant Bit) mode, likewise an option for the Behringer units and Pocket Dial. It is Behringer's Relative 3 mode. As intimated above, it is probably best, where possible, to choose absolute mode (often the default) and avoid confusion. All scripts have four variables that can be edited by the user in any text editor, such as Notepad. They are located near the beginning of the script. The first variable is CHANnel number, which defaults to 1. The second is BANK, which represents the first controller number of a group of contiguous controller numbers. (AbsoluteEncoderFix.vbs inserts here an additional variable, DESTination, which defaults to the same value as BANK. DEST allows for the option of changing controller #'s without an accompanying .oxm file. Make sure DEST and BANK are identical unless you wish to change controller #'s.) Variable three is the NUMBER of controllers in the bank. (The fact that there is a single BANK simply means that controller numbering must be continuous. For example, there might be three groups of eight controllers numbered consecutively as a single 24-controller BANK.) The last variable, MAX, is the one that addresses "travel." MAX is the number of steps (or "stops") within which you want to constrain the entire 0-127 range. The default value is 24, as this is the number of steps per rotation for most encoders (though there are many exceptions). As comments within the scripts suggest, you may wish to set this number lower - for *less* than a full rotation. Setup for MIDIOx and your selected VBScript is as follows (it is the same for all scripts): 1) Before MIDIOx can be run, the MIDIYoke "virtual patch cord" driver must be installed. (MIDIYoke is also downloadable free at http://www.midiox.com.) The fairly elaborate installation instructions are well detailed in the Midiyoke.rtf file included in the self-extracting download. Follow them carefully. For our purposes, only a single MIDI Yoke Junction Port need be created. Fortunately, once this setup is complete, you can forget about it. 2) Run MIDIOx, setting the MIDI Output device to MIDI Yoke Junction: 1. (Click Options, then MIDI Devices.) In the same window, select the MIDI Input device (usually your sound card) that connects your control surface to your computer. (Once you make these selections, they remain the same until you change them.) 3) Disable the MAP icon if it's selected on the taskbar. 4) During your Csound (.csd) or other software setup, select MIDI Yoke Junction: 1 as MIDI Input Device. 5) Click on your selected VBScript. (It will "attach" itself to the running MIDIOx automatically.) Alternatively, you can do this prior to step 2, in which case the VBScript will itself open MIDIOx; you then proceed to set the devices as above. 6) To shut down the script (and MIDIOx), click Actions, then Stop WScript. (Do not close MIDIOx the normal way.) ADDENDUM1 - THE NICHE AUTOMATION STATION Also included in the RotaryEncoders.zip file are two routines designed specifically for the Niche Automation Station. The Niche sports a bank of four endless encoders, and produces a non-standard range (1-127) on its sixteen sliders. To address "encoder travel", a somewhat simplified version of AbsoluteEncoderFix, called NicheEncoderFix.vbs, is included here. To adjust the non-standard slider range, a basic NicheSliderFix.oxm file is offered. NicheEncoderFix.vbs offers only two user-configurable variables: BANK (# of first CC of the 4-encoder set) and STEPS (# of "stops" to comprise the 0-127 range). As mentioned above, for the Niche, 36 steps make up a single dial rotation. (The channel is hard-coded to 1, and number of encoders to 4.) The two "fixes" can be applied simultaneously or separately. To run NicheEncoderFix alone, simply follow the procedure above, substituting the new .vbs file. To run NicheSliderFix.oxm by itself, substitute the following step 2, and omit 5 and 6: 2) Under Options, Data Mapping, load the NicheSliderFix.oxm (or .txm) file. Click OK, then click/enable the MAP icon if it's not already enabled on the taskbar. To run both "fixes" concurrently, follow the above procedure completely, but substitute alternate step 2. And again replace your selected VBScript with NicheEncoderFix.vbs. Be sure here that the slider numbering does not overlap that of the rotary encoders. (Default for sliders is 1-16; encoders, 36-39. These are the hardware defaults for the Niche as well.) ADDENDUM2 - THE DIGIDESIGN R1 REMOTE CONTROLLER The Digidesign R1 presents a highly unusual set of 4 encoders: its 36 steps (per rotation) do not increase by single increments, rather by jumps of 8 - thus covering the entire range in 16 steps (less than one-half rotation!) Once an extreme is reached (0 or "128") the sequence repeats, endlessly. Interestingly, the repeat downward does not match the repeat upward (a repeat downward results in values one less than a repeat in an upward direction). The R1 is somewhat unique in two other ways: 1) the controller numbers are hardware-fixed (the .vbs file must change them to the CCs you want); 2) the encoders are not numbered consecutively in the usual sense. Indeed, each encoder can have any of *five* different CC #'s! Specifically, the four encoder CCs are hardware-set to range between 64 and 83. Encoder1 is assigned to CCs 64-68, encoder2 to 69-73, encoder3 to 74- 78, and encoder4 to 79-83. Just which of the 5 CC #'s applies is determined by the toggling of one of five buttons (MUTE, SOLO, etc.) immediately above. MUTE selects the first CC #, SOLO the second, and so on to PAN, which selects the fifth. As a result, the CC numbers active at a given time are not contiguous; it is up to the script to make them into a "BANK". Thus, study of DigidesignEncoderFix.vbs is particularly instructive as a model for dealing with unusual encoder behavior. (The monitor facility in MIDIOx is essential in determining just what kind of data is being output by the encoders.) The unique features of this script are these: first, reducing the five-CC range for each encoder to a single index so that it can be tracked independent of which button is selected; then determining whether the step is in an upward or downward direction (there are no repeat values, and each MIDI message here represents precisely one step [no "acceleration" is involved]). Several conditional statements take care of the various possible repeat patterns, both at the top and bottom of the range. A value of +1 is assigned to upward movement, -1 to downward (thus the initial conversion is to a simple relative mode!) This value, multiplied by the STEPS factor to arrive at appropriate step size, is then added to the previous (saved) value, and once sent out, becomes a new "last value." The value is directed to the *user-specified* BANK controller - now in a contiguous set of four CCs (with the help of the reduced indexing done previously). The .vbs file itself is extensively commented. Follow the first setup above to run DigidesignEncoderFix.vbs. Note that only STEPS and BANK are here user-definable. Hardware determines the CHANnel # (throughout the R1) to be 1, the NUMBER of encoders is 4, and there seems little reason normally to modify either value.