com.dixshtix.midi
Class Controller

java.lang.Object
  |
  +--java.lang.Number
        |
        +--com.dixshtix.midi.MidiNumber
              |
              +--com.dixshtix.midi.Controller

All Implemented Interfaces:

java.lang.Cloneable, java.io.Serializable

public class Controller

extends MidiNumber

Controller is in the range 0-127. Many Controls are previously defined. All controllers are specifically defined by agreement of the MIDI Manufacturers Association (MMA) and the Japan MIDI Standards Committee (JMSC). Manufacturers can request through the MMA or JMSC that logical controllers be assigned to physical ones as necessary. The controller allocation table must be provided in the user's operation manual.

A Controller message has a Status byte of 0xB0 to 0xBF depending upon the MIDI channel. There are two more data bytes.

The first data byte is the Controller Number. There are 128 possible controller numbers (ie, 0 to 127). Some numbers are defined for specific purposes. Others are undefined, and reserved for future use.

The second byte is the "value" that the controller is to be set to.

Most controllers implement an effect even while the MIDI device is generating sound, and the effect will be immediately noticeable. In other words, MIDI controller messages are meant to implement various effects by a musician while he's operating the device.

If the device is a MultiTimbral module, then each one of its Parts may respond differently (or not at all) to a particular controller number. Each Part usually has its own setting for every controller number, and the Part responds only to controller messages on the same channel as that to which the Part is assigned. So, controller messages for one Part do not affect the sound of another Part even while that other Part is playing.

Some controllers are continuous controllers, which simply means that their value can be set to any value within the range from 0 to 16,384 (for 14-bit coarse/fine resolution) or 0 to 127 (for 7-bit, coarse resolution). Other controllers are switches whose state may be either on or off. Such controllers will usually generate only one of two values; 0 for off, and 127 for on. But, a device should be able to respond to any received switch value from 0 to 127. If the device implements only an "on" and "off" state, then it should regard values of 0 to 63 as off, and any value of 64 to 127 as on.

Many (continuous) controller numbers are coarse adjustments, and have a respective fine adjustment controller number. For example, controller #1 is the coarse adjustment for Modulation Wheel. Using this controller number in a message, a device's Modulation Wheel can be adjusted in large (coarse) increments (ie, 128 steps). If finer adjustment (from a coarse setting) needs to be made, then controller #33 is the fine adjust for Modulation Wheel. For controllers that have coarse/fine pairs of numbers, there is thus a 14-bit resolution to the range. In other words, the Modulation Wheel can be set from 0x0000 to 0x3FFF (ie, one of 16,384 values). For this 14-bit value, bits 7 to 13 are the coarse adjust, and bits 0 to 6 are the fine adjust. For example, to set the Modulation Wheel to 0x2005, first you have to break it up into 2 bytes (as is done with Pitch Wheel messages). Take bits 0 to 6 and put them in a byte that is the fine adjust. Take bits 7 to 13 and put them right-justified in a byte that is the coarse adjust. Assuming a MIDI channel of 0, here's the coarse and fine Mod Wheel controller messages that a device would receive (coarse adjust first):

 0xB0 0x01 0x40
 

Controller on channel 0, Mod Wheel coarse, bits 7 to 13 of 14-bit value right-justified (with high bit clear).

 0xB0 0x33 0x05
 

Controller on channel 0, Mod Wheel fine, bits 0 to 6 of 14-bit value (with high bit clear).

Some devices do not implement fine adjust counterparts to coarse controllers. For example, some devices do not implement controller #33 for Mod Wheel fine adjust. Instead the device only recognizes and responds to the Mod Wheel coarse controller number (#1). It is perfectly acceptable for devices to only respond to the coarse adjustment for a controller if the device desires 7-bit (rather than 14-bit) resolution. The device should ignore that controller's respective fine adjust message. By the same token, if it's only desirable to make fine adjustments to the Mod Wheel without changing its current coarse setting (or vice versa), a device can be sent only a controller #33 message without a preceding controller #1 message (or vice versa). Thus, if a device can respond to both coarse and fine adjustments for a particular controller (ie, implements the full 14-bit resolution), it should be able to deal with either the coarse or fine controller message being sent without its counterpart following. The same holds true for other continuous (ie, coarse/fine pairs of) controllers.

Here's a list of the defined controllers. To the left is the controller number (ie, how the MIDI Controller message refers to a particular controller), and on the right is its name (ie, how a human might refer to the controller). To get more information about what a particular controller does, click on its controller name to bring up a description. Each description shows the controller name and number, what the range is for the third byte of the message (ie, the "value" data byte), and what the controller does. For controllers that have separate coarse and fine settings, both controller numbers are shown.

MIDI devices should use these controller numbers for their defined purposes, as much as possible. For example, if the device is able to respond to Volume controller (coarse adjustment), then it should expect that to be controller number 7. It should not use Portamento Time controller messages to adjust volume. That wouldn't make any sense. Other controllers, such as Foot Pedal, are more general purpose. That pedal could be controlling the tempo on a drum box, for example. But generally, the Foot Pedal shouldn't be used for purposes that other controllers already are dedicated to, such as adjusting Pan position. If there is not a defined controller number for a particular, needed purpose, a device can use the General Purpose Sliders and Buttons, or NRPN for device specific purposes. The device should use controller numbers 0 to 31 for coarse adjustments, and controller numbers 32 to 63 for the respective fine adjustments.

CHANNEL MODES

Synthesizers contain sound generation elements called voices. Voice assignment is the algorithmic process of routing Note On/Off data from the keyboard to the voices so that the musical notes are correctly played with accurate timing.

