Miscelanous objects

class alsa_midi.Address(arg1: int, arg2: int = 0)[source]

class alsa_midi.Address(arg1: AddressType)

class alsa_midi.Address(arg1: str)

class alsa_midi.Address(arg1: SequencerClient, arg2: int = 0)

ALSA sequencer port address (immutable).

Usage:

>>> addr = Address(128, 1)
>>> addr
Address(client_id=128, port_id=1)
>>> print(f"addres: {addr} client id: {addr.client_id} port id: {addr.port_id}")
addres: 128:1 client id: 128 port id: 1
>>> Address(128, 1)
Address(client_id=128, port_id=1)
>>> Address("128:1")
Address(client_id=128, port_id=1)
>>> addr = Address((128, 1))
Address(client_id=128, port_id=1)
>>> addr = Address(client, 1)
>>> addr = Address(port)

Parameters

arg1 (Union[int, str, Address, Port, PortInfo, Tuple[int, int], SequencerClient]) – address or client_id
arg2 (int) – port id

Variables

client_id – client id
port_id – port id

Return type

Address

class alsa_midi.RealTime(seconds=0, nanoseconds=0)[source]

Event time in seconds and nanoseconds.

Used for precise timing of events.

Parameters

seconds (int) – time in seconds
nanoseconds (int) – nanoseconds

Variables

seconds – number of seconds
nanoseconds – number of nanoseconds

class alsa_midi.ClientInfo(client_id, name='', broadcast_filter=False, error_bounce=False, type=None, card_id=None, pid=None, num_ports=0, event_lost=0, event_filter=None)[source]

Client information.

Represents data from snd_seq_client_info_t

Parameters

client_id (int) – client identifier
name (str) – client name
broadcast_filter (bool) – broadcast filter usage
error_bounce (bool) – error-bounce usage
type (Optional[ClientType]) – client type
card_id (Optional[int]) – card identifier for hardware clients
pid (Optional[int]) – process id for software clients
num_ports (int) – number of opened ports
event_lost (int) – number of lost events
event_filter (Optional[Set[EventType]]) –

Variables

client_id – client identifier
name – client name
broadcast_filter – broadcast filter usage
error_bounce – error-bounce usage
type – client type
card_id – card identifier for hardware clients
pid – process id for software clients
num_ports – number of opened ports
event_lost – number of lost events

Return type

None

class alsa_midi.SystemInfo(queues, clients, ports, channels, cur_clients, cur_queues)[source]

System information.

Represents data from snd_seq_system_info_t

Variables

queues – maximum number of clients
clients – maximum number of ports
ports – maximum number of channels
channels – maximum number of channels
cur_clients – current number of clients
cur_queues – current number of queues

Parameters

queues (int) –
clients (int) –
ports (int) –
channels (int) –
cur_clients (int) –
cur_queues (int) –

Return type

None

class alsa_midi.ClientPool(client_id=0, output_pool=0, input_pool=0, output_room=0, output_free=0, input_free=0)[source]

Client kernel-side memory pool information.

Represents data from snd_seq_client_pool_t

Variables

client_id – client id
output_pool – output pool size
input_pool – input pool size
output_room – output pool room size
output_free – amount of free space in the output pool
input_free – amount of free space in the input pool

Parameters

client_id (int) –
output_pool (int) –
input_pool (int) –
output_room (int) –
output_free (int) –
input_free (int) –

Return type

None

alsa_midi.alsa: Provides direct access to ALSA library functions (snd_seq_*) as cffi bindings.

alsa_midi.ffi: FFI object for use with the alsa bindings.

class alsa_midi.client.StreamOpenType(value)[source]

Stream open type flags.

DUPLEX = 3

INPUT = 2

OUTPUT = 1

class alsa_midi.client.OpenMode(value)[source]

Sequencer client open mode flags.

NONBLOCK = 1

class alsa_midi.client.ClientType(value)[source]

Client type constants.

KERNEL = 2

USER = 1

class alsa_midi.client.SequencerType(value)[source]

Sequencer type constants.

HW = 0

INET = 2

SHM = 1

class alsa_midi.client.SequencerClientBase(client_name, streams=StreamOpenType.DUPLEX, mode=OpenMode.NONBLOCK, sequencer_name='default')[source]

Base class for SequencerClient and AsyncSequencerClient.

Constructor wraps snd_seq_open().

Parameters

client_name (str) – Client name
streams (int) – client streams open type
mode (int) – open mode (should be: OpenMode.NONBLOCK)
sequencer_name (str) –

Variables

client_id – ALSA client id
handle – ALSA client handle (for use with the cffi bindings)

close()[source]

Close the client connection and release any associated resources.

The SequencerClient object won’t be usable any more.

Wraps snd_seq_close().

