Like it!

Join us on Facebook!

MIDI output management

Giada is able to output MIDI messages to the external world, both from sample channels and, of course, MIDI channels, with some notable differences. More precisely, there are two kinds of messages: regular MIDI messages and MIDI lightning messages.

Regular messages vs lightning messages

Regular MIDI messages correspond to MIDI events, namely all those events you record with your physical devices, or actions edited in the Action Editor. Obviously this kind of events can be sent only from MIDI channels. On the other hand MIDI lightning messages are special codes used to light up parts of external devices, such as buttons, keys, knobs and many other shimmering things. The latter type of messages can be outputted from sample channels as well.

The following table shows what you can and cannot output from channels:

regular MIDI messages MIDI lightning messages
Sample channel
MIDI channel

Configuring the output

Click on the main button of any channel and select Setup MIDI output from the menu, in order to configure how to output MIDI messages. A new window will pop up containing several tools.

Regular MIDI messages

MIDI output config tool, regular This kind of messages are managed by the dropdown menu shown on the left. If you check enable MIDI output, MIDI messages will be sent outside Giada whenever an action occurs, through the MIDI channel specified with the drop-down menu on the right. With this technique you will be able to control external MIDI hardware or other software as well.

MIDI lightning messages

MIDI output config tool, lightning MIDI lightning requires key binding between the app and your physical device, so that whenever an event occurs, Giada sends a MIDI lightning message to the right part of your controller.

You bind controller elements to the events through the MIDI learning tool shown on the left, which works in the same way of the MIDI input learning tool described in MIDI input management.

Currently January 2016 you can light up your device for the following events:

  • playing events, including start, stop, wait, ending statuses;
  • mute events such as mute on and mute off;
  • solo events such as solo on and solo off.

How MIDI lightning works

Giada needs to know what data to send when MIDI lightning occurs. Each hardware producer defines its own set of messages, so we introduce the concept of midimap files. A midimap is a JSON-formatted text file where you define what kind of messages you want Giada to send. They reside in your configuration directory, or more precisely:

  • Linux — /home/[your_user]/.giada/midimaps/;
  • OS X — [your_home]/Library/Application Support/Giada/midimaps/;
  • Windows — midimaps/ folder, alongside the binary file.

Giada will look into those directories on startup. If the files are valid midimap files they will be listed in the Configuration window, MIDI section. Pick up the minimap file you want to use in the dropdown menu and you are ready to go.

Anatomy of a midimap file

A midimap file follows this naming convention: [brand]-[device].giadamap, lower-case text. For example if you own the Akai APC20, the corresponding midimap file would be akai-apc20.giadamap.

On the inside you will find a collection of JSON objects. Every midimap command is made of two things: a channel and a message. The following is a complete midimap file, with placeholders:

{
  "brand": "[text]",
  "device": "[text]",
  "init_commands": [
    {
      "channel": [MIDI-channel],
      "message": "[hex-message]"
    },
    {
      "channel": [MIDI-channel],
      "message": "[hex-message]"
    },
    ...
  ],
  "mute_on": {
    "channel": [MIDI-channel],
    "message": "[hex-message]"
  },
  "mute_off": {
    "channel": [MIDI-channel],
    "message": "[hex-message]"
  },
  "solo_on": {
    "channel": [MIDI-channel],
    "message": "[hex-message]"
  },
  "solo_off": {
    "channel": [MIDI-channel],
    "message": "[hex-message]"
  },
  "waiting": {
    "channel": [MIDI-channel],
    "message": "[hex-message]"
  },
  "playing": {
    "channel": [MIDI-channel],
    "message": "[hex-message]"
  },
  "stopping": {
    "channel": [MIDI-channel],
    "message": "[hex-message]"
  },
  "stopped": {
    "channel": [MIDI-channel],
    "message": "[hex-message]"
  }
}

The first three elements are the initializers:

  • brand — the producer name;
  • device — the device name;
  • init_commands — a set of lightning messages sent on startup.

The remaining elements are the events, defining what MIDI lighting message to send when each of them occur.

Writing a MIDI lightning message

A MIDI lightning message follows this structure:

{
  "channel": [MIDI-channel],
  "message": "[hex-message]"
}

In details:

  • MIDI-channel — the MIDI channel where to output to, in a numeric range of 0-15;
  • hex-message — the actual message to send, in hexadecimal form, 4 bytes long.

The hexadecimal message contains a special placeholder for the note. Since each message is customized by the vendor, you have to specify where the byte for the note resides. The placeholder is defined as nn; Giada will replace it on the fly once the key has been configured and grabbed with the MIDI learning tool seen before. Below a couple of illustrative lightning messages:

{
  "channel": 0,               // MIDI channel 0
  "message": "0x90nn3B00"     // note on byte 2
},
{
  "channel": 7,               // MIDI channel 7
  "message": "0x803Bnn00"     // note on byte 3
},

A complete example of a midimap file

The following is a midimap file prepared for the Novation Launchpad S MIDI controller:

{
  "brand": "AKAI",
  "device": "LPD8",
  "init_commands": [
    {
      "channel": 0,
      "message": "0xB0000000"
    },
    {
      "channel": 0,
      "message": "0xB0002800"
    }
  ],
  "mute_on": {
    "channel": 0,
    "message": "0x90nn3F00"
  },
  "mute_off": {
    "channel": 0,
    "message": "0x90nn0C00"
  },
  "solo_on": {
    "channel": 0,
    "message": "0x90nn0F00"
  },
  "solo_off": {
    "channel": 0,
    "message": "0x90nn0C00"
  },
  "waiting": {
    "channel": 0,
    "message": "0x90nn7f00"
  },
  "playing": {
    "channel": 0,
    "message": "0x90nn7f00"
  },
  "stopping": {
    "channel": 0,
    "message": "0x90nn7f00"
  },
  "stopped": {
    "channel": 0,
    "message": "0x80nn7f00"
  }
}

Where do I find midimaps?

We store the full list of midimap files on GitHub in the midimap repository, mirrored in the official midimaps topic in our forum. Download the zip archive and uncompress it in the midimap folders seen before.

Pull requests and file submissions are absolutely welcome and encouraged. If you have a MIDI controller whose midimap file is missing, feel free to add it to our collection!