1LINGOT - A musical instrument tuner.
2
3Written by:
4
5 Iban Cereijo <ibancg@gmail.com>
6 Jairo Chapela <jairochapela@gmail.com>
7
8Copyright (C) 2004-2018 Iban Cereijo
9Copyright (C) 2004-2018 Jairo Chapela
10
11
12Description
13===========
14
15Lingot is a musical instrument tuner. It's accurate, easy to use, and highly
16configurable. Originally conceived to tune electric guitars, it can now be used
17to tune other instruments.
18
19It looks like an analog tuner, with a gauge indicating the relative shift to a
20certain note found automatically as the closest note to the estimated frequency.
21
22
23Requirements
24============
25
26* Sound card.
27* Linux kernel with audio support (OSS, ALSA, JACK or PulseAudio).
28* GTK+ library, version 3.10.
29
30
31Installation
32============
33
34If you are building a release, just type:
35
36 > ./configure
37 > make install
38
39If you are building a development version obtained from our VCS you will need to
40create the configure script first by calling:
41
42 > ./bootstrap
43
44
45Lingot supports the following audio systems/servers:
46
47 OSS
48 ALSA
49 JACK
50 PulseAudio
51
52You can enable/disable each of them with the following options passed to the
53configure script, all of them enabled by default:
54
55 --enable-oss=<yes|no>
56 --enable-alsa=<yes|no>
57 --enable-jack=<yes|no>
58 --enable-pulseaudio=<yes|no>
59
60Also, the depedency to libfftw can be enabled/disabled with
61
62 --enable-libfftw=<yes|no>
63
64Please, see the INSTALL file.
65
66
67Synopsis
68========
69
70 lingot [-c config]
71
72The -c option causes the search of a file named {config}.conf in the ~/.lingot
73folder. For example:
74
75 lingot -c bass
76
77will take the configuration file ~/.lingot/bass.conf. This is useful for
78maintaining different configurations for different instruments. It's also
79possible to load and save configuration files from the GUI. The default
80configuration file is ~/.lingot/lingot.conf.
81
82
83Configuration file
84==================
85
86When lingot is launched for the first time, the default configuration file
87~/.lingot/lingot.conf will be created.
88
89The default values are optimized for tuning electric guitars, other musical
90instruments might require these values to be slightly changed (a good practice
91would be to have a configuration file for each instrument). The options can be
92changed via GUI.
93
94There is a wide range of options, with the purpose of keeping the maximum
95configurability. Some background in signal processing is needed for a good
96understanding of all of their effects.
97
98We detail the main options that constitute this file, and we recommend to make
99changes depending on the desired tuning precision and demanded CPU time. If you
100don't understand the effects of some options, then just try different values or,
101even better, don't change them.
102
103
104 AUDIO_SYSTEM
105
106 Audio system switch. Possible values:
107
108 OSS
109 ALSA [default value]
110 JACK
111 PulseAudio
112
113
114 AUDIO_DEV (OSS sound device)
115
116 Selected sound device for the OSS audio system. The default value is
117 '/dev/dsp'.
118
119
120 AUDIO_DEV_ALSA (ALSA sound device)
121
122 Selected sound device for ALSA, the default value is 'default'.
123
124
125 AUDIO_DEV_JACK (JACK port)
126
127 Selected sound port for JACK, the default value is 'default'.
128
129
130 AUDIO_DEV_PULSEAUDIO (PulseAudio sound device)
131
132 Selected sound device for PulseAudio, the default value is 'default'.
133
134
135 ROOT_FREQUENCY_ERROR ("A" reference note shift)
136
137 This option is used when we want to tune with a certain amount of shift
138 in frequency.
139
140 This can be useful when tuning an instrument against a recording with a
141 shifted tuning. For example, if we hear an "A" note in a recording that
142 it's a quarter of a tone over the real frequency (440 Hz), we can put 50
143 cents of shift here.
144
145 It must be a real number, expressed in cents. The default value is 0.
146
147
148 FFT_SIZE (Size of the FTT)
149
150 A high value gets more accuracy, especially more precision locking the
151 desired frequency, but it demands more CPU time.
152
153 We must consider the time interval involved on the calculus before
154 unnecessarily raising this value: having a buffer of 4096 samples for the
155 FFT, and a sampling rate of 8 KHz, each transform needs the last 512 ms
156 temporary values, so there is no point in putting a shorter temporal window.
157
158 It must be an integer power of 2. The default value is 512 samples.
159
160
161 TEMPORAL_WINDOW
162
163 The length in time of the signal used to compute the final frequency. With
164 higher values, we'll obtain a more accurate result, but also a slower
165 response polluted by earlier notes.
166
167 As a practical rule, we say that if we have a temporal window of 1 second,
168 we must wait 1 second between two consecutive notes to obtain a correct
169 tuning. Therefore, this parameter affects directly to the responsiveness
170 of the tuner.
171
172 The temporal window size in samples (obtained as the multiplication of its
173 duration in seconds and the effective sampling rate) must be greater than
174 the FFT buffer size.
175
176 It must be a real number in seconds. The default value is 0.32 seconds.
177
178
179 MIN_SNR
180
181 To avoid tuning noise, this is the lower signal-to-noise ratio we require
182 to start the tuning process.
183
184 It's a real number whose units are dB. The default value is 20 dB.
185
186
187 CALCULATION_RATE
188
189 With higher calculations per second, the tuner gives us a better dynamic
190 sensation, but it'll need more CPU time.
191
192 It's a real number, in hertz, and the default value is 20 Hz.
193
194
195 VISUALIZATION_RATE
196
197 It has impact in the dynamism sensation achieved, but less in the
198 computation time.
199
200 There is no point having a calculation rate greater than the visualization
201 rate.
202
203 It's a real number, in hertz. The default value is 30 Hz.
204
205
206 MINIMUM_FREQUENCY and MAXIMUM_FREQUENCY
207
208 The minimum and maximum notes the instrument can tipically generate. These
209 are not hard boundaries, but a guideline to help Lingot set its internal
210 parameters.
211
212 They are eal numbers, in hertz. The default values are 82.41 Hz (E2) and
213 329.63 Hz (E4)
214
215
216 SCALE
217
218 Definition of the scale used for the tuning. By default a 12 semitones
219 equal-tempered scale is used. It contains several parameters:
220
221 NAME: Scale name, only for your information.
222 BASE_FREQUENCY: The absolute frequency - in hertz - of the first note.
223 NOTE_COUNT: number of notes in the scale.
224 NOTES: list of notes, being them pairs of name and frequency shift. The
225 frequency shift can be expressed as a real number in cents or a
226 division of integer values, encoding a frequency ratio, like '3/2'
227 or '5/4'. Be careful with leaving wide gaps in frequency between each
228 pair of adjacent notes, as the gauge range will adapt to the maximum
229 of those distances. Try to use scales with at least 12 tones.
230