create_port(name, caps=PortCaps.None, type=PortType.None, *, port_id=None, midi_channels=None, midi_voices=None, synth_voices=None, timestamping=None, timestamp_real=None, timestamp_queue=None)[source]

Create a sequencer port.

Wraps snd_seq_create_port() or snd_seq_create_simple_port().

Parameters

name (str) – port name
caps (PortCaps) – port capability flags
type (PortType) – port type flags
port_id (Optional[int]) – requested port id
midi_channels (Optional[int]) – number of MIDI channels
midi_voices (Optional[int]) – number of MIDI voices
synth_voices (Optional[int]) – number of synth voices
timestamping (Optional[bool]) – request timestamping of incoming events
timestamp_real (Optional[bool]) – timestamp events with real time (otherwise MIDI ticks are used)
timestamp_queue (Optional[Union[Queue, int]]) – queue to use for timestamping

Returns

sequencer port created

Return type

Port

create_queue(name=None, info=None)[source]

Create a new queue.

Wraps snd_seq_create_queue(), snd_seq_alloc_named_queue() or snd_seq_alloc_queue().

Parameters

name (Optional[str]) – queue name
info (Optional[QueueInfo]) – queue creation parameters

Returns

queue object created.

Return type

Queue

drain_output()[source]

Send any outgoing events from the output buffer to the sequencer.

Wraps snd_seq_drain_output().

drop_input()[source]

Remove all incoming events in the input buffer and sequencer queue.

Wraps snd_seq_drop_input().

drop_input_buffer()[source]

Remove all incoming events in the input buffer.

Wraps snd_seq_drop_input_buffer().

drop_output()[source]

Remove all events from the output buffer (client and kernel side).

Wraps snd_seq_drop_output().

drop_output_buffer()[source]

Remove all events from the output buffer (client side only).

Wraps snd_seq_drop_output_buffer().

event_input(prefer_bytes=False)[source]

Receive an incoming event.

When no event is available ALSAError will be raised with errnum set to - errno.EAGAIN.

Wraps snd_seq_event_input() and snd_midi_event_decode() when prefer_bytes is True.

Parameters

prefer_bytes (bool) – set to True to return MidiBytesEvent when possible.
timeout – maximum time (in seconds) to wait for an event. Default: wait forever.

Returns

The event received or None if the timeout has been reached.

event_input_pending(fetch_sequencer=False)[source]

Check events in input buffer.

If events remain on the input buffer of user-space, this method returns the total byte size of events on it. If fetch_sequencer argument is True, this method checks the presence of events on sequencer FIFO When events exist, they are transferred to the input buffer, and the number of received events are returned. If fetch_sequencer argument is zero and no events remain on the input buffer, function simply returns zero.

Wraps snd_seq_event_input_pending().

Parameters: fetch_sequencer (bool) – check events pending on the kernel side too
Return type: int

event_output(event, queue=None, port=None, dest=None)[source]

Output an event.

The event will be appended to the output buffer and sent only when the buffer is full. Use drain_output() to force sending of the events buffered.

May raise an ALSAError when both the client-side and the kernel-side buffers are full.

Wraps snd_seq_event_output().

Parameters

event (Event) – the event to be sent
queue (Optional[Union[Queue, int]]) – the queue to force the event to. Default: send directly, unless event.queue is set.
port (Optional[Union[Port, int]]) – the port to send the event from. Default: the one set in the event.
dest (Optional[Union[Address, Port, PortInfo, Tuple[int, int]]]) – the destination. Default: all subscribers, unless event.dest says otherwise.

Returns

Number of bytes used in the output buffer.

Return type

int

event_output_buffer(event, queue=None, port=None, dest=None)[source]

Output an event to a buffer.

The event won’t be sent, it will just be appended to the output buffer.

The method never blocks, but may raise ALSAError with errnum = - errno.EAGAIN when the buffer is full.

Wraps snd_seq_event_output_buffer().

Parameters

event (Event) – the event to be sent
queue (Optional[Union[Queue, int]]) – the queue to force the event to. Default: send directly, unless event.queue is set.
port (Optional[Union[Port, int]]) – the port to send the event from. Default: the one set in the event.
dest (Optional[Union[Address, Port, PortInfo, Tuple[int, int]]]) – the destination. Default: all subscribers, unless event.dest says otherwise.

Returns

Number of bytes used in the output buffer.

Return type

int

event_output_direct(event, queue=None, port=None, dest=None)[source]

Output an event directly to the sequencer.

The event will be sent directly to the kernel and not stored in the local buffer.

May raise an ALSAError when the kernel-side buffers are full.

Wraps snd_seq_event_output_direct().

Parameters

