# klick - User Manual

## Table of Contents

- Basics
- Command Line Options
- Interactive Mode
- Tempo Map File Format
  - Example Tempo Map
- Click Track Export
- OSC Commands

## Basics

#### `klick [options] [bars] [meter] tempo[-tempo2/accel] [pattern]`

Plays a simple metronome with the given meter and tempo. To play a 3/4 beat at 120 bpm:

    klick 3/4 120

You can also specify a "target" tempo and acceleration rate, to use klick as a speed trainer. To play a 4/4 beat starting at 80 bpm, gradually increasing the tempo by 1 bpm every 10 measures until reaching 120 bpm:

    klick 80-120/10

Once the final tempo is reached, klick will continue playing at a constant tempo.

#### `klick [options] -f filename`

Loads a tempo map from a file. This allows for more complex setups including meter and tempo changes etc.
See Tempo Map File Format.

#### `klick [options] -i`

Runs klick in interactive mode, allowing you to change tempo and meter while klick is running.
The keyboard commands available in this mode are described in Interactive Mode.

#### `klick [options] -j`

In this mode, klick gets all tempo information from JACK. Just run a sequencer as JACK transport master, and klick will play a simple metronome pattern in sync with JACK transport.

## Command Line Options

    -f filename       load tempo map from file
    -j                no tempo map, just follow jack transport
    -n name           set jack client name
    -p port,..        jack port(s) to connect to
    -P                automatically connect to hardware ports
    -o port           OSC port to listen on
    -i                interactive mode
    -W filename       export click track to audio file
    -r samplerate     sample rate of export (default: 48000)
    -s number         use built-in sounds:
                        0: square wave (default)
                        1: sine wave
                        2: noise
                        3: acoustic bell/click
    -S file[,file]    load sounds from file(s)
    -e                no emphasized beats
    -E                emphasized beats only
    -v mult[,mult]    adjust playback volume (default: 1.0)
    -w mult[,mult]    adjust playback pitch (default: 1.0)
    -t                enable jack transport
    -T                become transport master (implies -t)
    -d seconds        delay before starting playback
    -c bars           pre-roll. use -c 0 for 2 beats
    -l label          start playback at the given label
    -x multiplier     multiply tempo by the given factor
    -h                show this help

## Interactive Mode

The following keyboard commands are available in interactive mode:

Arrow up/down | increase/reduce tempo by 10 bpm
Arrow right/left | increase/reduce tempo by 1 bpm
0-9 | set beats per bar (0/1: all beats are even)
q/w/e/r | set beat type (whole, half, quarter, eighth note)
+/=, - | increase/reduce volume
Space | start/stop metronome
Escape | exit klick

## Tempo Map File Format

A tempo map is a plain text file, consisting of an arbitrary number of lines which will be played sequentially. Each line must have the following format:

    [label:] bars [meter] tempo [pattern] [volume]

Everything in brackets is optional, and can be omitted to use the default. '`#`' indicates the start of a comment, empty lines are ignored.

`label` | An optional name that can be used to refer to this line, and start playback at this position.
`bars` | The number of bars for this tempo map entry.
`meter` | The meter, written as `beats/denominator`. This is optional, the default is 4/4.

`tempo`

The tempo in beats per minute, with a "beat" always referring to quarter notes, no matter what the meter actually is.

`tempo` | Sets the tempo for the duration of the whole tempo map entry.
`tempo1-tempo2` | Specifies the tempo for the start and the end of this entry, with a gradual tempo change in between.
`tempo1,tempo2,...` | Sets a different tempo for each beat. The number of tempo values must be the same as the total number of beats for this entry (bars * beats).

`pattern` | This can be used to alter the pattern of accented/normal beats. Use '`X`' (upper case) for accented beats, '`x`' (lower case) for normal beats, and '`.`' for silence. So for example, given a 6/8 measure, and you only want the 1st and 4th beat to be played, you could use the pattern '`X..x..`'; the default is '`Xxxxxx`'.
`volume` | Allows you to set a different volume for each part, default is 1.0.

