68b05a031c
Much of what a scanner finds is not speech. Doorbells, tyre-pressure sensors, weather stations, remote controls, paging and packet radio all carry something a receiver can read, and until now the answer was "OOK / ASK data burst" and a WAV file. Now the bits come out. The observation the whole thing is built on is that whatever the modulation, a data signal is the same shape once it has been sliced: a train of alternating runs whose lengths carry the information. On-off keying gives that directly -- the carrier is up or it is down -- and two-level FSK gives exactly the same thing from the discriminator, one tone or the other. So both reduce to a run-length train and everything after that is shared. What the runs mean is the line code, and it is worked out from the runs alone rather than configured, because each code makes a different prediction about which of the two histograms is the bimodal one: PWM (EV1527, PT2262, and nearly every 433 MHz remote), PPM, Manchester, and plain NRZ. Four-level FSK is recognised as such and read as symbols rather than sliced down the middle, which produces bits that mean nothing; where a frame sync word appears the system is named outright. Two protocols carry their own framing and checksums and so are read in full. POCSAG paging: all three rates tried because nothing in the signal says which it is, every codeword checked and single-bit errors corrected against the BCH code, and the address, function letter and message text reported. AX.25 as APRS uses it: the frame check has to come out right before a frame is reported at all, and the sender's callsign goes onto the map with everyone else's. The hard half is refusing what is not data. Noise sliced at a threshold produces runs and runs produce bits, so three things guard against it: the runs have to quantise to the line code's own grid; most of the bursts in a capture have to decode the same way, because one lucky window in eight is a coincidence and that is exactly what SSB voice produced; and, much the strongest, the packet has to repeat, because bits that come back identical six times did not come from noise. A reading with none of that behind it is reported as nothing at all rather than as a bit string with a low number beside it that somebody will read anyway. Across 27 recordings of speech, music, static, a bare carrier, Morse and PSK it returns nothing 27 times. A firm decode also outranks the content check, which is statistical: a burst of keying demodulated as FM audio is a buzz and the speech detector likes a buzz, but a frame whose own checksum came out right is not a statistic. Such a capture is kept and filed as data, not as voice. What comes out is written to a _data.txt beside the recording, shown on the live display and in the line-per-hit output, and takes the place of the transcript at the top of saunterbrowse -- where it is searchable, so "which page mentioned engine 4" is a question that can be asked. `bandsaunter analyze` decodes a file you already have. The simulator gained two honest transmitters to test against: a pulse-width remote that repeats a real payload, and a pager that sends real POCSAG batches with real BCH check bits. Random keying exercises the classifier but leaves a decoder nothing to get right. The POCSAG encoder lives next to the decoder rather than in the test helpers, so a bug shared by both cannot hide. Fixed along the way: - Rich reads a square bracket as markup, and a decoded page is arbitrary text off the air. "[/x]" in a message ended the live display with a MarkupError; so did typing "[/" at saunterbrowse's search prompt. Everything that did not come from this program is escaped now. - Otsu returned the first bin of a plateau. Two populations with nothing between them -- silence and full carrier, which is what on-off keying is -- make every threshold in the gap equally good, and taking the first put it hard against the lower population with the hysteresis band outside the data entirely, so nothing sliced at all. - Estimating the symbol clock by counting along a cumulative grid is a fixed point: a unit two per cent small produces two per cent more symbols and reproduces itself exactly. Rounding each run on its own converges instead, because every run votes independently. The grid is then the right way to extract the bits, where rounding runs one at a time drifts. - A clipped first repeat used to truncate every other repeat to its length. The consensus is taken over the commonest length now. 761 -> 869 tests.
308 lines
10 KiB
Groff
308 lines
10 KiB
Groff
.\" Generated by packaging/make-browse-man.py -- do not edit by hand.
|
|
.TH SAUNTERBROWSE 1 "2026-08-28" "bandsaunter 2026-08-28_02" "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 ]
|
|
.RB [ \-\-callsigns ]
|
|
.RB [ \-\-kml
|
|
.RI [ FILE ]]
|
|
.RB [ \-\-no\-lookup ]
|
|
.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 \-\-callsigns
|
|
Print every callsign heard in the directory, with the licence it belongs to
|
|
and where and when it was heard, then exit.
|
|
.TP
|
|
.BI \-\-kml " [FILE]"
|
|
Write a map of where the stations heard in this directory are licensed, and
|
|
exit. Without a filename it writes
|
|
.I callsigns.kml
|
|
in the recordings directory \[em] the same file a scan writes, so a map built
|
|
this way is continued by the next scan rather than duplicated. See
|
|
.B THE MAP
|
|
below.
|
|
.TP
|
|
.B \-\-no\-lookup
|
|
Do not contact the licence database. Callsigns are still found and still
|
|
described from their prefix; only the name and address are missing.
|
|
.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 DETECTED CALLSIGNS
|
|
Under the transcript, headed
|
|
.BR "DETECTED CALLSIGNS:" ,
|
|
is every callsign heard in it, with the name and location on the licence.
|
|
.PP
|
|
Finding them is not a matter of one regular expression over the text as
|
|
written. A speech recogniser is poor at callsigns \[em] they are not words,
|
|
they are said one character at a time \[em] so it breaks them wherever the
|
|
speaker paused and writes the phonetic alphabet down verbatim. "KU 0W",
|
|
"K7 RA" and "kilo uniform zero whiskey" are all one callsign each, and all
|
|
three are read back correctly.
|
|
.PP
|
|
False positives are the thing to avoid: a browser that invents callsigns is
|
|
worse than one that finds none. So a run of words is only accepted when none
|
|
of its parts is an ordinary English word \[em] "or 3. Can you open 4" fits the
|
|
shape once the punctuation is gone, and is not a callsign \[em] while a single
|
|
token said in one breath is trusted, because W1BOY is a perfectly good
|
|
callsign.
|
|
.PP
|
|
The lookup uses the FCC's own licence data, published at callook.info, which
|
|
needs no account and no key. The callsign is the only thing sent, results are
|
|
cached under
|
|
.I ~/.cache/bandsaunter/
|
|
so the same net is looked up once however many nights it is recorded, and a
|
|
lookup never delays the display: the entry says "looking up" and fills itself
|
|
in.
|
|
.PP
|
|
.B \-\-no\-lookup
|
|
contacts nothing at all. Callsigns are still found, and still described from
|
|
their own structure \[em] the prefix is allocated by the ITU and the digit is
|
|
the US licensing district, so a callsign says which country and which region
|
|
it belongs to without any database. Outside the United States that is all
|
|
there is; callook.info holds US licences only.
|
|
.PP
|
|
.B \-\-callsigns
|
|
prints every callsign in the directory, who it belongs to, and each frequency
|
|
and time it was heard on, then exits.
|
|
.PP
|
|
US amateur licence records are public by law, and include the licensee's
|
|
address. That is what is shown.
|
|
.SH THE MAP
|
|
A licence says where its holder is, so a list of callsigns is also a map. The
|
|
scanner writes one as it runs and
|
|
.B \-\-kml
|
|
builds one from recordings already on disk; both write the same file, so
|
|
either can carry on from the other.
|
|
.PP
|
|
Each station is one placemark, not one per transmission: hearing the same
|
|
repeater twenty times in an evening is one station, and twenty pins stacked
|
|
on the same rooftop would say less than one. The pin holds the callsign, the
|
|
licensee, the town, the grid square, and every frequency and time it was
|
|
heard on, so clicking it answers "when did I hear this, and where on the
|
|
dial".
|
|
.PP
|
|
The file is added to rather than replaced. A scan on Tuesday continues the
|
|
map Monday made, which over a few weeks turns into a picture of what your
|
|
aerial can actually reach.
|
|
.PP
|
|
Where the licence carries no coordinates the grid square is used instead, and
|
|
the placemark says so, because a grid square is kilometres across where a
|
|
licensed address is a street. A callsign with no licence on file at all is
|
|
still recorded, in a folder named
|
|
.IR "no location on file" ,
|
|
switched off by default: that a station was heard is worth keeping even when
|
|
nothing says where it was.
|
|
.PP
|
|
KML is the format Google Earth uses.
|
|
.BR qgis (1),
|
|
.BR marble (1)
|
|
and OsmAnd open it too, and it is XML, so a scan interrupted halfway through
|
|
leaves a file that still opens.
|
|
.SH DECODED DATA
|
|
Where a capture carried data rather than speech, what was decoded takes the
|
|
place of the transcript at the top of the screen: the kind of packet, and then
|
|
the message. A pager's text, an APRS position report, or the bits and hex of a
|
|
remote control. It is searchable with
|
|
.B /
|
|
like anything else, so "which page mentioned engine 4" is a question that can
|
|
be asked here.
|
|
.PP
|
|
The text comes from the
|
|
.I _data.txt
|
|
beside the recording, or from the sidecar where there is none.
|
|
.BR bandsaunter (1)
|
|
describes how it is decoded and what has to be true before a decode is
|
|
believed.
|
|
.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.
|
|
.TP
|
|
.IR ... _data.txt
|
|
What was decoded, where the capture carried data.
|
|
.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.
|
|
.PP
|
|
.RS
|
|
.EX
|
|
saunterbrowse \-\-callsigns
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Everyone who identified themselves, and where they were heard.
|
|
.PP
|
|
.RS
|
|
.EX
|
|
saunterbrowse \-\-kml ~/heard.kml
|
|
.EE
|
|
.RE
|
|
.PP
|
|
The same thing as a map, to open in Google Earth.
|
|
.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.
|