ALSA MIDI Kommander is a DCOP  interface exposing many ALSA Sequencer  features for shell scripts, Kommander scripts, or KDE programs requiring MIDI Sequencer services. A few MIDI utilities have been developed with this tool, which can be used both as programming examples and as real work tools.
Motivations for writing these things were the complexity of the ALSA Sequencer API programming, and the need for an extensible set of MIDI tools, built from a common set of reusable pieces.
This document tries to explain the behavior
and main features of the system. This is a work in progress, and some
are expected as long as the system is maturing and growing.
Copyright (C) 2005, Pedro Lopez-Cabanillas <plcl AT users.sourceforge.net>
The main program, "kaseq" is a single executable, used as a DCOP service program. It runs as a daemon, allowing only a single running instance, and providing a system tray icon to give visual feedback for MIDI activity, and a way to control the program execution itself. It depends on KDE 3.x and the Qt library.
You can write DCOP  clients in C++, or use a ready-to-use one:
- dcop CLI utility, it is used mainly for Bash scripts or directly in the command line.
- kdcop, is a GUI utility, with a DCOP services browser and executor. Very useful to explore and learn.
- Kommander . It is a two part application. The first part is the editor, based on "Qt-designer", where you visually build dialogs and applications and edit the scripting elements. The second part is the executor which processes the generated XML file. With Kommander, you can write scripts with rich Graphic User Interfaces.
ALSA  is an audio and MIDI system infrastructure for Linux. It is included in Linux 2.6.x kernels as a set of drivers and modules, and has a user-space library providing a powerful and complex API. The sequencer part is the high level MIDI engine providing support for input and output MIDI streams, time-stamped events, and routing the streams between clients which can be hardware (MIDI physical ports) or software clients (applications). There is a lot of documentation  around.
Following is a brief enumeration of the current functions available as DCOP calls. The first parameter (QString name) is common to all functions, and identifies each Sequencer client. The client instance is created on the open() call, and it is destroyed on a corresponding close(). All other functions for this client must be invoked with the same client name.
Currently, there are only functions for sending non scheduled events. Future plans are to provide functions for incoming (recording) events with- and without timestamp, queue management, and a set of easy String-based syntax commands.
These functions manage the creation and destruction of the Sequencer client instance, and the associated Port.
QString name, QString ports )
Creates one sequencer client instance and one sequencer port;
"ports" argument can be: "IN", "OUT", or "IO".
void openInput( QString name )
Same as open( name, "IN" )
void openOutput( QString name )
Same as open( name, "OUT" )
void openDuplex( QString name )
Same as open( name, "IO" )
void open( QString name )
Same as openOutput( name )
void close( QString name )
Destroys one Sequencer client instance
The following functions provide the means to establish port subscriptions between the internal Sequencer port and another external one, or between two arbitrary sequencer ports.
QString name, QString
int connectFrom( QString name, QString port )
int disconnectTo( QString name, QString port )
int disconnectFrom( QString name, QString port )
int connectTwo( QString name, QString sender, QString dest )
int disconnectTwo( QString name, QString orig, QString dest )
void disconnectAll( QString name )
The following functions provide a list of ALSA Sequencer ports available in the system.
QStringList availableInputs( QString
QStringList availableOutputs( QString name )
These functions can be used to send any MIDI event to all the subscribed destinations.
QString name, int chan,
int pitch, int vel )
int sendNoteOff( QString name, int chan, int pitch, int vel )
int sendCtlChange( QString name, int chan, int control, int value )
int sendPgmChange( QString name, int chan, int program )
int sendPolyAft( QString name, int chan, int pitch, int value )
int sendChanAft( QString name, int chan, int value )
int sendBender( QString name, int chan, int value )
int sendSystemRealTime( QString name, int msg )
int sendSysex( QString name, QByteArray data )
int sendSysex( QString name, QString data )
These are convenient functions with self-explained names.
getLastError( QString name )
In the directory examples/ of the distribution package you can find several shell and Kommander script examples.
All of them require the "kaseq" program. It can be executed at the command line prompt or invoked by the scripts in the initialization stage. It is a daemon-like program, allowing only a single running instance, and also providing a system tray icon. The icon shows a simulated green LED lighting when there is some outgoing MIDI activity. Another red LED is provided for incoming MIDI, which will be more useful in the future.
dcop kaseq kaseqIface openOutput "$CLIENTNAME"
dcop kaseq kaseqIface connectTo "$CLIENTNAME" "$DESTINATION"
dcop kaseq kaseqIface sendPgmChange "$CLIENTNAME" 0 55
dcop kaseq kaseqIface sendCtlChange "$CLIENTNAME" 0 7 127
dcop kaseq kaseqIface sendNoteOn "$CLIENTNAME" 0 66 127
dcop kaseq kaseqIface sendNoteOff "$CLIENTNAME" 0 66 127
dcop kaseq kaseqIface close "$CLIENTNAME"
This example shows some basic functionality. First, two variables are defined for the client name (Example1) and the destination port (KMidimon:0). The flow begins with an open() call, then a connectTo() to subscribe the created port with the input port of the KMidimon application, which should be started previously. You can find KMidimon in the resources . After that, you can send some events to the subscribed ports, and finally call close() to release resources.
Example2 is very similar, using a different way to call dcop with error checking.
Example3 shows how to detect if some sequencer client is already running, examining the list returned by availableOutputs().
Example4 introduces a Kommander dialog, invoked from a shell script. This is not the best way to do it, as you will see in the following section.
To run the dialogs, you can use a command like with the following syntax:
$ kmdr-executor example5.kmdr
Or simply, double click over the .kmdr file name in Konqueror.
To learn about Kommander, go to the program home page  and read the documentation. It works basically with associated text holding script snippets. Every example has an initialization section (as associated text) with the following lines:
The first line executes "kaseq" if it is not running already. Then, a global variable CLIENT_NAME is created, with the name that will be used for all the following dcop calls. Also, a combo box component is populated with the available output ports. There is also an associated text invoked before the dialog is closed:
When the user selects some item with the combo box, a ScriptObject.execute() method is invoked, which holds the following snippet with shell script syntax:
dcop kaseq kaseqIface disconnectAll @global(CLIENT_NAME)
if [ @Connections.currentItem -ne 0 ]; then
dcop kaseq kaseqIface connectTo @global(CLIENT_NAME) @Connections.selection
StatusBar object has a population text, executing:
The signal activated(int) of the Combo Box object is connected to both slots ScriptObject.execute() and also StatusBar.populate().
The example5 has also two buttons sending
"Note On" and "Note Off" MIDI events. You can imagine how to do that.
There are three more examples, not much more technically complex, but closer to real world applications. Example6 has a set of MMC Transport buttons. Example7 has eight faders with variable controller and channel numbers, and Example8 is a controller for GM synthesizers featuring several goodies.
Guess how this gadget can be used. There are some hardware devices that can understand MMC commands and can be controlled using this dialog. You can try also some interesting Linux MIDI programs, among others:
There are several programs with similar functionality:
The second one is interesting because the GUI is designed using a visual tool (Glade) and the resulting definition is stored on a XML file. It depends on libglademm and gtkmm. It sends MIDI Control Change messages only, but the main technical differences are the signal/slot connections not being stored in the XML file (this is an exclusive Qt characteristic), and doesn't use scripts so the widgets must be named using a fixed pattern scheme to trigger different channel and controller number values.
The most interesting parts of this example are the implementations of the buttons "Panic" and "GM Reset". The first one executes a for loop:
@for(CHAN, 0, 15, 1)
The "GM Reset" button sends a System Exclusive message:
@dcop(kaseq,kaseqIface,sendSysex(QString,QString),@global(CLIENT_NAME),"f0 7e 7f 09 01 f7")
You can download the latest released sources from SourceForge.
There are ready to install packages for:
Licensed under the GNU General Public License (GPL).
In order to successfully use this program, you need KDE 3.3 and
ALSA 1.0 drivers and library.
ALSA library, drivers and utilities can be found at ALSA home page.
This page was modified on April 19, 2010