event (Event) – the event to be sent
queue (Optional[Union[Queue, int]]) – the queue to force the event to. Default: send directly, unless event.queue is set.
port (Optional[Union[Port, int]]) – the port to send the event from. Default: the one set in the event.
dest (Optional[Union[Address, Port, PortInfo, Tuple[int, int]]]) – the destination. Default: all subscribers, unless event.dest says otherwise.

Returns

Number of bytes used in the output buffer.

Return type

int

event_output_pending()[source]

Return the size of pending events on output buffer.

Wraps snd_seq_event_output_pending().

Return type: int

extract_output()[source]

Extract the first event in output buffer.

Wraps snd_seq_extract_output().

Return type: Event

get_client_info(client_id=None)[source]

Obtain information about a client.

Wraps snd_seq_get_client_info() or snd_seq_get_any_client_info().

Parameters: client_id (Optional[int]) – client to get information about. Default: self.
Returns: client information
Return type: ClientInfo

get_client_pool()[source]

Obtain the pool information of the client.

Wraps snd_seq_get_client_pool().

Return type: ClientPool

get_input_buffer_size()[source]

Get input buffer size.

Wraps snd_seq_get_input_buffer_size().

Return type: int

get_named_queue(name)[source]

Get a queue object by name.

Wraps snd_seq_query_named_queue() and snd_seq_set_queue_usage().

Parameters: name (str) – queue name
Returns: queue by the provided name
Return type: Queue

get_output_buffer_size()[source]

Get output buffer size.

Wraps snd_seq_get_output_buffer_size().

Return type: int

get_port_info(port)[source]

Obtain information about a specific port.

Wraps snd_seq_get_port_info() or snd_seq_get_any_port_info().

Parameters: port (Union[int, Address, Port, PortInfo, Tuple[int, int]]) – port to get information about
Returns: port information
Return type: PortInfo

get_queue(queue_id)[source]

Get a queue object by id.

Wraps snd_seq_set_queue_usage() when a new object is returned.

Returns: queue with a provided name
Parameters: queue_id (int) –
Return type: Queue

get_queue_info(queue_id)[source]

Obtain queue attributes.

Wraps snd_seq_get_queue_info().

Parameters: queue_id (int) – identifier of the queue
Returns: queue information
Return type: QueueInfo

get_queue_status(queue_id)[source]

Get queue status.

Wraps snd_seq_get_queue_status().

Parameters: queue_id (int) – identifier of the queue
Return type: QueueStatus

get_sequencer_name()[source]

Get sequencer name.

Wraps snd_seq_name().

Return type: str

get_sequencer_type()[source]

Get sequencer type.

Wraps snd_seq_type().

Return type: SequencerType

get_system_info()[source]

Obtain information about the sequencer.

Wraps snd_seq_system_info().

Returns: system information
Return type: SystemInfo

list_port_subscribers(port, type=None)[source]

Lists subscribers accessing a port.

Wraps snd_seq_query_port_subscribers().

Parameters

port (Union[Address, Port, PortInfo, Tuple[int, int]]) – Port address to query
type (Optional[SubscriptionQueryType]) – limit query to the specific type

Return type

List[SubscriptionQuery]

list_ports(*, input=None, output=None, type=PortType.MIDI_GENERIC, include_system=False, include_midi_through=True, include_no_export=True, only_connectable=True, sort=True)[source]

More friendly interface to list available ports.

Queries ALSA for all clients and ports and returns those matching the selected criteria.

The result is sorted in a way that the first returned entry should be the ‘most usable’ one for the selected purpose. E.g. when output = True then the first entry will be a synthesizer input port rather than the dummy ‘Midi Through’ port. This is still a guess, though, so in the end the user should be able to choose.

Wraps snd_seq_query_next_client() and snd_seq_query_next_port().

Parameters

input (Optional[bool]) – return ports usable for event input (PortCaps.READ)
output (Optional[bool]) – return ports usable for event output (PortCaps.WRITE)
type (PortType) – limit ouput to ports of this type
include_system (bool) – include system ports
include_midi_through (bool) – include ‘midi through’ ports
include_no_export (bool) – include ‘no export’ ports
only_connectable (bool) – only list ports that can be connected to/from
sort (Union[bool, Callable[[PortInfo], Any]]) – output sorting. True to for default algorithm, False to disable sorting (return in ALSA identifiers order) or callable for custom sort key.

Returns

list of port information

Return type

List[PortInfo]

query_named_queue(name)[source]

Query queue by name.

Wraps snd_seq_query_named_queue().

Parameters: name (str) – queue name
Returns: queue id
Return type: int

query_next_client(previous: ClientInfo) → Optional[ClientInfo][source]

query_next_client(previous: Optional[int] = None) → Optional[ClientInfo]

Obtain information about the first or the next sequencer client.

Wraps snd_seq_query_next_client().

Parameters: previous – previous client id or info object, None to query the first one
Returns: client information of None if there are no more clients

