Synchronous Client API

class alsa_midi.SequencerClient(client_name, **kwargs)[source]

ALSA sequencer client connection.

This is the main interface to interact with the sequencer. Provides synchronous (blocking) event I/O.

Parameters:

  • client_name (str) – client name for the connection

  • kwargs – arguments for the SequencerClientBase constructor

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.READ|WRITE|SUBS_READ|SUBS_WRITE: 99>, type=<PortType.MIDI_GENERIC|SOFTWARE: 131074>, *, 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 (int | None) – requested port id

  • midi_channels (int | None) – number of MIDI channels

  • midi_voices (int | None) – number of MIDI voices

  • synth_voices (int | None) – number of synth voices

  • timestamping (bool | None) – request timestamping of incoming events

  • timestamp_real (bool | None) – timestamp events with real time (otherwise MIDI ticks are used)

  • timestamp_queue (Queue | int | None) – 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 (str) – queue name

  • info (QueueInfo) – queue creation parameters

Returns:

queue object created.

Return type:

Queue

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

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

Wait for and receive an incoming event.

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 (float | None) – 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:

Event | None

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

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 (Queue | int) – the queue to force the event to. Default: send directly, unless event.queue is set.

  • port (Port | int) – the port to send the event from. Default: the one set in the event.

  • dest (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 (Queue | int) – the queue to force the event to. Default: send directly, unless event.queue is set.

  • port (Port | int) – the port to send the event from. Default: the one set in the event.

  • dest (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 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 (Queue | int) – the queue to force the event to. Default: send directly, unless event.queue is set.

  • port (Port | int) – the port to send the event from. Default: the one set in the event.

  • dest (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 (int | None) – 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 (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: 2>, 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 (bool) – return ports usable for event input (PortCaps.READ)

  • output (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 (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 (ClientInfo | int | None) – 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:

ClientInfo | None

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 (PortInfo | int | None) – 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:

PortInfo | None

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 (RemoveEvents | 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 (Queue | int) – Queue (object or id). Seems to be ignored by ALSA.

  • time (RealTime | int) – Time (real or tick) to compare event timestamps to.

  • dest (Address | Port | PortInfo | tuple[int, int]) – Destination address

  • channel (int) – MIDI channel number

  • event_type (EventType) – type of events to remove

  • tag (int) – event tag to matching

  • before (bool) – match events before specified time

  • ignore_off (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:
sync_output_queue()

Wait until all events are processed.

Wraps snd_seq_sync_output_queue().

unsubscribe_port(sender, dest)

Disconnect two ALSA ports.

Wraps snd_seq_unsubscribe_port().

Parameters: