PerfectSineWaves Wiki

Perfect and bit-perfect PCM encoded sine wave audio test tones

Brought to you by: sduplichan

Home

Documentation

Archive contents

The PerfectSineWaves archive contains a Windows command line executable program along with source code and many sample batch files. The wave files and FFT listings produced by the batch file buildall-mpfr.bat are also included. The utility can be rebuilt using Microsoft Visual Studio. A linux port shouldn't be too hard if needed. The batch files can be run from Windows explorer directly, or from the command line.

Utility functions

The utility is named waveutil.exe (also wu.exe for short). Its primary purpose is the generation of test tones containing one or more sine wave components. Additional functions are command line FFT (double precision) and DFT (extended precision). The utility can also dump a range of wave file samples as a decimal listing. New for version 1.2 is a command for measuring the true peak of a wave file. This command produces a high accuracy measurement for a periodic input file that is short or contains a short repeating pattern.

Command line examples

Make a 5 second telephone dial tone:
waveutil cosine,1,350 cosine,1,440 duration=5 dialtone.wav

Show the FFT of the above tone:
waveutil dialtone.wav fft

 Harmonic Frequency               Magnitude                   angle
 (0-2205)      (Hz)                    (dB)                   (rev)
       35       350      -9.030899869919436       0.000000000000000
       44       440      -9.030899869919436       0.000000000000000

Command line reference

The command line options can be arranged in any order. If an option ends with '.wav', it's considered a wave filename. The option wave= can be used if for some reason the file doesn't have a .wav extension. Some options apply only to wave generation and are ignored if used with an option such as fft. There is no warning about unused options, so be careful.

As shown in the dialtone example above, more than one instance of the sine option may be used. When multiple sine options are present, their outputs are summed and written to the wave file. The level of the generated tone is adjusted to +- 1.0 true peak (0 dBTP). The peak value of 1.0 can be changed using the command line option amplitude= (see below).

When a generated tone is encoded, the quantization error affects the amplitude. This amplitude quantization error is greatest at lower resolution encodings, such as i16. It's often possible to reduce this quantization amplitude error by rebuilding the file at a slightly higher or lower level. This process can be automated using the command line option finetune (see below).

If many sine components are needed, the command line length can exceed the Windows limit. A solution to this problem is to put the sine commands (or any other command line option) in a text file, one option per line. Then put the name of the command file on the waveutil command line, preceded by the @ character.

wave=
Name of wave file for read and write operations. The wave= prefix can be dropped if the wave filename ends in .wav.

@cmdfile
Read additional command line options from cmdfile. Each command must be on a separate line.

dumpwave,start,end,precision
Dump wave file samples from offset start to offset end, using precision number of digits. Precision is optional.

samplerate=
Set the output wave file PCM sample rate (samples per second). Default is 44100.

duration=
Set the minimum play time in seconds of the output wave file. The actual play time of the wave file will be increased enough to ensure every sine component contains a whole number of complete cycles. The default value of zero produces the shortest wave file that contains a whole number of complete cycles of each sine component.

patternlength=
In this project, patternlength refers to the smallest number of samples needed to ensure every sine component contains exactly a whole number of cycles. The samples in the pattern form one complete cycle of the PCM data. The term pattern is used instead of cycle to avoid confusion with the cycles of the individual sine waves making up the pattern. Because patternlength is the number of samples before the wave file data repeats, it constitutes exactly one cycle of the infinite tone described by the combined sine frequencies. For that reason, patternlength is the number of samples needed for correct FFT analysis.

For wave file generation, this option is often not needed because it's calculated by the utility. But if the requested sine frequencies and sample rate choice result in a patternlength that is greater than 268,435,456 (0x10000000), the utility will log an error message. In this case, patternlength must be entered on the command line. When patternlength is entered on the command line in this situation, the utility will adjust each sine frequency as needed to ensure a complete number of cycles fills the pattern. Setting patternlength manually is often needed for multitone generation because evenly spaced frequencies may not line up in a way that results in a results in a reasonable pattern length. For FFT friendliness, a small power of 2 patternlength is best. A small patternlength forces the utility to make large frequency adjustments, so there is a balance to reach when choosing patternlength.

amplitude=
Set the true peak amplitude for the summed output final scaling. The default value of 1.0 results in reconstructed output that is maximum without exceeding 0 dBTP.

finetune
Fine tune the peak output to reduce the effect of quantization error on the intended output level. When this option is used, the utility will check the true peak level of the generated wave file. It will then rebuild the wave file with an amplitude adjustment to minimize the quantization induced difference. The process is repeated until the error is smaller than DBL_EPSILON for f64 encoding (or analogous for other encodings). The finetune loop also exits if the process doesn't converge on a single amplitude adjustment value. The finetune adjustment procedure targets the encoding that has a true peak level closest to the target value without exceeding it.

sampleformat=
Set the wave file output sample format to one of: u8, i16, i24, i32, f32, f64. Default is f64. This option can be repeated on the command line with different values. When more than one output sample format is given, the utility generates a unique filename for each by appending the format name to the given wave filename.

sine,a,f[,p]
cosine,a,f[,p]
square,a,f[,p]
Add a sine, cosine, or square wave component to the output. The option can be repeated on the command line to generate multitone wave files.
a-amplitude (relative to other sine/cosine components)
f-sine/cosine component frequency in Hz
p-phase (starting angle) in revolutions

The calculated sine value is multiplied by the given amplitude value before adding to the other sine components. Use a value of 1 if differing sine component amplitudes is not needed. The amplitude value in this option is relative to the others, and the final wave file amplitude will be scaled separately.

sine,f
cosine,f
square,f
Same as sine,1,f or cosine,1,f or square,1,f

