Module xMidiInput

Asynchroneous interpretation of MIDI messages .

Features

Supports all common MIDI messages (including 14-bit).

Notes

About 14-bit multibyte CC messages: when this feature is enabled, the class will wait for the extra messages to arrive, which can delay the processing of "normal" 7-bit messages. So - if you don't need to support multibyte message, you can disable this feature, or exempt certain CC messages from being interpreted as multibyte messages (multibyte_exempted)

About Data Increment and Data Decrement: the value portion of these messages is sometimes given a value or step size, but the transmitted value byte is commonly set to zero. This class will preserve the value, but whether it is used or not depends on the application.

How to use

The class is implemented with a callback, which will recieve xMidiMessages

-- define our callback
myCallback = function(xmsg)
  -- do something with the message
end

-- Then, instantiate this class with the callback as argument:
myMidiInput = xMidiInput{
  callback_fn = myCallback
}

-- Now you can feed it with raw midi messages:
myMidiInput:input({0x90,0x45,0x6F})

Requires

xMidiMessage

Functions

__init (args) [Constructor] accepts a single table as argument
input (msg, port_name) [Class] Process incoming message - will invoke the callback function when able to construct a xMidiMessage from the data that has been received
_create_fingerprint (msg_type, midi_msgs) [Class] Create MIDI 'fingerprint' for the provided message(s) (just enough information to identify the CC/NRPN source)
add_multibyte_exempt (msg_type, msgs) [Class] Convenience method for adding messages to the exempt list
on_idle () [Class] Idle loop : process (or discard) multibyte messages, output messages which got delayed due to throttling

Tables

self._multibyte_exempted (table) messages that should never be interpreted as multibyte
self._nrpn_msb_only table NRPN messages that only require the MSB part (7-bit) note that 7bit NRPN works without this, but might be a bit sluggish as we need to wait for the idle mode to determine that no LSB part arrived
self._mb_messages

table of pending multibyte messages

[fingerprint]{
  type      = [enum] msg_type
  timestamp = [number]
  channel   = [int]
  num       = [int] (only for CC messages)
  lsb       = [int]
  msb       = [int]
  port_name = [string]
}
self._nrpn_messages

table of pending NRPN messages

{
  timestamp = [number]
  channel   = [int]
  num_msb   = [int]
  num_lsb   = [int]
  data_msb  = {int]
  data_lsb  = [int]
  port_name = [string]
}

Fields

self.callback_fn (function) specify where messages should go
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)
self.timeout number, the amount of time that should pass before we consider a multibyte message obsolete (0.1 = tenth of a second)


Functions

__init (args)
[Constructor] accepts a single table as argument

Parameters:

  • args , table callbackfn multibyteenabled nrpnenabled terminatenrpns timeout
input (msg, port_name)
[Class] Process incoming message - will invoke the callback function when able to construct a xMidiMessage from the data that has been received

Parameters:

  • msg (table), raw MIDI message with 3 parts
  • port_name (string), where message originated from
_create_fingerprint (msg_type, midi_msgs)
[Class] Create MIDI 'fingerprint' for the provided message(s) (just enough information to identify the CC/NRPN source)

Parameters:

  • msg_type
  • midi_msgs

Returns:

    string
add_multibyte_exempt (msg_type, msgs)
[Class] Convenience method for adding messages to the exempt list

Parameters:

  • msg_type
  • msgs
on_idle ()
[Class] Idle loop : process (or discard) multibyte messages, output messages which got delayed due to throttling

Tables

self._multibyte_exempted
(table) messages that should never be interpreted as multibyte
self._nrpn_msb_only
table NRPN messages that only require the MSB part (7-bit) note that 7bit NRPN works without this, but might be a bit sluggish as we need to wait for the idle mode to determine that no LSB part arrived
self._mb_messages

table of pending multibyte messages

[fingerprint]{
  type      = [enum] msg_type
  timestamp = [number]
  channel   = [int]
  num       = [int] (only for CC messages)
  lsb       = [int]
  msb       = [int]
  port_name = [string]
}
self._nrpn_messages

table of pending NRPN messages

{
  timestamp = [number]
  channel   = [int]
  num_msb   = [int]
  num_lsb   = [int]
  data_msb  = {int]
  data_lsb  = [int]
  port_name = [string]
}

Fields

self.callback_fn
(function) specify where messages should go
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)
self.timeout
number, the amount of time that should pass before we consider a multibyte message obsolete (0.1 = tenth of a second)
generated by LDoc 1.4.2