MIDI Control Surface Interface

About MIDI

Musical Instrument Digital Interface (MIDI) was originally developed to interconnect electronic musical instruments. This interface is flexible and has uses in applications far beyond musical instruments. Its simple unidirectional messaging protocol supports many different kinds of messaging. One kind of MIDI message is the Control Change message, which is used to communicate changes in controls, such as knobs, sliders, and buttons.

MIDI Control Surfaces

A MIDI control surface is a device with controls that sends MIDI Control Change messages when you turn a knob, move a slider, or push a button on its surface. Each Control Change message indicates which control changed and what its new position is.

Because the MIDI messaging protocol is unidirectional, determining a particular controller position requires that the receiver listen for Control Change messages that the controller sends. The protocol does not support querying the MIDI controller for its position.

The simplest MIDI control surfaces are unidirectional: They send MIDI Control Change messages but do not receive them. More sophisticated control surfaces are bidirectional: They can both send and receive Control Change messages. These control surfaces have knobs or sliders that can operate automatically. For example, a control surface can have motorized sliders or knobs. When it receives a Control Change message, the appropriate control moves to the position in the message.

Use MIDI Control Surfaces with MATLAB and Simulink

Audio Toolbox™ enables you to use MIDI control surfaces to control MATLAB^® programs and Simulink^® models by providing the capability to listen to Control Change messages. The toolbox also provides a limited capability to send Control Change messages to support synchronizing MIDI controls. This tutorial covers general MIDI functions. For functions specific to audio plugins in MATLAB, see MIDI Control for Audio Plugins. The Audio Toolbox general interface to MIDI control surfaces includes five functions and one block:

• midiid –– Interactively identify MIDI control.

• midicontrols –– Open group of MIDI controls for reading.

• midiread –– Return most recent value of MIDI controls.

• midisync –– Send values to MIDI controls for synchronization.

• midicallback –– Call function handle when MIDI controls change value.

• MIDI Controls (block) –– Output values from controls on MIDI control surface. The MIDI Controls block combines functionality of the general MIDI functions into one block for the Simulink environment.

This diagram shows a typical workflow involving general MIDI functions in MATLAB. For the Simulink environment, follow steps 1 and 2, and then use the MIDI Controls block for a user-interface guided workflow.

1. Connect MIDI Device and Then Start MATLAB

Before starting MATLAB, connect your MIDI control surface to your computer and turn it on. For connection instructions, see the instructions for your MIDI device. If you start MATLAB before connecting your device, MATLAB might not recognize your device when you connect it. To correct the problem, restart MATLAB with the device already connected.

2. Determine Device Name and Control Numbers

Use the midiid function to determine the device name and control numbers of your MIDI control surface. After you call midiid, it continues to listen until it receives a Control Change message. When it receives a Control Change message, it returns the control number associated with the MIDI controller number that you manipulated, and optionally returns the device name of your MIDI control surface. The manufacturer and host operating system determine the device name. See Control Numbers for an explanation of how MATLAB calculates the control number.

To set a default device name, see Set Default MIDI Device.

 View Example

Call midiid with two outputs and then move a controller on your MIDI device. midiid returns the control number specific to the controller you moved and the device name of the MIDI control surface.

[controlNumber,deviceName] = midiid;

3. Create Listener for Control Change Messages

Use the midicontrols function to create an object that listens for Control Change messages and caches the most recent values corresponding to specified controllers. When you create a midicontrols object, you specify a MIDI control surface by its device name and specific controllers on the surface by their associated control numbers. Because the midicontrols object cannot query the MIDI control surface for initial values, consider setting initial values when creating the object.

 View Example

Identify two control numbers on your MIDI control surface. Choose initial control values for the controls you identified. Create a midicontrols object that listens to Control Change messages that arrive from the controllers you identified on the device you identified. When you create your midicontrols object, also specify initial control values. These initial control values work as default values until a Control Change message is received.

controlNum1 = midiid;
[controlNum2,deviceName] = midiid;
initialControlValues = [0.1,0.9];

midicontrolsObject = midicontrols([controlNum1,controlNum2], ...
    initialControlValues, ...
    'MIDIDevice',deviceName);

4. Get Current Control Values

Use the midiread function to query your midicontrols object for current control values. midiread returns a matrix with values corresponding to all controllers the midicontrols object is listening to. Generally, you want to place midiread in an audio stream loop for continuous updating.

 View Example

Place midiread in an audio stream loop to return the current control value of a specified controller. Use the control value to apply gain to an audio signal.

[controlNumber, deviceName] = midiid;
initialControlValue = 1;
midicontrolsObject = midicontrols(controlNumber,initialControlValue,'MIDIDevice',deviceName);

