Controller listeners

These objects can be used to create MIDI and/or OSC listeners without the need to boot ands start an audio server before receiving messages.

Objects in this category

• MidiListener : Self-contained midi listener thread.

• MidiDispatcher : Self-contained midi dispatcher thread.

• OscListener : Self-contained OSC listener thread.

MidiListener

class MidiListener(function, mididev=-1, reportdevice=False)

Self-contained midi listener thread.

This object allows to setup a Midi server that is independent of the audio server (mainly to be able to receive Midi data even when the audio server is stopped). Although it runs in a separated thread, the same device can’t be used by this object and the audio server at the same time. It is adviced to call the deactivateMidi() method on the audio server to avoid conflicts.

Parent

threading.Thread

Args

function: Python function (can’t be a list)

Function that will be called when a new midi event is available. This function is called with the incoming midi data as arguments. The signature of the function must be:

def myfunc(status, data1, data2)

mididev: int or list of ints, optional

Sets the midi input device (see pm_list_devices() for the available devices). The default, -1, means the system default device. A number greater than the highest portmidi device index will open all available input devices. Specific devices can be set with a list of integers.

reportdevice: boolean, optional

If True, the device ID will be reported as a fourth argument to the callback. The signature will then be:

def myfunc(status, data1, data2, id)

Available at initialization only. Defaults to False.

Note

This object is available only if pyo is built with portmidi support (see withPortmidi function).

>>> s = Server()
>>> s.deactivateMidi()
>>> s.boot()
>>> def midicall(status, data1, data2):
...     print(status, data1, data2)
>>> listen = MidiListener(midicall, 5)
>>> listen.start()

Public Data Attributes:

Inherited from Thread

name	A string used for identification purposes only.
ident	Thread identifier of this thread or None if it has not been started.
native_id	Native integral thread ID of this thread, or None if it has not been started.
daemon	A boolean value indicating whether this thread is a daemon thread.

Public Methods:

__init__(function[, mididev, reportdevice])	This constructor should always be called with keyword arguments.
run()	Starts the process.
stop()	Stops the listener and properly close the midi ports.
getDeviceInfos()	Returns infos about connected midi devices.

Inherited from Thread

__init__([group, target, name, args, ...])	This constructor should always be called with keyword arguments.
__repr__()	Return repr(self).
start()	Start the thread's activity.
run()	Method representing the thread's activity.
join([timeout])	Wait until the thread terminates.
is_alive()	Return whether the thread is alive.
isDaemon()
setDaemon(daemonic)
getName()
setName(name)

Private Data Attributes:

Inherited from Thread

_initialized

Private Methods:

Inherited from Thread

_reset_internal_locks(is_alive)
_bootstrap()
_set_ident()
_set_native_id()
_set_tstate_lock()	Set a lock object which will be released by the interpreter when the underlying thread state (see pystate.h) gets deleted.
_bootstrap_inner()
_stop()
_delete()	Remove current thread from the dict of currently running threads.
_wait_for_tstate_lock([block, timeout])

---

run()

Starts the process. The thread runs as daemon, so no need to stop it.

stop()

Stops the listener and properly close the midi ports.

getDeviceInfos()

Returns infos about connected midi devices.

This method returns a list of dictionaries, one per device.

Dictionary format is:

{“id”: device_id (int), “name”: device_name (str), “interface”: interface (str)}

MidiDispatcher

class MidiDispatcher(mididev=-1)

Self-contained midi dispatcher thread.

This object allows to setup a Midi server that is independent of the audio server (mainly to be able to send Midi data even when the audio server is stopped). Although it runs in a separated thread, the same device can’t be used by this object and the audio server at the same time. It is adviced to call the deactivateMidi() method on the audio server to avoid conflicts.

Use the send method to send midi event to connected devices.

Use the sendx method to send sysex event to connected devices.

Parent

threading.Thread

Args

mididev: int or list of ints, optional

Sets the midi output device (see pm_list_devices() for the available devices). The default, -1, means the system default device. A number greater than the highest portmidi device index will open all available input devices. Specific devices can be set with a list of integers.

Note

This object is available only if pyo is built with portmidi support (see withPortmidi function).

>>> s = Server()
>>> s.deactivateMidi()
>>> s.boot()
>>> dispatch = MidiDispatcher(5)
>>> dispatch.start()
>>> dispatch.send(144, 60, 127)

Public Data Attributes:

Inherited from Thread

name	A string used for identification purposes only.
ident	Thread identifier of this thread or None if it has not been started.
native_id	Native integral thread ID of this thread, or None if it has not been started.
daemon	A boolean value indicating whether this thread is a daemon thread.

