Why not adopt me?

This distribution is up for adoption! If you're interested then please contact the PAUSE module admins via email.

NAME

MIDI::ALSA - the ALSA library, plus some interface functions

SYNOPSIS

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 );
}

DESCRIPTION

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

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(), controllerevent(), chanpress(), sysex()

Functions to interface with MIDI-Perl: alsa2scoreevent(), scoreevent2alsa()

Functions to get the current ALSA status: listclients(), listnumports(), listconnectedto(), listconnectedfrom()

client($name, $ninputports, $noutputports, $createqueue)

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 64 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.

connectfrom( $inputport, $src_client, $src_port )

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.

Unlike in the alsaseq.py Python module, it returns success or failure.

connectto( $outputport, $dest_client, $dest_port )

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.

Unlike in the alsaseq.py Python module, it returns success or failure.

disconnectfrom( $inputport, $src_client, $src_port )

Disconnect the connection from the remote src_client:src_port to my inputport. Returns success or failure.

disconnectto( $outputport, $dest_client, $dest_port )

Disconnect the connection from my outputport to the remote dest_client:dest_port. Returns success or failure.

fd()

Return fileno of sequencer.

id()

Return the client number, or 0 if the client is not yet created.

input()

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)

inputpending()

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

output($type,$flags,$tag,$queue,$time,\@source,\@destination,\@data)

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

Start the queue. It is ignored if the client does not have a queue.

status()

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

Stop the queue. It is ignored if the client does not have a queue.

syncoutput()

Wait until output events are processed.

noteevent( $ch, $key, $vel, $start, $duration )

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.

noteonevent( $ch, $key, $vel )

Returns an ALSA-event-array to be sent directly with output().

noteoffevent( $ch, $key, $vel )

Returns an ALSA-event-array to be sent directly with output().

pgmchangeevent( $ch, $value, $start )

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.

pitchbendevent( $ch, $value, $start )

Returns an ALSA-event-array to be sent by output(). The value is from -8192 to 8191. 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.

controllerevent( $ch, $controllernum, $value, $start )

chanpress( $ch, $value, $start )

sysex( $ch, $string, $start )

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.

alsa2scoreevent( @alsaevent )

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.

scoreevent2alsa( @event )

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.

listclients()

Returns a hash of the numbers and descriptive strings of all ALSA clients:

my %clientnumber2clientname = MIDI::ALSA::listclients();
my %clientname2clientnumber = reverse %clientnumber2clientname;

listnumports()

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

listconnectedto()

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

listconnectedfrom()

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

DOWNLOAD

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

TO DO

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.

AUTHOR

Peter J Billam, http://www.pjb.com.au/comp/contact.html

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

Why not adopt me?

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

DOWNLOAD

TO DO

AUTHOR

SEE ALSO

Module Install Instructions