MIDI::ALSA - the ALSA library, plus some interface functions
use MIDI::ALSA(SND_SEQ_EVENT_PORT_UNSUBSCRIBED); MIDI::ALSA::client( 'Perl MIDI::ALSA client', 1, 1, 0 ); MIDI::ALSA::connectfrom( 0, 14, 0 ); # input port is lower (0) MIDI::ALSA::connectto( 1, 20, 0 ); # output port is higher (1) while (1) { my @alsaevent = MIDI::ALSA::input(); if ($alsaevent[0] == SND_SEQ_EVENT_PORT_UNSUBSCRIBED()) { last; } MIDI::ALSA::output( @alsaevent ); }
This module offers a Perl interface to the ALSA library. It is a call-compatible translation into Perl of the Lua module midialsa http://www.pjb.com.au/comp/lua/midialsa.html which is in turn based on the Python modules alsaseq.py and alsamidi.py by Patricio Paez.
It also offers some functions to translate events from and to the event format used in Sean Burke's MIDI-Perl module.
Nothing is exported by default, but all the functions and constants can be exported, e.g.: use MIDI::ALSA(client, connectfrom, connectto, id, input, output); use MIDI::ALSA(':CONSTS');
The event-type constants, beginning with SND_SEQ_, are available not as scalars, but as module subroutines with empty prototypes. They must therefore be used without a dollar-sign e.g.: if ($event[0] == MIDI::ALSA::SND_SEQ_EVENT_PORT_UNSUBSCRIBED) { ...
Functions based on those in alsaseq.py: client(), connectfrom(), connectto(), disconnectfrom(), disconnectto(), fd(), id(), input(), inputpending(), output(), start(), status(), stop(), syncoutput()
Functions based on those in alsamidi.py: noteevent(), noteonevent(), noteoffevent(), pgmchangeevent(), pitchbendevent(), chanpress(), sysex()
Functions to interface with MIDI-Perl: alsa2scoreevent(), scoreevent2alsa()
Functions to get the current ALSA status: listclients(), listnumports(), listconnectedto(), listconnectedfrom()
Create an ALSA sequencer client with zero or more input or output ports, and optionally a timing queue. ninputports and noutputports are created if the quantity requested is between 1 and 4 for each. If createqueue = true, it creates a queue for stamping the arrival time of incoming events and scheduling future start times of outgoing events.
Unlike in the alsaseq.py Python module, it returns success or failure.
Connect from src_client:src_port to inputport. Each input port can connect from more than one client. The input() function will receive events from any intput port and any of the clients connected to each of them. Events from each client can be distinguised by their source field.
Connect outputport to dest_client:dest_port. Each output port can be Connected to more than one client. Events sent to an output port using the output() funtion will be sent to all clients that are connected to it using this function.
Disconnect the connection from the remote src_client:src_port to my inputport. Returns success or failure.
Disconnect the connection from my outputport to the remote dest_client:dest_port. Returns success or failure.
Return fileno of sequencer.
Return the client number, or 0 if the client is not yet created.
Wait for an ALSA event in any of the input ports and return it. ALSA events are returned as an array with 8 elements:
($type, $flags, $tag, $queue, $time, \@source, \@destination, \@data)
Unlike in the alsaseq.py Python module, the time element is in floating-point seconds. The last three elements are also arrays:
@source = ( $src_client, $src_port ) @destination = ( $dest_client, $dest_port ) @data = ( varies depending on type )
The source and destination arrays may be useful within an application for handling events differently according to their source or destination. The event-type constants, beginning with SND_SEQ_, are available as module subroutines with empty prototypes, not as strings, and must therefore be used without any dollar-sign e.g.:
if ($event[0] == MIDI::ALSA::SND_SEQ_EVENT_PORT_UNSUBSCRIBED) { ...
Note that if the event is of type SND_SEQ_EVENT_PORT_UNSUBSCRIBED then the remote client and port do not get set; you need to use listconnected() to see what's happened.
The data array is mostly as documented in http://alsa-project.org/alsa-doc/alsa-lib/seq.html. For NOTE events, the elements are ( $channel, $pitch, $velocity, unused, $duration ); For SYSEX events, the data array contains just one element: the byte-string, including any F0 and F7 bytes. For most other events, the elements are ($channel, unused,unused,unused, $param, $value)
Return the number of bytes available in input buffer. Use before input() to wait till an event is ready to be read. If a connection terminates, then inputpending() returns, and the next event will be of type SND_SEQ_EVENT_PORT_UNSUBSCRIBED
Send an ALSA-event-array to an output port. The format of the event is discussed in input() above. The event will be output immediately either if no queue was created in the client, or if the queue parameter is set to SND_SEQ_QUEUE_DIRECT and otherwise it will be queued and scheduled.
If only one port exists, all events are sent to that port. If two or more output ports exist, the dest_port of the event determines which to use. The smallest available port-number ( as created by client() ) will be used if dest_port is less than it, and the largest available port-number will be used if dest_port is greater than it.
An event sent to an output port will be sent to all clients that were subscribed using the connectto() function.
If the queue buffer is full, output() will wait until space is available to output the event. Use status() to know how many events are scheduled in the queue.
Start the queue. It is ignored if the client does not have a queue.
Return ($status,$time,$events ) of the queue.
Status: 0 if stopped, 1 if running. Time: current time in seconds. Events: number of output events scheduled in the queue.
If the client does not have a queue then (0,0,0) is returned. Unlike in the alsaseq.py Python module, the time element is in floating-point seconds.
Stop the queue. It is ignored if the client does not have a queue.
Wait until output events are processed.
Returns an ALSA-event-array, to be scheduled by output(). Unlike in the alsaseq.py Python module, the start and duration elements are in floating-point seconds.
Returns an ALSA-event-array to be sent directly with output().
Returns an ALSA-event-array to be sent by output(). If start is not used, the event will be sent directly; if start is provided, the event will be scheduled in a queue. Unlike in the alsaseq.py Python module, the start element, when provided, is in floating-point seconds.
Returns an ALSA-event-array to be sent by output(). If start is not used, the event will be sent directly; if start is provided, the event will be scheduled in a queue. The string should start with your Manufacturer ID, but should not contain any of the F0 or F7 bytes, they will be added automatically; indeed the string must not contain any bytes with the top-bit set.
Returns an event in the millisecond-tick score-format used by the MIDI.lua and MIDI.py modules, based on the score-format in Sean Burke's MIDI-Perl CPAN module. See: http://www.pjb.com.au/comp/lua/MIDI.html#events
Since it combines a note_on and a note_off event into one note event, it will return nil when called with the note_on event; the calling loop must therefore detect nil and not, for example, try to index it.
Returns an ALSA-event-array to be scheduled in a queue by output(). The input is an event in the millisecond-tick score-format used by the MIDI.lua and MIDI.py modules, based on the score-format in Sean Burke's MIDI-Perl CPAN module. See: http://www.pjb.com.au/comp/lua/MIDI.html#events
For example: output(scoreevent2alsa('note',4000,1000,0,62,110))
Some events in a .mid file have no equivalent real-time-midi event (which is the sort that ALSA deals in); these events will cause scoreevent2alsa() to return undef. Therefore if you are going through the events in a midi score converting them with scoreevent2alsa(), you should check that the result is not undef before doing anything further.
Returns a hash of the numbers and descriptive strings of all ALSA clients:
my %clientnumber2clientname = MIDI::ALSA::listclients(); my %clientname2clientnumber = reverse %clientnumber2clientname;
Returns a hash of the client-numbers and how many ports they are running, so if a client is running 4 ports they will be numbered 0..3
my %clientnumber2howmanyports = MIDI::ALSA::listnumports();
Returns a list of arrayrefs, each to a three-element array ( $outputport, $dest_client, $dest_port ) exactly as might have been passed to connectto(), or which could be passed to disconnectto().
Returns a list of arrayrefs, each to a three-element array ( $inputport, $src_client, $src_port ) exactly as might have been passed to connectfrom(), or which could be passed to disconnectfrom().
This Perl version is available from CPAN at http://search.cpan.org/perldoc?MIDI::ALSA
The Lua module is available as a LuaRock in http://luarocks.org/repositories/rocks/index.html#midi so you should be able to install it with the command: # luarocks install midialsa
Perhaps there should be a general connect_between() mechanism, allowing the interconnection of two other clients, a bit like aconnect 32 20
If an event is of type SND_SEQ_EVENT_PORT_UNSUBSCRIBED then the remote client and port seem to be zeroed-out, which makes it hard to know which client has just disconnected. You have to consult listconnectedto() and listconnectedfrom()
ALSA does not transmit Meta-Events like text_event, and there's not much can be done about that.
Peter J Billam, http://www.pjb.com.au/comp/contact.html
aconnect -oil http://pp.com.mx/python/alsaseq http://search.cpan.org/perldoc?MIDI::ALSA http://www.pjb.com.au/comp/lua/midialsa.html http://luarocks.org/repositories/rocks/index.html#midialsa http://www.pjb.com.au/comp/lua/MIDI.html http://www.pjb.com.au/comp/lua/MIDI.html#events http://alsa-project.org/alsa-doc/alsa-lib/seq.html http://alsa-project.org/alsa-doc/alsa-lib/structsnd__seq__ev__note.html http://alsa-project.org/alsa-doc/alsa-lib/structsnd__seq__ev__ctrl.html http://alsa-project.org/alsa-doc/alsa-lib/structsnd__seq__ev__queue__control.html http://alsa-project.org/alsa-doc/alsa-lib/group___seq_client.html http://alsa-utils.sourcearchive.com/documentation/1.0.20/aconnect_8c-source.html http://alsa-utils.sourcearchive.com/documentation/1.0.8/aplaymidi_8c-source.html snd_seq_client_info_event_filter_clear snd_seq_get_any_client_info snd_seq_get_client_info snd_seq_client_info_t
To install MIDI::ALSA, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MIDI::ALSA
CPAN shell
perl -MCPAN -e shell install MIDI::ALSA
For more information on module installation, please visit the detailed CPAN module installation guide.