- initial import of the original 0.7.6 release

git-svn-id: https://lampka.siedziba.pl:790/svn/repos/lingot-win32@291 455248ca-bdda-0310-9134-f4ebb693071a

1 files changed, 252 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..af53ce2
--- /dev/null
+++ b/README
@@ -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.