dustcouncil/bandsaunter
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add saunterbrowse, for reading back what a scan collected

Browse source 
A long scan leaves hundreds of recordings, each with a JSON sidecar of
measurements and, where a recogniser heard speech, a transcript.  Reading
that meant opening files one at a time and guessing which were worth
playing.

saunterbrowse is a second executable in the same package.  Arrow keys move
through the recordings; the transcript of whichever is highlighted fills
the top of the screen, because that is the part anyone actually wants to
read.  Enter plays it, handing the file to whichever player is installed
-- the recordings are ordinary WAVs, every desktop already has something
that plays them, and a browser that cannot start would be worse than one
that cannot play.  t opens the whole transcript full screen when it is
longer than the panel, and says so rather than cutting the end off
silently.  / filters on the frequency, the name, the identification, or
anything that was said, which is the point of it: "was the repeater
mentioned" is a question about content.

Sidecars are read only for the rows on screen, so a directory of ten
thousand recordings opens instantly.  Where there is no transcript the
panel says which of the reasons applies -- Morse (decoded, and shown),
data, a bare carrier, or speech never offered to a recogniser -- because
those want different things done about them.  It only ever reads.

Two things were only found by driving it through a real terminal.
sys.stdin.read(1) goes through a buffered text wrapper, which in cbreak
mode waits for more bytes than one keypress provides: the program drew its
first frame and then hung, while tests against a stand-in stream object
passed.  It reads the file descriptor now, and the tests drive a pty.  And
stopping playback signalled only the direct child, so a player that is a
wrapper script kept the sound going with nothing on screen to stop it; the
whole process group is signalled instead, which is what start_new_session
was there for.

man saunterbrowse ships beside man bandsaunter, and the two point at each
other.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg
This commit is contained in:
The Dust Council 2026-08-22 15:06:33 -07:00
parent 4a272eb1d5
commit cc317914e1
11 changed files with 2233 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

6
packaging/bandsaunter.1
View file

@ -1,5 +1,5 @@
.\" Generated by packaging/make-man.py -- do not edit by hand.
.TH BANDSAUNTER 1 "2026-08-22" "bandsaunter 2026-08-22_02" "User Commands"
.TH BANDSAUNTER 1 "2026-08-22" "bandsaunter 2026-08-22_03" "User Commands"
.SH NAME
bandsaunter \- scan, record and identify radio signals with an RTL-SDR
.SH SYNOPSIS
@ -961,6 +961,10 @@ Raise the squelch threshold and save it as the new default.
0 on success, 1 for a bad option or an unusable configuration, 2 when the
receiver could not be opened.
.SH SEE ALSO
.BR saunterbrowse (1)
\[em] browse and play back what a scan collected: the recordings list, their
transcripts and their identifications, on one screen.
.PP
.BR rtl_test (1),
.BR rtl_sdr (1),
.BR espeak-ng (1)

11
packaging/build-deb.sh
View file

@ -27,7 +27,10 @@ gzip -9n "$pkgdir/usr/share/doc/bandsaunter/README.md"
mkdir -p "$pkgdir/usr/share/man/man1"
python3 "$here/packaging/make-man.py" "$pkgdir/usr/share/man/man1/bandsaunter.1" \
>/dev/null
python3 "$here/packaging/make-browse-man.py" \
"$pkgdir/usr/share/man/man1/saunterbrowse.1" >/dev/null
gzip -9n "$pkgdir/usr/share/man/man1/bandsaunter.1"
gzip -9n "$pkgdir/usr/share/man/man1/saunterbrowse.1"
cat > "$pkgdir/usr/bin/bandsaunter" <<'EOF'
#!/usr/bin/python3
@ -37,6 +40,14 @@ sys.exit(main())
EOF
chmod 755 "$pkgdir/usr/bin/bandsaunter"
cat > "$pkgdir/usr/bin/saunterbrowse" <<'EOF'
#!/usr/bin/python3
import sys
from bandsaunter.browse import main
sys.exit(main())
EOF
chmod 755 "$pkgdir/usr/bin/saunterbrowse"
# Every one of these is in Debian, so apt resolves the lot. No speech
# recogniser is packaged for Debian, so that part ships as its own package
# (built by build-repo.sh) and is recommended rather than depended on: apt