When MIDI is implemented, the relationship between the sixteen available MIDI channels and the synthesizer's voice assignment must be defined. Several Mode messages are available for this purpose (see Table III). They are Omni (On/Off), Poly, and Mono. Poly and Mono are mutually exclusive, i.e., Poly Select disables Mono, and vice versa. Omni, when on, enables the receiver to receive Voice messages in all voice Channels without discrimination. When Omni is off, the receiver will accept Voice messages from only the selected Voice Channel(s). Mono, when on, restricts the assignment of Voices to just one voice per Voice Channel (Monophonic.) When Mono is off (=Poly On), any number of voices may be allocated by the Receiver's normal voice assignment algorithm (Polyphonic.)

For a receiver assigned to Basic Channel "N," the four possible modes arising from the two Mode messages are:

Mode	Omni
1	On	Poly	Voice messages are received from all Voice channels and assigned to voices polyphonically.
2	On	Mono	Voice messages are received from all Voice Channels, and control only one voice, monophonically.
3	Off	Poly	Voice messages are received in Voice channel N only, and are assigned to voices polyphonically.
4	Off	Mono	Voice messages are received in Voice channels N thru N+M-1, and assigned monophonically to voices 1 thru M, respectively. The number of voices M is specified by the third byte of the Mono Mode Message.

Four modes are applied to transmitters (also assigned to Basic Channel N). Transmitters with no channel selection capability will normally transmit on Basic Channel 1 (N=0).

Mode	Omni
1	On	Poly	All voice messages are transmitted in Channel N.
2	On	Mono	Voice messages for one voice are sent in Channel N.
3	Off	Poly	Voice messages for all voices are sent in Channel N.
4	Off	Mono	Voice messages for voices 1 thru M are transmitted in Voice Channels N thru N+M-1, respectively. (Single voice per channel).

A MIDI receiver or transmitter can operate under one and only one mode at a time. Usually the receiver and transmitter will be in the same mode. If a mode cannot be honored by the receiver, it may ignore the message (and any subsequent data bytes), or it may switch to an alternate mode (usually Mode 1, Omni On/Poly).

Mode messages will be recognized by a receiver only when sent in the Basic Channel to which the receiver has been assigned, regardless of the current mode. Voice messages may be received in the Basic Channel and in other channels (which are all called Voice Channels), which are related specifically to the Basic channel by the rules above, depending on which mode has been selected.

A MIDI receiver may be assigned to one or more Basic Channels by default or by user control. For example, an eight-voice synthesizer might be assigned to Basic Channel 1 on power-up. The user could then switch the instrument to be configured as two four-voice synthesizers, each assigned to its own Basic Channel. Separate Mode messages would then be sent to each four-voice synthesizer, just as if they were physically separate instruments.

POWER-UP DEFAULT CONDITIONS

On power-up all instruments should default to Mode #1. Except for Note On/Off Status, all Voice messages should be disabled. Spurious or undefined transmissions must be suppressed.

Version:

0.1

Author:

Richard C. Penner II

See Also:

EventStatus.ksnControlChange, EventType.kControlChange, Serialized Form

Field Summary

static int	kAllControllersOff All Controllers Off : 121.
static int	kAllNotesOff Channel Mode Message: All Notes Off.
static int	kAllSoundOff All Sound Off: 120.
static int	kBalance_Coarse Balance: 8 (coarse) 40 (fine).
static int	kBalance_Fine
static int	kBankSelect Bank Select: 0 (coarse) 32 (fine).
static int	kBankSelect_Fine
static int	kBreathController_Coarse Breath Controller: 2 (coarse) 34 (fine).
static int	kBreathController_Fine
static int	kCelesteLevel Celeste Level: 94.
static int	kChorusLevel Chorus Level: 93.
static int	kDataButtonDecrement Data Button decrement: 97.
static int	kDataButtonIncrement Data Button increment: 96.
static int	kDataEntry_Coarse Data Entry Slider: 6 (coarse) 38 (fine).
static int	kDataEntry_Fine
static int	kEffectControl1_Coarse Effect Control 1: 12 (coarse) 44 (fine).
static int	kEffectControl1_Fine
static int	kEffectControl2_Coarse Effect Control 2: 13 (coarse) 45 (fine).
static int	kEffectControl2_Fine
static int	kEffectsLevel Effects/Reverberation Level: 91.
static int	kExpression_Coarse Expression: 11 (coarse) 43 (fine).
static int	kExpression_Fine
static int	kFootPedal_Coarse Foot Pedal: 4 (coarse) 36 (fine).
static int	kFootPedal_Fine
static int	kGeneralPurposeButton1_Switch General Purpose Buttons: 80, 81, 82, 83.
static int	kGeneralPurposeButton2_Switch
static int	kGeneralPurposeButton3_Switch
static int	kGeneralPurposeButton4_Switch
static int	kGeneralPurposeSlider1 General Purpose Sliders: 16, 17, 18, 19.
static int	kGeneralPurposeSlider2
static int	kGeneralPurposeSlider3
static int	kGeneralPurposeSlider4
static int	kHold2Pedal_Switch Hold 2 Pedal: 69.
static int	kHoldPedal_Switch Hold Pedal : 64.
static int	kLegatoPedal_Switch Legato Pedal: 68.
static int	kLocalKeyboard_Switch Channel Mode Message: Local Control.
static int	kModulationWheel_Coarse MOD Wheel: 1 (coarse) 33 (fine).
static int	kModulationWheel_Fine
static int	kMonoOperation Channel Mode Message: Mono Mode On (Poly Off).
static int	kNonRegisteredParameter_Coarse Non-Registered Parameter Number (NRPN): 99 (coarse) 98 (fine).
static int	kNonRegisteredParameter_Fine
static int	kOmniModeOff Channel Mode Message: Omni Mode Off.
static int	kOmniModeOn Channel Mode Message: Omni Mode On.
static int	kPanPosition_Coarse Pan: 10 (coarse) 42 (fine).
static int	kPanPosition_Fine
static int	kPhaserLevel Phaser Level: 95.
static int	kPolyOperation Channel Mode Message: Poly Mode On (Mono Off).
static int	kPortamento_Switch Portamento : 65.
static int	kPortamentoControl
static int	kPortamentoTime_Coarse Portamento Time: 5 (coarse) 37 (fine).
static int	kPortamentoTime_Fine
static int	kRegisteredParameter_Coarse Registered Parameter Number (RPN) : 101 (coarse) 100 (fine).
static int	kRegisteredParameter_Fine
static int	kSoftPedal_Switch Soft Pedal: 67.
static int	kSoundAttackTime Sound Attack Time: 73.
static int	kSoundBrightness Sound Brightness: 74.
static int	kSoundControl10
static int	kSoundControl6 Sound Controls 6-10: 75, 76, 77, 78, 79.
static int	kSoundControl7
static int	kSoundControl8
static int	kSoundControl9
static int	kSoundReleaseTime Sound Release Time: 72.
static int	kSoundTimbre Sound Timbre: 71.
static int	kSoundVariation Sound Variation: 70.
static int	kSustenutoPedal_Switch Sustenuto : 66.
static int	kTremuloLevel Tremulo Level: 92.
static int	kVolume_Coarse Volume : 7 (coarse) 39 (fine).
static int	kVolume_Fine
static java.lang.String[]	names English strings corresponding to all known Controllers.

