midi

midi#

Description#

Virtual MIDI controller plugin. It allows you to send custom MIDI messages to any connected MIDI devices and listen for MIDI events.

Configuration#

midi:
  # [Optional]
  # Name of the MIDI device associated to this plugin.
  # device_name: Platypush MIDI plugin  # type=str

  # [Optional]
  # List of MIDI devices to open and monitor for
  # events, by name or by port number. If set, and ``poll_interval``
  # is set, then the plugin will only listen for events from these
  # devices. If not set, and ``poll_interval`` is set, then the plugin
  # will listen for events from all available MIDI devices (default).
  # midi_devices:   # type=Optional[Sequence[Union[str, int]]]

  # [Optional]
  # How often the plugin should scan for new MIDI
  # devices. Set this to 0 or null to disable polling.
  # poll_interval: 5.0  # type=Optional[float]

  # [Optional]
  # If set, then the plugin will throttle
  # MIDI events to the specified time resolution. If an event is
  # triggered within the specified time resolution, then the event will
  # be throttled and the last event will be discarded. This is useful
  # to avoid sending too many MIDI messages in a short time frame.
  # Default: no throttling.
  # event_resolution:   # type=Optional[float]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install rtmidi

Debian

apt install python3-rtmidi

Fedora

yum install python-rtmidi

Arch Linux

pacman -S python-rtmidi rtmidi

Triggered events#

Actions#

Module reference#

class platypush.plugins.midi.MidiPlugin(device_name: str = 'Platypush MIDI plugin', midi_devices: Sequence[str | int] | None = None, poll_interval: float | None = 5.0, event_resolution: float | None = None, **kwargs)[source]#

Bases: RunnablePlugin

Virtual MIDI controller plugin. It allows you to send custom MIDI messages to any connected MIDI devices and listen for MIDI events.

__init__(device_name: str = 'Platypush MIDI plugin', midi_devices: Sequence[str | int] | None = None, poll_interval: float | None = 5.0, event_resolution: float | None = None, **kwargs)[source]#
Parameters:

  • device_name – Name of the MIDI device associated to this plugin.

  • midi_devices – List of MIDI devices to open and monitor for events, by name or by port number. If set, and poll_interval is set, then the plugin will only listen for events from these devices. If not set, and poll_interval is set, then the plugin will listen for events from all available MIDI devices (default).

  • poll_interval – How often the plugin should scan for new MIDI devices. Set this to 0 or null to disable polling.

  • event_resolution – If set, then the plugin will throttle MIDI events to the specified time resolution. If an event is triggered within the specified time resolution, then the event will be throttled and the last event will be discarded. This is useful to avoid sending too many MIDI messages in a short time frame. Default: no throttling.

main()[source]#

Implementation of the main loop of the plugin.

play(note: int, velocity: int, duration: float = 0)[source]#

Play a note with selected velocity and duration.

Parameters:

  • note – MIDI note in range 0-127 with #60 = C4

  • velocity – MIDI note velocity in range 0-127

  • duration – Note duration in seconds. Pass 0 if you don’t want the note to get off

query()[source]#
Returns:

dict: A list of the available MIDI ports with index and name. Format: port_index: device_name.

{
  "in": {
    0: "Midi Through:Midi Through Port-0 14:0",
    1: "MPK mini 3:MPK mini 3 MIDI 1 32:0",
    2: "X-TOUCH MINI:X-TOUCH MINI MIDI 1 36:0",
    3: "RtMidiOut Client:Platypush MIDI plugin 129:0"
  },
  "out": {
    0: "Midi Through:Midi Through Port-0 14:0",
    1: "MPK mini 3:MPK mini 3 MIDI 1 32:0",
    2: "X-TOUCH MINI:X-TOUCH MINI MIDI 1 36:0"
  }
}

release(note: int)[source]#

Release a played note.

Parameters:

note – MIDI note in range 0-127 with #60 = C4

release_all()[source]#

Release all the notes being played.

send_message(values: Sequence[int], device: int | str | None = None)[source]#
Parameters:

  • values –

    Values is expected to be a list containing the MIDI command code and the command parameters - see reference.

    Available MIDI commands:

    • 0x80 Note Off

    • 0x90 Note On

    • 0xA0 Aftertouch

    • 0xB0 Continuous controller

    • 0xC0 Patch change

    • 0xD0 Channel Pressure

    • 0xE0 Pitch bend

    • 0xF0 Start of system exclusive message

    • 0xF1 MIDI Time Code Quarter Frame (Sys Common)

    • 0xF2 Song Position Pointer (Sys Common)

    • 0xF3 Song Select

    • 0xF6 Tune Request (Sys Common)

    • 0xF7 End of system exclusive message

    • 0xF8 Timing Clock (Sys Realtime)

    • 0xFA Start (Sys Realtime)

    • 0xFB Continue (Sys Realtime)

    • 0xFC Stop (Sys Realtime)

    • 0xFE Active Sensing (Sys Realtime)

    • 0xFF System Reset (Sys Realtime)

  • device – MIDI port to send the message to, by number or by name. If None then the message will be sent to the default port allocated for the plugin.

start()#

Start the plugin.

stop()[source]#

Stop the plugin.

wait_stop(timeout=None)#

Wait until a stop event is received.