Skip to content

pimidipy API Reference#

In this section you'll find the entire API Reference for the pimidipy library, version 0.1.2.post4.

pimidipy Classes#

PimidiPy#

PimidiPy class is the main gateway to the pimidipy library.

PimidiPy provides functions to open and close MIDI ports as well as to run the main loop.

__init__(client_name='pimidipy') #

Initialize the PimidiPy object.

Parameters:

Name Type Description
client_name str

The name of the ALSA Sequencer client to create.

list_ports(direction=PortDirection.ANY) #

List all available MIDI ports.

Returns:

Type Description
List[PortInfo]

A list of PortInfo objects.

resolve_port_name(port_name) #

Utility to resolve an ALSA Sequencer MIDI port name into a 'client_id:port_id' string.

Parameters:

Name Type Description
port_name str

The name of the port to parse.

Returns:

Type Description
Optional[str]

A normalized 'client_id:port_id' string, or None if the port was not found.

get_port(id, input) staticmethod #

Get the port string id for the given numeric id.

The port string id is read from the environment variable PORT_{IN/OUT}_{id} if it exists, otherwise it is constructed from the id. The port is returned in the format pimidi{device}:{port}.

You may set the PORT_{IN/OUT}_{id} variables in /etc/pimidipy.conf to avoid hardcoding the port ids in your code:

PORT_IN_0=pimidi0:0
PORT_OUT_0=pimidi3:1

Default port ids are pimidi{device}:{port} where device is id // 2 and port is id % 2. For example: 0 => pimidi0:0, 1 => pimidi0:1, 2 => pimidi1:0, 3 => pimidi1:1, etc...

Parameters:

Name Type Description
id int

The id of the port.
input bool

Whether the port is an input port.

Returns:

Type Description
str

The port string id for the given id.

get_input_port(id) staticmethod #

Get the port string id for the given numeric id.

The port string id is read from the environment variable PORT_IN_{id} if it exists, otherwise it is constructed from the id. The port is returned in the format pimidi{device}:{port}.

You may set the PORT_IN_{id} variables in /etc/pimidipy.conf to avoid hardcoding the port ids in your code:

PORT_IN_0=pimidi0:0
PORT_IN_1=pimidi3:1

Default port ids are pimidi{device}:{port} where device is id // 2 and port is id % 2. For example: 0 => pimidi0:0, 1 => pimidi0:1, 2 => pimidi1:0, 3 => pimidi1:1, etc...

Parameters:

Name Type Description
id int

The id of the port.

Returns:

Type Description
str

The port string id for the given id.

get_output_port(id) staticmethod #

Get the port string id for the given numeric id.

The port string id is read from the environment variable PORT_OUT_{id} if it exists, otherwise it is constructed from the id. The port is returned in the format pimidi{device}:{port}.

You may set the PORT_OUT_{id} variables in /etc/pimidipy.conf to avoid hardcoding the port ids in your code:

PORT_OUT_0=pimidi0:0
PORT_OUT_1=pimidi3:1

Default port ids are pimidi{device}:{port} where device is id // 2 and port is id % 2. For example: 0 => pimidi0:0, 1 => pimidi0:1, 2 => pimidi1:0, 3 => pimidi1:1, etc...

Parameters:

Name Type Description
id int

The id of the port.

Returns:

Type Description
str

The port string id for the given id.

open_input(port) #

Open an input port by name, or id (using get_input_port).

In case the port is not currently available, an InputPort object is still returned, and it will subscribe to the appropriate device as soon as it is connected automatically.

Parameters:

Name Type Description
port Union[str, PortInfo, Tuple[int, int], int]

The name/info/address/id of the port to open.

Returns:

Type Description
InputPort

An InputPort object representing the opened port.

open_output(port) #

Open an output port by name or id (using get_output_port).

In case the port is not currently available, an OutputPort object is still returned, and it will subscribe to the appropriate device as soon as it is connected automatically.

