====== MIDI Remote Control ======

mAirList can use any MIDI device for remote control. You can also use scripts to send MIDI messages from mAirList to a MIDI device.

===== Configuration =====

Open the config app or Control Panel, go to the //Remote Control// page, and add a new //MIDI// remote control.

In the dialog that appears, first select the desired MIDI device from the list on the top:

{{ :config:remotecontrol:pasted:20160830-121900.png?400 }}

The //Monitor// function is only available when a valid device is selected. It will always be enabled when you configure an enabled MIDI remote from the Control Panel, i.e., if the mAirList main program is running. All received MIDI messages will be displayed in the monitor list:

{{ :config:remotecontrol:pasted:20160830-121933.png?400 }}

You can just double-click any message to add it to the commands list and assign a [[reference:remote_control_commands|remote control command]] to it:

{{ :config:remotecontrol:pasted:20160830-121319.png?400 }}

Each MIDI message consists of three values:

  * Status (or Channel)
  * Data1
  * Data2

The values are displayed in hexadecimal format. For Data2, there is an additional //Condition//, so that the remote control command will be executed for a range of Data2 values:

  * ''='' - Command will be executed if Data2 equals the specified value.
  * ''!='' - Command will be executed if Data2 does not equal the specified value.
  * ''<'' - Command will be executed if Data2 is less than the specified value.
  * ''<nowiki><=</nowiki>'' - Command will be executed if Data2 is less or equal the specified value.
  * ''>'' - Command will be executed if Data2 is greater than the specified value.
  * ''>='' - Command will be executed if Data2 is greater or equal the specified value.
  * ''*'' - Command will be executed regardless of the Data2 value.

When using ranges for Data2, you can include the ''$DATA2'' variable in the remote control command, which will be replaced by the received Data2 value (in the range 0..127, decimal notation). This is particularly useful when you want to use a fader on your MIDI controller to control the volume of a player in mAirList. Just type the following command:

  PLAYER 1-1 VOLUME $DATA2/127

Or for voicetracking player A:

  VT PLAYER A VOLUME $DATA2/127

This will set the volume to the fader position. The ''/127'' parts defines the 0 dB point to be at the upper end of the fader range. You could also use a value like ''/100'' if you want some overhead in the volume.

The ''VOLUME'' command will automatically use a reasonable logarithmic scale to convert the fader value to a volume. There is no need for any logarithmic conversions.

===== Scripting =====

Any received MIDI message will also be passed to background scripts, using the following procedure:

  // Called when a MIDI message is received
  procedure OnMidiMessage(Device: integer; Status, Data1, Data2: byte);
  begin
  end;
  
There is another procedure that will catch all MIDI SysEx messages:

  // Called when a MIDI sysex is received
  procedure OnMidiSysex(Device: integer; Data: string);
  begin
  end;

If you want to send back messages to the MIDI device, you should first enumerate the available devices, as the order of the output devices will not necessarily coincide with the order of the input devices. The following procedure will list all available output devices to the System Log:

  MidiOutListDevices;
  
At the beginning of your script (or in the ''OnLoad'' procedure in case of a background script), you must first use the MidiOutOpen procedure to open the device for output, e.g. the device with index 1:

  MidiOutOpen(1);
  
Then you can send messages to that device. Note that we use hexadecimal values here, prefixed by ''$'' in the Pascal language.

  MidiOut(1, $B0, $10, 0); // device, status, data1, data2
  
There is also a procedure to send out SysEx messages:

  MidiOutSysEx(1, 'somesysexdata');
 
At the end of the script, or in ''OnUnload'', you should close the device again:

  MidiOutClose(1);