Draw the waterfall for everything that never spoke

Every capture that is not voice, or whose voice yields five characters
or fewer of transcript, now gets a PNG of the waterfall it would have
painted on screen: spectrogram from the IQ where it was kept, from the
demodulated audio otherwise, captioned and labelled either way.

The browser shows it in the picture panel, but only when there is no
transcript, Morse or decoded data to show instead.

  bandsaunter waterfall [PATH...] [--all] [--redraw] [--min-chars N]

draws them after the fact for recordings already on disk.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg

packaging/bandsaunter.1

@@ -1,5 +1,5 @@
 .\" Generated by packaging/make-man.py -- do not edit by hand.
-.TH BANDSAUNTER 1 "2026-09-02" "bandsaunter 2026-09-01_02" "User Commands"
+.TH BANDSAUNTER 1 "2026-09-03" "bandsaunter 2026-09-03_01" "User Commands"
 .SH NAME
 bandsaunter \- scan, record and identify radio signals with an RTL-SDR
 .SH SYNOPSIS
@@ -62,6 +62,12 @@ Transcribe existing recordings, or list which speech recognisers are
 installed with
 .BR \-\-engines .
 .TP
+.B waterfall
+Draw a waterfall for every recording in a directory that produced no
+readable words. See
+.B WATERFALLS
+below.
+.TP
 .B devices
 List attached receivers.
 .TP
@@ -549,6 +555,26 @@ Setting name \fBdecode_images\fR, default \fByes\fR.
 Three of the things a receiver can hear are pictures: the weather satellites on 137 MHz, amateur slow-scan television, and the shortwave weather fax stations. All three are images sent as sound, so they arrive in the same recordings everything else does. Each is recognised by its own header rather than guessed at, so this costs a moment per recording and finds nothing where there is nothing. What it does find is written as a PNG beside the audio.
 .RE
 .TP
+.B --waterfall / --no-waterfall
+Draw a waterfall \[em] picture every capture that produced no readable words.
+.br
+Setting name \fBwaterfall\fR, default \fByes\fR.
+.RS
+.PP
+Most of what a scanner records cannot be turned into words: a data burst, a keyed carrier, a pager, a control channel, a stretch of something unidentified. A waterfall shows the shape of a signal rather than its meaning -- how wide it is, how long it lasted, whether it was keyed, swept, hopping or steady, and whether it was one signal or three side by side -- so every capture that produced no readable words gets one drawn beside it as a PNG. Where the raw IQ was kept it draws the radio spectrum; otherwise the demodulated audio, and it says on the picture which it is.
+.RE
+.TP
+.B --waterfall-min-chars
+Words that count as readable \[em] a transcript shorter than this counts as no transcript.
+.br
+Setting name \fBwaterfall_min_chars\fR, default \fB5\fR.
+.br
+Accepts: at least 0, at most 200.
+.RS
+.PP
+How much transcript counts as having read a capture. Under this, the recogniser found a word or two of nothing in particular, and a picture of the signal is worth more than the word.
+.RE
+.TP
 .B --morse / --no-morse
 Decode CW to text \[em] decode keyed carriers as Morse.
 .br
@@ -999,6 +1025,37 @@ Nothing is joined across a slash: a suffix says where the station is, not
 what it is called, so
 .I W1AW/B
 is W1AW.
+.SH WATERFALLS
+Most of what a scanner records cannot be turned into words: a data burst, a
+keyed carrier, a pager, a control channel, a stretch of something
+unidentified. A waterfall says something about every signal there is,
+because it shows the shape of the thing rather than its meaning \[em] how
+wide it is, how long it lasted, whether it was keyed, swept, hopping or
+steady, and whether it was one signal or three side by side.
+.PP
+So every capture that produced no readable words is drawn beside the audio
+as a PNG: no voice, or voice the recogniser came back from with fewer than
+.B \-\-waterfall\-min\-chars
+characters, which is what a recogniser handed something that is not speech
+reliably does. Time runs down the picture and frequency across it, with the
+frequency scale on top, the seconds down the left and a caption underneath
+saying what the capture was.
+.PP
+The caption also says what the picture is *of*, and that matters. Where the
+raw IQ was kept this draws the radio spectrum around the tuned frequency,
+which is the waterfall an operator would have been watching. Where only the
+audio was kept \[em] the usual case, since IQ is off by default \[em] it
+draws the demodulated audio instead: after an FM detector the frequency axis
+is no longer radio frequency, and a picture that did not say so would be a
+lie told in a convincing font.
+.PP
+.B bandsaunter waterfall
+does the same for a directory already recorded, drawing only what cannot be
+read unless
+.B \-\-all
+is given, and skipping what it has already drawn unless
+.B \-\-redraw
+is.
 .SH CW AND IDENTIFICATION
 Every capture is offered to a CW decoder once it has finished, whatever the
 classifier made of it. Most of the Morse on the air is not a conversation:

