16.4. MIDI Controlling
Prev Chapter 16. MIDI Next

16.4. MIDI Controlling

This section explains how you can change parameters in Hydrogen, start playback or recording, switch patterns, and many more using incoming MIDI messages. Firstly, we will have a look at which types of MIDI messages are supported in MIDI Events. Then we will discuss two different ways of mapping them to Actions: via the MIDI table in the Preferences and MIDI-learnable Widgets

16.4.1. MIDI Events

There is a vast number of MIDI message types available. But Hydrogen only supports a selection of most common ones listed below.

  • NOTE_ON: an incoming note triggered by a regular black/white key of a MIDI keyboard or a pad of an e-drum. The note's pitch will be used as event parameter and its velocity as new value.

  • CONTROL_CHANGE (CC): controller commands coming from e.g. faders or rotary controllers. These ones can be used for MIDI Feedback as well.

  • PROGRAM_CHANGE (PC): usually intended to change the sound of instruments or to select different sound banks. It does only contain an single event parameter, e.g. the bank number, which will be interpreted as new value.

  • MMC_x: MIDI machine control events coming from e.g. buttons, like 'play' or 'stop', on a controller. These messages carry neither an event parameter nor a number which could be used as new value. They are intended for triggering Actions expecting no input arguments, like toggling mute or playback, and will use 0 as new value for all other Actions.

  • START: System Realtime message which is hard-coded to start playback in Hydrogen. It can not be mapped to an Action or an MIDI-learnable widget.

  • CONTINUE: System Realtime message which is hard-coded to start playback in Hydrogen. It can not be mapped to an Action or an MIDI-learnable widget.

  • STOP: System Realtime message which is hard-coded to pause playback in Hydrogen. It can not be mapped to an Action or an MIDI-learnable widget.

Whether the MIDI event sent by the play button of your MIDI device corresponds to e.g. a START or MMC_PLAY event is up to the manufacturer and should be stated in the user manual.

[Note]Note

For all message types except of the MMC_x ones the Channel set in the Preferences must be matched.

16.4.2. Actions

An MIDI Event recognized by Hydrogen can be mapped to an Action using the MIDI table in the MIDI System tab of the Preferences.

[Note]Note

Only actions performed in the GUI can be undone. MIDI, on the other hand, can not!

Figure 16.1. Actions are set in MIDI System tab of the Preferences Dialog

Actions are set in MIDI System tab of the Preferences Dialog

You can define mapping between incoming MIDI Events and Actions by either choosing an event type and parameter manually or by pressing the Red circle. button in the left-most column of the table. A popup will inform you that Hydrogen is waiting for your input. Press/hit/turn the key/pad/knob on your MIDI keyboard (or controller) that you want to link to the Action. The popup will close and the Event Param. value will now show the MIDI message corresponding to the key you pressed. Once this is done you can select an Action from the drop-down list.

The Action Param. columns to the right of the table specifies the parameters to the Action not provided by the MIDI message. In the example shown in the picture above the value set using the controller 70 of your MIDI device will be assigned to the pan of the third top-most instrument in the current drumkit.

[Note]Note

Most Action parameters references a specific channel, instrument, FXsend id, ... Keep in mind that their values are zero-based. So, if you want to reference channel 1 you have to enter 0 in the Action Param. field (1 for channel 2, 2 for channel 3, and so on).

[Tip]Tip

In order to delete a row in the MIDI table, you have to set both its Incoming Event and Action to an empty value.