219
packaging/make-browse-man.py Executable file
View file

@ -0,0 +1,219 @@
#!/usr/bin/env python3
"""Generate the saunterbrowse manual page.
Hand-written rather than generated from a table: unlike the scanner, the
browser's surface is a dozen keys and five flags, and describing those is
prose, not a listing. The version and date still come from the program, so
the page cannot claim to document a release that was never built.
"""
import sys
from datetime import date
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
import bandsaunter # noqa: E402
from bandsaunter.browse import PLAYERS, SORTS # noqa: E402
PAGE = r'''.\" Generated by packaging/make-browse-man.py -- do not edit by hand.
.TH SAUNTERBROWSE 1 "{date}" "bandsaunter {version}" "User Commands"
.SH NAME
saunterbrowse \- read and listen to what a bandsaunter scan collected
.SH SYNOPSIS
.B saunterbrowse
.RI [ DIRECTORY ]
.RB [ \-\-sort
.IR ORDER ]
.RB [ \-\-filter
.IR TEXT ]
.RB [ \-\-player
.IR CMD ]
.RB [ \-\-list ]
.SH DESCRIPTION
A scan leaves a directory of recordings. Beside each one is a JSON file
holding what the classifier made of it, and for speech a transcript of what
was said. Reading that by hand means opening files one at a time and guessing
which are worth playing.
.PP
.B saunterbrowse
shows them as a list you move through with the arrow keys. The transcript of
whichever recording is highlighted fills the top of the screen, because that
is the part you actually want to read; underneath it are the identification,
the bands the frequency falls in, and the list itself. Pressing Enter plays
the recording.
.PP
With no
.I DIRECTORY
it opens the one the scanner writes to, taken from your saved settings, so it
normally needs no arguments at all.
.PP
It only ever reads. Nothing in the recordings directory is renamed, moved or
deleted.
.SH KEYS
.TP
.B "Up Down k j"
Move through the recordings.
.TP
.B "PgUp PgDn"
A screenful at a time.
.TP
.B "Home End"
The first and the last.
.TP
.B Enter
Play the highlighted recording. Playing a second one stops the first: two
players talking over each other is worse than either alone.
.TP
.B Space
Stop playing. With nothing playing, it starts, like Enter.
.TP
.B t
Read the whole transcript full screen, scrolling with the arrow keys. Useful
for a long net, where the panel at the top can only show the first few lines
\[em] it says so when there is more.
.TP
.B /
Filter. What you type is matched against the frequency, the filename, the
identification and
.I everything that was said,
so "was the repeater mentioned" is a question you can ask directly. Enter
accepts, Escape clears.
.TP
.B s
Cycle the order: {sorts}.
.TP
.B r
Re-read the directory. A scan running in another window is still writing to
it, and this picks up what has arrived since.
.TP
.B o
Print the highlighted recording's path and quit, for piping into something
else.
.TP
.B "? h"
The list of keys, and which audio player was found.
.TP
.B q
Quit. With a filter in force, Escape clears the filter first.
.SH OPTIONS
.TP
.BI DIRECTORY
Where the recordings are. Defaults to the scanner's output directory, or to
.B $BANDSAUNTER_OUTPUT
when that is set.
.TP
.BI \-\-sort " ORDER"
Start in this order: {sorts}. Time is newest first; duration is longest
first.
.TP
.BI \-\-filter " TEXT"
Start with only the recordings matching this, exactly as if it had been typed
at the
.B /
prompt.
.TP
.BI \-\-player " CMD"
The command used to play a recording. The path is appended as its last
argument. By default the first of these that is installed is used:
{players}.
.TP
.B \-\-list
Print one line per recording and exit, without drawing anything. This is what
to use over a pipe, in a script, or anywhere there is no terminal.
.TP
.B \-V ", " \-\-version
Print the version and exit.
.SH SOUND
Playback is handed to whichever player is installed rather than done in the
program: the recordings are ordinary WAV files, every desktop already has
something that plays them, and a browser that cannot start is worse than one
that cannot play. If none is found, everything else still works and the
message says which packages would fix it.
.PP
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 TRANSCRIPTS
A transcript appears only where a recogniser produced one, which means the
capture was judged to be speech and
.B bandsaunter\-transcribe
was installed at the time. Where there is none, the panel says which of the
several reasons applies \[em] Morse, data, a bare carrier, or speech that was
never offered to a recogniser \[em] because those want different things done
about them.
.PP
Two places can hold the text: the JSON sidecar records what was recognised
during the scan, and the
.I _transcription.txt
beside the recording is what a later re\-run wrote. The file wins, being the
more recent of the two.
.SH FILES
.TP
.I ~/bandsaunter/
Where recordings are written, unless the saved settings say otherwise.
.TP
.IR frequency \-\- date _ time \- modulation .wav
A recording.
.TP
.IR ... .json
Its measurements and identification.
.TP
.IR ... _transcription.txt
What was said, where a recogniser heard speech.
.SH ENVIRONMENT
.TP
.B BANDSAUNTER_OUTPUT
The directory to open, overriding the saved settings.
.SH EXAMPLES
.PP
.RS
.EX
saunterbrowse
.EE
.RE
.PP
Open the scanner's output directory.
.PP
.RS
.EX
saunterbrowse /mnt/recordings \-\-sort frequency
.EE
.RE
.PP
Browse somewhere else, grouped by channel rather than by time.
.PP
.RS
.EX
saunterbrowse \-\-list | grep \-i "mile marker"
.EE
.RE
.PP
Search the transcripts from a script.
.SH EXIT STATUS
0 on a clean exit, 1 when the directory holds no recordings, 2 when it does
not exist or there is no terminal to draw on.
.SH SEE ALSO
.BR bandsaunter (1)
.SH BUGS
The list is read when the browser opens. Press
.B r
to pick up recordings a running scan has written since.
'''
def main() -> int:
text = PAGE.format(
date=date.today().isoformat(),
version=bandsaunter.__version__,
sorts=", ".join(SORTS),
players=", ".join(name for name, _ in PLAYERS))
text = text.replace("\n\n", "\n") # troff dislikes blank lines
target = Path(sys.argv[1] if len(sys.argv) > 1
else Path(__file__).parent / "saunterbrowse.1")
target.write_text(text)
print(target)
return 0
if __name__ == "__main__":
raise SystemExit(main())