Fields inherited from class com.dixshtix.midi.MidiNumber

number

Fields inherited from class java.lang.Number

serialVersionUID

Constructor Summary

Controller(int num)
Initializer.

Method Summary

java.lang.String	toName() Accessor.
static java.lang.String	toName(int cntlNumber) Conversion Utility.
java.lang.String	toString() Accessor.

Methods inherited from class com.dixshtix.midi.MidiNumber

byteValue, doubleValue, equals, floatValue, hashCode, intValue, longValue, shortValue

Methods inherited from class java.lang.Object

, clone, finalize, getClass, notify, notifyAll, registerNatives, wait, wait, wait

Field Detail

kBankSelect

public static final int kBankSelect

Bank Select: 0 (coarse) 32 (fine).

Affects:

Some MIDI devices have more than 128 Programs (ie, Patches, Instruments, Preset, etc). MIDI Program Change messages only support switching between 128 programs. So, Bank Select Controller (sometimes called Bank Switch) is sometimes used to allow switching between groups of 128 programs. For example, let's say that a device has 512 Programs. It may divide these into 4 banks of 128 programs apiece. So, if you want program #129, that would actually be the first program within the second bank. You would send a Bank Select Controller to switch to the second bank (ie, the first bank is #0), and then follow with a Program Change to select the first Program in this bank. If a MultiTimbral device, then each Part usually can be set to its own Bank/Program.

On MultiTimbral devices that have a Drum Part, the Bank Select is sometimes used to switch between "Drum Kits".

NOTE: When a Bank Select is received, the MIDI module doesn't actually change to a patch in the new bank. Rather, the Bank Select value is simply stored by the MIDI module without changing the current patch. Whenever a subsequent Program Change is received, the stored Bank Select is then utilized to switch to the specified patch in the new bank. For this reason, Bank Select must be sent before a Program Change, when you desire changing to a patch in a different bank. (Of course, if you simply wish to change to another patch in the same bank, there is no need to send a Bank Select first).

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF.