Available Actions:

  • <<_PREVIOUS_BAR: moves the playhead to the previous pattern/bar.

  • >>_NEXT_BAR: moves the playhead to the next pattern/bar.

  • BEATCOUNTER: calculates the average time passing between successive encounters of this commands and uses it to set the current tempo using the Beat Counter.

  • BPM_CC_RELATIVE: changes the tempo relative to the current tempo, using a controller. Using Action Param. 1 you can specify by how much the current tempo will change. If the incoming Event is -1 (negative), the tempo will be increased and if it's 1 (positive), it will be increased.

    [Note]Note

    This Action will have no effect if Hydrogen is both in Song Mode and the Timeline is activated.

  • BPM_DECR: decreases the current tempo by the supplied value.

    [Note]Note

    This Action will have no effect if Hydrogen is in Song Mode or Timeline is activated.

  • BPM_FINE_CC_RELATIVE: as BPM_CC_RELATIVE but with changes 100 times smaller than the value specified in Action Param. 1.

    [Note]Note

    This Action will have no effect if Hydrogen is in Song Mode or Timeline is activated.

  • BPM_INCR: increases the current tempo by the supplied value.

    [Note]Note

    This Action will have no effect if Hydrogen is in Song Mode or Timeline is activated.

  • CLEAR_PATTERN: removes all notes of the selected pattern.

  • CLEAR_SELECTED_INSTRUMENT: removes all notes of the selected pattern associated with the currently selected instrument.

  • EFFECT_LEVEL_ABSOLUTE: changes the volume level of an FX. Action Param. 1 determines the Instrument Channel Strip and Action Param. 2 specifies the FX the Action will be applied to.

  • EFFECT_LEVEL_RELATIVE: same as EFFECT_LEVEL_ABSOLUTE but instead mapping the incoming values directly to the FX volume 1 will increase and all other values will decrease it by 5%.

  • FILTER_CUTOFF_LEVEL_ABSOLUTE: for a value of 0 it sets the Filter Cutoff of the instrument strip specified using the Action Param. 1 to 0. For all other values it sets the cutoff to the provided number divided by 127.0.

  • GAIN_LEVEL_ABSOLUTE: sets the Layer Gain. Action Param. 1 specifies the instrument, Action Param. 2 the component, and Action Param. 3 the layer.

  • INSTRUMENT_PITCH: sets the Pitch of the instrument specified by Action Param. 1.

  • MASTER_VOLUME_ABSOLUTE: sets the Master output volume to the value provided by the MIDI event times 1.5 and divided by 127.

  • MASTER_VOLUME_RELATIVE: changes the Master output volume, relative to its current setting. For a value of 0 it sets the volume of the master fader to 0. For a value of 1 it increases its volume by 0.05 and for all other values it decreases it by 0.05. (-1: -0.05 , 0: 0 ,1: +0.05)

  • MUTE: mutes the Master output (sequencer keeps running).

  • MUTE_TOGGLE: toggles the muting of the Master output (sequencer keeps running).

  • PAN_ABSOLUTE: changes the pan of an instrument determined by the Action Param. 1 to the absolute value that the linked controller sends to Hydrogen. Incoming values from 0 to 127 will be mapped to pan values between -1 and 1.

  • PAN_ABSOLUTE_SYM: same as PAN_ABSOLUTE but supports incoming values from -127 to 127 will be mapped.

  • PAN_RELATIVE: changes the pan of an instrument determined by Action Param. 1 relative to the current value. For a value of 1 it increase the pan by 0.05. For all other values it decreases it by 0.05. (-1: -0.05 , 1: +0.05).

  • PAUSE: pauses playback.

  • PITCH_LEVEL_ABSOLUTE: sets the Layer Pitch. Action Param. 1 specifies the instrument, Action Param. 2 the component, and Action Param. 3 the layer.

  • PLAY: starts playback.

  • PLAY/PAUSE_TOGGLE: works the same as PLAY if the playback has not started yet and same as. PAUSE otherwise. (The playhead will not return to the start of the song, but will stay at its current position).

  • PLAY/STOP_TOGGLE: works the same as PLAY if the playback has not started yet and same as. STOP otherwise.

  • PLAYLIST_NEXT_SONG: opens the song in the current playlist corresponding to the song number specified in Action Param. 1.

  • PLAYLIST_PREV_SONG: opens the previous song in the current playlist.

  • PLAYLIST_SONG: opens the next song in the current playlist.

  • RECORD/STROBE_TOGGLE: toggles recording (same as pressing the record button in the main toolbar).

  • RECORD_EXIT: deactivates recording.

  • RECORD_READY: toggles recording (same as pressing the record button in the main toolbar) if the playback has not started yet.

  • RECORD_STROBE: activates recording.

  • REDO_ACTION: redoes the previously undone GUI action (not MIDI action!).

  • SELECT_AND_PLAY_PATTERN: works as SELECT_NEXT_PATTERN combined with PLAY.

  • SELECT_INSTRUMENT: selects the instrument in the drumkit corresponding to the number supplied in the incoming MIDI Event.

  • SELECT_NEXT_PATTERN: selects the pattern specified in Action Param. 1.

    [Note]Note

    If Hydrogen is in Selected Pattern Mode, playback will be switched to the selected pattern immediately. If it is, instead, in Stacked Pattern Mode, playback of the selected pattern will be toggled next time transport is loop again. In case the pattern was already playing, it will be stopped. If not, it will be started.

    If Hydrogen is in Song Mode, the command will have no effect.

  • SELECT_NEXT_PATTERN_CC_ABSOLUTE: like SELECT_NEXT_PATTERN but the pattern to be selected is determined by the value of the MIDI message.

  • SELECT_NEXT_PATTERN_RELATIVE: like SELECT_NEXT_PATTERN but the pattern to be selected is determined by the pattern number of the currently selected one plus the value specified in Action Param. 1.

  • SELECT_ONLY_NEXT_PATTERN: selects the pattern specified in Action Param. 1.

    [Note]Note

    If Hydrogen is in Stacked Pattern Mode, only the selected pattern will be played back once the transport gets looped again. For Selected Pattern Mode this Action behaves as SELECT_NEXT_PATTERN.

    If Hydrogen is in Song Mode, the command will have no effect.

    [Tip]Tip

    By providing a number smaller than 0 or larger than the number of available patterns all playing patterns can be stopped at once without stopping playback itself.

  • SELECT_ONLY_NEXT_PATTERN_CC_ABSOLUTE: like SELECT_ONLY_NEXT_PATTERN but the pattern to be selected is determined by the value of the MIDI message.

  • STOP: stops playback and moves the playhead to the beginning of the song.

  • STRIP_MUTE_TOGGLE: mutes the instrument specified in Action Param. 1.

  • STRIP_SOLO_TOGGLE: mutes the instrument specified in Action Param. 1.

  • STRIP_VOLUME_ABSOLUTE: see MASTER_VOLUME_ABSOLUTE, but applies to the Instrument Channel Strip specified in Action Param. 1.

  • STRIP_VOLUME_RELATIVE: see MASTER_VOLUME_RELATIVE, but applies to the Instrument Channel Strip specified in Action Param. 1.

  • TAP_TEMPO: another command calculating the average time passing between successive encounters of this commands and uses it to set the current tempo using Tap Tempo.

  • TOGGLE_METRONOME: toggles the metronome.

  • UNDO_ACTION: undoes the previous GUI action (not MIDI action!).

  • UNMUTE: unmutes the Master output (sequencer keeps running).

16.4.3. MIDI-learnable Widgets

For more convenient handling some Actions are associated with GUI elements and can directly be mapped to MIDI Events by pressing Shift while left-clicking the widget.

Such elements are:

A 'Waiting for MIDI input...' popup informs you that Hydrogen is now waiting for you to press a key or turn/move a controller on your MIDI device. If successful, the new mapping is shown in both the tooltip of the GUI element as well as the MIDI table in the Preferences.

[Note]Note

If the element that does not support MIDI automation, a different popup will inform you.

Prev Up Next
16.3. MIDI Output Home Chapter 17. OSC API