# The &kmetronome; Handbook

## 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 rhythm figure 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 by minute (Mälzel Metronome units). You can also double click with the mouse over the main window to open a dialog box where you can enter a new tempo directly with the keyboard.

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 rhythm figure is the denominator on the time signature specification, and represents how long is each beat. Changing this figure doesn't change the meaning of the tempo units.

### 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 (borg.com/~jglatt).

&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 “Config” dialog or using an external connection manager like QJackCtl. Here you can see an image of the three programs working together.

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

Here's a screenshot of &kmetronome; running along with QSynth and QJackCtl Screenshot

### 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 with the program QJackCtl.

Channel is usually 9, meaning the percussion channel of a MIDI synthesizer. It can be a number beween 0 and 15.

Program can be any value between 0 and 127. Most synthesizers don't understand program changes for the percussion channel, or require unsupported bank changes too.

Resolution is the number of ticks (time units) for each quarter note. Values are from 48 to 480.

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. Values are from 0 to 127, and the defaults 33 and 34 are the General MIDI sounds for metronome click and metronome bell.

Note velocity changes the volume to the played notes. Values from 0 to 127.

Send NOTE OFF events checkbox. Percussion sounds usually don't need Note Off events to be sent after every Note On. Un-check it only if your synthesizer or instrument supports this setting.

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 NOT OFF events is also enabled. Very low values can cause muted clicks on some synthesizers.

## Command Reference

### The main &kmetronome; window

#### The File Menu

&Ctrl;Q File Quit

- Quits &kmetronome;

#### The Settings Menu

Settings Configure KMetronome...

- Configures &kmetronome;

#### The Help Menu

&help.menu.documentation;

## External Control

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

### DCOP Interface

&kmetronome; provides some functions through its DCOP interface. You can use a DCOP-enabled program to control &kmetronome; like kdcop or the commandline utility dcop.

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

    $ dcop kmetronome transport play
    $ dcop kmetronome transport stop
    $ dcop kmetronome transport cont
    $ dcop kmetronome transport setTempo 150
    $ dcop kmetronome transport 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-2008 Pedro Lopez-Cabanillas plcl@users.sourceforge.net

Documentation copyright 2005-2008 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 use &kmetronome;, you need &kde; 3.X. and ALSA drivers and library.

The build system requires CMake 2.4.4 or newer.

ALSA library, drivers and utilities can be found at ALSA 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
    % 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;