4
packaging/make-man.py
View file

@ -412,6 +412,10 @@ Raise the squelch threshold and save it as the new default.
0 on success, 1 for a bad option or an unusable configuration, 2 when the
receiver could not be opened.
.SH SEE ALSO
.BR saunterbrowse (1)
\[em] browse and play back what a scan collected: the recordings list, their
transcripts and their identifications, on one screen.
.PP
.BR rtl_test (1),
.BR rtl_sdr (1),
.BR espeak-ng (1)

182
packaging/saunterbrowse.1 Normal file
View file

@ -0,0 +1,182 @@
.\" Generated by packaging/make-browse-man.py -- do not edit by hand.
.TH SAUNTERBROWSE 1 "2026-08-22" "bandsaunter 2026-08-22_03" "User Commands"
.SH NAME
saunterbrowse \- read and listen to what a bandsaunter scan collected
.SH SYNOPSIS
.B saunterbrowse
.RI [ DIRECTORY ]
.RB [ \-\-sort
.IR ORDER ]
.RB [ \-\-filter
.IR TEXT ]
.RB [ \-\-player
.IR CMD ]
.RB [ \-\-list ]
.SH DESCRIPTION
A scan leaves a directory of recordings. Beside each one is a JSON file
holding what the classifier made of it, and for speech a transcript of what
was said. Reading that by hand means opening files one at a time and guessing
which are worth playing.
.PP
.B saunterbrowse
shows them as a list you move through with the arrow keys. The transcript of
whichever recording is highlighted fills the top of the screen, because that
is the part you actually want to read; underneath it are the identification,
the bands the frequency falls in, and the list itself. Pressing Enter plays
the recording.
.PP
With no
.I DIRECTORY
it opens the one the scanner writes to, taken from your saved settings, so it
normally needs no arguments at all.
.PP
It only ever reads. Nothing in the recordings directory is renamed, moved or
deleted.
.SH KEYS
.TP
.B "Up Down k j"
Move through the recordings.
.TP
.B "PgUp PgDn"
A screenful at a time.
.TP
.B "Home End"
The first and the last.
.TP
.B Enter
Play the highlighted recording. Playing a second one stops the first: two
players talking over each other is worse than either alone.
.TP
.B Space
Stop playing. With nothing playing, it starts, like Enter.
.TP
.B t
Read the whole transcript full screen, scrolling with the arrow keys. Useful
for a long net, where the panel at the top can only show the first few lines
\[em] it says so when there is more.
.TP
.B /
Filter. What you type is matched against the frequency, the filename, the
identification and
.I everything that was said,
so "was the repeater mentioned" is a question you can ask directly. Enter
accepts, Escape clears.
.TP
.B s
Cycle the order: time, frequency, duration.
.TP
.B r
Re-read the directory. A scan running in another window is still writing to
it, and this picks up what has arrived since.
.TP
.B o
Print the highlighted recording's path and quit, for piping into something
else.
.TP
.B "? h"
The list of keys, and which audio player was found.
.TP
.B q
Quit. With a filter in force, Escape clears the filter first.
.SH OPTIONS
.TP
.BI DIRECTORY
Where the recordings are. Defaults to the scanner's output directory, or to
.B $BANDSAUNTER_OUTPUT
when that is set.
.TP
.BI \-\-sort " ORDER"
Start in this order: time, frequency, duration. Time is newest first; duration is longest
first.
.TP
.BI \-\-filter " TEXT"
Start with only the recordings matching this, exactly as if it had been typed
at the
.B /
prompt.
.TP
.BI \-\-player " CMD"
The command used to play a recording. The path is appended as its last
argument. By default the first of these that is installed is used:
pw-play, paplay, aplay, play, ffplay, mpv.
.TP
.B \-\-list
Print one line per recording and exit, without drawing anything. This is what
to use over a pipe, in a script, or anywhere there is no terminal.
.TP
.B \-V ", " \-\-version
Print the version and exit.
.SH SOUND
Playback is handed to whichever player is installed rather than done in the
program: the recordings are ordinary WAV files, every desktop already has
something that plays them, and a browser that cannot start is worse than one
that cannot play. If none is found, everything else still works and the
message says which packages would fix it.
.PP
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 TRANSCRIPTS
A transcript appears only where a recogniser produced one, which means the
capture was judged to be speech and
.B bandsaunter\-transcribe
was installed at the time. Where there is none, the panel says which of the
several reasons applies \[em] Morse, data, a bare carrier, or speech that was
never offered to a recogniser \[em] because those want different things done
about them.
.PP
Two places can hold the text: the JSON sidecar records what was recognised
during the scan, and the
.I _transcription.txt
beside the recording is what a later re\-run wrote. The file wins, being the
more recent of the two.
.SH FILES
.TP
.I ~/bandsaunter/
Where recordings are written, unless the saved settings say otherwise.
.TP
.IR frequency \-\- date _ time \- modulation .wav
A recording.
.TP
.IR ... .json
Its measurements and identification.
.TP
.IR ... _transcription.txt
What was said, where a recogniser heard speech.
.SH ENVIRONMENT
.TP
.B BANDSAUNTER_OUTPUT
The directory to open, overriding the saved settings.
.SH EXAMPLES
.PP
.RS
.EX
saunterbrowse
.EE
.RE
.PP
Open the scanner's output directory.
.PP
.RS
.EX
saunterbrowse /mnt/recordings \-\-sort frequency
.EE
.RE
.PP
Browse somewhere else, grouped by channel rather than by time.
.PP
.RS
.EX
saunterbrowse \-\-list | grep \-i "mile marker"
.EE
.RE
.PP
Search the transcripts from a script.
.SH EXIT STATUS
0 on a clean exit, 1 when the directory holds no recordings, 2 when it does
not exist or there is no terminal to draw on.
.SH SEE ALSO
.BR bandsaunter (1)
.SH BUGS
The list is read when the browser opens. Press
.B r
to pick up recordings a running scan has written since.