Parameters:

Name Type Description
port Union[str, PortInfo, Tuple[int, int], int]

The name/address/info/id of the port to open.

Returns:

Type Description
OutputPort

An OutputPort object representing the opened port.

drain_output() #

Drain the output buffer. Use this when if you set drain to False in OutputPort.write.

quit() #

Ask the main loop to stop.

run() #

Run the main loop.

PortDirection#

PortDirection is an enumeration of MIDI port directions.

Available values are:

  • ANY: Any direction. Useful for use with PimidiPy.list_ports
  • INPUT: Input port.
  • OUTPUT: Output port.
  • BOTH: Input and output port.

The values can be used as bitwise flags.

PortInfo#

PortInfo class, which is returned by PimidiPy.list_ports, holds a collection of MIDI port attributes.

Attributes:

Name Type Description
client_name str

The name of the client owning the port.
port_name str

The name of the port.
client_id int

The client ID.
port_id int

The port ID.
address str

The address of the port in the form of 'client_id:port_id'.
direction PortDirection

The direction of the port.
capabilities PortCaps

The capabilities of the port. See SND_SEQ_PORT_CAP_... enum docs for more information.
type PortType

The type of the port. See SND_SEQ_PORT_TYPE_... enum docs for more information.

InputPort#

InputPort class represents a MIDI input port.

name: Optional[str] property #

The name of the port. None if the port is closed.

is_input: Optional[bool] property #

Whether the port is an input port. None if the port is closed.

is_output: Optional[bool] property #

Whether the port is an output port. None if the port is closed.

add_callback(callback) #

Add a callback function to be called when a MIDI event is received from the input port.

Parameters:

Name Type Description
callback Callable[[MIDI_EVENTS], None]

The callback function to add.

remove_callback(callback) #

Remove a previously added callback function from the input port.

Parameters:

Name Type Description
callback Callable[[MIDI_EVENTS], None]

The callback function to remove.

close() #

Optional function to close the input port.

Note that if there's multiple InputPort instances referring to the same port, the port will only be closed when all of them are closed.

OutputPort#

OutputPort class represents a MIDI output port.

name: Optional[str] property #

The name of the port. None if the port is closed.

is_input: Optional[bool] property #

Whether the port is an input port. None if the port is closed.

is_output: Optional[bool] property #

Whether the port is an output port. None if the port is closed.

write(event, drain=True) #

Write a MIDI event or raw data to the output port.

The function accepts either one of the Event classes defined below, or raw MIDI data in the form of a bytearray.

Parameters:

Name Type Description
event Union[MIDI_EVENTS, bytearray]

The MIDI event or raw data to write.
drain bool

If True, the output buffer will be drained after writing the event.

Returns:

Type Description
int

The number of bytes written, or a negative error code.

close() #

Optional function to close the output port.

Note that if there's multiple OutputPort instances referring to the same port, the port will only be closed when all of them are closed.

pimidipy Channel Events#

NoteOnEvent#

A class representing a Note On event.

Attributes:

Name Type Description
channel int

MIDI Channel
note int

MIDI Note Number
velocity int

Note Velocity

__init__(channel, note, velocity) #

Parameters:

Name Type Description
channel int

MIDI Channel
note int

MIDI Note Number
velocity int

Note Velocity

NoteOffEvent#

A class representing a Note Off event.

Attributes:

Name Type Description
channel int

MIDI Channel
note int

MIDI Note Number
velocity int

Note Velocity

__init__(channel, note, velocity) #

Parameters:

Name Type Description
channel int

MIDI Channel
note int

MIDI Note Number
velocity int

Note Velocity

ControlChangeEvent#

A class representing a Control Change event.

Attributes:

Name Type Description
channel int

MIDI Channel
control int

Control Number
value int

Control Value

__init__(channel, control, value) #

Parameters:

Name Type Description
channel int

