Abstract

This is the reference documentation for drumstick. These libraries are a set of C++ MIDI related classes, using Qt objects, idioms and style.

Currently, there are four libraries designed to work together if/when needed:

Drumstick::ALSA is a Linux only C++/Qt wrapper around the ALSA Sequencer API. ALSA sequencer provides software support for MIDI technology on Linux.
Drumstick::File provides easy multiplatform file I/O for Standard MIDI Files (.mid), RIFF MIDI (.rmi) and Cakewalk (.wrk) file formats.
Drumstick::RT is a realtime MIDI I/O library with pluggable backends. It uses Drumstick::ALSA on Linux, and other native frameworks on macOS and Windows.
Drumstick::Widgets contains MIDI widgets, including a Virtual Piano used by VMPK among other programs

See also: https://doc.qt.io/qt-5/index.html; https://www.alsa-project.org/alsa-doc/alsa-lib/seq.html; https://www.ics.com/intro-design-patterns-c-qt-2nd-edition; https://www.midi.org/articles/tutorials

Disclaimer

This document is a work in progress and it will be always in development. Please visit the drumstick web site to read the latest version.

See also: https://drumstick.sourceforge.io

Introduction

For an introduction to design and programming with C++ and Qt, see the book "An Introduction to Design Patterns in C++ with Qt" by by Alan Ezust and Paul Ezust. It is available published on dead trees, and also online.

Drumstick::ALSA was the first library developed under the Drumstick umbrella, and is available only on Linux, because ALSA Sequencer is an exclusive Linux technology. Here is how a simple program playing notes using Drumstick::ALSA looks like:

#include <QCoreApplication>
#include <drumstick/alsaclient.h>
#include <drumstick/alsaevent.h>
 
int main(int argc, char **argv)
{
    QCoreApplication app(argc, argv);
    // create a client object on the heap
    drumstick::ALSA::MidiClient *client = new drumstick::ALSA::MidiClient;
    client->open();
    client->setClientName( "MyClient" );
    // create the port. The pointer is owned by the client instance
    drumstick::ALSA::MidiPort *port = client->createPort();
    port->setPortName( "MyPort" );
    port->setCapability( SND_SEQ_PORT_CAP_READ | SND_SEQ_PORT_CAP_SUBS_READ );
    port->setPortType( SND_SEQ_PORT_TYPE_MIDI_GENERIC );
    // subscribe the port to some other client:port
    port->subscribeTo( "128:0" ); // or "name:port", like in "FluidSynth:0"
    QList<int> notelist{ 60, 62, 64, 65, 67, 69, 71, 72 };
    for(auto note : notelist)
    {
        // create event objects on the stack, to send note on/off messages
        drumstick::ALSA::NoteOnEvent ev1( 0, note, 100 ); // (channel, note number, velocity)
        ev1.setSource( port->getPortId() );
        ev1.setSubscribers();   // deliver to all the connected ports
        ev1.setDirect();        // not scheduled, deliver immediately
        client->output( &ev1 ); // or outputDirect() if you prefer not buffered
        client->drainOutput();  // flush the buffer
 
        QThread::msleep(250);   // wait a quarter second
 
        drumstick::ALSA::NoteOffEvent ev2( 0, note, 0 ); // (channel, note number, velocity)
        ev2.setSource( port->getPortId() );
        ev2.setSubscribers();   // deliver to all the connected ports
        ev2.setDirect();        // not scheduled, deliver immediately
        client->output( &ev2 ); // or outputDirect() if you prefer not buffered
        client->drainOutput();  // flush the buffer
    }
    // close and clean
    client->close();
    // it also deletes the port and other owned objects
    delete client;
    return 0;
}

MIDI is a real time protocol, so it is not a surprise that many applications using MIDI require only real time functionality. In this case, you may use the Drumstick::RT library, which is multiplatform. An example equivalent to the former one, but implemented using the Drumstick::RT library looks like this:

#include <QCoreApplication>
#include <QThread>
#include <QDebug>
#include <drumstick/backendmanager.h>
#include <drumstick/rtmidioutput.h>
 
int main(int argc, char **argv) {
    QCoreApplication app(argc, argv);
    drumstick::rt::BackendManager man;
    drumstick::rt::MIDIOutput* output = man.outputBackendByName("SonivoxEAS");
    if (output != 0) {
        qDebug() << "testing backend: " << output->backendName();
        qDebug() << "public name " << output->publicName();
        auto conn = output->connections().first();
        qDebug() << "port " << conn.first;
        output->open(conn);
        QList<int> note_list{ 60, 62, 64, 65, 67, 69, 71, 72 };
        for(auto midi_note : note_list)
        {
            output->sendNoteOn(0, midi_note, 100);
            QThread::msleep(250); // wait a quarter second
            output->sendNoteOff(0, midi_note, 0);
        }
        output->close();
    }
    return 0;
}