### Example Tempo Map

    intro:    8 120           # play 8 measures at 120 bpm (4/4)
    verse1:   12 120 X.x.     # 12 measures at 120 bpm, playing only the 1st and 3rd beat
              4 120-140 X.x.  # gradually increase tempo to 140 bpm
    chorus1:  16 140
    bridge:   8 3/4 140 0.5   # change to 3/4 time, reduce volume
              8 3/4 140       # normal volume again
    verse2:   12 120          # back to 4/4 (implied)
    chorus2:  16 140          # jump to 140 bpm
    outro:    6 140
              2 140-80        # ritardando over the last 2 bars

## Click Track Export

By default, klick connects to JACK for audio output. To export a click track to an audio file instead, use the `-W` parameter to specify an output filename. The file type is determined by extension, supported formats are WAV, AIFF, FLAC, Ogg Vorbis (with libsndfile >= 1.0.18).
The `-r` parameter can be used to set the sample rate of the exported audio, default is 48000 Hz.

## OSC Commands

klick understands the following OSC messages:

General
/klick/ping /klick/ping ,s <return_address> | responds: /klick/pong
/klick/register_client /klick/register_client ,s <address> | registers a client to receive notifications when any parameter changes
/klick/unregister_client /klick/unregister_client ,s <address> | unregisters a client
/klick/query /klick/query ,s <return_address> | reports current state (same as /klick/*/query)
/klick/quit | terminates klick
Configuration
/klick/config/set_sound ,i <number> | sets the sound to one of the built-in ones
/klick/config/set_sound ,ss <filename> <filename> | loads the sound from two audio files
/klick/config/set_sound_volume ,ff <emphasis> <normal> | changes the volume individually for both samples
/klick/config/set_sound_pitch ,ff <emphasis> <normal> | changes the pitch individually for both samples
/klick/config/set_volume ,f <volume> | sets the overall output volume
/klick/config/autoconnect | connects klick's output port to the first two hardware ports
/klick/config/connect ,s... <port> ... | connects klick's output port to the specified JACK ports
/klick/config/disconnect_all | disconnects all connections from klick's output port
/klick/config/get_available_ports /klick/config/get_available_ports ,s <return_address> | returns a list of all JACK input ports: /klick/config/available_ports ,s... <port> ...
/klick/config/query /klick/config/query ,s <return_address> | reports current state: /klick/config/sound ,i /klick/config/sound ,ss /klick/config/sound_volume ,ff /klick/config/sound_pitch ,ff /klick/config/volume ,f
Generic Metronome Functions
/klick/metro/set_type ,s <type> | sets the metronome type, one of 'simple', 'map', 'jack'
/klick/metro/start | starts the metronome
/klick/metro/stop | stops the metronome
/klick/metro/query /klick/metro/query ,s <return_address> | reports current state: /klick/metro/type ,s /klick/metro/active ,i
Simple (Dynamic) Metronome
/klick/simple/set_tempo ,f <tempo> | sets the metronome's tempo
/klick/simple/set_tempo_increment ,f <increment> | sets the tempo increment per bar
/klick/simple/set_tempo_start ,f <start> | sets the start tempo
/klick/simple/set_tempo_limit ,f <limit> | sets the maximum tempo
/klick/simple/set_meter ,ii <beats> <denom> | sets the metronome's meter
/klick/simple/set_pattern ,s <pattern> | sets the beat pattern
/klick/simple/tap | tap tempo
/klick/simple/query /klick/simple/query ,s <return_address> | reports current state: /klick/simple/tempo ,f /klick/simple/tempo_increment ,f /klick/simple/tempo_limit ,f /klick/simple/current_tempo ,f /klick/simple/meter ,ii /klick/simple/pattern ,s
Tempo Map Metronome
/klick/map/load_file ,s <filename> | loads a tempo map from a file
/klick/map/set_preroll ,i <bars> | sets the preroll before the start of the tempo map
/klick/map/set_tempo_multiplier ,f <mult> | sets the tempo multiplier
/klick/map/query /klick/map/query ,s <return_address> | reports current state: /klick/map/filename ,s /klick/map/preroll ,i /klick/map/tempo_multiplier ,f
JACK Transport Metronome
/klick/jack/query /klick/jack/query ,s <return_address> | currently does nothing