Controllers#

Schemas#

Support for any model of a MIDI controller can be added by creating its schema, which is represented as a simple YAML file.

The YAML file should contain all fields from the Controller class. See example.

Built-in schemas are available in config_files/controllers on GitHub.

midi_app_controller.models.controller.Controller #

A controller's schema.

Attributes:

Name	Type	Description
`name`	`str`	The name of the controller. Cannot be empty. Must be unique among all schemas.
`button_value_off`	`int`	The number sent by the controller when a button is in 'off' state. Should be in the range [0, 127].
`button_value_on`	`int`	The number sent by the controller when a button is in 'on' state. Should be in the range [0, 127].
`knob_value_min`	`int`	The minimum value sent by the controller when a knob is rotated. Should be in the range [0, 127].
`knob_value_max`	`int`	The maximum value sent by the controller when a knob is rotated. Should be in the range [0, 127].
`default_channel`	`int`	The default channel which MIDI messages will be sent on. Should be in the range [1, 16].
`preferred_midi_in`	`Optional[str]`	MIDI input name that is preferred for this controller.
`preferred_midi_out`	`Optional[str]`	MIDI output name that is preferred for this controller.
`buttons`	`list[ControllerElement]`	List of available buttons on the controller.
`knobs`	`list[ControllerElement]`	List of available knobs on the controller.

midi_app_controller.models.controller.ControllerElement #

Any element of a controller.

Attributes:

Name	Type	Description
`id`	`int`	The ID of the element that the controller sends with every event. Should be in the range [0, 127].
`name`	`str`	A user-defined name for the element that helps to differentiate elements. Cannot be empty.

Example of a valid schema#

name: "MyController"
button_value_off: 0
button_value_on: 127
knob_value_min: 0
knob_value_max: 127
default_channel: 1
preferred_midi_in: "Some midi input port"
preferred_midi_out: "Some midi output port"
buttons:
  - id: 1
    name: "Button 1"
  - id: 2
    name: "Button 2"
knobs:
  - id: 1
    name: "Knob 1"

Finding ids of knobs and buttons#

Install python-rtmidi using:

python -m pip install python-rtmidi

and then run the following script:

import rtmidi

def get_type(command):
    if command in (0x80, 0x90):
        return "Button"
    elif command == 0xB0:
        return "Knob"
    else:
        return "Unknown"

def midi_input_callback(event, data):
    message, _ = event
    command = message[0] & 0xF0
    print(get_type(command), "id:", message[1])

def select_midi_port(available_ports):
    print("Available MIDI input ports:")
    for i, port_name in enumerate(available_ports):
        print(f"{i}. {port_name}")
    return int(input("Select number of MIDI input port: "))

def main():
    midi_in = rtmidi.MidiIn()
    port_index = select_midi_port(midi_in.get_ports())
    midi_in.open_port(port_index)
    print("Listening...")
    print("Interact with elements of the MIDI controller to show their ids here.")
    midi_in.set_callback(midi_input_callback)
    input("Press Enter to quit.\n")
    midi_in.close_port()

if __name__ == "__main__":
    main()