query_next_port(client_id: int, previous: PortInfo) → Optional[PortInfo][source]

query_next_port(client_id: int, previous: Optional[int] = None) → Optional[PortInfo]

Obtain information about the first or the next port of a sequencer client.

Wraps snd_seq_query_next_port().

Parameters

client_id – client id
previous – previous client id or info object, None to query the first one

Returns

client information of None if there are no more ports

query_port_subscribers(query)[source]

Queries the subscribers subscribers to a port.

At least, the client id, the port id, the index number and the query type must be set in to perform a proper query. As the query type, SubscriptionQueryType.READ or SubscriptionQueryType.WRITE can be specified to check whether the readers or the writers to the port. To query the first subscription, set 0 to the index number. To list up all the subscriptions, call this method with the index numbers from 0 until this raises ALSAError. Or use list_port_subscribers() instead.

Wraps snd_seq_query_port_subscribers().

Parameters: query (SubscriptionQuery) – Query parameters
Return type: SubscriptionQuery

remove_events(condition: alsa_midi.client.RemoveEvents)[source]

remove_events(condition: alsa_midi.client.RemoveCondition = None, queue: Union[Queue, int] = None, time: RealTime = None, dest: Union[Address, Port, PortInfo, Tuple[int, int]] = None, channel: int = None, event_type: EventType = None, tag: int = None, before: bool = False, ignore_off: bool = None)

Remove selected from output and/or input buffers.

Wraps snd_seq_remove_events().

Note: while this wraps complete ALSA ‘remove events’ API a lot of possible conditions are not actually implemented in ALSA, especially on the kernel side.

Parameters

condition – Condition flags. Additional flags will be added, as needed when other arguments are provided. Can also be a RemoveEvents objects, to describe whole ALSA condition.
queue – Queue (object or id). Seems to be ignored by ALSA.
time – Time (real or tick) to compare event timestamps to.
dest – Destination address
channel – MIDI channel number
event_type – type of events to remove
tag – event tag to matching
before – match events before specified time
ignore_off – do not remove Note Off events

set_client_event_filter(event_type)[source]

Add an event to client’s event filter.

Wraps snd_seq_set_client_event_filter().

Parameters: event_type (EventType) – event type to accept

set_client_info(info)[source]

Set client information including event filter.

Wraps snd_seq_set_client_info().

Parameters: info (ClientInfo) – new client info

set_client_pool(pool)[source]

Change pool settings of the client.

Parameters: pool (ClientPool) – new pool settings

Wraps snd_seq_set_client_pool().

set_client_pool_input(size)[source]

Change input pool size for the client.

Parameters: size (int) – requested pool size

Wraps snd_seq_set_client_pool_input()

set_client_pool_output(size)[source]

Change output pool size for the client.

Parameters: size (int) – requested pool size

Wraps snd_seq_set_client_pool_output()

set_client_pool_output_room(size)[source]

Change output pool room size for the client.

Parameters: size (int) – requested room size

Wraps snd_seq_set_client_pool_output_room()

set_input_buffer_size(size)[source]

Change input buffer size.

Parameters: size (int) – the size of input buffer in bytes

Wraps snd_seq_set_input_buffer_size().

set_output_buffer_size(size)[source]

Change output buffer size.

Parameters: size (int) – the size of output buffer in bytes

Wraps snd_seq_set_output_buffer_size().

set_port_info(port, info)[source]

Set information about a specific own port.

Wraps snd_seq_set_port_info().

Parameters

port (Union[int, Port]) –
info (PortInfo) –

set_queue_info(queue_id, info)[source]

Change queue attributes.

Parameters

queue_id (int) – identifier of the queue
info (QueueInfo) –

Wraps snd_seq_set_queue_info().

subscribe_port(sender, dest, *, queue=None, exclusive=False, time_update=False, time_real=False)[source]

Connect two ALSA ports.

Wraps snd_seq_subscribe_port().

Parameters

sender (Union[Address, Port, PortInfo, Tuple[int, int]]) – source port address
dest (Union[Address, Port, PortInfo, Tuple[int, int]]) – destination port adddress
exclusive (bool) – set up an exclusive connection
queue (Optional[Union[Queue, int]]) – queue to use for time stamping
time_update (bool) – enable time stamp updates
time_real (bool) – use real time instead of MIDI ticks for time stamps

sync_output_queue()[source]

Wait until all events are processed.

Wraps snd_seq_sync_output_queue().

unsubscribe_port(sender, dest)[source]

Disconnect two ALSA ports.

Wraps snd_seq_unsubscribe_port().

Parameters

sender (Union[Address, Port, PortInfo, Tuple[int, int]]) – source port address
dest (Union[Address, Port, PortInfo, Tuple[int, int]]) – destination port adddress