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.