MIDI Channel
control int

Control Number
value int

Control Value

AftertouchEvent#

A class representing an Aftertouch event.

Attributes:

Name Type Description
channel int

MIDI Channel
note int

MIDI Note Number
value int

Aftertouch Value

__init__(channel, note, value) #

Parameters:

Name Type Description
channel int

MIDI Channel
note int

MIDI Note Number
value int

Aftertouch Value

ProgramChangeEvent#

A class representing a Program Change event.

Attributes:

Name Type Description
channel int

MIDI Channel
program int

Program Number

__init__(channel, program) #

Parameters:

Name Type Description
channel int

MIDI Channel
program int

Program Number

ChannelPressureEvent#

A class representing a Channel Pressure event.

Attributes:

Name Type Description
channel int

MIDI Channel
value int

Pressure Value

__init__(channel, value) #

Parameters:

Name Type Description
channel int

MIDI Channel
value int

Pressure Value

PitchBendEvent#

A class representing a Pitch Bend event.

Attributes:

Name Type Description
channel int

MIDI Channel
value int

Pitch Bend Value

__init__(channel, value) #

Parameters:

Name Type Description
channel int

MIDI Channel
value int

Pitch Bend Value

Control14BitChangeEvent#

A class representing a 14-bit Control Change event.

Attributes:

Name Type Description
channel int

MIDI Channel
control int

Control Number
value int

Control Value

__init__(channel, control, value) #

Parameters:

Name Type Description
channel int

MIDI Channel
control int

Control Number
value int

Control Value

NRPNChangeEvent#

A class representing a Non-Registered Parameter Number Change event.

Attributes:

Name Type Description
channel int

MIDI Channel
param int

Parameter Number
value int

Parameter Value

__init__(channel, param, value) #

Parameters:

Name Type Description
channel int

MIDI Channel
param int

Parameter Number
value int

Parameter Value

RPNChangeEvent#

A class representing a Registered Parameter Number Change event.

Attributes:

Name Type Description
channel int

MIDI Channel
param int

Parameter Number
value int

Parameter Value

__init__(channel, param, value) #

Parameters:

Name Type Description
channel int

MIDI Channel
param int

Parameter Number
value int

Parameter Value

pimidipy System Common Events#

SongPositionPointerEvent#

A class representing a Song Position Pointer event.

Attributes:

Name Type Description
position int

Song Position - 14-bit value. Position is counted in "MIDI beats" (1 beat = 6 MIDI clocks)

__init__(position) #

Parameters:

Name Type Description
position int

Song Position

SongSelectEvent#

A class representing a Song Select event.

Attributes:

Name Type Description
song int

Song Number

__init__(song) #

Parameters:

Name Type Description
song int

Song Number

TuneRequestEvent#

A class representing a Tune Request event.

__init__() #

Default Constructor.

SysExEvent#

A class representing a System Exclusive event.

Attributes:

Name Type Description
data bytes

SysEx Data

__init__(data) #

Parameters:

Name Type Description
data bytes

SysEx Data

pimidipy System Real Time Events#

StartEvent#

A class representing a Start event.

__init__() #

Default Constructor.

ContinueEvent#

A class representing a Continue event.

__init__() #

Default Constructor.

StopEvent#

A class representing a Stop event.

__init__() #

Default Constructor.

ClockEvent#

A class representing a Clock event. 24 Clock events make up a quarter note.

__init__() #

Default Constructor.

ResetEvent#

A class representing a Reset event.

__init__() #

Default Constructor.

ActiveSensingEvent#

A class representing an Active Sensing event.

__init__() #

Default Constructor.

Other Events#

MidiBytesEvent#

A class for writing Raw MIDI Bytes to an OutputPort.

Attributes:

Name Type Description
data bytes

Raw MIDI Bytes

__init__(data) #

Parameters:

Name Type Description
data bytes

Raw MIDI Bytes