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)
- class alsa_midi.RealTime(seconds, nanoseconds=0)[source]
Event time in seconds and nanoseconds.
Used for precise timing of events.
- 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
- 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
- Return type
- 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
- Return type
- 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.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
andAsyncSequencerClient
.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
- 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().
- 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.
- 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
- 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
- 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
- event_output_pending()[source]
Return the size of pending events on output buffer.
Wraps snd_seq_event_output_pending().
- Return type
- extract_output()[source]
Extract the first event in output buffer.
Wraps snd_seq_extract_output().
- Return type
- 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
- get_client_pool()[source]
Obtain the pool information of the client.
Wraps snd_seq_get_client_pool().
- Return type
- get_input_buffer_size()[source]
Get input buffer size.
Wraps snd_seq_get_input_buffer_size().
- Return type
- get_named_queue(name)[source]
Get a queue object by name.
Wraps snd_seq_query_named_queue() and snd_seq_set_queue_usage().
- get_output_buffer_size()[source]
Get output buffer size.
Wraps snd_seq_get_output_buffer_size().
- Return type
- get_port_info(port)[source]
Obtain information about a specific port.
Wraps snd_seq_get_port_info() or snd_seq_get_any_port_info().
- get_queue(queue_id)[source]
Get a queue object by id.
Wraps snd_seq_set_queue_usage() when a new object is returned.
- get_queue_info(queue_id)[source]
Obtain queue attributes.
Wraps snd_seq_get_queue_info().
- 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
- get_sequencer_name()[source]
Get sequencer name.
Wraps snd_seq_name().
- Return type
- get_sequencer_type()[source]
Get sequencer type.
Wraps snd_seq_type().
- Return type
- get_system_info()[source]
Obtain information about the sequencer.
Wraps snd_seq_system_info().
- Returns
system information
- Return type
- list_port_subscribers(port, type=None)[source]
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)[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().
- 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
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: 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
- set_client_pool_output(size)[source]
Change output pool size for the client.
- Parameters
size (int) – requested pool size
- set_client_pool_output_room(size)[source]
Change output pool room size for the client.
- Parameters
size (int) – requested room size
- set_input_buffer_size(size)[source]
Change input buffer size.
- Parameters
size (int) – the size of input buffer in bytes
- set_output_buffer_size(size)[source]
Change output buffer size.
- Parameters
size (int) – the size of output buffer in bytes
- set_port_info(port, info)[source]
Set information about a specific own port.
Wraps snd_seq_set_port_info().
- set_queue_info(queue_id, info)[source]
Change queue attributes.
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