NOTE: Most devices use the Coarse adjust (#0) alone to switch banks since most devices don't have more than 128 banks (of 128 Patches each).

kBankSelect_Fine

public static final int kBankSelect_Fine

kModulationWheel_Coarse

public static final int kModulationWheel_Coarse

MOD Wheel: 1 (coarse) 33 (fine).

Affects:

Sets the MOD Wheel to a particular value. Usually, MOD Wheel introduces some sort of (LFO) vibrato effect. If a MultiTimbral device, then each Part usually has its own MOD Wheel setting.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is no modulation effect.

kModulationWheel_Fine

public static final int kModulationWheel_Fine

kBreathController_Coarse

public static final int kBreathController_Coarse

Breath Controller: 2 (coarse) 34 (fine).

Affects:

Whatever the musician sets this controller to affect. Often, this is used to control a parameter such as what Aftertouch can. After all, breath control is a wind player's version of how to vary pressure. If a MultiTimbral device, then each Part usually has its own Breath Controller setting.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is minimum breath pressure.

kBreathController_Fine

public static final int kBreathController_Fine

kFootPedal_Coarse

public static final int kFootPedal_Coarse

Foot Pedal: 4 (coarse) 36 (fine).

Affects:

Whatever the musician sets this controller to affect. Often, this is used to control the a parameter such as what Aftertouch can. This foot pedal is a continuous controller (ie, potentiometer). If a MultiTimbral device, then each Part usually has its own Foot Pedal value.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is minimum effect.

kFootPedal_Fine

public static final int kFootPedal_Fine

kPortamentoTime_Coarse

public static final int kPortamentoTime_Coarse

Portamento Time: 5 (coarse) 37 (fine).

Affects:

The rate at which portamento slides the pitch between 2 notes. If a MultiTimbral device, then each Part usually has its own Portamento Time.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is slowest rate.

kPortamentoTime_Fine

public static final int kPortamentoTime_Fine

kDataEntry_Coarse

public static final int kDataEntry_Coarse

Data Entry Slider: 6 (coarse) 38 (fine).

The value of some Registered or Non-Registered Parameter. Which parameter is affected depends upon a preceding RPN or NRPN message (which itself identifies the parameter's number).

On some devices, this slider may not be used in conjunction with RPN or NRPN messages. Instead the musician can set the slider to control a single parameter directly, often a parameter such as what Aftertouch can control.

If a MultiTimbral device, then each Part usually has its own RPN and NRPN settings, and Data Entry slider setting.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is minimum effect.

kDataEntry_Fine

public static final int kDataEntry_Fine

kVolume_Coarse

public static final int kVolume_Coarse

Volume : 7 (coarse) 39 (fine).

Affects:

The device's main volume level. If a MultiTimbral device, then each Part has its own volume. In this case, a device's master volume may be controlled by another method such as the Universal SysEx Master Volume message, or take its volume from one of the Parts, or be controlled by a General Purpose Slider controller.

Expression Controller also may affect the volume.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is no volume at all.

NOTE: Most all devices ignore the Fine adjust (#39) for Volume, and just implement Coarse adjust (#7) because 14-bit resolution isn't needed for this. In this case, maximum is 127 and off is 0.

kVolume_Fine

public static final int kVolume_Fine

kBalance_Coarse

public static final int kBalance_Coarse

Balance: 8 (coarse) 40 (fine).

Affects:

The device's stereo balance (assuming that the device has stereo audio outputs). If a MultiTimbral device, then each Part usually has its own Balance. This is generally when Balance becomes useful, because then you can use Pan, Volume, and Balance controllers to internally mix all of the Parts to the device's stereo outputs. Typically, Balance would be used on a Part that had stereo elements (where you wish to adjust the volume of the stereo elements without changing their pan positions), whereas Pan is more appropriate for a Part that is strictly a "mono instrument".

Value Range:

14-bit coarse/fine resolution. 16,384 possible setting, 0x0000 to 0x3FFF where 0x2000 is center balance, 0x0000 emphasizes the left elements mostly, and 0x3FFF emphasizes the right elements mostly. Some devices only respond to coarse adjust (128 settings) where 64 is center, 0 is leftmost emphasis, and 127 is rightmost emphasis.

NOTE: Most all devices ignore the Fine adjust (#40) for Balance, and just implement Coarse adjust (#8) because 14-bit resolution isn't needed for this.

kBalance_Fine

public static final int kBalance_Fine

kPanPosition_Coarse

public static final int kPanPosition_Coarse

Pan: 10 (coarse) 42 (fine).

Affects:

Where within the stereo field the device's sound will be placed (assuming that it has stereo audio outputs). If a MultiTimbral device, then each Part usually has its own pan position. This is generally when Pan becomes useful, because then you can use Pan, Volume, and Balance controllers to internally mix all of the Parts to the device's stereo outputs.

Value Range:

14-bit coarse/fine resolution. 16,384 possible positions, 0x0000 to 0x3FFF where 0x2000 is center position, 0x0000 is hard left, and 0x3FFF is hard right. Some devices only respond to coarse adjust (128 positions) where 64 is center, 0 is hard left, and 127 is hard right.

NOTE: Most all devices ignore the Fine adjust (#42) for Pan, and just implement Coarse adjust (#10) because 14-bit resolution isn't needed for this.

kPanPosition_Fine

public static final int kPanPosition_Fine

kExpression_Coarse

public static final int kExpression_Coarse

Expression: 11 (coarse) 43 (fine).

Affects:

This is a percentage of Volume (ie, as set by Main Volume Controller). In other words, Expression divides the current volume into 16,384 steps (or 128 if 8-bit instead of 14-bit resolution is used). Volume Controller is used to set the overall volume of the entire musical part, whereas Expression is used for doing crescendos and decrescendos. By having both a master Volume and sub-Volume (ie, Expression), it makes possible doing crescendos and decrescendos without having to do algebraic calculations to maintain the relative balance between instruments. When Expression is at 100% (ie, the maximum of 0x3FFF), then the volume represents the true setting of Main Volume Controller. Lower values of Expression begin to subtract from the volume. When Expression is 0% (ie, 0x0000), then volume is off. When Expression is 50% (ie, 0x1FFF), then the volume is cut in half.

Here's how Expression is typically used. Let's assume only the MSB is used (ie, #11) and therefore only 128 steps are possible. Set the Expression for every MIDI channel to one initial value, for example 100. This gives you some leeway to increase the expression percentage (ie, up to 127 which is 100%) or decrease it. Now, set the channel (ie, instrument) "mix" using Main Volume Controllers. Maybe you'll want the drums louder than the piano, so the former has a Volume Controller value of 110 whereas the latter has a value of 90, for example. Now if, at some point, you want to drop the volumes of both instruments to half of their current Main Volumes, then send Expression values of 64 (ie, 64 represents a 50% volume percentage since 64 is half of 128 steps). This would result in the drums now having an effective volume of 55 and the piano having an effective volume of 45. If you wanted to drop the volumes to 25% of their current Main Volumes, then send Expression values of 32. This would result in the drums now having an effective volume of approximately 27 and the piano having an effective volume of approximately 22. And yet, you haven't had to change their Main Volumes, and therefore still maintain that relative mix between the two instruments. So think of Main Volume Controllers as being the individual faders upon a mixing console. You set up the instrumental balance (ie, mix) using these values. Then you use Expression Controllers as "group faders", whereby you can increase or decrease the volumes of one or more tracks without upsetting the relative balance between them.

If a MultiTimbral device, then each Part usually has its own Expression level.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is minimum effect.

NOTE: Most all devices ignore the Fine adjust (#43) for Expression, and just implement Coarse adjust (#11) because 14-bit resolution isn't needed for this.

kExpression_Fine

public static final int kExpression_Fine

kEffectControl1_Coarse

public static final int kEffectControl1_Coarse

Effect Control 1: 12 (coarse) 44 (fine).

Affects:

This can control any parameter relating to an effects device, such as the Reverb Decay Time for a reverb unit built into a GM sound module.

NOTE: There are separate controllers for setting the Levels (ie, volumes) of Reverb, Chorus, Phase Shift, and other effects.

If a MultiTimbral device, then each Part usually has its own Effect Control 1.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is minimum effect.

kEffectControl1_Fine

public static final int kEffectControl1_Fine

kEffectControl2_Coarse

public static final int kEffectControl2_Coarse

Effect Control 2: 13 (coarse) 45 (fine).

Affects:

This can control any parameter relating to an effects device, such as the Reverb Decay Time for a reverb unit built into a GM sound module.

NOTE: There are separate controllers for setting the Levels (ie, volumes) of Reverb, Chorus, Phase Shift, and other effects.

If a MultiTimbral device, then each Part usually has its own Effect Control 2.

Value Range:

14-bit coarse/fine resolution. 0x0000 to 0x3FFF where 0 is minimum effect.

kEffectControl2_Fine

public static final int kEffectControl2_Fine

kGeneralPurposeSlider1

public static final int kGeneralPurposeSlider1

General Purpose Sliders: 16, 17, 18, 19.

Affects:

Whatever the musician sets this controller to affect. There are 4 General Purpose Sliders, with the above controller numbers. Often, these are used to control parameters such as what Aftertouch can. If a MultiTimbral device, then each Part usually has its own responses to the 4 General Purpose Sliders. Note that these sliders don't have a fine adjustment.

Value Range:

0x00 to 0x7F where 0 is minimum effect.

kGeneralPurposeSlider2

public static final int kGeneralPurposeSlider2

kGeneralPurposeSlider3

public static final int kGeneralPurposeSlider3

kGeneralPurposeSlider4

public static final int kGeneralPurposeSlider4

kHoldPedal_Switch

public static final int kHoldPedal_Switch

Hold Pedal : 64.

Affects:

When on, this holds (ie, sustains) notes that are playing, even if the musician releases the notes (ie, the Note Off effect is postponed until the musician switches the Hold Pedal off). If a MultiTimbral device, then each Part usually has its own Hold Pedal setting.

NOTE: When on, this also postpones any All Notes Off controller message on the same channel.

Value Range:

0 (to 63) is off. 127 (to 64) is on.

kPortamento_Switch

public static final int kPortamento_Switch

Portamento : 65.

Affects:

Whether the portamento effect is on or off. If a MultiTimbral device, then each Part usually has its own portamento on/off setting.

NOTE: There is another controller to set the portamento time.

Value Range:

0 (to 63) is off. 127 (to 64) is on.

kSustenutoPedal_Switch

public static final int kSustenutoPedal_Switch

Sustenuto : 66.

Affects:

Like the Hold Pedal controller, except this only sustains notes that are already on (ie, the device has received Note On messages, but the respective Note Offs haven't yet arrived) when the pedal is turned on. After the pedal is on, it continues to hold these initial notes all of the while that the pedal is on, but during that time, all other arriving Note Ons are not held. So, this pedal implements a "chord hold" for the notes that are sounding when this pedal is turned on. If a MultiTimbral device, then each Part usually has its own Sustenuto setting.

NOTE: When on, this also postpones any All Notes Off controller message on the same channel for those notes being held.

Value Range:

0 (to 63) is off. 127 (to 64) is on.

kSoftPedal_Switch

public static final int kSoftPedal_Switch

Soft Pedal: 67.

Affects:

When on, this lowers the volume of any notes played. If a MultiTimbral device, then each Part usually has its own Soft Pedal setting.

Value Range:

0 (to 63) is off. 127 (to 64) is on.

kLegatoPedal_Switch

public static final int kLegatoPedal_Switch

Legato Pedal: 68.

Affects:

When on, this causes a legato effect between notes, which is usually achieved by skipping the attack portion of the VCA's envelope. Use of this controller allows a keyboard player to better simulate the phrasing of wind and brass players, who often play several notes with a single tonguing, or simulate guitar pull-offs and hammer-ons (ie, where secondary notes are not picked). If a MultiTimbral device, then each Part usually has its own Legato Pedal setting.

Value Range:

0 (to 63) is off. 127 (to 64) is on.

kHold2Pedal_Switch

public static final int kHold2Pedal_Switch

Hold 2 Pedal: 69.

Affects:

When on, this lengthens the release time of the playing notes' VCA (ie, makes the note take longer to fade out after it's released, versus when this pedal is off). Unlike the other Hold Pedal controller, this pedal doesn't permanently sustain the note's sound until the musician releases the pedal. Even though the note takes longer to fade out when this pedal is on, the note may eventually fade out despite the musician still holding down the key and this pedal. If a MultiTimbral device, then each Part usually has its own Hold 2 Pedal setting.

Value Range:

0 (to 63) is off. 127 (to 64) is on.

kSoundVariation

public static final int kSoundVariation

Sound Variation: 70.

Affects:

Any parameter associated with the circuitry that produces sound. For example, if a device uses looped digital waveforms to create sound, this controller may adjust the sample rate (ie, playback speed), for a "tuning" control. If a MultiTimbral device, then each Part usually has its own patch with its respective VCA, VCF, tuning, sound sources, etc, parameters that can be adjusted with this controller.

NOTE: There are other controllers for adjusting VCA attack and release times, VCF cutoff frequency, and other generic sound parameters.

Value Range:

0 to 127, with 0 being minimum setting.

kSoundTimbre

public static final int kSoundTimbre

Sound Timbre: 71.

Affects:

Controls the (VCF) filter's envelope levels, for a "brightness" control. If a MultiTimbral device, then each Part usually has its own patch with its respective VCF cutoff frequency that can be adjusted with this controller.

NOTE: There are other controllers for adjusting VCA attack and release times, and other generic sound parameters.

Value Range:

0 to 127, with 0 being minimum setting.

kSoundReleaseTime

public static final int kSoundReleaseTime

Sound Release Time: 72.

Affects:

Controls the (VCA) amp's envelope release time, for a control over how long it takes a sound to fade out. If a MultiTimbral device, then each Part usually has its own patch with its respective VCA envelope that can be adjusted with this controller.

NOTE: There are other controllers for adjusting VCA attack time, VCF cutoff frequency, and other generic sound parameters.

Value Range:

0 to 127, with 0 being minimum setting.

kSoundAttackTime

public static final int kSoundAttackTime

Sound Attack Time: 73.

Affects:

Controls the (VCA) amp's envelope attack time, for a control over how long it takes a sound to fade in. If a MultiTimbral device, then each Part usually has its own patch with its respective VCA envelope that can be adjusted with this controller.

NOTE: There are other controllers for adjusting VCA release time, VCF cutoff frequency, and other generic sound parameters.

Value Range:

0 to 127, with 0 being minimum setting.

kSoundBrightness

public static final int kSoundBrightness

Sound Brightness: 74.

Affects:

Controls the (VCF) filter's cutoff frequency, for a "brightness" control. If a MultiTimbral device, then each Part usually has its own patch with its respective VCF cutoff frequency that can be adjusted with this controller.

NOTE: There are other controllers for adjusting VCA attack and release times, and other generic sound parameters.

Value Range:

0 to 127, with 0 being minimum setting.

kSoundControl6

public static final int kSoundControl6

Sound Controls 6-10: 75, 76, 77, 78, 79.

Affects:

These 5 controllers can be used to adjust any parameters associated with the circuitry that produces sound. For example, if a device uses looped digital waveforms to create sound, one controller may adjust the sample rate (ie, playback speed), for a "tuning" control. If a MultiTimbral device, then each Part usually has its own patch with its respective VCA, VCF, tuning, sound sources, etc, parameters that can be adjusted with these controllers.

NOTE: There are other controllers for adjusting VCA attack and release times, and VCF cutoff frequency.

Value Range:

0 to 127, with 0 being minimum setting.

kSoundControl7

public static final int kSoundControl7

kSoundControl8

public static final int kSoundControl8

kSoundControl9

public static final int kSoundControl9

kSoundControl10

public static final int kSoundControl10

kGeneralPurposeButton1_Switch

public static final int kGeneralPurposeButton1_Switch

General Purpose Buttons: 80, 81, 82, 83.

Affects:

Whatever the musician sets this controller to affect. There are 4 General Purpose Buttons, with the above controller numbers. This are either on or off, so they are often used to implement on/off functions, such as a Metronome on/off switch on a sequencer. If a MultiTimbral device, then each Part usually has its own responses to the 4 General Purpose Buttons.

Value Range:

0 (to 63) is off. 127 (to 64) is on.

kGeneralPurposeButton2_Switch

public static final int kGeneralPurposeButton2_Switch

kGeneralPurposeButton3_Switch

public static final int kGeneralPurposeButton3_Switch

kGeneralPurposeButton4_Switch

public static final int kGeneralPurposeButton4_Switch

kPortamentoControl

public static final int kPortamentoControl

kEffectsLevel

public static final int kEffectsLevel

Effects/Reverberation Level: 91.

Affects:

The effects amount (ie, level) for the device. Often, this is the reverb or delay level. If a MultiTimbral device, then each Part usually has its own effects level.

Value Range:

0 to 127, with 0 being no effect applied at all.

kTremuloLevel

public static final int kTremuloLevel

Tremulo Level: 92.

Affects:

The tremulo amount (ie, level) for the device. If a MultiTimbral device, then each Part Parts usually has its own tremulo level.

Value Range:

0 to 127, with 0 being no tremulo applied at all.

kChorusLevel

public static final int kChorusLevel

Chorus Level: 93.

Affects:

The chorus effect amount (ie, level) for the device. If a MultiTimbral device, then each Part usually has its own chorus level.

Value Range:

0 to 127, with 0 being no chorus effect applied at all.

kCelesteLevel

public static final int kCelesteLevel

Celeste Level: 94.

Affects:

The celeste (detune) amount (ie, level) for the device. If a MultiTimbral device, then each Part usually has its own celeste level.

Value Range:

0 to 127, with 0 being no celeste effect applied at all.

kPhaserLevel

public static final int kPhaserLevel

Phaser Level: 95.

Affects:

The Phaser effect amount (ie, level) for the device. If a MultiTimbral device, then each Part usually has its own Phaser level.

Value Range:

0 to 127, with 0 being no phaser effect applied at all.

kDataButtonIncrement

public static final int kDataButtonIncrement

Data Button increment: 96.

Affects:

Causes a Data Button to increment (ie, increase by 1) its current value. Usually, this data button's value is being used to set some Registered or Non-Registered Parameter. Which RPN or NRPN parameter is being affected depends upon a preceding RPN or NRPN message (which itself identifies the parameter's number).

Value Range:

The value byte isn't used and defaults to 0.

kDataButtonDecrement

public static final int kDataButtonDecrement

Data Button decrement: 97.

Affects:

Causes a Data Button to decrement (ie, decrease by 1) its current value. Usually, this data button's value is being used to set some Registered or Non-Registered Parameter. Which RPN or NRPN parameter is being affected depends upon a preceding RPN or NRPN message (which itself identifies the parameter's number).

Value Range:

The value byte isn't used and defaults to 0.

kRegisteredParameter_Coarse

public static final int kRegisteredParameter_Coarse

Registered Parameter Number (RPN) : 101 (coarse) 100 (fine).

Affects:

Which parameter the Data Button Increment, Data Button Decrement, or Data Entry controllers affect. Since RPN has a coarse/fine pair (14-bit), the number of parameters that can be registered is 16,384. That's a lot of parameters that a MIDI device could allow to be controlled over MIDI. It's up to the IMA to assign Registered Parameter Numbers to specific functions.

Value Range:

0 to 16,384 where each value stands for a different RPN. Here are the currently registered parameter numbers:

Pitch Bend Range (ie, Sensitivity) 0x0000

NOTE: The coarse adjustment (usually set via Data Entry 6) sets the range in semitones. The fine adjustment (usually set via Data Entry 38) set the range in cents. For example, to adjust the pitch wheel range to go up/down 2 semitones and 4 cents:

B0 65 00 Controller/channel 0, RPN coarse (101), Pitch Bend Range

B0 64 00 Controller/channel 0, RPN fine (100), Pitch Bend Range

B0 06 02 Controller/channel 0, Data Entry coarse, +/- 2 semitones

B0 26 04 Controller/channel 0, Data Entry fine, +/- 4 cents

Master Fine Tuning (ie, in cents) 0x0001

NOTE: Both the coarse and fine adjustments together form a 14-bit value that sets the tuning in semitones, where 0x2000 is A440 tuning.

Master Coarse Tuning (in half-steps) 0x0002

NOTE: Setting the coarse adjustment adjusts the tuning in semitones, where 0x40 is A440 tuning. There is no need to set a fine adjustment.

RPN Reset 0x3FFF

NOTE: No coarse or fine adjustments are applicable. This is a "dummy" parameter.

Here's the way that you use RPN. First, you decide which RPN you wish to control. Let's say that we wish to set Master Fine Tuning on a device. That's RPN 0x0001. We need to send the device the RPN Coarse and RPN Fine controller messages in order to tell it to affect RPN 0x0001. So, we divide the 0x0001 into 2 bytes, the fine byte and the coarse byte. The fine byte contains bits 0 to 6 of the 14-bit value. The coarse byte contains bits 7 to 13 of the 14-bit value, right-justified. So, here are the RPN Coarse and Fine messages (assuming that the device is responding to MIDI channel 0):

B0 65 00 Controller/channel 0, RPN coarse (101), bits 7 to 13 of 0x0001, right-justified (with high bit clear)

B0 64 01 Controller/channel 0, RPN fine (100), bits 0 to 6 of 0x0001, (with high bit clear)

Now, we've just told the device that any Data Button Increment, Data Button decrement, or Data Entry controllers it receives should affect the Master Fine Tuning. Let's say that we wish to set this tuning to the 14-bit value 0x2000 (which happens to be centered tuning). We could use the Data Entry (coarse and fine) controller messages as so to send that 0x2000:

B0 06 40 Controller/channel 0, Data Entry coarse (6), bits 7 to 13 of 0x2000, right-justified (with high bit clear)

B0 26 00 Controller/channel 0, Data Entry fine (38), bits 0 to 6 of 0x2000, (with high bit clear)

As a final example, let's say that we wish to increment the Master Fine Tuning by one (ie, to 0x2001). We could use the Data Entry messages again. Or, we could use the Data Button Increment, which doesn't have a coarse/fine pair of controller numbers like Data Entry.

B0 60 00 Controller/channel 0, Data Button Increment (96), last byte is unused

Of course, if the device receives RPN messages for another parameter, then the Data Button Increment, Data Button Decrement, and Data Entry controllers will switch to adjusting that parameter.

RPN 0x3FFF (reset) forces the Data Button increment, Data Button decrement, and Data Entry controllers to not adjust any RPN (ie, disables those buttons' adjustment of any RPN).

kRegisteredParameter_Fine

public static final int kRegisteredParameter_Fine

kNonRegisteredParameter_Coarse

public static final int kNonRegisteredParameter_Coarse

Non-Registered Parameter Number (NRPN): 99 (coarse) 98 (fine).

Affects:

Which parameter the Data Button Increment, Data Button Decrement, or Data Entry controllers affect. Since NRPN has a coarse/fine pair (14-bit), the number of parameters that can be registered is 16,384. That's a lot of parameters that a MIDI device could allow to be controlled over MIDI. It's entirely up to each manufacturer which parameter numbers are used for whatever purposes. These don't have to be registered with the IMA.

Value Range:

The same scheme is used as per the Registered Parameter controller. Refer to that. By contrast, the coarse/fine messages for NRPN for the preceding RPN example would be:

B0 63 00

B0 62 01

NOTE: Since each device can define a particular NRPN controller number to control anything, it's possible that 2 devices may interpret the same NRPN number in different manners. Therefore, a device should allow a musician to disable receipt of NRPN, in the event that there is a conflict between the NRPN implementations of 2 daisy-chained devices.

kNonRegisteredParameter_Fine

public static final int kNonRegisteredParameter_Fine

kAllSoundOff

public static final int kAllSoundOff

All Sound Off: 120.

Affects:

Mutes all sounding notes that were turned on by received Note On messages, and which haven't yet been turned off by respective Note Off messages. This message is not supposed to mute any notes that the musician is playing on the local keyboard. So, if a device can't distinguish between notes played via its MIDI IN and notes played on the local keyboard, it should not implement All Sound Off.

NOTE: The difference between this message and All Notes Off is that this message immediately mutes all sound on the device regardless of whether the Hold Pedal is on, and mutes the sound quickly regardless of any lengthy VCA release times. It's often used by sequencers to quickly mute all sound when the musician presses "Stop" in the middle of a song.

Value Range:

The value byte isn't used and defaults to 0.

kAllControllersOff

public static final int kAllControllersOff

All Controllers Off : 121.

Affects:

Resets all controllers to default states. This means that all switches (such as Hold Pedal) are turned off, and all continuous controllers (such as Mod Wheel) are set to minimum positions. If the device is MultiTimbral, this only affects the Part assigned to the MIDI channel upon which this message is received.

Value Range:

The value byte isn't used and defaults to 0.

kLocalKeyboard_Switch

public static final int kLocalKeyboard_Switch

Channel Mode Message: Local Control.

When Local Control is Off, all devices on a given channel will respond only to data received over MIDI. Played data, etc. will be ignored. Local Control On restores the functions of the normal controllers.

Value 0x00, Local Control Off.

Value 0x7F, Local Control On.

Turns the device's keyboard on or off locally. If off, the keyboard is disconnected from the device's internal sound generation circuitry. So when the musician presses keys, the device doesn't trigger any of its internal sounds. But, the keyboard still generates Note On, Note Off, Aftertouch, and Channel Pressure messages. In this way, a musician can eliminate a situation where MIDI messages get looped back (over MIDI cables) to the device that created those messages. Furthermore, if a device is only going to be played remotely via MIDI, then the keyboard may be turned off in order to allow the device to concentrate more on dealing with MIDI messages rather than scanning the keyboard for depressed notes and varying pressure.

kAllNotesOff

public static final int kAllNotesOff

Channel Mode Message: All Notes Off.

When an All Notes Off is received, all oscillators will turn off.

Value 0x00, All Notes Off.

Turns off all notes that were turned on by received Note On messages, and which haven't yet been turned off by respective Note Off messages. This message is not supposed to turn off any notes that the musician is playing on the local keyboard. So, if a device can't distinguish between notes played via its MIDI IN and notes played on the local keyboard, it should not implement All Notes Off. Furthermore, if a device is in Omni On state, it should ignore this message on any channel.

NOTE: If the device's Hold Pedal controller is on, the notes aren't actually released until the Hold Pedal is turned off. See All Sound Off controller message for turning off the sound of these notes immediately. The value byte isn't used and defaults to 0.

kOmniModeOff

public static final int kOmniModeOff

Channel Mode Message: Omni Mode Off.

(Note: Also causes All Notes Off.)

Value 0x00, Omni Mode Off.

The value byte isn't used and defaults to 0.

kOmniModeOn

public static final int kOmniModeOn

Channel Mode Message: Omni Mode On.

(Note: Also causes All Notes Off.)

Value 0x00, Omni Mode On.

The value byte isn't used and defaults to 0.

kMonoOperation

public static final int kMonoOperation

Channel Mode Message: Mono Mode On (Poly Off).

(Note: Also causes All Notes Off.)

Value 0x00, Omni Mode On.

Value 0x0X, Omni Mode Off, X is the number of channels.

Affects:

Enables Monophonic operation (thus disabling Polyphonic operation). See the discussion on MIDI Modes.

Value Range: If Omni is off, this Value tells how many MIDI channels the device is expected to respond to in Mono mode. In other words, if Omni is off, this value is used to select a limited set of the 16 MIDI channels (ie, 1 to 16) to respond to.Conversely, if Omni is on, this Value is ignored completely, and the device only ever plays one note at a time (unless a MultiTimbral device). So, the following discussion is only relevant if Omni Off.

If Value is 0, then the number of MIDI channels that the device will respond to simultaneously will be equal to how many voices the device can sound simultaneously. In other words, if the device can sound at least 16 voices simultaneously, then it can respond to Voice Category messages on all 16 channels. Of course, being Monophonic operation, the device can only sound one note at a time per each MIDI channel. So, it can sound a note on channel 1 and channel 2 simultaneously, for example, but can't sound 2 notes both on channel 1 simultaneously.

Of course, MultiTimbral devices completely violate the preceding theory. MultiTimbral devices always can play polyphonically on each MIDI channel. If Value is 0, what this means is that the device can play as many MIDI channels as it has Parts. So, if the device can play 16 of its patches simultaneously, then it can respond to Voice Category messages on all 16 channels.

If Value is not 0 (ie, 1 to 16), then that's how many MIDI channels the device is allowed to respond to. For example, a value of 1 would mean that the device would only be able to respond to 1 MIDI channel. Since the device is also limited to sounding only 1 note at a time on that MIDI channel, then the device would truly be a Monophonic instrument incapable of sounding more than one note at a time. If a device is asked to respond to more MIDI channels than it has voices to accommodate, then it will handle only as many MIDI channels as it has voices. For example, if an 8-voice synthesizer, on Base Channel 0, receives the value 16 in the Mono message, then the synthesizer will play messages on MIDI channels 0 to 7 and ignore messages on 8 to 15.

Again, MultiTimbral devices violate the above theory. A value of 1 would mean that the device would only be able to respond to 1 MIDI channel (and therefore only play 1 Part), but would do so Polyphonically. If a MultiTimbral device is asked to respond to more MIDI channels than it has Parts to accommodate, then it will handle only as many MIDI channels as it has Parts. For example, if a device can play only 5 Patches simultaneously, and receives the value 8 in the Mono message, then the device will play 5 patches on MIDI channels 0 to 4 and ignore messages on channels 5 to 7.

Most devices capable of Monophonic operation, allow the user to specify a Base Channel. This will be the lowest MIDI channel that the device responds to. For example, if a Mono message specifies that the device is to respond to only 2 channels, and its Base Channel is 2, then the device responds to channels 2 and 3.

NOTE: When a device receives a Mono Operation message, it should automatically turn off all playing notes.

kPolyOperation

public static final int kPolyOperation

Channel Mode Message: Poly Mode On (Mono Off).

(Note: Also causes All Notes Off.)

Value 0x00, Poly Mode On.

names

public static final java.lang.String[] names

English strings corresponding to all known Controllers.

Constructor Detail

Controller

public Controller(int num)

Initializer.

Parameters:

num - In the range 0-127. Some Controllers are not previously defined.

Method Detail

toName

public static java.lang.String toName(int cntlNumber)

Conversion Utility.

Parameters:

cntlNumber - Should be in the range 0..127

toName

public java.lang.String toName()

Accessor.

toString

public java.lang.String toString()

Accessor.

Overrides:

toString in class MidiNumber