pydiffsa.1

.TH PYDIFFSA 1 "2026-04-02" "pydiffsa 1.0.0" "User Commands"
.SH NAME
pydiffsa \- periodic windowed frequency (spectral) analysis of WAV files
.SH SYNOPSIS
.B pydiffsa
[\fIOPTIONS\fR] \fIfile.wav\fR
.br
.B pydiffsa
[\fIOPTIONS\fR] \fIfile_a.wav\fR \fIfile_b.wav\fR
.SH DESCRIPTION
.B pydiffsa
reads one or two WAV files, applies a Hann-windowed FFT at regular hop
intervals, and prints frequency bin magnitudes in dBFS for each window.
.PP
When a single file is given, the spectrum of each window is printed,
followed by the averaged spectrum across all windows.
.PP
When two files are given, the spectrum of each window is printed for both
files, both averaged spectra are printed, and \fB\-\-diff\fR can be used
to show the per-bin dB difference (B \(mi A) averaged across all windows.
.PP
If
.B numpy
is installed it is used for fast FFT computation; otherwise a pure-Python
DFT fallback is used (slow for large frame sizes).
.SH OPTIONS
.TP
.BI \-\-frame\-size " N"
FFT window size in samples.
Default: \fB256\fR.
.TP
.BI \-\-hop " N"
Hop size between successive windows in samples.
Default: \fIframe\-size\fR/2 (50 % overlap).
.TP
.BI \-\-top " N"
Number of highest-magnitude bins to print per window.
Default: \fB15\fR.
.TP
.BI \-\-floor " dB"
Noise floor in dBFS used for display.
Bins at or below this value are suppressed in averaged and per-window output.
Default: \fB\-80.0\fR.
.TP
.B \-\-avg
Print only the averaged spectrum; suppress per-window output.
.TP
.B \-\-diff
Show per-bin dB difference (B \(mi A) averaged across all windows.
Requires two WAV files.
Bins whose magnitude difference is less than 0.5 dB are suppressed.
.TP
.B \-\-no\-bar
Suppress the ASCII bar charts shown alongside bin magnitudes.
.TP
.B \-\-version
Print version information and exit.
.TP
.B \-h ", " \-\-help
Print a short usage summary and exit.
.SH EXAMPLES
Print the per-window spectrum of a single file:
.PP
.RS
.B pydiffsa file.wav
.RE
.PP
Print only the averaged spectrum:
.PP
.RS
.B pydiffsa file.wav \-\-avg
.RE
.PP
Compare two files with a larger window and show the dB difference:
.PP
.RS
.B pydiffsa ref.wav gen.wav \-\-frame\-size 512 \-\-hop 256 \-\-avg \-\-diff
.RE
.PP
Redirect the difference report to a file:
.PP
.RS
.B pydiffsa ref.wav gen.wav \-\-avg \-\-diff > report.fa
.RE
.PP
Suppress bar charts and lower the noise floor:
.PP
.RS
.B pydiffsa file.wav \-\-avg \-\-floor \-96 \-\-no\-bar
.RE
.SH OUTPUT FORMAT
For each analysis window,
.B pydiffsa
prints a header line of the form
.PP
.RS
t=\fIt\fRs  [\fIfilename\fR]
.RE
.PP
followed by a table of the top \fIN\fR bins sorted by magnitude:
.PP
.RS
.nf
  Freq (Hz)     dBFS
    440.0      -12.34  ################
   1320.0      -18.76  ###########
.fi
.RE
.PP
The averaged spectrum lists all bins with magnitude above \fB\-\-floor\fR,
sorted by frequency.
.PP
The difference report lists bins whose absolute difference exceeds 0.5 dB,
with a \fB+\fR or \fB\-\fR bar indicating which file is louder.
.SH NOTES
Only mono and stereo PCM WAV files with 8-bit or 16-bit sample widths are
supported.
Stereo files are mixed to mono before analysis.
.PP
The FFT frame size must be a power of two for best performance with numpy.
.PP
When two files have different sample rates a warning is printed to
standard error and the difference report may be misleading.
.SH AUTHOR
Kris Kirby <ke4ahr@gmail.com>
.SH COPYRIGHT
Copyright \(co 2026 Kris Kirby.
.PP
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.
.PP
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License along
with this program.
If not, see <https://www.gnu.org/licenses/>.
.SH SEE ALSO
.BR sox (1),
.BR ffmpeg (1),
.BR aplay (1)