# pod source for klick man page
# pod2man -s1 -r0.12.2 --stderr -nKLICK -cSlackBuilds.org < klick.pod > klick.1

=head1 NAME

klick - an advanced metronome for JACK

=head1 SYNOPSIS

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

klick [options] -f filename

klick [options] -i

klick [options] -j

=head1 DESCRIPTION

    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 B<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.

=head1 OPTIONS

=over

=item -f filename     

load tempo map from file

=item -j              

no tempo map, just follow jack transport

=item -n name         

set jack client name

=item -p port,..      

jack port(s) to connect to

=item -P              

automatically connect to hardware ports

=item -o port         

OSC port to listen on. Only available when compiled with liblo support.

=item -i              

interactive mode

=item -W filename     

export click track to audio file

=item -r samplerate   

sample rate of export (default: 48000)

=item -s number       

use built-in sounds:

=over

=item  0

square wave (default)

=item  1

sine wave

=item  2

noise

=item  3

acoustic bell/click

=back

=item -S file[,file]  

load sounds from file(s)

=item -e              

no emphasized beats

=item -E              

emphasized beats only

=item -v mult[,mult]  

adjust playback volume (default: 1.0)

=item -w mult[,mult]  

adjust playback pitch (default: 1.0)

=item -t              

enable jack transport

=item -T              

become transport master (implies -t)

=item -d seconds      

delay before starting playback

=item -c bars         

pre-roll. use -c 0 for 2 beats

=item -l label        

start playback at the given label

=item -x multiplier   

multiply tempo by the given factor

=item -h              

show this help

=back

=head1 INTERACTIVE MODE

The following keyboard commands are available in interactive mode:

=over

=item Arrow up/down

increase/reduce tempo by 10 bpm                                 

=item Arrow right/left

increase/reduce tempo by 1 bpm                                  

=item 0-9

set beats per bar (0/1: all beats are even)                     

=item q/w/e/r

set beat type (whole, half, quarter, eighth note)               

=item +/=, -

increase/reduce volume                                          

=item Space

start/stop metronome                                            

=item Escape

exit klick                                                      

=back

=head1 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.

=over

=item label

An optional name that can be used to refer to this line, and start       
playback at this position.                                               

=item bars

The number of bars for this tempo map entry.                             

=item meter

The meter, written as beats/denominator. This is optional, the default
is 4/4. The tempo in beats per minute, with a "beat" always referring
to quarter notes, no matter what the meter actually is.

=item tempo

=over

=item tempo

Sets the tempo for the duration of the whole tempo map entry.                                                 

=item tempo1-tempo2  

Specifies the tempo for the start and the end of this  
entry, with a gradual tempo change in between.         

=item 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).

=back

=item 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'.                                                 

=item volume

Allows you to set a different volume for each part, default is 1.0.      

=back

=head2 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

=head1 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.

=head1 OSC MESSAGES

klick must be compiled with lilbo support to use OSC.

klick understands the following OSC messages:

=head2 General

=over

=item /klick/ping

=item /klick/ping ,s <return_address>

responds: /klick/pong

=item /klick/register_client

=item /klick/register_client ,s <address>

registers a client to receive notifications when any parameter changes

=item /klick/unregister_client

=item /klick/unregister_client ,s <address>

unregisters a client

=item /klick/query

=item /klick/query ,s <return_address>

reports current state (same as /klick/*/query)

=item /klick/quit

terminates klick

=back

=head2 Configuration

=over

=item /klick/config/set_sound ,i <number>

sets the sound to one of the built-in ones

=item /klick/config/set_sound ,ss <filename> <filename>

loads the sound from two audio files

=item /klick/config/set_sound_volume ,ff <emphasis> <normal>

changes the volume individually for both samples

=item /klick/config/set_sound_pitch ,ff <emphasis> <normal>

changes the pitch individually for both samples

=item /klick/config/set_volume ,f <volume>

sets the overall output volume

=item /klick/config/autoconnect

connects klick's output port to the first two hardware ports

=item /klick/config/connect ,s... <port> ...

connects klick's output port to the specified JACK ports

=item /klick/config/disconnect_all

disconnects all connections from klick's output port

=item /klick/config/get_available_ports

=item /klick/config/get_available_ports ,s <return_address>

returns a list of all JACK input ports:

	/klick/config/available_ports ,s... <port> ...

=item /klick/config/query

=item /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

=back

=head2 Generic Metronome Functions

=over

=item /klick/metro/set_type ,s <type>

sets the metronome type, one of 'simple', 'map', 'jack'

=item /klick/metro/start

starts the metronome

=item /klick/metro/stop

stops the metronome

=item /klick/metro/query

=item /klick/metro/query ,s <return_address>

reports current state:

	/klick/metro/type ,s
	/klick/metro/active ,i

=back

=head2 Simple (Dynamic) Metronome

=over

=item /klick/simple/set_tempo ,f <tempo>

sets the metronome's tempo

=item /klick/simple/set_tempo_increment ,f <increment>

sets the tempo increment per bar

=item /klick/simple/set_tempo_start ,f <start>

sets the start tempo

=item /klick/simple/set_tempo_limit ,f <limit>

sets the maximum tempo

=item /klick/simple/set_meter ,ii <beats> <denom>

sets the metronome's meter

=item /klick/simple/set_pattern ,s <pattern>

sets the beat pattern

=item /klick/simple/tap

tap tempo

=item /klick/simple/query

=item /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

=back

=head2 Tempo Map Metronome

=over

=item /klick/map/load_file ,s <filename>

loads a tempo map from a file

=item /klick/map/set_preroll ,i <bars>

sets the preroll before the start of the tempo map

=item /klick/map/set_tempo_multiplier ,f <mult>

sets the tempo multiplier

=item /klick/map/query

=item /klick/map/query ,s <return_address>

reports current state:

	/klick/map/filename ,s
	/klick/map/preroll ,i
	/klick/map/tempo_multiplier ,f

=back

=head2 JACK Transport Metronome

=over

=item /klick/jack/query

=item /klick/jack/query ,s <return_address>

currently does nothing

=back

=head1 AUTHOR

klick is opyright (C) 2007-2009  Dominic Sacre  <dominic.sacre@gmx.de>
