Skip to content

Latest commit

 

History

History
427 lines (292 loc) · 18.4 KB

README.md

File metadata and controls

427 lines (292 loc) · 18.4 KB

lrtmidi Documentation

Contents

Overview

lrtmidi is a Lua binding for RtMidi.

This binding enables Lua scripting code to use MidiIn and MidiOut objects for connecting to MIDI ports and to send or receive MIDI event data.

This module can be installed from Luarocks: https://luarocks.org/modules/osch/lrtmidi.

The module name to require is "lrtmidi":

local lrtmidi = require("lrtmidi")

Module Functions

  • lrtmidi.getRtMidiVersion()

    Returns the RtMidi version as string.

  • lrtmidi.getCompiledApi()

    Returns a string list of possible audio API names that can be used for creating a new controller object with lrtmidi.new().

    Possible API names for RtMidi 5.0.0 are: "core" (CoreMidi), "alsa" (ALSA), "jack" (Jack), "winmm" (Windows MultiMedia) or "web" (Web MIDI API).

  • lrtmidi.newMidiIn([apiName][, clientName])

    Creates a new MidiIn object for receiving MIDI events from a MIDI OUT port.

    • apiName - optional string or nil: name of the MIDI API that is used with this MidiIn object. If not given, the default order of use is "core", "alsa", "jack", "winmm", "web". For possible values see: lrtmidi.getCompiledApi()

    • clientName - optional string client name. This will be used to group the ports that are created by the application.

    See also MidiIn Methods.

  • lrtmidi.newMidiOut([apiName][, clientName])

    Creates a new MidiOut object for sending MIDI events to a MIDI IN port.

    • apiName - optional string or nil: name of the MIDI API that is used with this MidiOut object. If not given, the default order of use is "core", "alsa", "jack", "winmm", "web". For possible values see: lrtmidi.getCompiledApi()

    • clientName - optional string client name. This will be used to group the ports that are created by the application.

    See also MidiOut Methods.

MidiIn Methods

MidiIn objects are created by invoking the function lrtmidi.newMidiIn(). A MidiIn object can be used to receive MIDI events from a MIDI Output port.

  • midiin:getCurrentApi()

    Returns the MIDI API name used with this MidiIn object. For possible values see lrtmidi.getCompiledApi().

  • midiin:getPortCount()

    Returns the number of available MIDI Output ports that can be used for MIDI input by connecting this MidiIn object using the method midiin:openPort().

  • midiin:getPortName(portNumber)

    Returns as string value the name of the specified MIDI port.

    portNumber - integer value, it must be 1 <= portNumber <= midiin:getPortCount().

  • midiin:getPortNames()

    Returns a list of all port names. The list contains for each port the port name as string value at the list position of the corresponding port number.

  • midiin:openPort(portNumber[, portName])

    A MidiIn object can handle one MIDI input connection for receiving MIDI events. This methods connects the MidiIn object to the MIDI OUT port specified by the given portNumber.

    • portNumber - integer value, it must be 1 <= portNumber <= midiin:getPortCount().
    • portName - optional string value, port name of the MIDI IN port of this MidiIn object visible for other applications.

  • midiin:openVirtualPort([portName])

    A MidiIn object can handle one MIDI input connection for receiving MIDI events. This methods creates a virtual input port to allow software connections to this MidiIn object.

    This method creates a virtual MIDI input port to which other software applications can connect. This type of functionality is currently only supported by the Macintosh OS-X, any JACK, and Linux ALSA APIs (the function returns an error for the other APIs).

    • portName - optional string value, a name for the virtual port that is visible for other applications.

  • midiin:ignoreTypes(types)

    Specify whether certain MIDI message types should be queued or ignored during input.

    • types - a Lua table with optional boolean entries for the keys "midiSysex", "midiTime" and "midiSense".

    By default, MIDI timing and active sensing messages are ignored during message input because of their relative high data rates. MIDI sysex messages are ignored by default as well. Table entry values of true imply that the respective message type will be ignored. Missing entries are assumed to be have the value true, i.e. default is to ignore these message types.

  • midiin:setReceiver(receiver)

    Sets a receiver object for receiving asynchronously MIDI event data.

    • receiver - receiver object for MIDI events, must implement the Receiver C API, e.g. a mtmsg buffer.

    The receiver object receivers for each MIDI event a message with two arguments:

    • the time difference to the previous MIDI event as float value in seconds
    • the MIDI event bytes, an carray of 8-bit integer values.

    While not absolutely necessary, it is best to set the receiver before opening a MIDI port to avoid leaving some messages in the queue.

    See also example02.lua.

  • midiin:cancelReceiver()

    Disables the receiver that was set with the method midiin:setReceiver(). The receiver object will no longer receive MIDI events.

    This method throws an error if there is active receiver and the MidiIn object is connected to a MIDI port.

  • midiin:getMessage([buffer])

    Obtains next MIDI message if available. Returns immediately whether a new message is available or not.

    • buffer - optional carray object of 8-bit integer values that is filled by this method with the MIDI message bytes. If not given, a new carray object will be created if a MIDI message is available.

    If a MIDI message is available, this method returns two values:

    • the event-delta time in seconds as float value
    • the event data as carray object of 8-bit integer values (re-using buffer argument if given)

    If no MIDI message is availabe, this methods returns immediately without any return values.

    This methods throws an error if a receiver was set with the method midiin:setReceiver() or if the MidiIn object is not connected to a MIDI port.

  • midiin:closePort()

    Disconnects the MidIn object from the MIDI port. Afterwards the MidiIn object can be used to connect to another port using midiin:openPort() or midiin:openVirtualPort().

  • midiin:close()

    Closes the MidIn object and releases underlying resources. Afterwards the MidiIn object becomes invalid and cannot be used again.

    MidiIn objects are subject to garbage collection, i.e. the close method is implicitly called if the object becomes garbage collected.

  • midiin:setErrorReceiver(receiver)

    • receiver - receiver object for error/debug information, must implement the Receiver C API, e.g. a mtmsg buffer.

    The receiver object receives for each error/debug information a message with two arguments:

    • error type as string value, possible values: "WARNING", "DEBUG_WARNING", "UNSPECIFIED", "NO_DEVICES_FOUND", "INVALID_DEVICE", "MEMORY_ERROR", "INVALID_PARAMETER", "INVALID_USE", "DRIVER_ERROR", "SYSTEM_ERROR", "THREAD_ERROR".
    • error message as string value

    This method must be called before the MidiIn object is connected to a MIDI port, i.e. before midiin:openPort() or midiin:openVirtualPort() is called.

