Asynchronous Client API

class alsa_midi.AsyncSequencerClient(*args, **kwargs)[source]

ALSA sequencer client connection (async API).

This is the other main interface to interact with the sequencer. Provides asynchronous (asyncio) event I/O.

Mostly the same as SequencerClient, but a few methods are coroutines here.

Parameters

  • client_name – client name for the connection

  • kwargs – arguments for the SequencerClientBase constructor

async aclose()[source]

Close the client connection and release any associated resources.

The SequencerClient object won’t be usable any more.

Currently the same as close().

close()

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)

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)

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

async drain_output()[source]

Send events in the output queue to the sequencer.

May block when the kernel-side buffer is full.

Wraps snd_seq_drain_output().

Returns

Number of bytes remaining in the buffer.

Return type

int

drop_input()

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

Wraps snd_seq_drop_input().

drop_input_buffer()

Remove all incoming events in the input buffer.

Wraps snd_seq_drop_input_buffer().

drop_output()

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

Wraps snd_seq_drop_output().

drop_output_buffer()

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

Wraps snd_seq_drop_output_buffer().

async event_input(prefer_bytes=False, timeout=None)[source]

Wait for and receive an incoming event.

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

Parameters

  • prefer_bytes (bool) – set to True to return MidiBytesEvent when possible.

  • timeout (Optional[float]) – maximum time (in seconds) to wait for an event. Default: wait forever.

Returns

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

Return type

Optional[Event]

event_input_pending(fetch_sequencer=False)

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

async 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 block 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)

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

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

Output an event without buffering.

The event will be sent immediately. The function may block when the kernel-side buffer is 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 sent to the sequencer.

Return type

int

event_output_pending()

Return the size of pending events on output buffer.

Wraps snd_seq_event_output_pending().

Return type

int

extract_output()

Extract the first event in output buffer.

Wraps snd_seq_extract_output().

Return type

Event

get_client_info(client_id=None)

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()

Obtain the pool information of the client.

Wraps snd_seq_get_client_pool().

Return type

ClientPool

get_input_buffer_size()

Get input buffer size.

Wraps snd_seq_get_input_buffer_size().

Return type

int

get_named_queue(name)

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()

Get output buffer size.

Wraps snd_seq_get_output_buffer_size().

Return type

int

get_port_info(port)

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)

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)

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)

Get queue status.

Wraps snd_seq_get_queue_status().

Parameters

queue_id (int) – identifier of the queue

Return type

QueueStatus

get_sequencer_name()

Get sequencer name.

Wraps snd_seq_name().

Return type

str

get_sequencer_type()

Get sequencer type.

Wraps snd_seq_type().

Return type

SequencerType

get_system_info()

Obtain information about the sequencer.

Wraps snd_seq_system_info().

Returns

system information

Return type

SystemInfo

list_port_subscribers(port, type=None)

Lists subscribers accessing a port.

Wraps snd_seq_query_port_subscribers().

Parameters
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)

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)

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=None)

Obtain information about the first or the next sequencer client.

Wraps snd_seq_query_next_client().

Parameters

previous (Optional[Union[ClientInfo, int]]) – previous client id or info object, None to query the first one

Returns

client information of None if there are no more clients

Return type

Optional[ClientInfo]

query_next_port(client_id, previous=None)

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

Wraps snd_seq_query_next_port().

Parameters

  • client_id (int) – client id

  • previous (Optional[Union[PortInfo, int]]) – previous client id or info object, None to query the first one

Returns

client information of None if there are no more ports

Return type

Optional[PortInfo]

query_port_subscribers(query)

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=None, queue=None, time=None, dest=None, channel=None, event_type=None, tag=None, before=False, ignore_off=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 (Optional[Union[alsa_midi.client.RemoveEvents, alsa_midi.client.RemoveCondition]]) – 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 (Optional[Union[Queue, int]]) – Queue (object or id). Seems to be ignored by ALSA.

  • time (Optional[Union[RealTime, int]]) – Time (real or tick) to compare event timestamps to.

  • dest (Optional[Union[Address, Port, PortInfo, Tuple[int, int]]]) – Destination address

  • channel (Optional[int]) – MIDI channel number

  • event_type (Optional[EventType]) – type of events to remove

  • tag (Optional[int]) – event tag to matching

  • before (bool) – match events before specified time

  • ignore_off (Optional[bool]) – do not remove Note Off events

set_client_event_filter(event_type)

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)

Set client information including event filter.

Wraps snd_seq_set_client_info().

Parameters

info (ClientInfo) – new client info

set_client_pool(pool)

Change pool settings of the client.

Parameters

pool (ClientPool) – new pool settings

Wraps snd_seq_set_client_pool().

set_client_pool_input(size)

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)

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)

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)

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)

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)

Set information about a specific own port.

Wraps snd_seq_set_port_info().

Parameters
set_queue_info(queue_id, info)

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)

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

unsubscribe_port(sender, dest)

Disconnect two ALSA ports.

Wraps snd_seq_unsubscribe_port().

Parameters