# The &kmetronome; Handbook

Pedro Lopez-Cabanillas

    plcl@users.sourceforge.net

2005-2012 Pedro Lopez-Cabanillas
&FDLNotice;
2012-05-28
0.10.1

&kmetronome; is a MIDI based metronome using the ALSA sequencer.

KDE KMetronome Metronome ALSA MIDI

## Introduction

&kmetronome; is a MIDI based metronome using the ALSA sequencer.

The intended audience are musicians and music students. Like the solid, real metronomes it is a tool to keep the rhythm while playing musical instruments.

It uses MIDI for sound generation instead of digital audio, allowing low CPU usage and very accurate timing thanks to the ALSA sequencer.

Report problems, bugs and feature requests to the mailing lists or the tracking system at SourceForge project site

## Using &kmetronome;

Here's a screenshot of &kmetronome;

Screenshot

### Features

You only need to adjust some controls, like the tempo slider, the beats/bar spin box and the beat length selector. Press the play button to start. Use the stop button at your convenience.

Tempo can be set from 25 to 250 QPM using the slider. The units are quarters per minute (Mälzel Metronome units). You can also double click over the main window to open a dialog box where you can enter a new tempo directly with the keyboard. There is also a combo box to choose and display the tempo using Italian musical names.

Beats/Bar can be set from 1 to 32 beats. These are the number of beats on each measure or bar, and it is the numerator on the time signature as it would be notated.

The beat length is the denominator on the time signature specification, and represents the duration of each beat. Changing this value doesn't change the meaning of the tempo units.

Pattern is a drop-down list to choose a pattern definition. The default "Automatic" value means that the program generates patterns using the notes set in the configuration dialog (Strong/Weak) and the rhythm definition provided by "Beats/Bar" and "Beat length". It also contains the names of user-defined patterns.

### Getting Started

This program uses the MIDI protocol, so it is a good idea to to have some basic notions about MIDI in order to fully understand the concepts behind it. You can find here a good introduction: What is MIDI.

&kmetronome; produces MIDI events. If you want to hear the events translated into sounds you need to connect the MIDI OUT port from this program to the MIDI IN port of a MIDI synthesizer. It can be either a hardware MIDI synthesizer or a software one. If it is an external hardware synthesizer, you also need an ALSA supported MIDI interface installed in your computer, and a MIDI cable attached to both the computer's MIDI interface, and the synthesizer MIDI IN socket.

If you don't have an external MIDI synthesizer, you can still use the program with a MIDI software synthesizer supporting ALSA sequencer connections, like QSynth. Start your software synthesizer before &kmetronome;, and then make the connection between the two programs, either on &kmetronome;'s configuration dialog or using an external connection manager like QJackCtl.

Don't forget to install a good Sound Font into QSynth's "Setup..." dialog.

### Configuration

Here's a screenshot of &kmetronome; configuration dialog

Screenshot

&kmetronome; has limited session management capabilities. It can remember one connection for the ALSA output port, and one connection for its input port. Connections are stored when the program exits and remembered at startup. You don't need this feature if you prefer to make such connections by hand, using aconnect or any other equivalent utility, or if you use an external session manager like the patchbay included in the program QJackCtl.

&kmetronome; uses an instrument definition file in .INS format, the same format as Qtractor, TSE3, Cakewalk and Sonar. The Output instrument drop-down list allows to choose one among the standard General MIDI, Roland GS and Yamaha XG drum maps. You can add more definitions creating a file named drums.ins at $HOME/.kde4/share/apps/kmetronome. The contents of Bank, Program, Weak and Strong note drop-down lists also depend on this definition.

Channel is usually 10, meaning the percussion channel of a MIDI synthesizer. It must be a number beween 1 and 16.

Resolution is the number of ticks (time units) for each quarter note. Value range from 48 to 960.

Note duration is the length (in number of ticks) of the time span between a NOTE ON and its corresponding NOTE OFF event. This control is enabled only when Send NOTE OFF events is also enabled. Very low values can cause muted clicks on some synthesizers.

Percussion sounds usually don't need NOTE OFF events to be sent after every NOTE ON. Select the Send NOTE OFF events checkbox only if your synthesizer or instrument supports or requires this setting.

Bank and Program is used to change the drum set for instruments supporting several settings. Many synthesizers don't understand program changes for the percussion channel.

In Automatic pattern mode, Strong note is played as the first beat in every measure, while any other beat in the same measure is played using the Weak note. The numeric values 33 and 34 are the GM2 and XG sounds for metronome click and metronome bell.

### Pattern Editor

Pattern Editor

Screenshot