packaging/make-browse-man.py

@@ -197,6 +197,13 @@ message says which packages would fix it.
 Over ssh there is usually no sound server at the far end. The browser and its
 transcripts work regardless; only Enter has nothing to do.
 .SH DETECTED CALLSIGNS
+A capture that produced no readable words has a waterfall drawn beside it
+instead \[em] a picture of the signal, which for a data burst or a keyed
+carrier is the only view there is. The browser marks it, gives the path in
+full, and
+.B o
+prints it: there is no listening to a data burst.
+.PP
 Under the transcript, headed
 .BR "DETECTED CALLSIGNS:" ,
 is every callsign heard in it, with the name and location on the licence.

packaging/make-man.py

@@ -120,6 +120,12 @@ Transcribe existing recordings, or list which speech recognisers are
 installed with
 .BR \-\-engines .
 .TP
+.B waterfall
+Draw a waterfall for every recording in a directory that produced no
+readable words. See
+.B WATERFALLS
+below.
+.TP
 .B devices
 List attached receivers.
 .TP
@@ -412,6 +418,37 @@ Nothing is joined across a slash: a suffix says where the station is, not
 what it is called, so
 .I W1AW/B
 is W1AW.
+.SH WATERFALLS
+Most of what a scanner records cannot be turned into words: a data burst, a
+keyed carrier, a pager, a control channel, a stretch of something
+unidentified. A waterfall says something about every signal there is,
+because it shows the shape of the thing rather than its meaning \[em] how
+wide it is, how long it lasted, whether it was keyed, swept, hopping or
+steady, and whether it was one signal or three side by side.
+.PP
+So every capture that produced no readable words is drawn beside the audio
+as a PNG: no voice, or voice the recogniser came back from with fewer than
+.B \-\-waterfall\-min\-chars
+characters, which is what a recogniser handed something that is not speech
+reliably does. Time runs down the picture and frequency across it, with the
+frequency scale on top, the seconds down the left and a caption underneath
+saying what the capture was.
+.PP
+The caption also says what the picture is *of*, and that matters. Where the
+raw IQ was kept this draws the radio spectrum around the tuned frequency,
+which is the waterfall an operator would have been watching. Where only the
+audio was kept \[em] the usual case, since IQ is off by default \[em] it
+draws the demodulated audio instead: after an FM detector the frequency axis
+is no longer radio frequency, and a picture that did not say so would be a
+lie told in a convincing font.
+.PP
+.B bandsaunter waterfall
+does the same for a directory already recorded, drawing only what cannot be
+read unless
+.B \-\-all
+is given, and skipping what it has already drawn unless
+.B \-\-redraw
+is.
 .SH CW AND IDENTIFICATION
 Every capture is offered to a CW decoder once it has finished, whatever the
 classifier made of it. Most of the Morse on the air is not a conversation:

packaging/saunterbrowse.1

@@ -1,5 +1,5 @@
 .\" Generated by packaging/make-browse-man.py -- do not edit by hand.
-.TH SAUNTERBROWSE 1 "2026-09-02" "bandsaunter 2026-09-01_02" "User Commands"
+.TH SAUNTERBROWSE 1 "2026-09-03" "bandsaunter 2026-09-03_01" "User Commands"
 .SH NAME
 saunterbrowse \- read and listen to what a bandsaunter scan collected
 .SH SYNOPSIS
@@ -171,6 +171,13 @@ message says which packages would fix it.
 Over ssh there is usually no sound server at the far end. The browser and its
 transcripts work regardless; only Enter has nothing to do.
 .SH DETECTED CALLSIGNS
+A capture that produced no readable words has a waterfall drawn beside it
+instead \[em] a picture of the signal, which for a data burst or a keyed
+carrier is the only view there is. The browser marks it, gives the path in
+full, and
+.B o
+prints it: there is no listening to a data burst.
+.PP
 Under the transcript, headed
 .BR "DETECTED CALLSIGNS:" ,
 is every callsign heard in it, with the name and location on the licence.