drumstick  1.1.0
ALSA Sequencer Clients

ALSA clients are any entities using ALSA sequencer services. More...

Detailed Description

ALSA clients are any entities using ALSA sequencer services.

A client may be an application or a device driver for an external MIDI port, like USB MIDI devices or the MIDI/game ports of some sound cards. This library allows to easily create applications managing ALSA clients.

ALSA clients are also file descriptors representing a sequencer device, that must be opened before reading or writing MIDI events. When the client is opened, it is given some handle and a number identifying it to other clients in the system. You can also provide a name for it.

Each ALSA sequencer client can have several ports attached. The ports can be readable or writable, and can be subscribed in pairs: one readable port to one writable port. The subscriptions can be made and queried by external applications, like "aconnect" or "qjackctl".

SystemInfo is an auxiliary class to query several system capabilities.

The PoolInfo class represents a container to query and change some values for the kernel memory pool assigned to an ALSA client.

The ClientInfo class is another container to query and change properties of the MidiClient itself.

The SequencerEventHandler abstract class is used to define an interface that other class can implement to receive sequencer events. It is one of the three methods of delivering input events offered by the library.

Input

MidiClient uses a separate thread to receive events from the ALSA sequencer. The input thread can be started and stopped using the methods MidiClient::startSequencerInput() and MidiClient::stopSequencerInput(). It is necessary to have this thread in mind when using this library to read events. There are three delivering methods of input events:

The selected method depends only on your requirements and your preferences.

Whichever method you select, it excludes the other methods for the same program. A callback takes precedence over the others. If it is not set, then the events are sent if MidiClient::setEventsEnabled() is called. If neither a callback handler is set nor events are enabled, then the signal is emitted. In any case, the event pointer must be deleted by the receiver method.

See Also
http://qt-project.org/doc/qt-5/threads-reentrancy.html

Output

The methods to send a single event to the ALSA sequencer are:

The two first methods usually require a call to MidiClient::drainOutput() to flush the ALSA library output buffer. The third one bypasses the buffer, and doesn't require the call to MidiClient::drainOutput(). Note that the buffer can be automatically drained by the first method when it becomes full.

After being dispatched to the ALSA Sequencer, the events can be scheduled at some time in the future, or immediately. This depends on the following methods of the SequencerEvent class:

When you need to schedule a lot of events, for instance reproducing a Standard MIDI File (SMF) or a MIDI sequence, you may want to use the abstract class SequencerOutputThread.

Memory

There are two memory issues: the memory pool belongs to the kernel sequencer, and can be managed by the class PoolInfo and the methods MidiClient::getPoolInfo() and MidiClient::setPoolInfo(). The library buffer can be controlled using the methods MidiClient::getOutputBufferSize() and MidiClient::setOutputBufferSize() as well as MidiClient::getInputBufferSize() and MidiClient::setInputBufferSize().

See Also
http://www.alsa-project.org/alsa-doc/alsa-lib/group___seq_client.html