# liveSHOW_MIDI Client

Short explanation MIDI
Settings
Connect to a server
Selection of Midi devices
Remote control of the server - MIDI in
Sending MIDI commands through triggers - MIDI out
Saving and loading MIDI settings
The MIDI client software is based on the SPIT protocol (see www.liveSHOWSoftware.de). The software can connect to a SPIT server (such as the live SHOW software), remotely control it via midi commands, or send midi commands based on received triggers.
The SPIT protocol is a network protocol therefore the Midi Client software can also run on another computer, which is connected via network to the computer of the server software. It is also allowed to connect several midi clients to one server, each midi client may be configured with different midi commands.
You do not need to be a MIDI expert to use the MIDI client, but it helps to have clue about MIDI at all. Therefore, now follows an extremely summarized explanation of MIDI, who wants to know more exactly can read it at the MIDI Association (www.midi.org).

## Short Explanation MIDI:

MIDI (Musical Instrument Digital Interface) is originally an industry standard for the exchange of musical control information between electronic instruments. MIDI was developed by Dave Smith in cooperation with Ikutaro Kakehashi of the Roland Corporation and introduced in August 1982, meanwhile MIDI has been extended several times. An example of using MIDI is a keyboard. Each press of a key sends a MIDI message to a synthesizer, which then generates an audible tone from that MIDI message.
In principle, each MIDI command consists of a number of bytes that are sent back and forth between the devices. There are basically three categories of Midi commands:

