<html>
<head>
<title>Defining MIDI events for StudioSound</title>
</head>
<h2>Defining MIDI events for use in StudioSound</h2>

The file <tt>&lt;StudioSound$Dir&gt;.MIDI.Devices</tt> contains a list of the MIDI-event files to be loaded. The filenames are relative to the path <tt>&lt;StudioSound$Dir&gt;.MIDI</tt>.


<h4>Format of MIDI-event files for StudioSound</h4>
An event starts with the command  <tt>event_start</tt>  followed by the commands for the event and terminated by the command  <tt>event_end</tt><br>

Possible commands in an event are:<br>

<tt>
title &lt;title&gt;<br>
event &lt;event byte stream&gt;<br>
group &lt;groupname&gt;<br>
port &lt;portnumber&gt;<br>
locked<br>
id &lt;id&gt;<br>
</tt>
<br>
Possible commands outside events are:<br>

<tt>
family &lt;family&gt;<br>
port &lt;portnumber&gt;<br>
channel &lt;channel&gt;<br>
no channel<br>
lock<br>
unlock<br>
device "&lt;device name&gt;"<br>
group &lt;groupname&gt;<br>
no group<br>
</tt>
<br>

Other commands:<br>
<tt>
event_start<br>
event_end<br>
</tt>
<br>

Legal port numbers are <b>A</b>, <b>B</b>, <b>C</b> and <b>D</b>.<br>
Legal channel numbers are <b>1</b>-<b>16</b> (<b>&amp;0</b>-<b>&amp;F</b>).<br>
Legal families are <b>&amp;00</b> to <b>&amp;FF</b> (<b>0</b>-<b>255</b>).<br>
Legal ids are <b>&amp;00</b> to <b>&amp;FF</b> (<b>0</b>-<b>255</b>).<br>
The title can be up to 15 chars.<br>
The groupnames can be up to 15 chars.<br>
The event can be up to 100 bytes. The bytes must be written in hex, with a prefixing '<b>&amp;</b>'.<br>


<p><h5>Locking an event</h5>
If an event includes the command <tt>locked</tt> it will be <i>locked</i>, ie. it cannot be edited by the user in the MIDI event window in StudioSound, and the event-byte-stream will not be displayed.<br>

You can include the command <tt>lock</tt> outside the events to lock all subsequent events. The <tt>unlock</tt> command returns control to the individual events.<br>


<p><h5>Groups</h5>
If an event doesn't select a <i>group</i>, the event will be placed in the default group. The default group is set by selecting a group outside all event, and can be re-selected at any point:<br>
<tt>
group &lt;groupname&gt;<br>
</tt>

The groups are not defined anywhere in the file; when a non-existing group is selected, the group is created. A maximum of 32 groups are allowed, any further groups are ignored and the events are placed outside all groups.<br>
Groupnames are case-sensitive, so the groupnames <i>Echo</i> and <i>ECHO</i> refer to two different groups.<br>
If <tt>&lt;groupname&gt;</tt> is empty, the event will be placed outside all groups. You may also use the command <tt>no group</tt> to do this.<br>

A groupname can be no longer than 15 chars.<br>
The groupname is used in the predefined-events menu.<br>


<p><h5>Ports</h5>
If the <i>port number</i> isn't defined in an event, the default port will be used. The default port is <b>A</b>, but can be redefined at any point in an eventfile by setting the port number outside an event:<br>
<tt>
port &lt;portnumber&gt;<br>
</tt>
Allowed port numbers are <b>A</b>, <b>B</b>,<b>C</b> and <b>D</b>.

<p><h5>Channels</h5>
The command <tt>channel &lt;channelnumber&gt;</tt> allows you to set the default <i>channel</i> to be used for all subsequent events.
If no default channel is defined in a file, the channel will not be forced to any specific value, but will remain as specified in the first byte of the event byte stream.<br>
<tt>&lt;channel number&gt;</tt> is from 1-16, eg.:<br>
<tt>
channel 4<br>
</tt>

The channel number may be redefined at any point; to completely de-select the default channel, use the command <tt>no channel</tt>.<br>
The channel cannot be changed inside an event.<br>
The channel will only be used if the first byte in the event byte stream (including the prefix) is not &ampFx.<br>


<p><h5>IDs</h5>
An event may specify a unique <i>id</i>. This is used when loading an EDL which includes MIDI events. If an event in the EDL has an ID &lt;&gt; 0, the list of predefined events will be scanned for a predefined event with the same ID.<br>
If this is found, the MIDI event being loaded is changed to the predefined event with the same ID. This allows events to be interpreted differently on different systems.<br>
IDs are in the range &amp;0000 - &amp;FFFF, but you only specify the bottom byte for each event; the top byte is the <i>id-family</i> and specifies the hardware.<br>
The id-family defaults to 0 (no family) and is set by the command <tt>family &lt;idfamily&gt;</tt>, eg.:

<tt>
family &amp;04<br>
</tt>

The id-families are allocated by Oregan:<br>

<ul>
<li>&amp;00 No family
<li>&amp;01 Yamaha REX50
</ul>


<h5>Prefix and postfix</h5>
You may also define a <i>prefix-byte-stream</i> and a <i>postfix-byte-stream</i>:<br>

<tt>
prefix &lt;byte stream&gt;
postfix &lt;byte stream&gt;
</tt>

The prefix is inserted at the start of all subsequent event-byte-streams and the postfix is appended to the end of the event-byte-stream.<br>
Prefix and postfix can be redefined at any point, but must appear outside the events.<br>


<p><h5>General rules</h5>
Un-recognised lines and lines starting with # are ignored.<br>

The very first line in the file should be <tt>device "&lt;devicename&gt;"</tt>.<br>

<hr>

<h5>Example:</h5>
<pre>
device "MIDI Light Control"

port A
prefix &amp;F0 &amp;23 &amp;16 &amp;2C
postfix &amp;F7
group Lights

event_start
  title On1
  event &amp;02 &amp;20 &amp;20
event_end

event_start
  title Off1
  event &amp;01
event_end

event_start
  title SystemPowerOff
  no group
  event &amp;00
event_end
</pre>


<p>
This will define 3 events:<br>
<pre>
  On1            &amp;F0 &amp;23 &amp;16 &amp;2C &amp;02 &amp;20 &amp;20 &amp;F7
  Off1           &amp;F0 &amp;23 &amp;16 &amp;2C &amp;01 &amp;F7
  SystemPowerOff &amp;F0 &amp;23 &amp;16 &amp;2C &amp;00 &amp;F7
</pre>
<tt>On1</tt> and <tt>Off1</tt> will be placed in the group <tt>Lights</tt> and <tt>SystemPowerOff</tt> will be placed outside all groups.

</html>
