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
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 |
self._mb_messages |
table of pending multibyte messages
|
self._nrpn_messages |
table of pending NRPN messages
|
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)