Public Methods:

__init__([mididev])	This constructor should always be called with keyword arguments.
run()	Starts the process.
send(status, data1[, data2, timestamp, device])	Send a MIDI message to the selected midi output device.
sendx(msg[, timestamp, device])	Send a MIDI system exclusive message to the selected midi output device.
getDeviceInfos()	Returns infos about connected midi devices.

Inherited from Thread

__init__([group, target, name, args, ...])	This constructor should always be called with keyword arguments.
__repr__()	Return repr(self).
start()	Start the thread's activity.
run()	Method representing the thread's activity.
join([timeout])	Wait until the thread terminates.
is_alive()	Return whether the thread is alive.
isDaemon()
setDaemon(daemonic)
getName()
setName(name)

Private Data Attributes:

Inherited from Thread

_initialized

Private Methods:

Inherited from Thread

_reset_internal_locks(is_alive)
_bootstrap()
_set_ident()
_set_native_id()
_set_tstate_lock()	Set a lock object which will be released by the interpreter when the underlying thread state (see pystate.h) gets deleted.
_bootstrap_inner()
_stop()
_delete()	Remove current thread from the dict of currently running threads.
_wait_for_tstate_lock([block, timeout])

---

run()

Starts the process. The thread runs as daemon, so no need to stop it.

send(status, data1, data2=0, timestamp=0, device=-1)

Send a MIDI message to the selected midi output device.

Arguments can be list of values to generate multiple events in one call.

Args

status: int

Status byte.

data1: int

First data byte.

data2: int, optional

Second data byte. Defaults to 0.

timestamp: int, optional

The delay time, in milliseconds, before the note is sent on the portmidi stream. A value of 0 means to play the note now. Defaults to 0.

device: int, optional

The index of the device to which the message will be sent. The default (-1) means all devices. See getDeviceInfos() to retrieve device indexes.

sendx(msg, timestamp=0, device=-1)

Send a MIDI system exclusive message to the selected midi output device.

Arguments can be list of values to generate multiple events in one call.

Args

msg: str

A valid system exclusive message as a string. The first byte must be 0xf0 and the last one must be 0xf7.

timestamp: int, optional

The delay time, in milliseconds, before the note is sent on the portmidi stream. A value of 0 means to play the note now. Defaults to 0.

device: int, optional

The index of the device to which the message will be sent. The default (-1) means all devices. See getDeviceInfos() to retrieve device indexes.

getDeviceInfos()

Returns infos about connected midi devices.

This method returns a list of dictionaries, one per device.

Dictionary format is:

{“id”: device_id (int), “name”: device_name (str), “interface”: interface (str)}

OscListener

class OscListener(function, port=9000)

Self-contained OSC listener thread.

This object allows to setup an OSC server that is independent of the audio server (mainly to be able to receive OSC data even when the audio server is stopped).

Parent

threadind.Thread

Args

function: Python function (can’t be a list)

Function that will be called when a new OSC event is available. This function is called with the incoming address and values as arguments. The signature of the function must be:

def myfunc(address, *args)

port: int, optional

The OSC port on which the values are received. Defaults to 9000.

>>> s = Server().boot()
>>> def call(address, *args):
...     print(address, args)
>>> listen = OscListener(call, 9901)
>>> listen.start()

Public Data Attributes:

Inherited from Thread

name	A string used for identification purposes only.
ident	Thread identifier of this thread or None if it has not been started.
native_id	Native integral thread ID of this thread, or None if it has not been started.
daemon	A boolean value indicating whether this thread is a daemon thread.

Public Methods:

__init__(function[, port])	This constructor should always be called with keyword arguments.
run()	Starts the process.

Inherited from Thread

__init__([group, target, name, args, ...])	This constructor should always be called with keyword arguments.
__repr__()	Return repr(self).
start()	Start the thread's activity.
run()	Method representing the thread's activity.
join([timeout])	Wait until the thread terminates.
is_alive()	Return whether the thread is alive.
isDaemon()
setDaemon(daemonic)
getName()
setName(name)

Private Data Attributes:

Inherited from Thread

_initialized

Private Methods:

_oscrecv(address, *args)

Inherited from Thread

_reset_internal_locks(is_alive)
_bootstrap()
_set_ident()
_set_native_id()
_set_tstate_lock()	Set a lock object which will be released by the interpreter when the underlying thread state (see pystate.h) gets deleted.
_bootstrap_inner()
_stop()
_delete()	Remove current thread from the dict of currently running threads.
_wait_for_tstate_lock([block, timeout])

---

run()

Starts the process. The thread runs as daemon, so no need to stop it.