precision=
Set the precision for MPFR extended precision floating point math. Units are bits and the default is 128. MPFR extended precision math is used for all operations that can affect accuracy of the output file. Note that the DFT: dump option has its own precision field that overrides this one.

generator=
Select the waveform generation method:
mpfr - Default. Use the MPFR extended precision sine function and math to generate, add, and scale the sine components. The resulting values are rounded down to double precision then passed to libsndfile which writes the wave file.
ifftw - Inverse FFT using FFTW double precision library. The starting phase angle calculations are done usng MPFR extended precision math. The final amplitude is applied to the double precision IFFTW output using double precision math. The final wave file result is nearly as accurate as the mpfr option, and the generation speed is faster.

upsampleratio=
When the option generator=ifftw is in effect, the default upsample ratio for true peak determination is 16. Use this option to change it.

fft[.fmt][mindb]
Dump the FFT of the wave file. The double precision FFTW library is used.
If the fmt value is given, it overrides the default number of digits to print for harmonic magnitude and angle. The default values are 3, 5, 7, 8, 10, and 16 for sample formats u8, i16, i24, f32, i32, f64 respectively.
If the mindb value is given, it overrides the default logging cutoff for small magnitude harmonics. The default value is calculated as half way between the dB level of the largest harmonic, and the dB level of worse-case quantization noise (6.02 * effective bits per sample). Note: even if mindb is overridden, the utility will never log harmonics that are smaller than what the double precision math can resolve. As a result, the utility can be forced to log the quantization noise harmonics for sample types u8, i16, i24, f32, i32, but not for f64. To accurately log the noise harmonics of a double precision (f64) wave file, use the extended precision DCT option.
The FFT dump command calculates ENOB (effectiv e number of bits) as the difference between the maximum harmonic and worse-case quantization noise. ENOB is logged with a warning if it is lower than the expected value of 6.02 * effective number of sample bits.
The FFT command should process exactly one set of samples making up the repeating pattern in the input wave file. By default, the FFT command processes all samples in the wave file. If the wave file contains more than one complete pattern of samples, you must use command line option patternlength= to limit the processing to the correct number of samples. The number of samples in the repeating pattern may not be obvious if you did not create the file. Future enhancement: pattern length detection.

fftformat=
{gainangle[f]|dbangle[f]|ab|cmdline|cmdfile|batch} [f]: fraction
FFT output formatting options. dbangle, the default, prints magnitude in dB and angle with units of revolutions. Option gainangle prints magnitude in v/v and angle with units of revolutions. Append 'f' to either of these two options for angle as fraction. Option ab prints the real and imaginary parts.
Option cmdline prints a complete command line for regenerating the input file. Option cmdfile dumps the commands needed for recreating the input file, one line per command. This option avoids the Windows command line length limitation present in the cmdline and batch options. Examples can be found in demo\bitperfect\intersamplePeak. Option batch generates a batch file for recreating the input file.

fftscale=
Option rms (default) scales the magnitude a full scale sinusoid to .7071... Option peak scales the magnitude a full scale sinusoid to 1.

normalizephases
Time shift the phase angles so that at least one of them is zero.

samplephase
Add a time offset in units of samples to the component functions when building the output file.

fftfindpeak
Read a wave file and report the true peak using FFT upsampling. If the input file contains a repeating pattern, only a single instance of the pattern is used. The utility treats the input pattern as periodic and uses FFT to find the sinusoid components. It then uses the components as input to an inverse FFT pass that creates an upsampled pattern. The upsampled output is scanned for the peak value. The upsampling ratio and corresponding true peak value is reported. For the wave files included in this project, the upsampling ratio is a minimum of 1024:1.

upsample,ratio,name
Upsample the input wave file by ratio:1, then write to wave output file name

fftangle=
Starting with version 1.2, the fft and dft commands log the phase angle in terms of cosine. Use this option if you want to log the phase angles in terms of sine. As with other options, units are revolutions.

dft:prec[.fmt][mindb]
Dump the DFT of the wave file. MPFR extended precision math is used. The prec field selects number of precision bits.
If the fmt value is given, it overrides the default number of digits to print for harmonic magnitude and angle. The default values are 3, 5, 7, 8, 10, and 16 for sample formats u8, i16, i24, f32, i32, f64 respectively.
If the mindb value is given, it overrides the default logging cutoff for small magnitude harmonics. The default value is calculated as half way between the dB level of the largest harmonic, and the dB level of worse-case quantization noise (6.02 * effective bits per sample).
The FFT dump command calculates ENOB (effectiv e number of bits) as the difference between the maximum harmonic and worse-case quantization noise. ENOB is logged with a warning if it is lower than the expected value of 6.02 * effective number of sample bits.
The DFT command should process exactly one set of samples making up the repeating pattern in the input wave file. By default, the DFT command processes all samples in the wave file. If the wave file contains more than one complete pattern of samples, you must use command line option patternlength= to limit the processing to the correct number of samples. The number of samples in the repeating pattern may not be obvious if you did not create the file. Future enhancement: pattern length detection.

info
verbose
These options increase the amount of output detail and debug information logged.

logsteps,L,H,N[,p]
The logsteps option prints a logarithmically scaled list of values. The optional p value overrides the default number of 6 printing digits.
L - low value
H - high value
N - number of steps

The output of this command can be used in combination with a text editor to create new multitone generation batch files.

linearsteps,L,H,N[,p]
The linearsteps option prints a linearly scaled list of values. The optional p value overrides the default number of 6 printing digits.
L - low value
H - high value
N - number of steps

The output of this command can be used in combination with a text editor to create new multitone generation batch files.