path: root/README

LINGOT - A musical instrument tuner.

Written by:
  Ibán Cereijo Graña <ibancg@gmail.com>
  Jairo Chapela Martínez <jairocm@wanadoo.es>

Copyright (C) 2004-2007 Ibán Cereijo Graña, Jairo Chapela martínez

Description
===========

Lingot is a musical instrument tuner. It's accurate, easy to use, and
highly configurable. Originally conceived to tune electric guitars,
its configurability gives it a more general character.

It looks like an analogic tuner, with a gauge indicating the 
relative shift to a certain note --found automatically as the closest 
note to the estimated frequency--, indicating that note and its frequency.

The note will be found automatically, since the program hasn't any
manual function mode (indicating the note to tune manually), for
mantaining generality.

We recommend using the tuner in conjunction with a sound mixer for 
selecting the desired recording source and the signal recording levels.


Requisites
==========

	* Sound card.
	* Kernel linux with audio support (OSS).
	* GTK+ library, version 2.0.
	
Installation
============

	Please, see the INSTALL file.

Synopsis
========

	lingot [-c config]

The -c option causes the search of a file named {config}.conf in the
~/.lingot folder. For example:

	lingot -c bass

will take the configuration file ~/.lingot/bass.conf . This is useful for
maintaining different configurations for different instruments.

Configuration file
==================

When lingot is launched, the configuration file ~/.lingot/lingot.conf
will be created.

The configuration options can be also changed in GUI, and we recommend
use it to make changes. The default values are optimized for electric
guitar tuning, for other musical instruments the default values must be 
slightly changed (it's a good idea to have one config file for each 
instrument, and use '-c' option to load the configuration that best fits
to you)

With the purpose of maintaining the maximun configurability, the user 
has many options, and signal processing knowledge was need for the total 
understanding of its effects. Following, the effects of the options will
be tried to explain, but if you don't understand it well, the best is no
change it. Future versions would have less options to obtain an easy to
use tuner.

Now we detail the options that we'll found in this file, and we recommend
to make changes according with the tunning precission obtained and the
cpu power needed.

AUDIO_DEV (sound device)

	Selected sound device.

SAMPLE_RATE (sampling rate)

	The input signal will be sampled at this frecuency by the sound card.
	Not all cards support arbitrary sampling rate, and we recommend to
	choose one of the options that the GUI gives us:

	  8000 Hz
	 11025 Hz
	 22050 Hz
	 44100 Hz

	We will be able to find an effective sampling rate submultiple 
	of that we'll put here by means of a oversampling factor.

	In order to select a sampling rate, we must consider the maximun
	frecuency which we want to tune our instrument, and choose an
	effective sampling rate (already divided by the oversampling factor)
	that is the double of the maximun at least (Nyquist frequency). 
	All spectral components that are over the half of effective sampling
	rate will be filtered and they will not appear in the spectrum.

	It must be an integer number, in Hertzs.

OVERSAMPLING (oversampling factor) 

	The sampled signal will be decimated by this factor. This has the
	same effect that if the sound card was using as sampling rate the
	effective sampling rate.

	For example, to obtain a effective sampling rate of 4 KHz (we can
	tune tones until 2 KHz), we can choose a sampling rate of 8 KHz
	and an oversampling factor of 2.

	It must be an integer number, dimensionless.

ROOT_FREQUENCY_ERROR ("A" reference note error)

	This option is used when we want to tune with a certain amount of
	frecuency shift error.

	This is useful when we want to adapt the instrument tuning to
     	a recording which have a shifted tuning. For example, if we
	hear an "A" note in a recording that it's a quarter of a
	tone over the real note (440 Hz), we put here an 50% error.
	(error is the amount percentual error in halftones)

	It must be a real number in as much by one (0.5 is equal to
	a 50% error, expressed in percentage of	halftones)

MIN_FREQUENCY (minimum valid frequency)

	To avoid detecting the continuous component as the fundamental peak when
	it has enough power, we consider a minimum valid frequency.
	 
	It must be a real number, in hertzs.

FFT_SIZE (Size of the FTT)

	A high value gets more accuracy, especially more precision locking
	the desired frecuency, but it needs more compute time.

	It must consider the calculation time interval that implies to raise 
	unnecessarily this value: having a buffer of 4096 samples for FFT,
	with a sampling rate of 8 KHz implies that each transform needs
	last 512 ms temporary values, so it's no sense to put a shorter time
	window. 

	Let's see more extrem example:

	Let us suppose we have an instrument able to generate low frecuencies
	(< 200 Hz), and therebefore we choose a efective sampling rate of 
	400 Hz 	(an audio card sampling rate of 8 Khz and an oversampling factor 
	of 20). With the aim to obtain the better initial precision, we choose
	a FFT buffer length of 4096 samples. This implies that the minimal 
	temporal window length has to be 10.24 seconds, in other words, the 
	sounds from the last 10.24 seconds are polluting the tuning taking.
	So, we've to wait 10.24 seconds between note and note to avoid 
	interferences.
	
	Note that the spetrum viewer only displays 256 samples, and higher 
	values of this parameter can make that the fundamental frecuency
	matched is out the viewer window (a viewer that shifts in frecuency
	isn't implemented at the moment)

	It must be an integer power of 2.


TEMPORAL_WINDOW

	The length in time of the signal that is used to compute the final
	frecuency. With greater values, we'll obtain a more accurate result, 
	but also a slower response polluted by early notes.

	As a practical rule, we say that if we've a temporal window of one
	second, we must wait one second to between two consecutive notes
	to obtain a correct tuning. So, this parameter affects directly
	to the dinamic response of the tuner.

	The temporal window size in samples (obtained as the multiplication of
	its duration in seconds and the effective sampling rate) must be 
	greater than FFT buffer size.

	It must be a real number in seconds.


NOISE_THRESHOLD

	To avoid to tune noise, this threshold distingish what is signal and
	what is noise. Obtain a correct value empirically with the help of a
	sound mixer to deal with the signal level.

	It's a real number which units are dB

CALCULATION_RATE

	With higher calculations per second, the tuner give us a better 
	dynamic sensation, but it'll needs more computer time.
	

VISUALIZATION_RATE

	It's impact in the dynamism sensation achieved, but less in the
	compute time.

	It does have no sense that the calculation rate are greater than
	the visualization rate.


PEAK_NUMBER (Number of peaks)

	For the identification of the fundamental peak, we must consider
	the number of armonics peaks (in frecuencies that are multiple of the
	fundamental). They are function of the timbre generated by the 
	instrument, and they can be greater than the fundamental peak (until
	the relation signaled in the next option)


PEAK_REJECTION_RELATION

	Any peak which magnitude has a relationship with the magnitude of the 
	max. peak bigger than this parameter will be discarded (this parameter 
	is to deal with the instrument timbre)

	Its a real number with dB units.

PEAK_ORDER

	Number of samples needed to accept a peak. The correct tuning of this
	parameter will depend on the instrument, and in a more important way,
	on the spectral resolution obtained with effective sampling rate and
	the FFT size. Point out that N samples of the FFT means that a
	variable frecuency interval that depends in those parameteres.
	

DFT_NUMBER (Number of DFTs)

	After the max. peak in the FFT is found, a certain amount of 
  localized DFTs in the frecuency domain was done to get close to the
	note frecuency before to launch a final aproximation that uses
	a iterative method (Newton-Raphson).

	
DFT_SIZE

	DTF size in samples. Bigger values gets more locking precision, but
	more computer time is needed.


How it works
============

	Check technical docs.