Vobarian Software
Home to Harmometer to Manual
Last update: 2006-01-13
Harmometer Manual

Contents

1.  Quick intro
2.  Recording sound
3.  Running Harmometer
4.  Troubleshooting
5.  Analyzing results
Appendix A.  License
Appendix B.  Accuracy testing

1. Quick intro

Harmometer is a program for measuring the harmonic content of sound. Complex sounds, such as the sound of a cello or the sound of someone singing, are made up of a fundamental component plus harmonics, also called partials or overtones. The fundamental is the lowest frequency component of the tone (as long as there are no sub-harmonics) and all the harmonics have frequencies which are integer multiples of the fundamental. For example, a 100 Hz tone has a fundamental component at 100 Hz, and may have harmonics at 200 Hz (the first harmonic), 300 Hz (the second harmonic), and so on.

Harmometer measures the fundamental frequency using a pitch detection algorithm and then measures the harmonics using a simplified discrete Fourier transform at each of the harmonic frequencies. This technique is extremely accurate as long as the pitch detection algorithm correctly identifies the fundamental (see accuracy testing).

Please look over the license before using Harmometer. Harmometer is free for non-commercial use.

Thanks are due as follows:

2. Recording sound

Harmometer expects its input to be in a certain format. The program accepts Wave format files (.wav extension). Most audio programs can record wave files, such as the Sound Recorder accessory which comes with Windows or more advanced programs such as Audacity. The following settings are expected:

If you're using the Sound Recorder accessory that comes with Windows, you can configure these settings as follows: Click "File", select "Properties", click "Convert Now...", under "Format" select "PCM", under "Attributes" select 16 bit mono with an appropriate sampling rate (recommended values are 22.05 kHz to 48 kHz).

The sound you record must follow a specific pattern. Play a tone, then pause, then play the next tone, and so forth. For example, you may wish to measure the change in the first harmonic with frequency. To accomplish this, you would play a chromatic scale on the instrument, pausing between each tone. The required lengths of the tones and pauses depend on the settings you enter when you run Harmometer. In general, using the default settings, the tone should be about one second long and the pause should be at least half a second. These timings do NOT have to be precise, however. If you pause for several seconds, that is okay, the silence will just be ignored. Also, if you play the tone longer, you may get a more accurate measurement. The tone you play will be divided into small frames of 0.3 seconds each. The frames will be measured individually and the results will be averaged. So if you play a 2 second tone, the first 0.2 seconds will be skipped (assuming default settings), then the remaining 1.8 seconds will be divided into 6 frames. The results of each frame will be averaged. This is why playing longer tones might result in a more accurate measurement. Each tone should be steady and unbroken.

Below is a picture of an example recording (screenshot taken from Audacity). The scale above the waveform shows time in seconds. Notice that there are tones, each a single note, separated by breaks of silence.

Picture of a sample waveform

3. Running Harmometer

To run Harmometer, double-click on harmometer.exe. When it starts, first you will be asked to select the wave file that you have recorded. Next you will be asked for a file name for the file to which the output will be written. Next you will be asked if you want to modify the default settings. It is easiest to answer no, which will cause the default settings to be used. The default settings have been selected to work correctly in most cases. However, if the pitch detection is incorrect or you want to experiment with the settings, you will need to answer "yes" to the prompt and proceed to modify the settings. A description of all the settings follows.

Settings

Note: For any setting, you can just press the Enter key to use the default.

  1. Number of harmonics to measure: This setting determines how many harmonics are measured for each tone. Entering zero means that only the fundamental will be measured.
  2. Minimum tone duration: This is the duration of the shortest section of tone to analyze. This setting also determines the size of the analysis frame. Tones will be broken up into frames of the size you enter here. Using shorter analysis frames allows more accurate pitch tracking in case the pitch of the tone varies slightly throughout its duration. However, using too short of a frame may result in inaccuracy. The default setting of 0.3 seconds is a good compromise.
  3. Note attack length: This is the length of the note attack, in seconds. The "attack" is the beginning period of a note. During this time the instrument may produce some random noise and the tone is not stable. For example, when bowing a stringed instrument, there is a brief crackling noise at the beginning of each note when the bow begins to move. This attack period should be skipped because it could result in incorrect pitch detection and inaccurate harmonic measurement. The period of time you enter here will be skipped at the beginning of each note. The default setting of 0.2 seconds is the approximate length of the attack for a cello.
  4. Peak detection threshold: This is the threshold level for peaks in the frequency spectrum. This is the most important parameter for accurate pitch detection. If you are getting incorrect pitch detection results, try adjusting this parameter. In general, if the pitch detected is higher than the actual pitch, then a peak is being overlooked, so try lowering this value. If the pitch detected is lower than the actual pitch, a false peak is being detected, so try increasing this parameter.

"Advanced" settings

In general, you can skip the advanced settings. However, you can adjust them if you wish to experiment.

  1. Length of break of silence: This setting determines how much silence must separate the tones.
  2. FFT size: This setting determines the length of the frame used for pitch detection. Using a longer frame may possibly result in more accurate pitch detection.
  3. Number of samples between FFT frames: This setting is used in pitch detection.
  4. Silence threshold: This is the maximum sample value that will be considered "silent". The break between notes must be silent, so the waveform must be below this value during the breaks of silence. Also, the tones must be above this threshold to be detected.
  5. Minimum number of cycles: This determines the minimum frame size for low frequency tones.
  6. Maximum extra time: Extra time may be added to the DFT frame beyond the "minimum tone duration" setting. Allowing extra time may improve accuracy.
  7. Maximum fractional cycle: This affects the accuracy of the DFT. Smaller values mean higher accuracy.
  8. Number of peaks: This is the number of peaks in the spectrum that will be considered when performing pitch detection.

