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
- 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().
- 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
- 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.
- 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
- 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
- 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
- event_output_pending()
Return the size of pending events on output buffer.
Wraps snd_seq_event_output_pending().
- Return type
- extract_output()
Extract the first event in output buffer.
Wraps snd_seq_extract_output().
- Return type
- 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
- get_client_pool()
Obtain the pool information of the client.
Wraps snd_seq_get_client_pool().
- Return type
- get_input_buffer_size()
Get input buffer size.
Wraps snd_seq_get_input_buffer_size().
- Return type
- get_named_queue(name)
Get a queue object by name.
Wraps snd_seq_query_named_queue() and snd_seq_set_queue_usage().
- get_output_buffer_size()
Get output buffer size.
Wraps snd_seq_get_output_buffer_size().
- Return type
- get_port_info(port)
Obtain information about a specific port.
Wraps snd_seq_get_port_info() or snd_seq_get_any_port_info().
- get_queue(queue_id)
Get a queue object by id.
Wraps snd_seq_set_queue_usage() when a new object is returned.
- get_queue_info(queue_id)
Obtain queue attributes.
Wraps snd_seq_get_queue_info().
- get_queue_status(queue_id)
Get queue status.
Wraps snd_seq_get_queue_status().
- Parameters
queue_id (int) – identifier of the queue
- Return type
- get_sequencer_name()
Get sequencer name.
Wraps snd_seq_name().
- Return type
- get_sequencer_type()
Get sequencer type.
Wraps snd_seq_type().
- Return type
- get_system_info()
Obtain information about the sequencer.
Wraps snd_seq_system_info().
- Returns
system information
- Return type
- 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().
- 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().
- 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
orSubscriptionQueryType.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 raisesALSAError
. Or uselist_port_subscribers()
instead.Wraps snd_seq_query_port_subscribers().
- Parameters
query (SubscriptionQuery) – Query parameters
- Return type
- 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
- set_client_pool_output(size)
Change output pool size for the client.
- Parameters
size (int) – requested pool size
- set_client_pool_output_room(size)
Change output pool room size for the client.
- Parameters
size (int) – requested room size
- set_input_buffer_size(size)
Change input buffer size.
- Parameters
size (int) – the size of input buffer in bytes
- set_output_buffer_size(size)
Change output buffer size.
- Parameters
size (int) – the size of output buffer in bytes
- set_port_info(port, info)
Set information about a specific own port.
Wraps snd_seq_set_port_info().
- set_queue_info(queue_id, info)
Change queue attributes.
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