% Create a dsp.AudioFileReader System object™ with default settings. Create
% an audioDeviceWriter System object and specify the sample rate.
fileReader = dsp.AudioFileReader('RockDrums-44p1-stereo-11secs.mp3');
deviceWriter = audioDeviceWriter(...
    'SampleRate',fileReader.SampleRate);

% In an audio stream loop, read an audio signal frame from the file, apply
% gain specified by the control on your MIDI device, and then write the
% frame to your audio output device. By default, the control value returned
% by midiread is normalized.
while ~isDone(fileReader)
    audioData = step(fileReader);
    
    controlValue = midiread(midicontrolsObject);
    
    gain = controlValue*2;
    audioDataWithGain = audioData*gain;
    
    play(deviceWriter,audioDataWithGain);
end

% Close the input file and release your output device.
release(fileReader);
release(deviceWriter);

5. Synchronize Bidirectional MIDI Control Surfaces

You can use midisync to send Control Change messages to your MIDI control surface. If the MIDI control surface is bidirectional, it adjusts the specified controllers. One important use of midisync is to set the controller positions on your MIDI control surface to initial values.

 View Example

In this example, you initialize a controller on your MIDI control surface to a specified position. Calling midisync(midicontrolsObject) sends a Control Change message to your MIDI control surface, using the initial control values specified when you created the midicontrols object.

[controlNumber,deviceName] = midiid;
initialControlValue = 0.5;
midicontrolsObject = midicontrols(controlNumber,initialControlValue,'MIDIDevice',deviceName);

midisync(midicontrolsObject);

Another important use of midisync is to update your MIDI control surface if control values are adjusted in an audio stream loop. In this case, you call midisync with both your midicontrols object and the updated control values.

 View Example

In this example, you check the normalized output volume in an audio stream loop. If the volume is above a given threshold, midisync is called and the MIDI controller that controls the applied gain is reduced.

[controlNumber, deviceName] = midiid;
initialControlValue = 0.5;
midicontrolsObject = midicontrols(controlNumber,initialControlValue);
fileReader = dsp.AudioFileReader('Ambiance-16-44p1-mono-12secs.wav');
deviceWriter = audioDeviceWriter(...
    'SampleRate',fileReader.SampleRate);

% Synchronize specified initial value with the MIDI control surface.
midisync(midicontrolsObject);          

while ~isDone(fileReader)
    audioData = step(fileReader);
    controlValue = midiread(midicontrolsObject);
    gain = controlValue*2;
    audioDataWithGain = audioData*gain;
    
    % Check if max output is above a given threshold.
    if max(audioDataWithGain) > 0.7
        
        % Force new control value to be nonnegative.
        newControlValue = max(0,controlValue-0.5);
        
        % Send a Control Change message to the MIDI control surface.
        midisync(midicontrolsObject,newControlValue)
    end
    
    play(deviceWriter,audioDataWithGain);
end

release(fileReader);
release(deviceWriter);

midisync is also a powerful tool in systems that also involve user interfaces (UIs), so that when one control is changed, the other control tracks it. Typically, you implement such tracking by setting callback functions on both the midicontrols object (using midicallback) and the UI control. The callback for the midicontrols object sends new values to the UI control. The UI uses midisync to send new values to the midicontrols object and MIDI control surface. See midisync for examples.

Alternative to Stream Processing

You can use midicallback as an alternative to placing midiread in an audio stream loop. If a midicontrols object receives a Control Change message, midicallback automatically calls a specified function handle. The callback function typically calls midiread to determine the new value of the MIDI controls. You can use this callback when you want a MIDI controller to trigger an action, such as updating a UI. Using this approach prevents having a MATLAB program continuously running in the command window.

Set Default MIDI Device

You can set the default MIDI device in the MATLAB environment by using the setpref function. Use midiid to determine the name of the device, and then use setpref to set the preference.

[~,deviceName] = midiid

Move the control you wish to identify; type ^C to abort.
Waiting for control message... done

deviceName =

BCF2000

setpref('midi','DefaultDevice',deviceName)

This preference persists across MATLAB sessions, so you only have to set it once, unless you want to change devices.

If you do not set this preference, MATLAB and the host operating system choose a device for you. However, such autoselection can cause unpredictable results because many computers have "virtual" (software) MIDI devices installed that you might not be aware of. For predictable behavior, set the preference.

Control Numbers

MATLAB defines control numbers as (MIDI channel number) × 1000 + (MIDI controller number).

• MIDI channel number is the transmission channel that your device uses to send messages. This value is in the range 1–16.

• MIDI controller number is a number assigned to an individual control on your MIDI device. This value is in the range 1–127.

Your MIDI device determines the values of MIDI channel number and MIDI controller number.