Creates a channel aftertouch (also known as channel pressure) message.

On a keyboard, an aftertouch message is sent by pressing down further on keys after it has already reached the bottom. Not all keyboards have aftertouch.

With channel aftertouch, one of the following is used; Either the:

• average amount of pressure of all the keys held down; or the
• single greatest pressure value of all the current depressed keys. Therefore channel aftertouch is independent of which key or how many keys are held. polyphonic_aftertouch is specific to each key however.

This function takes as it's parameters:

1. pressure: a number between 0 and 127 representing the pressure on the key. By defaut 127 is used.

The following option can also be passed:

• channel: the MIDI channel to which the message will be sent (there are 16 channels per MIDI device, in the range 0 to 15). By default channel 1 is used.

Example

alias Midiex.Message

# Create a series of aftertouch messages from 0 to 127 for channel 1
0..127//1
|> Enum.map(fn pressure -> Message.channel_aftertouch(pressure, channel: 1) end)

Creates a MIDI CC or 'control change' message.

MIDI Control Change messages are used to control functions in a synthesiser. Controllers include devices such as pedals, levers/sliders, wheels, switches and other control-oriented devices.

This function takes as its parameters:

1. contoller number: a number between 0-119. Controller numbers between 120-127 are reserved as "Channel Mode Messages".
2. value: depends on the control function, but usually is a a number between 0 and 127. See the MIDI 1.0 Control Change Messages Spec or consult the MIDI device manual for specific codes an values.

The following option can be passed:

• channel: the MIDI channel to which the message will be sent (there are 16 channels per MIDI device, in the range 0 to 15). By default channel 1 is used.

Example

The MIDI CC message of 123 equates to "All Notes Off" (a Channel Mode Message), thus stopping all notes being played.

# Create a 'all notes off' CC message.
Midiex.control_change(127)

Reference

See the official MIDI 1.0 Control Change Messages Spec.

Creates a MIDI note-off message.

Takes as it's parameters:

1. note: a note as a string (e.g. "C4"), atom (e.g. :C4) or number (e.g. 60) as the first parameter
2. velocity: a number between 0 and 127 representing how hard (or loud) a key was pressed. By defaut 127 is used.

The following options can be passed:

• channel: the MIDI channel to which the message will be sent (there are 16 channels per MIDI device, in the range 0 to 15). By default channel 1 is used.

All notes can be switched off with Message.all_notes_off/1.

Example

# Note-off for middle-C
Message.note_off(:C4)

# Returns: <<128, 60, 123>>

Creates a MIDI note-on message.

Takes as it's parameters:

1. note: a note as a string (e.g. "C4"), atom (e.g. :C4) or number (e.g. 60) as the first parameter
2. velocity: a number between 0 and 127 representing how hard (or loud) a key was pressed. By defaut 127 is used.

The following options can be passed:

• channel: the MIDI channel to which the message will be sent (there are 16 channels per MIDI device, in the range 0 to 15). By default channel 1 is used.

Note that MIDI channels are in the range 0 - 15. But in MIDI software and hardware it may be offset by +1, so MIDI channel 0 might be called MIDI channel 1 and so on to channel 16.

Examples

# Note-on message for middle-C
Midiex.Message.note_on(:C4)

# Returns: <<144, 60, 127>>

# Note-on message for middle-C on channel 2 with a velocity of 40
Midiex.Message.note_on(:C4, 40, channel: 2)

# Returns: <<145, 60, 40>>

These can be sent to a connection using Midiex.send_msg/2, for example:

alias Midiex.Message
Midiex.send_msg(out_conn, Message.note_on(:C4, 40, channel: 2))

Creates a pitch bend message, representing a change in pitch.

Pitch bend change messages a usually sent from a keyboard with a pitch bend wheel or lever.

Takes as it's first parameter, the pitch bend amount. The channel cane be passed as an option.

The range of a pitch bend is as follows:

• 0-8191 represent negative bends,
• 8192 (Hex: 0x2000) is no bend and
• 8193-16383 are positive bends

Example

alias Midiex.Message, as: M

# Play a note
Midiex.send_msg(piano, M.note_on(:D3))

# Bend up, then down, then back to center (8192)
(Enum.to_list(8193..16383//1) ++ Enum.to_list(8191..0//-1) ++ [8192])
|> Enum.each(fn pitch -> Midiex.send_msg(piano, M.pitch_bend(pitch)) end)

Creates a polyphonic aftertouch message.

On a keyboard, polyphonic aftertouch (or key pressure) is message sent by pressing down further on a key after it has already reached the bottom. Not all keyboards have aftertouch.

Note: polyphonic_aftertouch is specific to each key, where as channel_aftertouch is average amount of pressure applied to whichever keys are held down.

The function takes as it's parameters:

1. note: a note as a string (e.g. "C4"), atom (e.g. :C4) or number (e.g. 60) as the first parameter
2. pressure: a number between 0 and 127 representing the pressure on the key. By defaut 127 is used.

The following options can be passed:

• channel: the MIDI channel to which the message will be sent (there are 16 channels per MIDI device, in the range 0 to 15). By default channel 1 is used.

Example

alias Midiex.Message

# Create a series of aftertouch messages from 0 to 127 for the note middle-C (C4)
0..127//1
|> Enum.map(fn pressure -> Message.polyphonic_aftertouch(:C4, pressure) end)

Creates a program change message, used select the instrument type to play sounds with or a different 'patch'.

This function takes one data byte which specifies the new program number.

To apply this to a particular channel, use the channel option, e.g.:

Message.program_change(1, channel: 3)