Module Duplex.MidiDevice

A generic MIDI device class, providing the ability to send and receive MIDI

Changes

0.99.5

- Full NRPN support (14 bit messages, absolute and relative modes)
- Input throttling

0.99

- Support for MMC (Midi Machine Control) messages over sysex
- Support for 14-bit MIDI pitch bend messages
- Ability to pass unmatched (not just unhandled) messages to Renoise

0.98.28

- FIXME MIDI pass-on got ignored when message was not handled by any controls

0.98.21

- Fixed: bug when handling MIDI ports that are added/removed while running

0.9

- First release

Functions

__init (display_name, message_stream, port_in, port_out) Initialize MidiDevice class
open () Attempt to open the device MIDI ports
release () Attempt to release the device MIDI ports
midi_callback (message, no_multibyte) Invoked when we receive MIDI from device, construct a string identical to the value attribute in order to locate the control-map parameter
build_message (value_str, msg_value, msg_context, msg_channel, msg_is_note_off, bit_depth, midi_msgs) Following up on the midi_callback, this method will extract parameters from the control-map and construct messages for each of them...
sysex_callback (message) Invoked when we receive sysex data from the device
send_midi (msg) Send raw MIDI message to device, optionally dump to console (used by sendcc, sendpitch_bend etc.
send_cc_message (number, value, channel, multibyte) Send CC message to device
send_nrpn_message (number, value, channel, send_only_msb) Send NRPN message to device
assemble_nrpn_message (match_nrpn_num) (Re)construct the table of MIDI messages that together form a complete NRPN message (compares the provided number with the active NRPN messages)
send_sysex_message (...) Send sysex message to device (adding the initial 0xF0 and 0xF7 values)
send_pitch_bend_message (value, channel, mode) Send Pitch-Bend message to device.
send_note_message (key, velocity, channel) Send note message to device
pass_to_renoise (messages) Pass unhandled/unmatched message to Renoise?
on_idle () Idle loop implementation for the MidiDevice class main purpose: process (or discard) NRPN messages
_note_to_string (int) Convert MIDI note to control-map string, range C--1 to C-9
_midi_cc_to_string (int) Convert MIDI CC value to string, e.g.
_program_change_to_string (int) Convert Program Change value to string, e.g.
_nrpn_to_string (num) Convert NRPN value to string, e.g.
extract_midi_cc (str) Extract MIDI CC number (range 0-127)
extract_midi_nrpn (str) Extract MIDI NRPN number (range 0-16383)
extract_midi_channel (str) Determine channel for the given message (use default port if not specified)
_create_fingerprint (msg_context, midi_msgs) Create MIDI 'fingerprint' for the provided message(s) (just enough information to identify the CC/NRPN source)

Tables

self._mb_messages

(table) table of multibyte messages

[fingerprint]{
  type      = [enum] msg_context
  timestamp = [number]
  channel   = [int]
  num       = [int] (only for CC messages)
  lsb       = [int]
  msb       = [int]
  midi_msgs = [table]
}
self._multibyte_exempted (table) messages that should not be interpreted as multibyte (table is created when parsing control-map)
self._nrpn_messages

(table) table of NRPN messages

{
  timestamp = [number]
  terminated = [bool]
  channel   = [int]
  num_msb   = [int]
  num_lsb   = [int]
  data_msb  = {int]
  data_lsb  = [int]
}
self._nrpn_msb_only (table) NRPN messages that only require the MSB part (7-bit) (table is created when parsing control-map)
self._throttle_buffer (table) most recently received messages [fingerprint] = {

timestamp   = [number]
msg_context = [enum]
msg_channel = [int]
value_str   = [string]
msg_value   = [number]
msg_is_note_off
bit_depth   = [int]
midi_msgs   = [table]

}
self._throttle_exempted (table) messages that should not be throttled (table is created when parsing control-map)

Fields

self.port_in (string) the MIDI input port
self.port_out (string) the MIDI output port
self.midi_in (MidiInputDevice)
self.midi_out (MidiOutputDevice)
self.default_parameter_mode (Duplex.Globals.PARAM_MODE) the default parameter mode
self.throttling_enabled (bool) decide whether to throttle incoming messages (the actual threshold is defined in preferences)
self.multibyte_enabled (bool) decide if multibyte (14-bit) support is enabled
self.nrpn_enabled (bool) decide if NRPN support is enabled
self.terminate_nrpns (bool) true when we expect a Null value from the device after receiving or transmitting a NRPN message (enabling this feature will transmit Null values too) important: only enable this feature if the device is known to transmit these messages (midi bytes 2&3: 0x65,0x7F followed by 0x64,0x7F)


Functions

__init (display_name, message_stream, port_in, port_out)
Initialize MidiDevice class

Parameters:

  • display_name (string) the friendly name of the device
  • message_stream (MessageStream) the msg-stream we should attach to
  • port_in (string) the MIDI input port
  • port_out (string) the MIDI output port
open ()
Attempt to open the device MIDI ports
release ()
Attempt to release the device MIDI ports
midi_callback (message, no_multibyte)
Invoked when we receive MIDI from device, construct a string identical to the value attribute in order to locate the control-map parameter

Parameters:

  • message (Table/MIDIMessage)
  • no_multibyte (bool) temporarily disable multibyte support
build_message (value_str, msg_value, msg_context, msg_channel, msg_is_note_off, bit_depth, midi_msgs)
Following up on the midi_callback, this method will extract parameters from the control-map and construct messages for each of them...

Parameters:

  • value_str (string) the control-map value to look for
  • msg_value (int) the value we recieved
  • msg_context (enum) (Duplex.Globals.DEVICE_MESSAGE)
  • msg_channel (int) between 1 and 16
  • msg_is_note_off (bool)
  • bit_depth (int) 7 or 14 bits
  • midi_msgs (list of tables, each with three bytes)
sysex_callback (message)
Invoked when we receive sysex data from the device

Parameters:

  • message (table) MIDIMessage
send_midi (msg)
Send raw MIDI message to device, optionally dump to console (used by sendcc, sendpitch_bend etc. methods)

Parameters:

  • msg
send_cc_message (number, value, channel, multibyte)
Send CC message to device

Parameters:

  • number (int) 7-bit control-number
  • value (int) 7 or 14-bit control-value
  • channel (int) midi channel, between 1-16
  • multibyte (bool) true when sending a 14-bit value
send_nrpn_message (number, value, channel, send_only_msb)
Send NRPN message to device

Parameters:

  • number (int) 14-bit control-number
  • value (int) 14-bit control-value
  • channel (int) midi channel, between 1-16
  • send_only_msb (bool) when sending 7-bit messages
assemble_nrpn_message (match_nrpn_num)
(Re)construct the table of MIDI messages that together form a complete NRPN message (compares the provided number with the active NRPN messages)

Parameters:

  • match_nrpn_num

Returns:

    table or nil
send_sysex_message (...)
Send sysex message to device (adding the initial 0xF0 and 0xF7 values)

Parameters:

  • ... (vararg) values to send, e.g. 0x47, 0x7F, 0x7B,...
send_pitch_bend_message (value, channel, mode)
Send Pitch-Bend message to device. sending pitch-bend back to a device doesn't make sense when you're using a keyboard - it's generally recommended to tag the parameter with the "skip_echo" attribute in such a case... however, some device setups are different (e.g. Mackie Control)

Parameters:

  • value (int) the pitch-bend value, 7 bit value
  • channel (int) the MIDI channel, 1-16 (optional)
  • mode (string) specify sending mode, e.g. "abs" or "abs_14"
send_note_message (key, velocity, channel)
Send note message to device

Parameters:

  • key (int) the MIDI note pitch, 0-127
  • velocity (int) the MIDI note velocity, 0-127
  • channel (int) the MIDI channel, 1-16
pass_to_renoise (messages)
Pass unhandled/unmatched message to Renoise?
(this is defined in the device settings panel)

Parameters:

  • messages (table of MIDI messages)

Returns:

    bool (true when message was passed)
on_idle ()
Idle loop implementation for the MidiDevice class main purpose: process (or discard) NRPN messages
_note_to_string (int)
Convert MIDI note to control-map string, range C--1 to C-9

Parameters:

  • int (int) the MIDI note key, between 0-120

Returns:

    string
_midi_cc_to_string (int)
Convert MIDI CC value to string, e.g. "CC#%d"

Parameters:

  • int (int) the 7-bit CC number
_program_change_to_string (int)
Convert Program Change value to string, e.g. "Prg#%d"

Parameters:

  • int (int) the 7-bit Program Change number
_nrpn_to_string (num)
Convert NRPN value to string, e.g. "NRPN#16383"

Parameters:

  • num (int) the parameter number (0-16383)
extract_midi_cc (str)
Extract MIDI CC number (range 0-127)

Parameters:

  • str (string), control-map value attribute (e.g. "CC#10")

Returns:

    (int) the MIDI CC number, 0-127
extract_midi_nrpn (str)
Extract MIDI NRPN number (range 0-16383)

Parameters:

  • str (string), control-map value attribute (e.g. "NRPN#16383")

Returns:

    (int) the MIDI NRPN number, 0-16383
extract_midi_channel (str)
Determine channel for the given message (use default port if not specified)

Parameters:

  • str (string), control-map value

Returns:

    (int) the MIDI channel, 1-16
_create_fingerprint (msg_context, midi_msgs)
Create MIDI 'fingerprint' for the provided message(s) (just enough information to identify the CC/NRPN source)

Parameters:

  • msg_context
  • midi_msgs

Returns:

    string

Tables

self._mb_messages

(table) table of multibyte messages

[fingerprint]{
  type      = [enum] msg_context
  timestamp = [number]
  channel   = [int]
  num       = [int] (only for CC messages)
  lsb       = [int]
  msb       = [int]
  midi_msgs = [table]
}
self._multibyte_exempted
(table) messages that should not be interpreted as multibyte (table is created when parsing control-map)
self._nrpn_messages

(table) table of NRPN messages

{
  timestamp = [number]
  terminated = [bool]
  channel   = [int]
  num_msb   = [int]
  num_lsb   = [int]
  data_msb  = {int]
  data_lsb  = [int]
}
self._nrpn_msb_only
(table) NRPN messages that only require the MSB part (7-bit) (table is created when parsing control-map)
self._throttle_buffer
(table) most recently received messages [fingerprint] = {

timestamp   = [number]
msg_context = [enum]
msg_channel = [int]
value_str   = [string]
msg_value   = [number]
msg_is_note_off
bit_depth   = [int]
midi_msgs   = [table]

}

self._throttle_exempted
(table) messages that should not be throttled (table is created when parsing control-map)

Fields

self.port_in
(string) the MIDI input port
self.port_out
(string) the MIDI output port
self.midi_in
(MidiInputDevice)
self.midi_out
(MidiOutputDevice)
self.default_parameter_mode
(Duplex.Globals.PARAM_MODE) the default parameter mode
self.throttling_enabled
(bool) decide whether to throttle incoming messages (the actual threshold is defined in preferences)
self.multibyte_enabled
(bool) decide if multibyte (14-bit) support is enabled
self.nrpn_enabled
(bool) decide if NRPN support is enabled
self.terminate_nrpns
(bool) true when we expect a Null value from the device after receiving or transmitting a NRPN message (enabling this feature will transmit Null values too) important: only enable this feature if the device is known to transmit these messages (midi bytes 2&3: 0x65,0x7F followed by 0x64,0x7F)
generated by LDoc 1.4.2