diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 252 |
1 files changed, 252 insertions, 0 deletions
@@ -0,0 +1,252 @@ +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. |