ZebraTuner - Ciobi's Guitar Tuner


Hosted by Get ZebraTuner (guitar tuner) at SourceForge.net. Fast, secure and Free Open Source software downloads

Contents


What is ZebraTuner?

Well, experts agree that zebras need some tuning every once in a while, so this is the tool to do it ;-)

OK, it's a program that determines the frequency of a signal coming from a microphone and compares it to other predefined or user-defined frequencies. This can be used to tune musical instruments, and was initially created for guitar tuning. I thought of several names for it, but those names are already used by other people, so I asked myself: If this program were an animal, which animal would it be? The answer to this is question is (obviously) "a zebra", hence the name.

Top

Why another guitar tuner?

I looked at several guitar tuners before and I couldn't find a free one that worked OK on my computer. So I decided to write one. It seems to be quite tolerant of noisy environments but there's always room for improvements.

Top

Requirements

Top

License

This is supposed to be "free software" that anybody can use however they want, in binary or source form. Personally I feel that only "public domain" is free enough, but I wasn't able to find a clear way to put something into the public domain. Apparently it's quite tricky to renounce the right to have a copyright on something you wrote. Besides, some sites hosting public collections of software seem to want some kind of license. The next best thing seems to be the MIT license, and thus I chose it for ZebraTuner.

Top

Download

Binary
Source code


Top

Install and uninstall

Well, it's a Java program. Just extract the files from ZebraTuner.tgz wherever you want. To uninstall it - delete the files, but before doing this you should probably remove the configuration data. This is done by typing at a command prompt / console:
uninst.bat
or by calling the .jar directly:
java -jar zebratuner.jar -r

Top

Starting ZebraTuner

To use it to tune a guitar, just start the application by typing at a command prompt / console:
ZebraTuner.bat
This should work on UNIX-like systems too, despite the ".bat" extension. If it doesn't, you can try this:
sh ZebraTuner.bat
or start the .jar directly:
java -jar zebratuner.jar
Depending on your computer's configuration, double-clicking on the .jar file in some file manager might work too.

Keep in mind that it's not enough to have the microphone connected to your PC. The signal coming from the microphone must be selected as the source for sound recording. This is done by a mixer / "volume control" application.

Top

What is supposed to happen

After the microphone is selected as the source and the application is started, the main window is displayed:

In each of the 5 panels, a note name and its frequency in Hertz are displayed. ZebraTuner regularly reads data from the microphone and searches the signal for frequencies. Once a frequency is found, it is assigned to one of the 5 panels. To do this, the frequencies are "normalized", by doubling or halving them, once or several times, so the result is as close as possible to one of the frequencies shown on the panels. That is why there are 5 panels, although the guitar has 6 strings: the first and the last strings are both E, and the 2 octaves between them don't matter for ZebraTuner.

(Doubling the frequency of a note results in a note with the same name but which is one octave higher, while halving it creates a note one octave lower.)

A frequency assigned to a panel is represented as a vertical black line whose height corresponds to the strength of the signal. Several frequencies may be detected at any given time, and the strongest 5 of them are displayed as vertical lines in their corresponding panel. Particularly, harmonics of the main signal can be detected and displayed.

Lines from previous measurements are displayed too, with a shade of gray that gets lighter as the corresponding measurement gets older, becoming invisible after 5 measurements.

Also, the value in Hertz of the frequency of the strongest signal in a panel is displayed, along with a percentage indicating how much the signal deviates from the panel's frequency.

Ideally the black and gray lines should be displayed such that they fall on the vertical band in the middle of a panel. How close is "close enough", depends on the particular situation. One thing to keep in mind is that the position of the lines is highly nonlinear, and the farther a line is from the middle band, the more the frequency has to change in order for the line to change its position.

While the frequency detector is not perfect, it seems to be doing a pretty good job with generated sounds. But don't expect lines from consecutive measurements to regularly overlap in the middle of the panel. Musical instruments don't emit sounds with a perfectly constant frequency (for one thing, such a sound is quite unpleasant), and a 0.01% (1 in 10000) variation is quite visible on the screen, although it seems that humans can't detect such a small difference. According to Encyclopaedia Britannica the just noticeable difference (JND) for sounds "is about 0.5 percent of the frequency of the tone, or about one-tenth of a musical half-step"; this doesn't make sense, because it is 5% (and not 0.5%) of the frequency increase corresponding to a tone that is about 10% of the increase corresponding to a semitone. Calculations based on Wikipedia give a frequency increase of about 0.35% for JND, so probably "about one-tenth of a musical half-step" is the correct value at Britannica, which gives a 0.58% frequency increase for JND. Also, it looks like the amplitude of the sound produced by a guitar has some impact on its frequency, which decreases slightly as the sound fades out.