Using this dialog box you may edit, test and select patterns. To create new patterns, you simply save the current definition under a new name. Patterns are represented by a table. The rows in the table correspond to the percussion sounds. You can remove and add rows from a list of sounds defined by the instrument settings in the configuration dialog. The number of columns in the table determine the length of the pattern, between 1 and 99 elements of any beat length.

Each table cell accepts values between N=1 and 9, corresponding to the MIDI velocity (N*127/9) of the notes, or 0 to cancel the sound. Valid values are also f (=forte) and p (=piano) corresponding to variable velocities defined by the rotary knobs (Strong/Weak) in the main window. The cell values can be selected and modified using either the keyboard or the mouse. There is no need to stop the playback before modifying the cells.

## Command Reference

### The main &kmetronome; window

#### The File Menu

File Import Patterns

  Imports pattern definitions into &kmetronome;

File Export Patterns

  Exports pattern definitions from &kmetronome;

File Play/Stop

  Controls pattern playback

&Ctrl;Q File Quit

  Quits &kmetronome;

#### The Edit Menu

Edit Patterns

  Opens the pattern editor

#### The Settings Menu

Settings Configure &kmetronome;...

  Configures &kmetronome;

#### The Help Menu

&help.menu.documentation;

## External Control

&kmetronome; can be controlled using its D-Bus interface, System Realtime and System Exclusive MIDI messages.

### D-Bus Interface

&kmetronome; provides some functions through its D-Bus interface. You can use a D-Bus enabled program to control &kmetronome; like kdbus or the commandline utility qdbus.

For instance, these commands can be used from a shell prompt:

    $ qdbus net.sourceforge.kmetronome-23324 / net.sourceforge.kmetronome.play
    $ qdbus net.sourceforge.kmetronome-23324 / net.sourceforge.kmetronome.stop
    $ qdbus net.sourceforge.kmetronome-23324 / net.sourceforge.kmetronome.cont
    $ qdbus net.sourceforge.kmetronome-23324 / net.sourceforge.kmetronome.setTempo 150
    $ qdbus net.sourceforge.kmetronome-23324 / net.sourceforge.kmetronome.setTimeSignature 3 8

### Universal System Exclusive messages

&kmetronome; understands some Universal System Exclusive messages. Because the device ID is not yet implemented, all the recogniced messages must be marked as broadcast (0x7F).

MTC Message: Time Signature Change Message

    Format: 0xF0 0x7F 0x7F 0x03 Command Length Numerator Denominator ... 0xF7
                                0x02: TS change
                                0x42: TS change

Notes: both commands affect only the next scheduled patterns after receiving the command. Length is at least 2. Extra bytes following Numerator and Denominator are ignored.

MMC Messages

    Format: 0xF0 0x7F 0x7F 0x06 Command 0xF7
                                0x01: Stop
                                0x02: Play
                                0x03: Deferred Play

### MIDI System Realtime Interface

You can use a MIDI device generating MIDI System Realtime messages to control &kmetronome;. System Realtime messages accepted are: Start (0xFA), Stop (0xFC) and Continue (0xFB).

Many master MIDI keyboards and MIDI buttons devices provide those three MIDI transport controls. You need to connect your external MIDI devices to the computer using MIDI (or USB) cables, and connect the corresponding ALSA port to the input port of &kmetronome;. This connection must be done by hand, or using a session management software like QJackCtl.

## Credits and License

&kmetronome;

Program copyright 2005-2012 Pedro Lopez-Cabanillas plcl@users.sourceforge.net

Documentation copyright 2005-2012 Pedro Lopez-Cabanillas plcl@users.sourceforge.net

&underFDL; &underGPL;

## Installation

### How to obtain &kmetronome;

Here you can find the last version: Project home page

### Requirements

In order to successfully compile and use &kmetronome;, you need &kde; 4.2 or later, Drumstick, ALSA drivers and ALSA library.

You also need a MIDI synthesizer to produce sound.

The build system requires CMake 2.6 or newer.

ALSA library, drivers and utilities can be found at ALSA home page.

Drumstick is a C++ wrapper around the ALSA sequencer interface using Qt4 objects, idioms and style. You can find it at the Drumstick home page.

You can find a list of changes at http://kmetronome.sourceforge.net

### Compilation and Installation

In order to compile and install &kmetronome; on your system, type the following in the base directory of the &kmetronome; distribution:

    % cmake .
    % make
    % sudo make install

Since &kmetronome; uses `cmake` and `make` you should have no trouble compiling it. Should you run into problems please report them to the author or the project's bug tracking system.
&documentation.index;