MidiOut Methods

MidiOut objects are created by invoking the function lrtmidi.newMidiOut(). A MidiOut object can be used to send MIDI events to a MIDI Input port.

  • midiout:getCurrentApi()

    Returns the MIDI API name used with this MidiOut object. For possible values see lrtmidi.getCompiledApi().

  • midiout:getPortCount()

    Returns the number of available MIDI Input ports that can be used for MIDI output by connecting this MidiOut object using the method midiout:openPort().

  • midiout:getPortName(portNumber)

    Returns as string value the name of the specified MIDI port.

    portNumber - integer value, it must be 1 <= portNumber <= midiout:getPortCount().

  • midiout:getPortNames()

    Returns a list of all port names. The list contains for each port the port name as string value at the list position of the corresponding port number.

  • midiout:openPort(portNumber[, portName])

    A MidiOut object can handle one MIDI output connection for sending MIDI events. This methods connects the MidiOut object to the MIDI IN port specified by the given portNumber.

    • portNumber - integer value, it must be 1 <= portNumber <= midiout:getPortCount().
    • portName - optional string value, port name of the MIDI OUT port of this MidiOut object visible for other applications.

  • midiout:openVirtualPort([portName])

    A MidiOut object can handle one MIDI output connection for sending MIDI events. This methods creates a virtual output port to allow software connections to this MidiOut object.

    This method creates a virtual MIDI output port to which other software applications can connect. This type of functionality is currently only supported by the Macintosh OS-X, any JACK, and Linux ALSA APIs (the function returns an error for the other APIs).

    • portName - optional string value, a name for the virtual port that is visible for other applications.

  • midiout:sendMessage(message)

    Sends a MIDI message.

    • message - string or carray object of 8-bit integer values containing the MIDI message bytes to be sent.

    See also example03.lua.

  • midiout:closePort()

    Disconnects the MidiOut object from the MIDI port. Afterwards the MidiOut object can be used to connect to another port using midiout:openPort() or midiout:openVirtualPort().

  • midiout:close()

    Closes the MidiOut object and releases underlying resources. Afterwards the MidiOut object becomes invalid and cannot be used again.

    MidiOut objects are subject to garbage collection, i.e. the close method is implicitly called if the object becomes garbage collected.

  • midiout:setErrorReceiver(receiver)

    • receiver - receiver object for error/debug information, must implement the Receiver C API, e.g. a mtmsg buffer.

    The receiver object receives for each error/debug information a message with two arguments:

    • error type as string value, possible values: "WARNING", "DEBUG_WARNING", "UNSPECIFIED", "NO_DEVICES_FOUND", "INVALID_DEVICE", "MEMORY_ERROR", "INVALID_PARAMETER", "INVALID_USE", "DRIVER_ERROR", "SYSTEM_ERROR", "THREAD_ERROR".
    • error message as string value

    This method must be called before the MidiOut object is connected to a MIDI port, i.e. before midiout:openPort() or midiout:openVirtualPort() is called.

End of document.