Top

Other features

While written mainly for guitar tuning, ZebraTuner can be used to tune other instruments. By pressing on the "Config" button, a window pops up where frequencies and labels can be edited. There is a button for setting the 5 predefined notes used for tuning the guitar and another one for the 12 notes in an equal temperament-based octave. Then notes can be added or removed and the frequencies can be changed, as needed. On every line there must be a label (which may contain spaces), followed by a space and a number, representing a frequency. Each line will get a panel.

Since frequencies can be edited, other tuning systems can be chosen besides those based on equal temperament, like something based on just intonation. In such a case the frequencies must be calculated separately and then entered manually, though.

It is possible to raise or lower the pitch of the target notes, without changing each frequency manually. This is also done in the "Configuration" dialog, by choosing for A4 a frequency other than 440Hz and then pressing on "Set guitar" or "Set all". Then the frequencies for all the notes are set to match the A4 value. This feature may be used for various reasons, like playing along with some recorded songs or an instrument that uses a different tune and can't be tuned, purposely tuning up or down a guitar, using a capo, making up for an fast or slow clock in the computer ...

The current configuration is saved when ZebraTuner exits and it is used automatically the next time it is started. Configuration includes the labels and frequencies for each panel, the frequence of A4 and the size and position of the main window. In order to remove the configuration information, ZebraTuner must be started with the "-r" option:
java -jar zebratuner.jar -r

Top

Status

Currently there's only one version, 0.9

As far as I'm concerned, ZebraTuner is pretty much finished and it works OK. A nicer UI could be done but I have no plans to work on one.

I understand that finding frequencies is normally done with Fourier transforms. I had some code that implemented this approach, but the current version works much better for me. Still, maybe it's something that I did wrong and that's why it didn't work very well, and better code based on Fourier transforms would actually outperform what's currently done.

It may be preferable to run ZebraTuner as an applet, and I have some code that starts an applet and soon finds that it doesn't have permissions to read from the sound port. I understand this can be dealt with by either changing some local Java configuration file on each client (which is probably unacceptable) or by signing the applet. For now it seems that it's not worth bothering with the applet implementation.

Maybe some effort should be put into eliminating harmonics, to reduce the amount of irrelevant information. But for now I don't plan to tackle this.

I think a version that works with JDK 1.4 and even 1.3 could be done, if there's any need. (The main feature from 1.5 used in the code is generics-based collections.)

Sometimes the config dialog opens full-screen on SuSE 10.1 with JDK 1.5.0_10, 64-bit. I wasn't able to figure why, but it happens with other programs too, including a demo from Sun. It still seems to work OK, though.

A few times my Linux box froze completely while running ZebraTuner. I suspect there's something wrong with my Linux installation, as it's not supposed to let other programs crash it.

More things could be made configurable, like the values used in a band-pass filter. Currently frequencies below 100Hz and above 1000Hz are filtered out, and these values are hard-coded.

I'm not sure it the default should be 5 or 12 notes. 12 seem more useful, as they allow checking other notes too, but I decided to keep it simpler.

Top

Troubleshooting


Top

Support and contact

If there are cases when people are trying to use it but it doesn't work at all or it works intermitently, I will provide email support to the extent that I have time available. The address is ciobi <at> inbox <dot> com . Also, I will check the forum provided by SourceForge.

I'd like to know what people think about ZebraTuner and if there are any suggestions to improve it.

I'd like to know what is the minimum CPU speed at which ZebraTuner can run acceptably, so please let me know if you have some idea of what that might be.

Code patches are welcome as long as I agree that they represent improvements (and the code isn't too messy). Otherwise I'd probably prefer that a different project be created to incorporate those changes and continue separately.

I normally use more comments in the code, but ZebraTuner's code seems simple enough and I don't expect major changes in the future (which would benefit from detailed documentation). So for now full documentation of the code is postponed indefinitely, as well as making "private" the members that should be so. Still, if you'd like to use the code but can't understand it, I will try to help and probably do the comments.

Top

Have fun,
Ciobi