A common pattern on both implementations is QThread::msleep(250) to do the rhythm. If you are targeting only Linux, you may be interested on another (better) way to do the same, using Drumstick::ALSA again, because ALSA Sequencer is capable of event scheduling (that is why it is called a Sequencer).

#include <QCoreApplication>
#include <drumstick/alsaclient.h>
#include <drumstick/alsaport.h>
#include <drumstick/alsaqueue.h>
#include <drumstick/alsaevent.h>
 
int main(int argc, char **argv)
{
    QCoreApplication app(argc, argv);
    drumstick::ALSA::MidiClient *client = new drumstick::ALSA::MidiClient;
    client->open();
    client->setClientName( "MyClient" );
 
    drumstick::ALSA::MidiPort *port = client->createPort();
    port->setPortName( "MyPort" );
    port->setCapability( SND_SEQ_PORT_CAP_READ | SND_SEQ_PORT_CAP_SUBS_READ );
    port->setPortType( SND_SEQ_PORT_TYPE_MIDI_GENERIC );
    port->subscribeTo( "FLUID Synth (qsynth):0" );
 
    drumstick::ALSA::MidiQueue *queue = client->createQueue( "MyQueue" );
    drumstick::ALSA::QueueTempo tempo = queue->getTempo();
    tempo.setPPQ( 120 );
    tempo.setNominalBPM( 120 );
    queue->setTempo(tempo);
    client->drainOutput();
    queue->start();
 
    int tick = 0;
    QList<int> notelist{ 60, 62, 64, 65, 67, 69, 71, 72 };
    for(auto midinote : notelist)
    {
        drumstick::ALSA::NoteOnEvent ev1( 0, midinote, 100 );
        ev1.setSource( port->getPortId() );
        ev1.setSubscribers();
        ev1.scheduleTick(queue->getId(), tick, false);
        client->output( &ev1 );
 
        tick += 60;
        drumstick::ALSA::NoteOffEvent ev2( 0, midinote, 0 );
        ev2.setSource( port->getPortId() );
        ev2.setSubscribers();
        ev2.scheduleTick(queue->getId(), tick, false);
        client->output( &ev2 );
    }
    client->drainOutput();
    client->synchronizeOutput();
    queue->stop();
    // close and clean
    client->close();
    delete client;
    return 0;
}

To build a program using Drumstick, you may use CMake or Qmake. Using CMake you need first to build or install Drumstick on your development machine, and create a project file like the following, with the name: "CMakeLists.txt"

cmake_minimum_required(VERSION 3.16)
project(example LANGUAGES CXX)
 
set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
find_package(Qt5 COMPONENTS Core REQUIRED)
find_package(Drumstick COMPONENTS ALSA REQUIRED)
 
add_executable(example main.cpp)
 
target_link_libraries( example
    Qt5::Core
    Drumstick::ALSA
)

Assuming that you have Qt 5.12.9 installed at your $HOME/Qt directory, and Drumstick is installed at $HOME/Drumstick, then you can configure and build your project with these commands: (your current directory is your project's)

mkdir build
cmake -S . -B build -DCMAKE_PREFIX_PATH="$HOME/Qt/5.12.9/gcc_64;$HOME/Drumstick"
cmake --build build

If you prefer to download the Drumstick sources and build it, you can also build your project without needing to install Drumstick. In this case:

mkdir build
cmake -S . -B build -DCMAKE_PREFIX_PATH=$HOME/Qt/5.12.9/gcc_64 -DDrumstick_DIR=$HOME/Source/Drumstick/build
cmake --build .

To run your Drumstick::RT programs without installing Drumstick and your program, you may need to use an environment variable to indicate the location of the plugins, like this:

export DRUMSTICKRT=$HOME/Source/Drumstick/build/lib/drumstick2/

./example

There are more examples in the source tree, under the utils/ directory, and you can also see applications using this library, like kmetronome, kmidimon and VMPK.

See also: https://dmidiplayer.sourceforge.io; https://kmetronome.sourceforge.io; https://kmidimon.sourceforge.io; https://vmpk.sourceforge.io; https://wrk2mid.sourceforge.io

Acknowledgments

Parts of this documentation are copied from the ALSA library documentation, whose authors are:

Jaroslav Kysela <perex AT perex.cz>
Abramo Bagnara <abramo AT alsa-project.org>
Takashi Iwai <tiwai AT suse.de>
Frank van de Pol <fvdpol AT coil.demon.nl>