4. Troubleshooting

Incorrect pitch detection

Error: no peaks found

No peaks were found when running the pitch detection algorithm. Try reducing the peak detection threshold.

5. Analyzing results

After you run Harmometer, you have a text file containing the output. It is formatted with one tone per row. The columns are separated by commas. Harmonic 0 represents the average amplitude of the fundamental, while Max Fundamental represents the maximum amplitude of the fundamental in any one analysis frame. Following are instructions on how to import this data into a spreadsheet.

Importing

Microsoft Excel

  1. Select a cell as the upper-right corner of the block into which the data will be placed.
  2. Click the "Data" menu, go to "Get External Data", click "Import Text File".
  3. Select the file and press "Open".
  4. Click "Next".
  5. Check the box labeled "Comma".
  6. Press "Finish". Press OK.

OpenOffice.org

  1. Go to File => Open.
  2. Under "Files of Type" select "Text CSV".
  3. Select the file to import and press "Open".
  4. Place a check mark next to "Comma" and press "OK".
  5. You can copy & paste the data into another spreadsheet if you want.

Quattro Pro 7

  1. Select a cell as the upper-right corner of the block into which the data will be placed.
  2. From the "Data" menu select "Text Import".
  3. Enter the filename or browse to find the text file output from WaveMeas.
  4. Select "Only Commas".
  5. Press OK.

Microsoft Works

  1. Go to File => Open.
  2. In "Files of Type" select "Text" or "All Files". Select the output wave file from WaveMeas.
  3. Press "Open".
  4. Select "Spreadsheet" to place the data in a spreadsheet.
  5. You can copy & paste the data into another spreadsheet if you want.

Transposition

The output from Harmometer has one row for each tone and one column for each harmonic. This makes it easy to plot the harmonics as a function of the fundamental frequency. However, you may wish to reverse this so that each row contains one harmonic and each column contains the harmonics for one tone. Switching the rows and columns is called transposition. Following are instructions on how to transpose the data in various spreadsheet programs.

Excel

  1. Select the data to transpose.
  2. Click "Copy" on the toolbar or on the "Edit" menu.
  3. Click the upper-left cell of the area where you want the results to appear.
  4. Click the "Edit" menu and click "Paste Special".
  5. Place a check mark next to "Transpose".
  6. Press "OK".

OpenOffice.org

  1. Select the data to transpose (click and drag the mouse from the upper-left to the lower-right corner of the data block).
  2. Click "Cut" on the toolbar or on the "Edit" menu.
  3. Click the upper-left cell of the area where you want the results to appear.
  4. Click the "Edit" menu and click "Paste Special".
  5. Place a check mark next to "Transpose".
  6. Press "OK".

QuattroPro 7

  1. Select the block of data.
  2. Click "Cut" on the toolbar or on the "Edit" menu.
  3. Click the upper-left cell of the area where the results should appear.
  4. Click the "Edit" menu and click "Paste Special".
  5. Place a check mark next to "Transpose Rows and Columns".
  6. Click "Paste".

Appendix A. License

This software and documentation is copyrighted. Your use or distribution of the software indicates your agreement with these terms.

  1. Software: The term "software" refers to the Harmometer program, in binary or executable form or source code form, and the documentation.
  2. Non-commercial use: You may use the software free of charge for non-commercial use. "Non-commercial" means the software may not be used to develop or test products which will be sold, it may not be used in connection with advertising products, and it may not be used to conduct tests for commercial projects or commercial research.
  3. Distribution: You may redistribute the software under these conditions: there will be no charge for the distribution, the software will not be distributed in a package or disk also containing commercial software, and the software will be distributed in its complete, unmodified form along with all documentation and this license.
  4. Derivative works: You may use the software source code to create derivative works only under these conditions: the derivative work must have a license and the license must include section 2, "non-commercial use" verbatim and section 3, "distribution" verbatim. The derivative work may not be sold or distributed for a fee. The derivative work must not be distributed under the name "Harmometer", to avoid confusion with the original version. The license of the derivative work will obey one of the two following options: (a) the license includes section 4, "derivative works" verbatim; or (b) the license explicitly prohibits development of further derivative works.
  5. No warranty, no liability: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, INCLUDING BUT NOT LIMITED TO DIRECT, INDIRECT, SPECIAL, OR CONSEQUENTIAL DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OR IN CONNECTION WITH THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  6. Termination: This license will be terminated if you violate any of its terms, or if you decide to terminate the license. Upon termination of the license, you must stop using the software and delete any copies of it that you have, and you must not distribute the software. You will cease to have the right to create any derivative works, and any existing derivative works must be destroyed. (This is to prevent use of derivative works outside of the terms of this license.)

Appendix B. Accuracy testing

To test the accuracy of Harmometer, test wave files were generated with precisely known waveforms. The following table shows that Harmometer can be extremely accurate.

Value NameActual ValueMeasured ValuePercent Error
Frequency100 Hz100.000 Hz0.000%
Harmonic 070006999.4-0.009%
Harmonic 160006000.00.000%
Harmonic 250004999.8-0.004%
Harmonic 340003999.9-0.002%
Harmonic 430002999.8-0.007%
Harmonic 520002000.00.000%
Harmonic 61000999.9-0.010%
Harmonic 7500500.00.000%
Harmonic 8250250.00.000%
Harmonic 9125125.00.000%
Harmonic 106261.9-0.161%

Comments and questions are welcome. E-mail address: contact delete-this-before-sending _AT_ vobarian.com (Obviously, delete the extraneous words and replace _AT_ with @. This is to reduce spam.)

Mountains & clouds at top of page (clouds.jpg) taken from photo by Oswald Skene / DHD Multimedia Gallery

©2009 Chad Berchek - everything here unless otherwise noted