1. SHORT Messages
   Here three bytes are always sent. Depending on the command, the bytes are interpreted differently. The first byte always contains the command identifier and the MIDI channel. The second and third bytes contain values. For example, a keystroke on a keyboard could produce the following Midi command: 99 31 7F
   The first byte contains the command and the MIDI channel (99 9x = Note ON, x9 = Channel 10), the second byte contains the note value (31 = C # 3), the third byte contains the velocity (7F = 100) %)
   If this command were sent to a MIDI synthesizer, you will hear a loud cymbal stroke (channel 10 is the percussion instruments, C # 3 is a cymbal and 7F is the highest velocity)
   When the button is released, the following command could be generated: 99 31 00 This is the same MIDI command, only with velocity value 00, this is interpreted as Note Off.
   A sound mixing console would interpret this command completely differently, e.g. It could be that with 99 31 7F the sound of channel 1 is muted.
2. SYSEX Messages
   Several bytes can be sent here, but there is a fixed structure of the bytes:
   F0 7F 01 04 01 xx.. F7 (F0 is always the status byte, 7F is the device manufacturer, 01 is the DeviceID, 04 is the SubID1, 01 is the SubID2, xx.. is a sequence of data bytes, F7 is always EOX).
   The structure status byte, manufacturer byte, DeviceID, SubID1, SubID2, data bytes, EOX is always present. The length of the data bytes may vary. Looking at the MIDI specific actions, this command will set the main volume to about 50%.
   Depending on the MIDI device, this command can also be interpreted differently. SYSEX messages open up a wide field of possible commands.
   Problem: Not all devices understand SYSEX messages and there are probably also some problems in the communication.
3. Midi Timecode
   The midi time code is a time signal. The idea is that there is one transmitter that sends a time and all other devices react to a certain time. This allows devices to synchronize in time.
   The liveSHOWsoftware could be used as a timer, but it could also be a Midi time code modem take over the role of the timer.
   Midi Timecode is a hybrid of Mid Sysex and Midi Short commands. Whenever there is a jump (fast forward, jump in a timeline, etc.) a MIDI Sysex command is sent with the current time (Full Frame Message).
   When a sequence is played (timeline, modem started, etc.) Midi Short commands are sent. The Midi Short commands, however, do not include the complete time. For the transmission of a time, 8 Midi Short commands are required, with only every second frame being sent (Quarter Frame Message).
   The Midi Tmecode comes from the time of the film editing, so not Milliskunden resolutions are sent but it is resolved in frame rates (24, 25, or 30 frames per second). The SPIT_MidiClient software, however, uses information in milliseconds and converts them into framates. This is more comfortable for operation.
   Note: Because Windows or Mac OS are not real-time operating systems, there may be some irregularities when sending timecode. A receiver that checks the timecode messages very strictly for plausibility may reject the messages as inconsistent.

Since there are many devices capable of receiving or transmitting MIDI messages, the MIDI protocol has been used for purposes other than instrument control. For example, there is a subsection of MIDI for show control (MIDI SHOW CONTROL).
As explained in the section above, in principle everything is a matter of interpreting a MIDI command. For example, the note command 99 31 7F can be assigned in the MIDI Client as a jump to the next scene.
In the past, MIDI devices were always connected with a MIDI cable.
Computers sometimes have MIDI devices built into the operating system (e.g. synthesizers for sound generation via the sound card), these can be used directly. External MIDI controllers can often be connected to the computer via a USB cable.
There are inexpensive USB MIDI interfaces that connect to the computer via USB and have MIDI in/out jacks on the opposite side. This way, MIDI controllers that only have a cable connection can also be connected to the computer. In the meantime there are also Bluetooth MIDI interfaces.
To enable two software programs on the computer to exchange MIDI messages, there are tools that simulate a virtual MIDI device on the computer (e.g. loopMIDI by Thomas Erichsen).
Thanks: At this point Derek Cook is thanked for the development of CoreMidi4j, without CoreMidi4j it would not be possible to receive or send sysex-messages with the SPIT_MidiClient on the Mac.

## Settings

##

### Connect the liveSHOW_MIDI client to a server (liveSHOWsoftware)

If the liveSHOW software (SPIT Server) is used, the liveSHOW_MIDI Client software finds all running liveSHOWsoftare instances automatically. For this a network connection between the computers must exist or the liveSHOW_MIDI client runs on the same computer as the liveSHOW software.
The SPIT servers (liveSHOWsoftware) found are displayed in the selection list on the top left. Here you can select the server and connect with. .
If the connection has worked, the computer name of the server, the identifier of the server software and the name of the loaded project are displayed below the selection list.
Once the liveSHOW_MIDI client has been connected to a server (server software), it will later automatically connect to the server software as soon as a server has been found on the network where the software is running and if 'connect automatically' is selected.

| Connects the liveSHOW_MIDI client to the selected server
| Disconnects the server
(connect automatically) | If this is activated, a connection will be established automatically if a suitable server was found. For this purpose, a connection must be established manually the first time the program is started.
(load last project at start) | If this is activated, the last loaded / saved settings are automatically opened when the liveSHOW_MIDI client is started.
| All settings can be saved in a file. The MIDI settings are closely linked to the server's project. In order to make this connection recognizable, you should always use the same file name as the project of the server. ATTENTION: If you port a server project to another computer (for example, from the office computer to the show computer, you must remember to copy the corresponding MIDI settings file to the other computer.
| The saved settings can be loaded from a file.
| Displays help for the liveSHOW_MIDI client |
| Here the playing time of the server is displayed. In liveSHOWsoftware this is the position of the media cursor. |

### Selection of Midi devices

At this point you can specify which MIDI devices should be used by the liveSHOW_MIDI client.
Midi devices can e.g. Synthesizers, Keyboards, Midi Controllers, Mixers, USB Interfaces, Midi Timecode Modems, ....
Depending on the type of device, Midi commands can be sent (midi out) or received (midi in).
Problem: Currently two identical (same) Midi devices can not be distinguished. You can only use several midi devices of different types!
(This is because the devices can only be identified by their name and manufacturer.)
Problem solving for two identical devices:
Under Mac OS, the names of Midi devices can be set using the 'Midi Studio'.
Under Windows you will have to change the names of the connected devices in the RegistryEditor (the instructions have to be searched on the internet).
As long as you only use one Midi device or several different Midi devices, the above problem does not occur.
In the SPIT_MidiClient software the connected Midi devices are listed under Midi in or Midi out.
Midi-In devices are used to send Midi commands.
Midi-Out devices are used to receive Midi commands, which can then trigger remote control commands.
There is a box in front of each device, which can be used to enable or disable the devices.
There are USB interfaces that are not built as a complete Midi device, but via a CommPort Midi exchange data with the computer. These devices are not automatically listed, they must be added explicitly.
An example of such a device is the Enttec USB DMX Pro MK2.

| Opens a selection window for CommPort devices or the virtual 'Timecode Loopback' device.
| Delete a selected device from the list (only CommPort devices or 'Timecode Loopback'
| Opens a settings window for a CommPort device.

If you click on , it opens a window in which you can select a CommPort device and add it with :
You can select a CommPort device or the virtual 'Loopback Timecode' device here. With you can add it.
'Loopback Timecode' is for testing and should not be used in live use.
'Loopback Timecode' is a virtual receiver that returns the sent midi timecode commands back to the SPIT_MidiClient software.
When you add a CommPort device, a settings window automatically opens, allowing you to enter the CommPort and connect the device.
The settings window can also be accessed via.

## Remote control of the SPIT server (e.g., live SHOW software) - MIDI in

The principle: The SPIT server informs the liveSHOW_MIDI client which remote control commands exist.
In the liveSHOW_MIDI client a Midi command can be assigned to each remote control command. When the Midi command is received, the corresponding remote control command is executed.
The Midi command can be sent through a connected midi controller (e.g. Midi-Keyboard).
In the case of the liveSHOWsoftware, for example, you can switch to the next scene or trigger another remote control command by pressing a midi controller key.
Use the search box to restrict the list.
When you click on a column heading, all rows are sorted accordingly.
The SPIT server (for example, the live SHOW software) sends all possible remote control commands to the connected liveSHOW_MIDI clients. In the list of these commands you can select one.
A MIDI command can now be assigned to a selected remote control command. This is done on the right side next to the list of remote control commands.
For MIDI controllers / keyboards, each key or slider is assigned a MIDI command that is sent when the key is pressed.
If a Midi command has been assigned to a remote control command, the remote control command is executed when the assigned Midi command is received.
Learning Midi commands:
If you click with the mouse on the green outlined learning field , it will be filled in green and the entire window gets a green border.
If you select a remote control command in the list and press a key etc. on your MIDI controller / keyboard, the transmitted MIDI command will be displayed on the right side. The command is only displayed and not executed.
Attention: You must remember to deactivate the learning field by clicking on the field again. As long as the learning field is activated and the entire window has a green border, no Midi command will be executed!
If nothing is displayed, you may need to select your Midi device in the Installations (Midi In - Remote Control) - see above.
The manual entry of a Midi command:
Of course, you may also enter and modify the MIDI command directly.
If you know the exact byte order, you can also enter it in the list of remote control commands in the 'MIDI IN' column. Simply double click on the corresponding table cell.
Or you can set the Midi command on the right-hand side.
ATTENTION: Pressing a controller or keyboard key usually triggers two MIDI messages.
The first MIDI command is sent when the button is pressed. Here is usually the value of the velocity indicated.
The second MIDI command is sent when the key is released. Here it is either the same command as when pressing the button, it is then usually the value 0 is indicated as a velocity. It can also be another MIDI command.
For example, when a key is pressed, a keyboard typically sends the MIDI note-on command with velocity as the value, and when released, sends either the note-on command with the velocity 0 or the note off.
Which command is sent depends on the MIDI device or its settings.
There are two types of remote control commands of the SPIT server:

1. Remote control commands without value: e.g. the jump to the next scene
2. Remote control commands with value: eg. changing the volume control, here the volume is indicated as value.

For MIDI controllers, there are:

1. Keys (discrete values)
2. Sliders or turning wheels (continuous values).

Case 1: You want to set a jump to the next scene, ie a remote control command without value specification.
Normally one could do without the value of the MIDI command. However, as mentioned above, pressing a key often sends two MIDI messages, which may differ only in the value of the velocity.
So one more statement has to be made when the remote control command is triggered:
(Trigger when MIDI value )
Here you can specify a condition and a value in percent. Only when the condition applies, the remote control command is triggered.
At the setting shown in the graph (value <= 0) and a keyboard key (as described above), the remote control command will not be sended until the key is released.
Such a condition (value <= 0) also makes it possible with a MIDI slider, e.g. to trigger a jump to the next scene. If you move the slider up nothing happens, only when you move the slider to the zero position, the remote control command is triggered.
Case 2: You want, e.g. Change a volume with a MIDI slider, ie trigger a remote control command with a value.
In any case, a value is required here. So you will use sliders or knobs of the MIDI controller.
Sliders usually provide the current position value in the MIDI command.
R otary knobs usually work in two ways. Either Knobs provide a continuous value or they provide a value> = 65 or a value <= 64 with each rotation, depending on whether they are turned clockwise or counterclockwise.
So one more indication has to be made:
(Value direct - In/Decrease)
Here you can specify if you want to use the value from the MIDI command directly (slider) or if you want to increase or decrease the remote control value by a percentage.
The remote control value is increased if a MIDI command delivers more than 50% of the MIDI value range (classic> = 65). If the value is less than 50% of the MIDI value range (classic <= 64), the remote control value is decreased by the percentage.
The percentage does not have to be an integer, values like 0.5 are allowed. If you choose too small a percentage, you may not achieve any changes.
Receive timecode, trigger action at a certain time
If you want to run a remote control command at a specific time, you can enter the time (midi timecode).
For this, a MIDI device must be selected that sends a MIDI tmecode.
This makes sense only for remote commands that do not require values. In the live SHOW software these are e.g. MainSceneBridges or Jingles. Controlling a fader via midi timecode makes no sense.
The time is given in the following format: hh: mm: ss: mmm (hh = hours, mm = minutes, ss = seconds, mmm = milliseconds)
You can also use the original time of the remote control object (position in the timeline etc.).

| The command is executed when the specified time is transmitted. In the table of SPIT remote control objects, this is shown with MTC and the time.
| The command is executed when the received time corresponds to the start time of the remote control object. In the live SHOW software this is e.g. the start time of a main scene bridge in the timeline. In the table of SPIT remote control objects, this is only shown with MTC.

Note: The SPIT_MidiClient does not do a strict check of the timecode, it also accepts temporally inconsistent timecode messages.

## Sending Midi Commands by Trigger - MIDI out

The principle: In the SPIT server software triggers can be created, in the liveSHOW_MIDI client software a midi command can be assigned to a trigger, which is sent when the trigger is played by the server software.
Here a distinction is made between trigger types and trigger objects. In the liveSHOWsoftware Trigger types can be created, which describe a desired action by name.
In the liveSHOW_MIDI Client can be assigned to a trigger type Midi commands.
If a trigger type is dragged in the liveSHOWsoftware into the Timeline (or into the Jinglefenster), then a trigger object, which refers to the trigger type, develops. Whenever a trigger object is played by the liveSHOWsoftware, this is communicated to the liveSHOW_MIDI Client and this executes the assigned Midi instruction of the trigger type.
Three situations are distinguished, for each situation a Midi command can be assigned:

1. The object is started (start)
   In the live SHOWsoftware, the play cursor is currently running into the object or the cursor is being placed in the object.
   The assigned Midi command is sent once.
2. The object is played (continous)
   In the live SHOWsoftware, the play cursor is inside the object.
   The assigned Midi command is sent repeatedly during playback.
3. The object is terminated (end)
   In the live SHOWsoftware, the play cursor exits the object.
   The assigned Midi command is sent once.

The set MIDI command is only sent to the selected Mid devices - see further below Selection of Midi-devices.
If you click the checkbox in front of the name of a device, the device is connected to the liveSHOW_MIDI client and MIDI messages can be sent to the device from the liveSHOW_MIDI client. Such a device could e.g. be a synthesizer or a sound mixer with MIDI capability.
Basically, a distinction is made between trigger types and trigger objects:

- A trigger type is the basis (source) for a trigger object. A specific trigger type exists exactly once. Trigger types can not be played, they are just the basis for a trigger object.
- A trigger object has exactly one trigger type. Trigger objects can exist multiple times. Trigger objects can be played.

Each trigger object has exactly one trigger type. A trigger type can be used in several trigger objects.
In the case of the live SHOW software, several trigger objects in the timeline can be generated from one trigger type (see liveSHOWsoftware - media section).
Which MIDI command is sent when playing a trigger object can be set by assigning MIDI commands to a trigger type.
In other words, all trigger objects that have the same trigger type as a source will send the same MIDI commands when playing. For different trigger types different MIDI commands can be set.
The liveSHOW_MIDI client lists all the trigger types created in the respective SPIT server software (e.g., live SHOW software).
Use the search box to restrict the list.
When you click on a column heading, all rows are sorted accordingly.
If you select a trigger type, you can assign MIDI commands to this trigger type. These MIDI commands are sent when a trigger object is played that has this trigger type as a source.
As already described above, there are three events when playing a trigger object, each of which can be assigned a Midi command:
(Start - Continous - End)

1. at Start: The trigger object is started or the play cursor jumps into the object
   The assigned Midi command is sent once when the object is started.
2. at End: The play cursor exits the trigger object
   The assigned Midi command is sent once when the play cursor leaves the object.
3. Continous: The play cursor is inside the object, trigger events are sent at regular intervals
   The assigned Midi command is sent continuously at regular intervals while the object is playing.

You can get the byte setting of the MIDI command, e.g. from the manual of the MIDI synthesizer or the mixer.
Selection of Midi devices to which the command(s) of the selected trigger type should be sent:
In the list all Midi devices are listed, which you have activated under Settings (Midi Out Send). If you select the checkbox in front of a midi device, the set commands for the selected trigger type will be sent to this midi device.
These assignments are retained even if you deactivate a midi device or the midi device is possibly not connected. Deactivated or not connected midi devices do not appear in the list!
This is important to keep the assignments to midi devices even if a device is removed for a short time.

| Deletes all assignments to midi devices. Also to midi devices that are not listed. If not all the necessary midi devices are currently connected, you must be careful when deleting the assignments.

A small application example: Let's say you have a sound mixer that can receive MIDI commands.
You want to open the microphone channel of an actor in a scene (Mute Channel 1 off), after this scene the microphone should be off again (Mute Channel 1 on).
In liveSHOWsoftware you could create a trigger type "Mute Channel 1". Drag this trigger type into the timeline to create a trigger object. Drag this trigger object along the length of the scene.
In the SPIT_Midi_Client software, assign a Start MIDI command to the trigger type (MIDI command for 'Mute Channel 1 off') by selecting the trigger type, clicking on the button 'at Start' and selecting the Midi command on the right.
You can find the appropriate Midi command in the manual of your sound mixer.
Then assign an end MIDI command (MIDI command for 'Mute Channel 1 on') to the trigger type by selecting the trigger type, clicking on the 'at End' button and entering the corresponding Midi command on the right.
Channel 1 is now open (mute off) as soon as the play cursor is inside the object. If the play cursor leaves the object, then channel 1 is closed (mute on).
Learning Midi commands:
If the MIDI device not only can receive MIDI commands but also send them, or you want to take a command from another device, you can also use the learning field.
To do this, under MIDI in (Remote), you must select the device from which you want to learn the commands and then switch back to MIDI out (Trigger).
If you click with the mouse on the green outlined learning field , it will be filled in green and the entire window gets a green border.
If you now press a key etc. on your MIDI controller / keyboard, the transmitted MIDI command will be displayed on the right side. The command is only displayed and not executed.
For this to work, you must have selected a MIDI input device under MIDI in (Remote)!
Attention: You must remember to deactivate the learning field by clicking on the field again. As long as the learning field is activated and the entire window has a green border, no Midi command will be executed!
Manually entry of Midi commands:
Of course, you may also enter and modify the MIDI command directly.
If you know the exact byte order, you can also enter it in the list of trigger types in the columns 'MIDI Start', 'MIDI Playing' or 'MIDI End'. Simply double click on the corresponding table cell.
Or you can set the Midi command on the right-hand side.
If a trigger object is played, a value can be provided. For example, the values of 0% - 100% are supplied when a trigger object is fadet in.

- A value of 0% is always returned at the end of a trigger object.
- When a trigger object is faded in (0% - 100%), the value for the start event is logically always 0%.
- If the trigger object is not faded in, the start event returns the set basic volume / brightness of the object as a value.

It is therefore necessary to consider carefully whether to use the value from the trigger object or to use the (fixed) value specified in the command.
You can specify whether the fixed value (mostly Data 2, for MIDISysex commands is the value hidden in the data bytes) or whether the supplied value from the trigger object should be used for the MIDI command:
(Use fixed Value) (Use Trigger Value)
At the bottom of the window, for the sake of completeness, you will see the trigger objects.
Use the search box to restrict the list.
When you click on a column heading, all rows are sorted accordingly.
The group and name of the assigned trigger type, the name of the object, the start time and the length are displayed. If the object is played back, the supplied value and the current position within the object are displayed.
Sending timecode
When a SPIT trigger object is playing, a time code can be sent while the object is playing. The Midi time code messages are sent to all selected Midi devices (Midi out).
Note: Because Windows or Mac OS are not real-time operating systems, there may be some irregularities when sending timecode. A receiver that checks the timecode messages very strictly for plausibility may reject the messages as inconsistent.
The start time can be specified at 'Midi Timecode'.
It only makes sense here for the start of an object to specify a time:
You can enter any start time or use the original start time of the trigger object.
The time is given in the following format: hh: mm: ss: mmm (hh = hours, mm = minutes, ss = seconds, mmm = milliseconds)

| When the object is playing, timecode messages are sent. The start time is the specified time. In the table of SPIT types this is shown with MTC and the time
| The start time is taken from the start position of the respective trigger object. In the table of SPIT types, this is only shown with MTC.

### Creating triggers using the liveSHOWsoftware as an example

In the liveSHOWsoftware menu, click Media - Trigger:
The trigger window opens:
If you click on the plus symbol, a new trigger type will be created. You can change the name of the trigger type in the table.
You can drag the trigger type into a media track of the timeline or into the media area of the jingle window by holding down the left mouse button.
A trigger object is created in the timeline.
When the media cursor reaches, leaves or plays within the trigger object, the midi commands are sent as you set above.
If no command has been set in the liveSHOW_Midi client for the trigger object (the associated trigger type) or no midi device has been assigned to which the commands are to be sent, the trigger object is displayed with a red frame in the timeline.
The red frame also appears if an assigned midi device is deactivated or is currently not connected.
Note: If several liveSHOW_Midi clients are started, the red frame appears ONLY if the assignment is wrong in ALL liveSHOW_Midi clients. If at least in one of the liveSHOW_Midi clients the assignment for the trigger type is correct, the red frame disappears.

## Loading and saving MIDI settings

MIDI settings depend on the loaded project of the SPIT server (e.g., live SHOW software). Therefore, the file name under which the settings are saved should correspond to the filename of the server project. The liveSHOW_MIDI client automatically suggests the appropriate name when saving or loading - assuming the liveSHOW_MIDI client is connected to the server.
If you get into the habit of always storing the MIDI settings in the project folder of the server, you will quickly find the file that matches the server project.
ATTENTION: If you port a server project to another computer (for example, from the office computer to the show computer), you must remember to copy the corresponding MIDI settings file to the other computer.

| All settings can be saved in a file. The MIDI settings are closely linked to the server's project. In order to make this connection recognizable, you should always use the same file name as the project of the server. ATTENTION: If you port a server project to another computer (for example, from the office computer to the show computer, you must remember to copy the corresponding MIDI settings file to the other computer. If you had already saved the midi settings once and a midi device is currently not connected, a message appears that there are references to unconnected midi devices. You can then decide whether you: want to keep the references If a Misi device is reconnected, it is automatically activated. do NOT want to keep the references Then all references to not connected midi devices are deleted and only the references to currently connected midi devices are stored.
| The saved settings can be loaded from a file.
(load last project at start) | If this is activated, the last loaded / saved settings are automatically opened when the liveSHOW_MIDI client is started. |

Note: All trigger types, trigger objects or remote control commands listed in the liveSHOW_MIDI client that do not match those of the server project will be displayed with a red background.