Main Content

midicontrols

Open group of MIDI controls for reading

collapse all in page

Syntax

midicontrolsObject = midicontrols
midicontrolsObject = midicontrols(controlNumbers)
midicontrolsObject = midicontrols(controlNumbers,initialValues)
midicontrolsObject = midicontrols(___,'MIDIDevice',deviceName)
midicontrolsObject = midicontrols(___,'OutputMode',mode)

Description

midicontrolsObject = midicontrols returns an object that listens to all controls on your default MIDI device.

Call midiread with the object to return the values of controls on your MIDI device. If you call midiread before a control is moved, midiread returns the initial value of your midicontrols object.

example

midicontrolsObject = midicontrols(controlNumbers) listens to controls specified by controlNumbers on your default MIDI device.

example

midicontrolsObject = midicontrols(controlNumbers,initialValues) specifies initialValues associated with controlNumbers.

example

midicontrolsObject = midicontrols(___,'MIDIDevice',deviceName) specifies the MIDI device your midicontrols object listens to, using any of the previous syntaxes.

example

midicontrolsObject = midicontrols(___,'OutputMode',mode) specifies the range of values returned by midiread and accepted as initialValues for midicontrols and as controlValues for midisync.

example

Examples

collapse all

Create a midicontrols object and read the default control value.

midicontrolsObject = midicontrols
midiread(midicontrolsObject)
midicontrolsObject = 

midicontrols object: any control on 'BCF2000'

ans =

     0

Move any control on your MIDI device. Use midiread to return the most recent value of the last control moved.

midiread(midicontrolsObject)
ans =

    0.3810

Use midiid to identify the name of your MIDI device and a specified control. Move the MIDI control you want to identify.

[controlNumber,deviceName] = midiid;
Move the control you wish to identify; type ^C to abort.
Waiting for control message...

Create an object that responds to the control you specified.

midicontrolsObject = midicontrols(controlNumber);

Move your selected MIDI control, and then use midiread to return its most recent value.

midicontrolsObject = midiread(midicontrolsObject);
ans =

    0.4048

Determine the control numbers of four different controls on your MIDI device.

[controlNumber1,~] = midiid;
[controlNumber2,~] = midiid;
[controlNumber3,~] = midiid;
[controlNumber4,~] = midiid;

controlNumbers = [controlNumber1,controlNumber3;...
                  controlNumber2,controlNumber4]
Move the control you wish to identify; type ^C to abort.
Waiting for control message... done
Move the control you wish to identify; type ^C to abort.
Waiting for control message... done
Move the control you wish to identify; type ^C to abort.
Waiting for control message... done
Move the control you wish to identify; type ^C to abort.
Waiting for control message... done

controlNumbers =

        1081        1085
        1082        1087

Create a midicontrols object that listens to your specified controls. Specify an initial value for all controls.

initialValue = 0.5;
midicontrolsObject = midicontrols(controlNumbers,initialValue);

Move one of your specified controls, and then read the latest value of all your specified controls.

midiread(midicontrolsObject)
ans =

    0.0873    0.5000
    0.5000    0.5000

Determine the control numbers of two different controls on your MIDI device.

[controlNumber1,~] = midiid;
[controlNumber2,~] = midiid;

controlNumbers = [controlNumber1,controlNumber2];

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

Create a midicontrols object that listens to your specified controls. Specify an initial value for all controls.

initialValue = 12;
midicontrolsObject = midicontrols(controlNumbers,initialValue,'OutputMode','rawmidi');

Move one of your specified controls, and then read the latest value of all your specified controls.

midiread(midicontrolsObject)
ans =

    63    12

Assume that your MIDI device is a Behringer BCF2000. Enter this syntax at the MATLAB® command line:

setpref midi DefaultDevice BCF2000
This preference persists across MATLAB sessions. You do not need to set it again unless you want to change your default device.

Assume that your MIDI device is a Behringer BCF2000 and has a control with identification number 1001. Create a midicontrols object, which listens to control number 1001 on your Behringer BCF2000 device.

midicontrolsObject = midicontrols(1001,'MIDIDevice','BCF2000');

Input Arguments

collapse all

MIDI device control numbers, specified as an integer or array of integers. Use midiid to interactively identify the control numbers of your device. See MIDI Device Control Numbers for an advanced explanation of how controlNumbers are determined.

If you specify controlNumbers as an empty vector, [ ], then the midicontrols object responds to any control on your MIDI device.

Example: 1081

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Initial values of MIDI controls, specified as a scalar or an array the same size as controlNumbers. If you specify initialValues as a scalar, all controls specified by controlNumbers are assigned that value.

The value associated with your MIDI controls cannot be determined until you move a MIDI control. If you specify an initial value associated with your MIDI control, the initial value is returned by the midiread function until the MIDI control is moved.

  • If OutputMode is specified as 'normalized', then initial values must be in the range [0,1]. Actual initial values are quantized and can be slightly different from initial values specified when your midicontrols object is created.

  • If OutputMode is specified as 'rawmidi', then initial values must be integers in the range [0,127]

Example: 0.3

Example: [0,0.3,0.6]

Example: 5

Example: [5;15;20]

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

MIDI device name, assigned by the device manufacturer or host operating system, specified as a string. The specified deviceName can be a substring of the exact name of your device. If you do not specify deviceName, the default MIDI device is used. See Set the Default MIDI Device for an example of specifying a default MIDI device.

If you do not set a default MIDI device, the host operating system chooses the default device in an unspecified way. As a best practice, use midiid to identify the name of the device you want.

Example: 'MIDIDevice','BCF2000 MIDI 1'

Data Types: char | string

Output mode for MIDI control value, specified as 'normalized' or 'rawmidi'.

  • 'normalized' — Values of your MIDI control are normalized. If your midicontrols object is called by midiread, then values in the range [0,1] are returned.

  • 'rawmidi' — Values of your MIDI control are not normalized. If your midicontrols object is called by midiread, then integer values in the range [0,127] are returned.

Example: 'OutputMode','normalized'

Example: 'OutputMode','rawmidi'

Data Types: char | string

Output Arguments

collapse all

Object that listens to the controls on a MIDI device.

More About

collapse all

MIDI Device Control Numbers

MATLAB defines MIDI device 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.

Version History

Introduced in R2016a

See Also

| | | | | | | | |

Topics