diff --git a/README.md b/README.md index de8a072..10f6ba6 100644 --- a/README.md +++ b/README.md @@ -296,6 +296,16 @@ bandsaunter scan -p local bandsaunter profiles ``` +Everything that can be given as a flag can be saved, and everything that can be +saved can be given as a flag — both front ends are generated from one table, so +they cannot drift apart. A profile written by an older version still loads: keys +it does not have take their defaults, and keys that no longer exist are reported +and ignored. + +Every setting is explained in plain language — what it is, and when you would +change it — in three places: `bandsaunter config --describe `, `?N` in the +settings menu, and `man bandsaunter`. + ## Entering frequencies **By hand** — repeat `-r` as many times as you like; there is no limit on the @@ -826,6 +836,11 @@ since that is the command to run when something is wrong, and | `l` | lock out this frequency — for this run and every later one | | `+` / `-` | adjust the squelch threshold | +There is no live display over ssh, in a log file, or piped to another program: +`--plain` prints one line per recording instead, and is chosen automatically +whenever output is not a terminal. It is a saved setting like any other, so a +headless machine can be told once and never asked again. + ### Lock-outs A pager transmitter down the road, or a birdie the receiver makes itself, is @@ -858,6 +873,23 @@ there explains that setting instead. From the command line, `bandsaunter config --describe ` does the same, and `bandsaunter scan --help` lists every flag grouped the same way as the menus. +### The manual page + +`man bandsaunter` documents every command, option and setting, each with a +plain-language note on what it is and why you would turn it up, down, on or +off — written for someone who does not already speak radio. + +It is generated from the same settings table the menus and the flags come from, +so it cannot describe a setting the program does not have, or miss one it does: + +```bash +./packaging/make-man.py # regenerate packaging/bandsaunter.1 +man -l packaging/bandsaunter.1 # read it without installing +``` + +The `.deb` installs it; installing from source does not, so read it from the +source tree with `man -l`. + ## HF Frequencies below 24 MHz need direct sampling, which most RTL-SDR dongles @@ -911,7 +943,19 @@ audio, IQ and metadata are correct. The simulator's voice transmitters carry synthesised speech -- glottal pulses through moving formants, compressed the way a real transmitter compresses, then gated into syllables and phrases -- because sine tones would not exercise -the speech detector at all. +the speech detector at all. SSB transmitters are filtered to their audio +passband first, since that filter is what makes a signal single-sideband, and +without it the simulated signal was several times wider than anything on the +air. + +Its transmitters seed themselves deterministically, so a test that fails can be +made to fail again -- the one thing needed to fix it. + +Settings have their own tests: every one is set to something other than its +default, saved, loaded back and compared, so nothing can quietly fail to +persist. Every setting must also be reachable from both the command line and +the menus, be read somewhere in the program, display a value that can be typed +straight back in, and appear in the manual page. ## Legal note diff --git a/bandsaunter/__init__.py b/bandsaunter/__init__.py index ccc5726..67a1e12 100755 --- a/bandsaunter/__init__.py +++ b/bandsaunter/__init__.py @@ -8,7 +8,7 @@ and transcribing speech. # Versions are the release date and a revision within that day, so # 2026-08-21_02 is the second build made on the 21st. The revision is padded # to two digits so versions sort as text. -VERSION_DATE = "2026-08-21" +VERSION_DATE = "2026-08-22" VERSION_REVISION = 1 __version__ = f"{VERSION_DATE}_{VERSION_REVISION:02d}" diff --git a/bandsaunter/settings.py b/bandsaunter/settings.py index fe3cbf2..cebecba 100644 --- a/bandsaunter/settings.py +++ b/bandsaunter/settings.py @@ -7,7 +7,7 @@ one and be missing from the other, and the help text is written once. from __future__ import annotations import re -from dataclasses import dataclass, fields +from dataclasses import dataclass, fields, replace from .bandplan import fmt_hz from .quality import CATEGORIES as CONTENT_CATEGORIES @@ -37,6 +37,7 @@ class Setting: off_flags: tuple[str, ...] = () # bool flags that turn it off metavar: str = "" example: str = "" + guidance: str = "" # plain words: what it is, when to change it @property def dest(self) -> str: @@ -59,7 +60,7 @@ S = Setting # The table. Order within a group is the order the TUI shows them. # --------------------------------------------------------------------------- -SETTINGS: tuple[Setting, ...] = ( +_TABLE: tuple[Setting, ...] = ( # -- dwell ------------------------------------------------------------- S("record_seconds", "Record for", "Dwell and recording", "float", @@ -411,6 +412,322 @@ SETTINGS: tuple[Setting, ...] = ( flags=("--plain",), off_flags=("--no-plain",)), ) +# --------------------------------------------------------------------------- +# Plain-language guidance: what a setting is in everyday terms, and why +# someone who does not speak radio might turn it up, down, on or off. Kept +# apart from the table above so that table stays readable. Shown by the +# built-in help, and by the manual page, which is generated from here. +# --------------------------------------------------------------------------- + +_GUIDANCE: dict[str, str] = { + "record_seconds": + "How long one signal may keep the receiver before the sweep moves " + "on. Set it to 0 and a transmission is followed until it actually " + "ends, which is what you want for listening to conversations. Give " + "it a number if you would rather sample a busy band widely than sit " + "on the first station that comes up.", + "hang_seconds": + "How much silence means 'they have finished talking'. People pause " + "between sentences, and two people taking turns leave a gap every " + "time the conversation changes hands; anything shorter than this is " + "recorded straight through, so an exchange stays in one file. Raise " + "it if conversations keep getting split into pieces, lower it if " + "the scanner sits on dead air.", + "max_record_seconds": + "A safety stop. With no record limit set, a stuck transmitter or a " + "continuously modulated data channel would record until the disk " + "filled, and this is where that stops. Only worth changing if you " + "are deliberately capturing something very long; 0 removes the stop " + "entirely.", + "min_record_seconds": + "Recordings shorter than this are deleted instead of kept. A click " + "of static or a passing car's ignition noise can hold the squelch " + "open for a fraction of a second, and this is what keeps those out " + "of the directory. Raise it if you are collecting lots of tiny " + "useless files; lower it if you are chasing very short " + "transmissions such as data bursts or single-word replies.", + "revisit_seconds": + "After recording a frequency, ignore it for this long. One busy " + "repeater can otherwise take over the whole scan, recorded again " + "and again while everything else goes unheard. Lower it if you want " + "everything from one channel; raise it if one talkative frequency " + "is drowning out the rest of the band.", + "threshold_db": + "How much louder than the background hiss something must be before " + "the scanner stops on it. This is the squelch knob. Too low and it " + "stops on noise; too high and it walks past quiet stations. If you " + "are getting nothing at all, try lowering it a few dB; if you are " + "recording static, raise it.", + "dwell_seconds": + "How long the receiver listens at each tuning position while " + "sweeping. A short dwell sweeps faster but can miss a transmission " + "that starts and ends between visits; a long one hears more of what " + "is there but goes round the band slowly. The default is a good " + "compromise for voice traffic.", + "resolution_hz": + "How finely the sweep divides the spectrum when looking for " + "signals. Finer resolution separates two stations sitting close " + "together and finds weak narrow ones, but takes longer to compute. " + "Worth making finer if you are scanning a crowded band of narrow " + "channels.", + "detector": + "How the sweep decides how strong each part of the band was. " + "Peak-hold remembers the loudest instant, so it catches a " + "transmission that starts and stops during the dwell, which is what " + "you want for scanning. Averaging is quieter and steadier, and is " + "better when you want a clean picture of the band rather than to " + "catch every burst.", + "detector_bias_db": + "A correction for the fact that peak-hold makes plain noise look " + "stronger than it is, which would otherwise trigger the squelch on " + "nothing. It is worked out automatically from the detector and the " + "sweep settings, and there is normally no reason to set it by hand.", + "squelch_margin_db": + "Once a signal has been found, it may drop this far below the " + "squelch threshold before being counted as gone. Without it a " + "station sitting exactly at the threshold would flicker on and off, " + "chopping the recording into fragments. Raise it if recordings of " + "weak stations keep breaking up.", + "adaptive_floor": + "Learns what the background noise looks like across several sweeps " + "rather than judging from one. It makes the squelch steadier, " + "especially where the noise level varies across the band. Turn it " + "off only if you are watching a band where the noise itself changes " + "fast and you want the scanner to react immediately.", + "max_detections_per_step": + "The sweep can see several stations at once in the chunk of " + "spectrum it is looking at, and this is how many of them it will " + "queue up. Raise it in a crowded band where you are missing " + "simultaneous transmissions; lower it if you would rather the " + "scanner keep moving.", + "probe_seconds": + "Before recording, the scanner listens briefly to work out what " + "kind of signal it is, so it can pick the right way to decode it. " + "Longer is a more reliable guess but delays every recording " + "slightly. The listen is not wasted: it is kept and played into the " + "start of the recording.", + "require_signal": + "Judge each capture and throw away anything that turns out to be " + "noise, static or interference rather than a real transmission. " + "This is the single setting that decides whether the recordings " + "directory is full of things worth listening to or full of hiss. " + "Turn it off only if you want everything that breaks squelch, " + "however empty.", + "accept": + "Which kinds of transmission are worth keeping: speech, Morse, " + "data, plain unmodulated carriers, and noise. Most people want " + "voice, cw and digital. Add carrier if you are hunting beacons or " + "interference sources, and noise only for diagnosing why nothing is " + "being recorded.", + "min_signal_score": + "How certain the content check must be before a recording is kept, " + "from 0 to 1. Lower it if real transmissions are being discarded, " + "since weak or noisy signals score lower. Raise it if borderline " + "rubbish is still getting through.", + "min_voice_score": + "How speech-like audio has to sound before it is called voice. " + "Speech has a pitch that moves and a rhythm of syllables; a steady " + "tone or a hum does not. Lower it if quiet or distorted speech is " + "being missed, raise it if music, hum or engine noise is being " + "recorded as if it were someone talking.", + "verify_seconds": + "How often a recording in progress is re-examined to see whether it " + "is still carrying anything. Checking often releases the receiver " + "quickly when a channel turns out to be holding static; checking " + "rarely costs less processing.", + "verify_max_seconds": + "How long a recording gets to prove it contains something. If " + "nothing recognisable has appeared by then it is abandoned and " + "deleted, and the sweep moves on rather than sitting on an open but " + "empty channel.", + "device_index": + "Which receiver to use when more than one is plugged in. Run " + "'bandsaunter devices' to see the list and their numbers. With a " + "single dongle this can be ignored.", + "sample_rate": + "How much spectrum the receiver takes in at once, which sets how " + "much ground each step of the sweep covers. Higher covers the band " + "in fewer steps but makes the computer work harder, and cheap " + "dongles start dropping samples. 2.048 MS/s suits most machines; " + "drop it if recordings sound wrong or the program warns about " + "dropped samples.", + "gain": + "How much the receiver amplifies. Automatic gain sounds convenient " + "but tends to wind itself up during quiet moments and amplify noise " + "until it breaks squelch. A fixed value is usually better for " + "scanning: start around 30 and lower it if strong stations sound " + "distorted, raise it if everything is too weak to hear.", + "ppm": + "Cheap receivers are tuned by a crystal that is never exactly " + "right, so every frequency reads slightly off, possibly by a few " + "kilohertz at UHF. If stations consistently appear a little above " + "or below where they should be, this corrects it. Leave at 0 unless " + "you have measured the error.", + "agc": + "A second, separate automatic gain control inside the receiver " + "chip, on top of the tuner gain. It is usually best left off, since " + "two automatic gain controls fighting each other makes the squelch " + "behave unpredictably.", + "bias_tee": + "Sends power up the antenna cable, which is how mast-mounted " + "amplifiers and some active antennas are fed. Leave it off unless " + "you have such a device: switching it on with ordinary equipment " + "attached can damage it.", + "offset_tuning": + "A trick for one older tuner chip, the E4000, that moves an " + "artefact away from the middle of the picture. Modern dongles, " + "including every R820T, ignore it. Leave it off unless you know you " + "have that tuner.", + "direct_sampling": + "How the receiver hears shortwave. These dongles cannot normally " + "tune below about 24 MHz, but they can be persuaded to sample the " + "antenna directly, which opens up everything beneath it: shortwave " + "broadcast, amateur HF, marine. Automatic switches it on when you " + "scan below 24 MHz and off again above. The Q branch is what almost " + "all hardware uses.", + "usable_fraction": + "The edges of what the receiver takes in are distorted by its own " + "filtering, so only the middle portion is trusted. Lowering this " + "uses less of each step and sweeps more slowly but avoids the poor " + "edges; raising it covers ground faster at the cost of missing or " + "mismeasuring signals near the edges.", + "dc_guard_hz": + "Every receiver of this type produces a spurious spike at the exact " + "centre of where it is tuned, which would otherwise look like a " + "station. The receiver is therefore deliberately parked slightly to " + "one side. There is rarely a reason to change this.", + "output_dir": + "Where recordings, transcripts and logs are written. Everything the " + "program produces goes here, so put it somewhere with room: audio " + "adds up quickly, and raw IQ adds up very quickly.", + "save_audio": + "Write the listenable audio file for each transmission. This is " + "almost certainly what you want; turning it off leaves only the log " + "and whatever other outputs are enabled, which is useful when you " + "only care about what was active and when.", + "save_iq": + "Also keep the raw radio samples, exactly as they came off the " + "receiver, alongside the audio. These can be re-analysed or decoded " + "later with other software, but they are enormous, many megabytes " + "per second, so leave this off unless you have a specific use for " + "them.", + "iq_format": + "The number format for those raw files. cf32 is the easiest for " + "other programs to read; cs16 is half the size for the same " + "samples. Only matters if raw IQ is being saved.", + "audio_rate": + "The sample rate of the saved audio. Higher preserves more of the " + "original sound at the cost of file size; the default is well " + "matched to what a radio channel can actually carry, and to what " + "speech recognisers expect.", + "classify": + "Work out what each recording actually is, whether FM voice, AM, " + "single sideband, Morse, a paging system or a digital voice mode, " + "and write it into the log and the filename. Turning it off saves a " + "little processing and leaves you to identify things by ear.", + "decode_morse": + "Turn keyed carriers into readable text, with the sending speed. " + "Morse is still in daily use by amateurs and by beacons, and this " + "saves you learning to read it by ear. It costs almost nothing when " + "there is no Morse about.", + "log_file": + "The name of the run log inside the output directory. It records " + "every recording with its time, frequency, duration and " + "identification, as JSON lines with a spreadsheet-friendly .csv " + "alongside.", + "combine_by_frequency": + "Instead of one file per transmission, keep one growing file per " + "frequency, with each new transmission appended to it. This turns a " + "scanner run into something you can play like a recording of that " + "channel, rather than hundreds of fragments to click through.", + "announce_timestamps": + "Speaks the date and time before each transmission in a combined " + "file, so you can hear when something happened without watching a " + "clock or reading filenames. It works with no extra software " + "installed; installing espeak-ng makes the voice clearer.", + "announce_frequency": + "Also read out the frequency with the time. Useful when several " + "nearby frequencies end up in the same combined file, or when you " + "want a spoken record of what you were listening to.", + "announce_engine": + "Which voice does the speaking. Automatic uses the best available: " + "espeak-ng if it is installed, otherwise a small built-in " + "synthesiser that needs nothing at all. Set it to builtin to force " + "the internal voice, or name another program.", + "combine_tolerance_hz": + "How far apart two receptions may be and still be treated as the " + "same frequency for combining. Transmitters drift and the " + "measurement is never exact, so a little tolerance keeps one " + "repeater in one file. Widen it if a single channel is being split " + "across several files.", + "combine_keep_individual": + "Keep the per-transmission files as well as the combined one. It " + "costs twice the disk space, but means you can still pick out a " + "single transmission without seeking through a long file.", + "transcribe": + "Write out what was said in each voice transmission as a text file " + "beside the recording, so a scan can be read rather than listened " + "to, and searched with ordinary text tools. It needs a speech " + "recogniser installed; the program says so plainly if none is " + "present.", + "transcribe_engine": + "Which speech recogniser to use when more than one is installed. " + "Automatic picks the best available. Radio audio is hard for these " + "programs, and the whisper-based ones are noticeably better at it " + "than the smaller alternatives.", + "transcribe_model": + "How large a recognition model to load. Bigger models are more " + "accurate and slower, and take more memory: tiny.en and base.en " + "keep up comfortably on an ordinary machine, small.en and medium.en " + "are better but heavier.", + "transcribe_language": + "The language to expect. Setting it is worth the trouble: on a " + "short, noisy clip automatic detection often guesses wrong and " + "returns confident nonsense in a language nobody was speaking. " + "Leave it blank only if you genuinely do not know.", + "transcribe_min_seconds": + "Do not bother transcribing captures shorter than this. Very short " + "clips rarely contain a whole word and mostly produce noise or " + "nothing, while still costing the processing.", + "max_cycles": + "Stop after this many complete passes through all the frequencies. " + "Useful for a quick survey of what is active, or for a scripted run " + "that must finish. 0 means keep going until you stop it.", + "max_runtime_seconds": + "Stop after this long, whatever the scan is doing. Handy for an " + "unattended run, or for keeping a test short. 0 means no limit.", + "lockout": + "Frequencies the scan must never stop on. Every receiving setup has " + "a few: a pager transmitter down the road, a nearby data link, or a " + "spurious signal the receiver manufactures itself. Give several " + "separated by commas, and a whole stretch of spectrum as a pair, " + "such as 162.55M, 450M-455M.", + "lockout_width": + "How wide a single locked-out frequency is. A transmitter is never " + "exactly on its nominal frequency, so the block covers a little " + "either side. A lock-out written as a span ignores this and uses " + "exactly the width you gave.", + "quiet": + "Print only errors. For running from a script or a scheduled job " + "where the usual progress reporting would just fill a log file.", + "save_lockouts": + "When you lock a frequency out during a scan, remember it for later " + "runs instead of only the current one. Only the lock-out list is " + "written back, so options you passed for one run stay one-off. Turn " + "it off if you would rather the program never modified your " + "settings file.", + "plain": + "Print one line per recording instead of the live updating display. " + "The live display needs a real terminal; plain output is what you " + "want over a remote connection, when saving output to a file, or " + "when feeding another program. It is chosen automatically when " + "output is not going to a terminal.", +} + +SETTINGS: tuple[Setting, ...] = tuple( + replace(s, guidance=" ".join(_GUIDANCE.get(s.key, "").split())) + for s in _TABLE) + GROUPS: tuple[str, ...] = tuple(dict.fromkeys(s.group for s in SETTINGS)) _BY_KEY = {s.key: s for s in SETTINGS} diff --git a/bandsaunter/tui.py b/bandsaunter/tui.py index 9f69019..26e132b 100644 --- a/bandsaunter/tui.py +++ b/bandsaunter/tui.py @@ -283,6 +283,8 @@ def setting_help(console: Console, setting: st.Setting, "", setting.help.capitalize() + "."] if setting.detail: body += ["", setting.detail] + if setting.guidance and setting.guidance != setting.detail: + body += ["", f"[grey62]{setting.guidance}[/grey62]"] body.append("") body.append(f"[grey62]now:[/grey62] " f"{st.format_value(setting, getattr(cfg, setting.key))}" diff --git a/packaging/bandsaunter.1 b/packaging/bandsaunter.1 new file mode 100644 index 0000000..c1bbadf --- /dev/null +++ b/packaging/bandsaunter.1 @@ -0,0 +1,882 @@ +.\" Generated by packaging/make-man.py -- do not edit by hand. +.TH BANDSAUNTER 1 "2026-08-22" "bandsaunter 2026-08-22_01" "User Commands" +.SH NAME +bandsaunter \- scan, record and identify radio signals with an RTL-SDR +.SH SYNOPSIS +.B bandsaunter +.RI [ command ] +.RI [ options ] +.br +.B bandsaunter scan +.BI \-r " RANGE" +.RI [ options ] +.br +.B bandsaunter +.RI "(no arguments: interactive menus)" +.SH DESCRIPTION +.B bandsaunter +sweeps any set of frequency ranges with an RTL-SDR receiver, stops on +signals that rise above the background noise, records them, and works out +what kind of signal each one was. Morse is decoded to text and speech can be +transcribed. +.PP +Ranges are given by hand or chosen from a built-in US band plan. There is no +limit on how many may be scanned at once. +.PP +Captures that turn out to be noise, static or interference are discarded +rather than saved, so what ends up on disk is transmissions rather than hiss. +This is the behaviour of +.B \-\-require\-signal +and it is on by default. +.PP +Every setting can be given as a command-line option, set in the menus, or +saved to a settings file; the three are the same list, described under +.B SETTINGS +below. +.SH COMMANDS +.TP +.B scan +Run a scan. Without +.B \-r +or +.B \-b +the interactive menus open instead. +.TP +.B bands +Browse the built-in US band plan: amateur, marine, aviation, public service, +business, railroad, GMRS/FRS, CB, ISM, weather, and more. +.TP +.B config +Show or change the saved settings. +.B "config KEY=VALUE" +sets one and saves it, +.B "config \-\-show" +prints them all, +.B "config \-\-describe KEY" +explains one in full, and +.B "config \-\-edit" +opens the menus. +.TP +.B transcribe +Transcribe existing recordings, or list which speech recognisers are +installed with +.BR \-\-engines . +.TP +.B devices +List attached receivers. +.TP +.B profiles +List saved profiles. +.TP +.B analyze +Identify a signal in an already-recorded file, or decode Morse from it. +.SH OPTIONS +.TP +.BI \-r " RANGE\fR, \fP" \-\-range " RANGE" +A frequency range to sweep, such as +.IR 144M\-148M . +Repeatable, and a comma-separated list is accepted. See +.B ENTERING FREQUENCIES +below. +.TP +.BI \-b " KEY\fR, \fP" \-\-band " KEY" +A band-plan preset, such as +.IR gmrs " or " marine\-vhf . +Repeatable. +.B bandsaunter bands +lists them. +.TP +.BI \-\-mode " MODE" +Force one demodulator for every range: nfm, wfm, am, usb, lsb, cw or raw. +Without this each range is demodulated according to what the signal turns out +to be, which is normally what you want. +.TP +.BI \-p " NAME\fR, \fP" \-\-profile " NAME" +Start from a saved profile instead of the saved default settings. +.TP +.BI \-\-save\-profile " NAME" +Save the settings this run would have used, under that name, and exit. +.TP +.B \-\-save +Save the settings this run would have used as the new defaults, and exit. +.TP +.B \-\-no\-config +Ignore the saved settings file and start from the built-in defaults. +.TP +.B \-\-simulate +Use a synthetic receiver instead of real hardware. Everything else behaves +normally, so the program can be tried out with no dongle attached. +.TP +.B \-\-dry\-run +Print the sweep plan \[em] every tuner step and how long a pass will take \[em] +and exit without receiving anything. +.TP +.B \-\-keep\-carriers +Also record steady unmodulated carriers, which are otherwise discarded as +having no content. Useful for beacon hunting or for tracking down a source of +interference. +.SH SETTINGS +Each of these can be given as a command-line option, changed in the menus +under +.BR "bandsaunter config" , +or written into the settings file. The command line wins for one run; the +settings file is what every run starts from. +.SS Dwell and recording +.TP +.B --record --record-seconds +Record for \[em] longest one signal may hold the receiver (0 = no limit) (s). +.br +Setting name \fBrecord_seconds\fR, default \fB30 s\fR. +.br +Accepts: at least 0. +.RS +.PP +How long one signal may keep the receiver before the sweep moves on. Set it to 0 and a transmission is followed until it actually ends, which is what you want for listening to conversations. Give it a number if you would rather sample a busy band widely than sit on the first station that comes up. +.RE +.TP +.B --hang --hang-seconds +Wait for quiet \[em] quiet time before the sweep resumes (s). +.br +Setting name \fBhang_seconds\fR, default \fB2 s\fR. +.br +Accepts: at least 0. +.RS +.PP +How much silence means 'they have finished talking'. People pause between sentences, and two people taking turns leave a gap every time the conversation changes hands; anything shorter than this is recorded straight through, so an exchange stays in one file. Raise it if conversations keep getting split into pieces, lower it if the scanner sits on dead air. +.RE +.TP +.B --max-record +Absolute limit \[em] ceiling on one capture, even when 'Record for' is 0 (s). +.br +Setting name \fBmax_record_seconds\fR, default \fB900 s\fR. +.br +Accepts: at least 0. +.RS +.PP +A safety stop. With no record limit set, a stuck transmitter or a continuously modulated data channel would record until the disk filled, and this is where that stops. Only worth changing if you are deliberately capturing something very long; 0 removes the stop entirely. +.RE +.TP +.B --min-record +Discard shorter than \[em] throw away captures shorter than this (s). +.br +Setting name \fBmin_record_seconds\fR, default \fB0.5 s\fR. +.br +Accepts: at least 0. +.RS +.PP +Recordings shorter than this are deleted instead of kept. A click of static or a passing car's ignition noise can hold the squelch open for a fraction of a second, and this is what keeps those out of the directory. Raise it if you are collecting lots of tiny useless files; lower it if you are chasing very short transmissions such as data bursts or single-word replies. +.RE +.TP +.B --revisit +Ignore again for \[em] hold-off before the same frequency can be recorded again (s). +.br +Setting name \fBrevisit_seconds\fR, default \fB8 s\fR. +.br +Accepts: at least 0. +.RS +.PP +After recording a frequency, ignore it for this long. One busy repeater can otherwise take over the whole scan, recorded again and again while everything else goes unheard. Lower it if you want everything from one channel; raise it if one talkative frequency is drowning out the rest of the band. +.RE +.PP +.SS Detection +.TP +.B -t --threshold +Squelch threshold \[em] margin over the noise before a signal counts as present (dB). +.br +Setting name \fBthreshold_db\fR, default \fB10 dB\fR. +.br +Accepts: at least 0.5. +.RS +.PP +How much louder than the background hiss something must be before the scanner stops on it. This is the squelch knob. Too low and it stops on noise; too high and it walks past quiet stations. If you are getting nothing at all, try lowering it a few dB; if you are recording static, raise it. +.RE +.TP +.B --dwell +Dwell per step \[em] how long the sweep listens at each tuner position (s). +.br +Setting name \fBdwell_seconds\fR, default \fB0.05 s\fR. +.br +Accepts: at least 0.005, at most 5. +.RS +.PP +How long the receiver listens at each tuning position while sweeping. A short dwell sweeps faster but can miss a transmission that starts and ends between visits; a long one hears more of what is there but goes round the band slowly. The default is a good compromise for voice traffic. +.RE +.TP +.B --resolution +Sweep resolution \[em] FFT bin width while sweeping (Hz). +.br +Setting name \fBresolution_hz\fR, default \fB3 kHz\fR. +.br +Accepts: at least 100. +.RS +.PP +How finely the sweep divides the spectrum when looking for signals. Finer resolution separates two stations sitting close together and finds weak narrow ones, but takes longer to compute. Worth making finer if you are scanning a crowded band of narrow channels. +.RE +.TP +.B --detector +Detector \[em] peak-hold catches bursts; averaging is quieter. +.br +Setting name \fBdetector\fR, default \fBpeak\fR. +.br +Accepts: one of: peak, avg. +.RS +.PP +How the sweep decides how strong each part of the band was. Peak-hold remembers the loudest instant, so it catches a transmission that starts and stops during the dwell, which is what you want for scanning. Averaging is quieter and steadier, and is better when you want a clean picture of the band rather than to catch every burst. +.RE +.TP +.B --detector-bias +Detector bias \[em] override the computed noise-peak offset (blank = automatic) (dB). +.br +Setting name \fBdetector_bias_db\fR, default \fBautomatic\fR. +.br +Accepts: at least 0. +.RS +.PP +A correction for the fact that peak-hold makes plain noise look stronger than it is, which would otherwise trigger the squelch on nothing. It is worked out automatically from the detector and the sweep settings, and there is normally no reason to set it by hand. +.RE +.TP +.B --squelch-margin +Squelch hysteresis \[em] how far below the threshold a signal may drop before it counts as gone (dB). +.br +Setting name \fBsquelch_margin_db\fR, default \fB3 dB\fR. +.br +Accepts: at least 0. +.RS +.PP +Once a signal has been found, it may drop this far below the squelch threshold before being counted as gone. Without it a station sitting exactly at the threshold would flicker on and off, chopping the recording into fragments. Raise it if recordings of weak stations keep breaking up. +.RE +.TP +.B --adaptive-floor / --no-adaptive-floor +Smooth the noise floor \[em] average the measured floor across sweeps. +.br +Setting name \fBadaptive_floor\fR, default \fByes\fR. +.RS +.PP +Learns what the background noise looks like across several sweeps rather than judging from one. It makes the squelch steadier, especially where the noise level varies across the band. Turn it off only if you are watching a band where the noise itself changes fast and you want the scanner to react immediately. +.RE +.TP +.B --max-detections +Signals per step \[em] how many separate signals one tuner position may report. +.br +Setting name \fBmax_detections_per_step\fR, default \fB4\fR. +.br +Accepts: at least 1. +.RS +.PP +The sweep can see several stations at once in the chunk of spectrum it is looking at, and this is how many of them it will queue up. Raise it in a crowded band where you are missing simultaneous transmissions; lower it if you would rather the scanner keep moving. +.RE +.TP +.B --probe +Probe length \[em] look at a signal for this long before choosing a demodulator (s). +.br +Setting name \fBprobe_seconds\fR, default \fB0.4 s\fR. +.br +Accepts: at least 0.05, at most 3. +.RS +.PP +Before recording, the scanner listens briefly to work out what kind of signal it is, so it can pick the right way to decode it. Longer is a more reliable guess but delays every recording slightly. The listen is not wasted: it is kept and played into the start of the recording. +.RE +.PP +.SS What counts as a signal +.TP +.B --require-signal / --keep-everything --no-require-signal +Check for content \[em] only keep captures that carry voice, CW or data. +.br +Setting name \fBrequire_signal\fR, default \fByes\fR. +.RS +.PP +Judge each capture and throw away anything that turns out to be noise, static or interference rather than a real transmission. This is the single setting that decides whether the recordings directory is full of things worth listening to or full of hiss. Turn it off only if you want everything that breaks squelch, however empty. +.RE +.TP +.B --accept +Record these \[em] which kinds of content are worth keeping. +.br +Setting name \fBaccept\fR, default \fBvoice, cw, digital\fR. +.br +Accepts: one of: voice, cw, digital, carrier, noise. +.RS +.PP +Which kinds of transmission are worth keeping: speech, Morse, data, plain unmodulated carriers, and noise. Most people want voice, cw and digital. Add carrier if you are hunting beacons or interference sources, and noise only for diagnosing why nothing is being recorded. +.RE +.TP +.B --min-signal-score +Minimum confidence \[em] confidence needed to keep a capture. +.br +Setting name \fBmin_signal_score\fR, default \fB0.45\fR. +.br +Accepts: at least 0, at most 1. +.RS +.PP +How certain the content check must be before a recording is kept, from 0 to 1. Lower it if real transmissions are being discarded, since weak or noisy signals score lower. Raise it if borderline rubbish is still getting through. +.RE +.TP +.B --min-voice-score +Minimum speech score \[em] how speech-like audio must be to count as voice. +.br +Setting name \fBmin_voice_score\fR, default \fB0.45\fR. +.br +Accepts: at least 0, at most 1. +.RS +.PP +How speech-like audio has to sound before it is called voice. Speech has a pitch that moves and a rhythm of syllables; a steady tone or a hum does not. Lower it if quiet or distorted speech is being missed, raise it if music, hum or engine noise is being recorded as if it were someone talking. +.RE +.TP +.B --verify-every +Re-check every \[em] how often a live capture is re-examined (s). +.br +Setting name \fBverify_seconds\fR, default \fB1.5 s\fR. +.br +Accepts: at least 0.2. +.RS +.PP +How often a recording in progress is re-examined to see whether it is still carrying anything. Checking often releases the receiver quickly when a channel turns out to be holding static; checking rarely costs less processing. +.RE +.TP +.B --verify-max +Give up after \[em] how long a capture has to show any content (s). +.br +Setting name \fBverify_max_seconds\fR, default \fB6 s\fR. +.br +Accepts: at least 0.5. +.RS +.PP +How long a recording gets to prove it contains something. If nothing recognisable has appeared by then it is abandoned and deleted, and the sweep moves on rather than sitting on an open but empty channel. +.RE +.PP +.SS Receiver +.TP +.B -d --device +Device index \[em] which dongle to use when more than one is attached. +.br +Setting name \fBdevice_index\fR, default \fB0\fR. +.br +Accepts: at least 0. +.RS +.PP +Which receiver to use when more than one is plugged in. Run 'bandsaunter devices' to see the list and their numbers. With a single dongle this can be ignored. +.RE +.TP +.B --sample-rate +Sample rate \[em] capture rate; sets how much spectrum one step covers (Hz). +.br +Setting name \fBsample_rate\fR, default \fB2.048 MHz\fR. +.RS +.PP +How much spectrum the receiver takes in at once, which sets how much ground each step of the sweep covers. Higher covers the band in fewer steps but makes the computer work harder, and cheap dongles start dropping samples. 2.048 MS/s suits most machines; drop it if recordings sound wrong or the program warns about dropped samples. +.RE +.TP +.B -g --gain +Tuner gain \[em] gain in dB, or 'auto' for the tuner's own control (dB). +.br +Setting name \fBgain\fR, default \fBauto\fR. +.RS +.PP +How much the receiver amplifies. Automatic gain sounds convenient but tends to wind itself up during quiet moments and amplify noise until it breaks squelch. A fixed value is usually better for scanning: start around 30 and lower it if strong stations sound distorted, raise it if everything is too weak to hear. +.RE +.TP +.B --ppm +Frequency correction \[em] crystal error correction (ppm). +.br +Setting name \fBppm\fR, default \fB0 ppm\fR. +.RS +.PP +Cheap receivers are tuned by a crystal that is never exactly right, so every frequency reads slightly off, possibly by a few kilohertz at UHF. If stations consistently appear a little above or below where they should be, this corrects it. Leave at 0 unless you have measured the error. +.RE +.TP +.B --agc / --no-agc +RTL2832 AGC \[em] the demodulator chip's own automatic gain. +.br +Setting name \fBagc\fR, default \fBno\fR. +.RS +.PP +A second, separate automatic gain control inside the receiver chip, on top of the tuner gain. It is usually best left off, since two automatic gain controls fighting each other makes the squelch behave unpredictably. +.RE +.TP +.B --bias-tee / --no-bias-tee +Bias tee \[em] put DC on the antenna port to power an external amplifier. +.br +Setting name \fBbias_tee\fR, default \fBno\fR. +.RS +.PP +Sends power up the antenna cable, which is how mast-mounted amplifiers and some active antennas are fed. Leave it off unless you have such a device: switching it on with ordinary equipment attached can damage it. +.RE +.TP +.B --offset-tuning / --no-offset-tuning +Offset tuning \[em] shift the tuner's own local oscillator (E4000 tuners only). +.br +Setting name \fBoffset_tuning\fR, default \fBno\fR. +.RS +.PP +A trick for one older tuner chip, the E4000, that moves an artefact away from the middle of the picture. Modern dongles, including every R820T, ignore it. Leave it off unless you know you have that tuner. +.RE +.TP +.B --direct-sampling +Direct sampling \[em] HF reception below 24 MHz: auto, 0 off, 1 I branch, 2 Q branch. +.br +Setting name \fBdirect_sampling\fR, default \fBauto\fR. +.br +Accepts: one of: auto, 0, 1, 2. +.RS +.PP +How the receiver hears shortwave. These dongles cannot normally tune below about 24 MHz, but they can be persuaded to sample the antenna directly, which opens up everything beneath it: shortwave broadcast, amateur HF, marine. Automatic switches it on when you scan below 24 MHz and off again above. The Q branch is what almost all hardware uses. +.RE +.TP +.B --usable-fraction +Usable bandwidth \[em] fraction of the sample rate each step covers. +.br +Setting name \fBusable_fraction\fR, default \fB0.75\fR. +.br +Accepts: at least 0.1, at most 0.95. +.RS +.PP +The edges of what the receiver takes in are distorted by its own filtering, so only the middle portion is trusted. Lowering this uses less of each step and sweeps more slowly but avoids the poor edges; raising it covers ground faster at the cost of missing or mismeasuring signals near the edges. +.RE +.TP +.B --dc-guard +DC guard \[em] how far the local oscillator is parked below each step (Hz). +.br +Setting name \fBdc_guard_hz\fR, default \fB8 kHz\fR. +.br +Accepts: at least 0. +.RS +.PP +Every receiver of this type produces a spurious spike at the exact centre of where it is tuned, which would otherwise look like a station. The receiver is therefore deliberately parked slightly to one side. There is rarely a reason to change this. +.RE +.PP +.SS Output +.TP +.B -o --output +Output directory \[em] where recordings and logs are written. +.br +Setting name \fBoutput_dir\fR, default \fB~/bandsaunter\fR. +.RS +.PP +Where recordings, transcripts and logs are written. Everything the program produces goes here, so put it somewhere with room: audio adds up quickly, and raw IQ adds up very quickly. +.RE +.TP +.B --audio / --no-audio +Save audio \[em] write a WAV of the demodulated audio. +.br +Setting name \fBsave_audio\fR, default \fByes\fR. +.RS +.PP +Write the listenable audio file for each transmission. This is almost certainly what you want; turning it off leaves only the log and whatever other outputs are enabled, which is useful when you only care about what was active and when. +.RE +.TP +.B --iq --save-iq / --no-iq +Save raw IQ \[em] also write the raw complex samples and a SigMF sidecar. +.br +Setting name \fBsave_iq\fR, default \fBno\fR. +.RS +.PP +Also keep the raw radio samples, exactly as they came off the receiver, alongside the audio. These can be re-analysed or decoded later with other software, but they are enormous, many megabytes per second, so leave this off unless you have a specific use for them. +.RE +.TP +.B --iq-format +IQ format \[em] sample format for raw IQ files. +.br +Setting name \fBiq_format\fR, default \fBcf32\fR. +.br +Accepts: one of: cf32, cs16. +.RS +.PP +The number format for those raw files. cf32 is the easiest for other programs to read; cs16 is half the size for the same samples. Only matters if raw IQ is being saved. +.RE +.TP +.B --audio-rate +Audio rate \[em] preferred audio sample rate (Hz). +.br +Setting name \fBaudio_rate\fR, default \fB16 kHz\fR. +.br +Accepts: at least 4000. +.RS +.PP +The sample rate of the saved audio. Higher preserves more of the original sound at the cost of file size; the default is well matched to what a radio channel can actually carry, and to what speech recognisers expect. +.RE +.TP +.B --classify / --no-classify +Identify signals \[em] work out what kind of signal each capture is. +.br +Setting name \fBclassify\fR, default \fByes\fR. +.RS +.PP +Work out what each recording actually is, whether FM voice, AM, single sideband, Morse, a paging system or a digital voice mode, and write it into the log and the filename. Turning it off saves a little processing and leaves you to identify things by ear. +.RE +.TP +.B --morse / --no-morse +Decode CW to text \[em] decode keyed carriers as Morse. +.br +Setting name \fBdecode_morse\fR, default \fByes\fR. +.RS +.PP +Turn keyed carriers into readable text, with the sending speed. Morse is still in daily use by amateurs and by beacons, and this saves you learning to read it by ear. It costs almost nothing when there is no Morse about. +.RE +.TP +.B --log-file +Log file \[em] name of the run log inside the output directory. +.br +Setting name \fBlog_file\fR, default \fBscan_log.jsonl\fR. +.RS +.PP +The name of the run log inside the output directory. It records every recording with its time, frequency, duration and identification, as JSON lines with a spreadsheet-friendly .csv alongside. +.RE +.PP +.SS Combining +.TP +.B --combine / --no-combine +Combine by frequency \[em] collect every transmission on one frequency into a single file. +.br +Setting name \fBcombine_by_frequency\fR, default \fBno\fR. +.RS +.PP +Instead of one file per transmission, keep one growing file per frequency, with each new transmission appended to it. This turns a scanner run into something you can play like a recording of that channel, rather than hundreds of fragments to click through. +.RE +.TP +.B --announce / --no-announce +Speak the time \[em] insert a spoken date and time before each transmission. +.br +Setting name \fBannounce_timestamps\fR, default \fByes\fR. +.RS +.PP +Speaks the date and time before each transmission in a combined file, so you can hear when something happened without watching a clock or reading filenames. It works with no extra software installed; installing espeak-ng makes the voice clearer. +.RE +.TP +.B --announce-frequency / --no-announce-frequency +Speak the frequency \[em] also read the frequency out with the timestamp. +.br +Setting name \fBannounce_frequency\fR, default \fBno\fR. +.RS +.PP +Also read out the frequency with the time. Useful when several nearby frequencies end up in the same combined file, or when you want a spoken record of what you were listening to. +.RE +.TP +.B --announce-engine +Speech engine \[em] which text-to-speech to use: auto, builtin, or a program name. +.br +Setting name \fBannounce_engine\fR, default \fBauto\fR. +.RS +.PP +Which voice does the speaking. Automatic uses the best available: espeak-ng if it is installed, otherwise a small built-in synthesiser that needs nothing at all. Set it to builtin to force the internal voice, or name another program. +.RE +.TP +.B --combine-tolerance +Same-frequency tolerance \[em] how far apart two receptions may be and still count as one frequency (Hz). +.br +Setting name \fBcombine_tolerance_hz\fR, default \fB6.25 kHz\fR. +.br +Accepts: at least 0. +.RS +.PP +How far apart two receptions may be and still be treated as the same frequency for combining. Transmitters drift and the measurement is never exact, so a little tolerance keeps one repeater in one file. Widen it if a single channel is being split across several files. +.RE +.TP +.B --keep-individual / --no-keep-individual +Keep separate files too \[em] also keep the one-file-per-transmission recordings. +.br +Setting name \fBcombine_keep_individual\fR, default \fBno\fR. +.RS +.PP +Keep the per-transmission files as well as the combined one. It costs twice the disk space, but means you can still pick out a single transmission without seeking through a long file. +.RE +.PP +.SS Transcription +.TP +.B --transcribe / --no-transcribe +Transcribe speech \[em] write out what was said in each voice transmission. +.br +Setting name \fBtranscribe\fR, default \fBno\fR. +.RS +.PP +Write out what was said in each voice transmission as a text file beside the recording, so a scan can be read rather than listened to, and searched with ordinary text tools. It needs a speech recogniser installed; the program says so plainly if none is present. +.RE +.TP +.B --transcribe-engine +Recogniser \[em] which speech recogniser to use, or auto. +.br +Setting name \fBtranscribe_engine\fR, default \fBauto\fR. +.RS +.PP +Which speech recogniser to use when more than one is installed. Automatic picks the best available. Radio audio is hard for these programs, and the whisper-based ones are noticeably better at it than the smaller alternatives. +.RE +.TP +.B --transcribe-model +Model \[em] model the recogniser should load. +.br +Setting name \fBtranscribe_model\fR, default \fBbase.en\fR. +.RS +.PP +How large a recognition model to load. Bigger models are more accurate and slower, and take more memory: tiny.en and base.en keep up comfortably on an ordinary machine, small.en and medium.en are better but heavier. +.RE +.TP +.B --transcribe-language +Language \[em] language to expect, or blank to detect it. +.br +Setting name \fBtranscribe_language\fR, default \fBen\fR. +.RS +.PP +The language to expect. Setting it is worth the trouble: on a short, noisy clip automatic detection often guesses wrong and returns confident nonsense in a language nobody was speaking. Leave it blank only if you genuinely do not know. +.RE +.TP +.B --transcribe-min +Skip clips shorter than \[em] do not bother transcribing very short captures (s). +.br +Setting name \fBtranscribe_min_seconds\fR, default \fB1 s\fR. +.br +Accepts: at least 0. +.RS +.PP +Do not bother transcribing captures shorter than this. Very short clips rarely contain a whole word and mostly produce noise or nothing, while still costing the processing. +.RE +.PP +.SS Run control +.TP +.B --cycles +Stop after sweeps \[em] stop after this many full passes (0 = run until stopped). +.br +Setting name \fBmax_cycles\fR, default \fBno limit\fR. +.br +Accepts: at least 0. +.RS +.PP +Stop after this many complete passes through all the frequencies. Useful for a quick survey of what is active, or for a scripted run that must finish. 0 means keep going until you stop it. +.RE +.TP +.B --duration +Stop after time \[em] stop after this long (0 = run until stopped) (s). +.br +Setting name \fBmax_runtime_seconds\fR, default \fBno limit\fR. +.br +Accepts: at least 0. +.RS +.PP +Stop after this long, whatever the scan is doing. Handy for an unattended run, or for keeping a test short. 0 means no limit. +.RE +.TP +.B --lockout +Locked-out frequencies \[em] never stop on these frequencies. +.br +Setting name \fBlockout\fR, default \fB(none)\fR. +.RS +.PP +Frequencies the scan must never stop on. Every receiving setup has a few: a pager transmitter down the road, a nearby data link, or a spurious signal the receiver manufactures itself. Give several separated by commas, and a whole stretch of spectrum as a pair, such as 162.55M, 450M-455M. +.RE +.TP +.B --lockout-width +Lock-out width \[em] how wide a locked-out frequency is (Hz). +.br +Setting name \fBlockout_width\fR, default \fB12.5 kHz\fR. +.br +Accepts: at least 1. +.RS +.PP +How wide a single locked-out frequency is. A transmitter is never exactly on its nominal frequency, so the block covers a little either side. A lock-out written as a span ignores this and uses exactly the width you gave. +.RE +.TP +.B --quiet / --no-quiet +Quiet output \[em] print errors only. +.br +Setting name \fBquiet\fR, default \fBno\fR. +.RS +.PP +Print only errors. For running from a script or a scheduled job where the usual progress reporting would just fill a log file. +.RE +.TP +.B --save-lockouts / --no-save-lockouts +Remember lock-outs \[em] keep frequencies locked out during a scan. +.br +Setting name \fBsave_lockouts\fR, default \fByes\fR. +.RS +.PP +When you lock a frequency out during a scan, remember it for later runs instead of only the current one. Only the lock-out list is written back, so options you passed for one run stay one-off. Turn it off if you would rather the program never modified your settings file. +.RE +.TP +.B --plain / --no-plain +Plain display \[em] print one line per hit instead of the live display. +.br +Setting name \fBplain\fR, default \fBno\fR. +.RS +.PP +Print one line per recording instead of the live updating display. The live display needs a real terminal; plain output is what you want over a remote connection, when saving output to a file, or when feeding another program. It is chosen automatically when output is not going to a terminal. +.RE +.PP +.SH ENTERING FREQUENCIES +Frequencies may be written with a unit or without: +.IR 146.52M ", " "146.52 MHz" ", " 146520k ", " 146520000 . +A bare number under 10000 is read as megahertz, since that is how people +write frequencies. +.PP +A range is a pair: +.IR 144M\-148M ", " 144\-148M " (the unit carries over), " "144M to 148M" ", " +.IR 144M..148M . +A single frequency on its own is treated as a narrow range around it. +.PP +A step and a demodulator may be attached: +.I 144M\-148M/25k@nfm +sweeps in 25 kHz steps and demodulates narrowband FM. +.PP +Several may be given at once, separated by commas, and +.B \-r +may be repeated. There is no limit on how many ranges a scan may cover. +.SH BAND PLAN +.B bandsaunter bands +lists over a hundred presets from the US band plan, each carrying the right +step size and demodulator for that service, so +.B "\-b gmrs" +is enough to scan GMRS properly. +.PP +Presets that stand for several others expand automatically: +.I all\-cw +sweeps every Morse segment of every amateur band, and +.IR 2m\-complete ", " 70cm\-complete +and their like sweep a whole amateur band end to end rather than one segment +of it. +.SH LOCK-OUTS +Every receiving setup has a few frequencies not worth stopping on: a pager +transmitter down the road, a nearby data link, or a spurious signal the +receiver manufactures itself. Locking one out makes the scan skip it. +.PP +Pressing +.B l +during a scan locks out whatever is being received. Unless +.B \-\-no\-save\-lockouts +is given, it is written back to the settings file the run started from, so it +stays locked out on later runs. Only the lock-out list is written back \[em] +options given on the command line for a single run stay one-off. +.PP +Lock-outs can also be given directly, several at a time, as single +frequencies or as spans: +.PP +.RS +.EX +bandsaunter scan \-r 144M\-148M \-\-lockout "162.55M, 450M\-455M" +.EE +.RE +.PP +A single frequency is widened by +.BR \-\-lockout\-width ; +a span is used exactly as written. +.SH KEYS DURING A SCAN +.TP +.B q +Stop. +.TP +.B p +Pause and resume. +.TP +.B s +Abandon this recording and resume sweeping. +.TP +.B l +Lock out this frequency, now and in future runs. +.TP +.B "+ \fRand\fB \-" +Raise or lower the squelch threshold by 1 dB. +.SH OUTPUT +Recordings are named +.IR frequency \-\- date _ time \- modulation .wav , +with the frequency padded to four digits so that an ordinary directory +listing sorts by frequency. Beside them are the run log, as JSON lines and as +CSV, and optionally a transcript per recording and the raw samples. +.PP +With +.B \-\-combine +every transmission on one frequency is appended to a single growing file for +that frequency, with a spoken date and time before each one, so a scan can be +played back as a recording of that channel rather than clicked through as +hundreds of fragments. +.SH HF RECEPTION +These receivers cannot normally tune below about 24 MHz. Below that they can +sample the antenna directly instead, which opens up shortwave: broadcast, +amateur HF, marine, aviation. It is switched on automatically when a scan +goes below 24 MHz. A direct connection to a suitable antenna is needed; the +whip supplied with most dongles will hear very little. +.SH SINGLE SIDEBAND +Single sideband is the one mode where tuning must be exact: its demodulator +is a filter that opens at the suppressed carrier, so tuning to the middle of +the voice discards its lower half and shifts the rest. bandsaunter measures +where the carrier is rather than assuming, and identifies upper from lower +sideband by which way the signal's energy leans, so +.B \-\-mode usb +is not needed. The frequency in the filename is the carrier \[em] the +frequency to dial into a radio. +.SH FILES +.TP +.I ~/.config/bandsaunter/config.yaml +The settings every run starts from. +.TP +.I ~/.config/bandsaunter/*.yaml +Named profiles. +.TP +.I ~/bandsaunter/ +Where recordings, transcripts and logs are written, unless +.B \-\-output +says otherwise. Chosen on first run. +.TP +.I /etc/modprobe.d/blacklist-rtlsdr.conf +Written by the package to keep the DVB-T television driver from claiming the +receiver. +.SH ENVIRONMENT +.TP +.B BANDSAUNTER_CONFIG_DIR +Where settings and profiles live, instead of +.IR ~/.config/bandsaunter . +.TP +.B BANDSAUNTER_LIBRTLSDR +Path to a particular librtlsdr shared library, when the system one is not the +one wanted. +.TP +.B BANDSAUNTER_DRIVER_MESSAGES +Set to 1 to let the receiver driver print its own chatter, which is +suppressed by default because it draws over the live display. +.TP +.B BANDSAUNTER_VENDOR_DIR +Where a packaged speech recogniser is installed. Default +.IR /usr/lib/bandsaunter/vendor . +.TP +.B BANDSAUNTER_MODEL_DIR +Where packaged recognition models are installed. Default +.IR /usr/share/bandsaunter/models . +.TP +.B BANDSAUNTER_ENGINE_OUTPUT +Set to 1 to let the speech recogniser print its own progress. +.SH EXAMPLES +.TP +.B bandsaunter +Interactive menus: pick bands, change settings, start scanning. +.TP +.B bandsaunter scan \-b 2m \-b 70cm \-\-record 0 \-\-hang 6 +Scan two amateur bands, following each conversation to its end and allowing +six seconds of silence between overs. +.TP +.B bandsaunter scan \-b marine\-vhf \-\-combine \-\-transcribe +Scan marine VHF, keeping one growing file per channel with spoken timestamps, +and write out what was said. +.TP +.B bandsaunter scan \-r 14.0M\-14.35M +Scan the 20 metre amateur band. Direct sampling switches on by itself. +.TP +.B bandsaunter scan \-b all\-cw \-\-decode\-morse +Sweep every Morse segment of every amateur band and decode what is heard. +.TP +.B bandsaunter scan \-b gmrs \-\-plain \-\-duration 3600 +Scan GMRS for an hour with line-per-hit output, suitable for a log file or a +remote session. +.TP +.B bandsaunter config threshold_db=12 +Raise the squelch threshold and save it as the new default. +.SH EXIT STATUS +0 on success, 1 for a bad option or an unusable configuration, 2 when the +receiver could not be opened. +.SH SEE ALSO +.BR rtl_test (1), +.BR rtl_sdr (1), +.BR espeak-ng (1) +.PP +The README shipped with the package covers the same ground at greater length, +including why the detection thresholds are what they are. +.SH BUGS +The DVB-T television driver claims these dongles on sight. If the receiver +cannot be opened, that is almost always why: the package blacklists the +driver on install, but the module must be unloaded once with +.B "rmmod dvb_usb_rtl28xxu" +or the dongle replugged. diff --git a/packaging/build-deb.sh b/packaging/build-deb.sh index 5b03ecd..9b4ae88 100755 --- a/packaging/build-deb.sh +++ b/packaging/build-deb.sh @@ -22,6 +22,13 @@ cp "$here"/bandsaunter/*.py "$site/bandsaunter/" cp "$here/README.md" "$pkgdir/usr/share/doc/bandsaunter/" gzip -9n "$pkgdir/usr/share/doc/bandsaunter/README.md" +# Regenerated from the settings table rather than copied, so the manual +# cannot describe a version of the settings that no longer exists. +mkdir -p "$pkgdir/usr/share/man/man1" +python3 "$here/packaging/make-man.py" "$pkgdir/usr/share/man/man1/bandsaunter.1" \ + >/dev/null +gzip -9n "$pkgdir/usr/share/man/man1/bandsaunter.1" + cat > "$pkgdir/usr/bin/bandsaunter" <<'EOF' #!/usr/bin/python3 import sys diff --git a/packaging/make-man.py b/packaging/make-man.py new file mode 100755 index 0000000..9ad8990 --- /dev/null +++ b/packaging/make-man.py @@ -0,0 +1,383 @@ +#!/usr/bin/env python3 +"""Generate the bandsaunter manual page from the settings table. + +The settings are described in exactly one place -- bandsaunter/settings.py -- +so the manual cannot drift from the program. Every setting appears here with +its command-line flag, its default, and the plain-language guidance that says +what it is and when someone would change it. +""" +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 import settings as st # noqa: E402 +from bandsaunter.config import ScanConfig # noqa: E402 + + +def esc(text: str) -> str: + """Escape for troff: a leading dot or apostrophe is a request.""" + out = text.replace("\\", "\\e") + return "\n".join(("\\&" + ln if ln[:1] in (".", "'") else ln) + for ln in out.split("\n")) + + +def settings_section() -> list[str]: + out = [] + defaults = ScanConfig() + for group in st.GROUPS: + out.append(f'.SS {esc(group)}') + for s in st.in_group(group): + flags = " ".join(s.flags) + if s.off_flags: + flags += " / " + " ".join(s.off_flags) + shown = st.format_value(s, getattr(defaults, s.key)) + unit = f" ({s.unit})" if s.unit and s.kind not in ("bool",) else "" + out.append('.TP') + out.append(f'.B {esc(flags)}') + out.append(f'{esc(s.label)} \\[em] {esc(s.help)}{esc(unit)}.') + out.append('.br') + out.append(f'Setting name \\fB{esc(s.key)}\\fR, ' + f'default \\fB{esc(shown)}\\fR.') + accepts = s.describe_range() + if accepts: + out.append('.br') + out.append(f'Accepts: {esc(accepts)}.') + if s.guidance: + # Indented to the entry it belongs to, not back out to the + # left margin, so an entry reads as one block. + out.append('.RS') + out.append('.PP') + out.append(esc(s.guidance)) + out.append('.RE') + out.append('.PP') + return out + + +HEAD = r'''.\" Generated by packaging/make-man.py -- do not edit by hand. +.TH BANDSAUNTER 1 "{date}" "bandsaunter {version}" "User Commands" +.SH NAME +bandsaunter \- scan, record and identify radio signals with an RTL-SDR +.SH SYNOPSIS +.B bandsaunter +.RI [ command ] +.RI [ options ] +.br +.B bandsaunter scan +.BI \-r " RANGE" +.RI [ options ] +.br +.B bandsaunter +.RI "(no arguments: interactive menus)" +.SH DESCRIPTION +.B bandsaunter +sweeps any set of frequency ranges with an RTL-SDR receiver, stops on +signals that rise above the background noise, records them, and works out +what kind of signal each one was. Morse is decoded to text and speech can be +transcribed. +.PP +Ranges are given by hand or chosen from a built-in US band plan. There is no +limit on how many may be scanned at once. +.PP +Captures that turn out to be noise, static or interference are discarded +rather than saved, so what ends up on disk is transmissions rather than hiss. +This is the behaviour of +.B \-\-require\-signal +and it is on by default. +.PP +Every setting can be given as a command-line option, set in the menus, or +saved to a settings file; the three are the same list, described under +.B SETTINGS +below. +.SH COMMANDS +.TP +.B scan +Run a scan. Without +.B \-r +or +.B \-b +the interactive menus open instead. +.TP +.B bands +Browse the built-in US band plan: amateur, marine, aviation, public service, +business, railroad, GMRS/FRS, CB, ISM, weather, and more. +.TP +.B config +Show or change the saved settings. +.B "config KEY=VALUE" +sets one and saves it, +.B "config \-\-show" +prints them all, +.B "config \-\-describe KEY" +explains one in full, and +.B "config \-\-edit" +opens the menus. +.TP +.B transcribe +Transcribe existing recordings, or list which speech recognisers are +installed with +.BR \-\-engines . +.TP +.B devices +List attached receivers. +.TP +.B profiles +List saved profiles. +.TP +.B analyze +Identify a signal in an already-recorded file, or decode Morse from it. +.SH OPTIONS +.TP +.BI \-r " RANGE\fR, \fP" \-\-range " RANGE" +A frequency range to sweep, such as +.IR 144M\-148M . +Repeatable, and a comma-separated list is accepted. See +.B ENTERING FREQUENCIES +below. +.TP +.BI \-b " KEY\fR, \fP" \-\-band " KEY" +A band-plan preset, such as +.IR gmrs " or " marine\-vhf . +Repeatable. +.B bandsaunter bands +lists them. +.TP +.BI \-\-mode " MODE" +Force one demodulator for every range: nfm, wfm, am, usb, lsb, cw or raw. +Without this each range is demodulated according to what the signal turns out +to be, which is normally what you want. +.TP +.BI \-p " NAME\fR, \fP" \-\-profile " NAME" +Start from a saved profile instead of the saved default settings. +.TP +.BI \-\-save\-profile " NAME" +Save the settings this run would have used, under that name, and exit. +.TP +.B \-\-save +Save the settings this run would have used as the new defaults, and exit. +.TP +.B \-\-no\-config +Ignore the saved settings file and start from the built-in defaults. +.TP +.B \-\-simulate +Use a synthetic receiver instead of real hardware. Everything else behaves +normally, so the program can be tried out with no dongle attached. +.TP +.B \-\-dry\-run +Print the sweep plan \[em] every tuner step and how long a pass will take \[em] +and exit without receiving anything. +.TP +.B \-\-keep\-carriers +Also record steady unmodulated carriers, which are otherwise discarded as +having no content. Useful for beacon hunting or for tracking down a source of +interference. +.SH SETTINGS +Each of these can be given as a command-line option, changed in the menus +under +.BR "bandsaunter config" , +or written into the settings file. The command line wins for one run; the +settings file is what every run starts from. +''' + +TAIL = r'''.SH ENTERING FREQUENCIES +Frequencies may be written with a unit or without: +.IR 146.52M ", " "146.52 MHz" ", " 146520k ", " 146520000 . +A bare number under 10000 is read as megahertz, since that is how people +write frequencies. +.PP +A range is a pair: +.IR 144M\-148M ", " 144\-148M " (the unit carries over), " "144M to 148M" ", " +.IR 144M..148M . +A single frequency on its own is treated as a narrow range around it. +.PP +A step and a demodulator may be attached: +.I 144M\-148M/25k@nfm +sweeps in 25 kHz steps and demodulates narrowband FM. +.PP +Several may be given at once, separated by commas, and +.B \-r +may be repeated. There is no limit on how many ranges a scan may cover. +.SH BAND PLAN +.B bandsaunter bands +lists over a hundred presets from the US band plan, each carrying the right +step size and demodulator for that service, so +.B "\-b gmrs" +is enough to scan GMRS properly. +.PP +Presets that stand for several others expand automatically: +.I all\-cw +sweeps every Morse segment of every amateur band, and +.IR 2m\-complete ", " 70cm\-complete +and their like sweep a whole amateur band end to end rather than one segment +of it. +.SH LOCK-OUTS +Every receiving setup has a few frequencies not worth stopping on: a pager +transmitter down the road, a nearby data link, or a spurious signal the +receiver manufactures itself. Locking one out makes the scan skip it. +.PP +Pressing +.B l +during a scan locks out whatever is being received. Unless +.B \-\-no\-save\-lockouts +is given, it is written back to the settings file the run started from, so it +stays locked out on later runs. Only the lock-out list is written back \[em] +options given on the command line for a single run stay one-off. +.PP +Lock-outs can also be given directly, several at a time, as single +frequencies or as spans: +.PP +.RS +.EX +bandsaunter scan \-r 144M\-148M \-\-lockout "162.55M, 450M\-455M" +.EE +.RE +.PP +A single frequency is widened by +.BR \-\-lockout\-width ; +a span is used exactly as written. +.SH KEYS DURING A SCAN +.TP +.B q +Stop. +.TP +.B p +Pause and resume. +.TP +.B s +Abandon this recording and resume sweeping. +.TP +.B l +Lock out this frequency, now and in future runs. +.TP +.B "+ \fRand\fB \-" +Raise or lower the squelch threshold by 1 dB. +.SH OUTPUT +Recordings are named +.IR frequency \-\- date _ time \- modulation .wav , +with the frequency padded to four digits so that an ordinary directory +listing sorts by frequency. Beside them are the run log, as JSON lines and as +CSV, and optionally a transcript per recording and the raw samples. +.PP +With +.B \-\-combine +every transmission on one frequency is appended to a single growing file for +that frequency, with a spoken date and time before each one, so a scan can be +played back as a recording of that channel rather than clicked through as +hundreds of fragments. +.SH HF RECEPTION +These receivers cannot normally tune below about 24 MHz. Below that they can +sample the antenna directly instead, which opens up shortwave: broadcast, +amateur HF, marine, aviation. It is switched on automatically when a scan +goes below 24 MHz. A direct connection to a suitable antenna is needed; the +whip supplied with most dongles will hear very little. +.SH SINGLE SIDEBAND +Single sideband is the one mode where tuning must be exact: its demodulator +is a filter that opens at the suppressed carrier, so tuning to the middle of +the voice discards its lower half and shifts the rest. bandsaunter measures +where the carrier is rather than assuming, and identifies upper from lower +sideband by which way the signal's energy leans, so +.B \-\-mode usb +is not needed. The frequency in the filename is the carrier \[em] the +frequency to dial into a radio. +.SH FILES +.TP +.I ~/.config/bandsaunter/config.yaml +The settings every run starts from. +.TP +.I ~/.config/bandsaunter/*.yaml +Named profiles. +.TP +.I ~/bandsaunter/ +Where recordings, transcripts and logs are written, unless +.B \-\-output +says otherwise. Chosen on first run. +.TP +.I /etc/modprobe.d/blacklist-rtlsdr.conf +Written by the package to keep the DVB-T television driver from claiming the +receiver. +.SH ENVIRONMENT +.TP +.B BANDSAUNTER_CONFIG_DIR +Where settings and profiles live, instead of +.IR ~/.config/bandsaunter . +.TP +.B BANDSAUNTER_LIBRTLSDR +Path to a particular librtlsdr shared library, when the system one is not the +one wanted. +.TP +.B BANDSAUNTER_DRIVER_MESSAGES +Set to 1 to let the receiver driver print its own chatter, which is +suppressed by default because it draws over the live display. +.TP +.B BANDSAUNTER_VENDOR_DIR +Where a packaged speech recogniser is installed. Default +.IR /usr/lib/bandsaunter/vendor . +.TP +.B BANDSAUNTER_MODEL_DIR +Where packaged recognition models are installed. Default +.IR /usr/share/bandsaunter/models . +.TP +.B BANDSAUNTER_ENGINE_OUTPUT +Set to 1 to let the speech recogniser print its own progress. +.SH EXAMPLES +.TP +.B bandsaunter +Interactive menus: pick bands, change settings, start scanning. +.TP +.B bandsaunter scan \-b 2m \-b 70cm \-\-record 0 \-\-hang 6 +Scan two amateur bands, following each conversation to its end and allowing +six seconds of silence between overs. +.TP +.B bandsaunter scan \-b marine\-vhf \-\-combine \-\-transcribe +Scan marine VHF, keeping one growing file per channel with spoken timestamps, +and write out what was said. +.TP +.B bandsaunter scan \-r 14.0M\-14.35M +Scan the 20 metre amateur band. Direct sampling switches on by itself. +.TP +.B bandsaunter scan \-b all\-cw \-\-decode\-morse +Sweep every Morse segment of every amateur band and decode what is heard. +.TP +.B bandsaunter scan \-b gmrs \-\-plain \-\-duration 3600 +Scan GMRS for an hour with line-per-hit output, suitable for a log file or a +remote session. +.TP +.B bandsaunter config threshold_db=12 +Raise the squelch threshold and save it as the new default. +.SH EXIT STATUS +0 on success, 1 for a bad option or an unusable configuration, 2 when the +receiver could not be opened. +.SH SEE ALSO +.BR rtl_test (1), +.BR rtl_sdr (1), +.BR espeak-ng (1) +.PP +The README shipped with the package covers the same ground at greater length, +including why the detection thresholds are what they are. +.SH BUGS +The DVB-T television driver claims these dongles on sight. If the receiver +cannot be opened, that is almost always why: the package blacklists the +driver on install, but the module must be unloaded once with +.B "rmmod dvb_usb_rtl28xxu" +or the dongle replugged. +''' + + +def main() -> int: + out = [HEAD.format(date=date.today().isoformat(), + version=bandsaunter.__version__)] + out += settings_section() + out.append(TAIL) + text = "\n".join(out) + text = text.replace("\n\n", "\n") # troff dislikes blank lines + target = Path(sys.argv[1] if len(sys.argv) > 1 + else Path(__file__).parent / "bandsaunter.1") + target.write_text(text) + print(target) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_manpage.py b/tests/test_manpage.py new file mode 100644 index 0000000..361fc22 --- /dev/null +++ b/tests/test_manpage.py @@ -0,0 +1,72 @@ +"""The manual page, which is generated from the settings table.""" +import shutil +import subprocess +import sys +from pathlib import Path + +import pytest + +from bandsaunter import settings as st + +GENERATOR = Path(__file__).resolve().parent.parent / "packaging" / "make-man.py" + + +@pytest.fixture(scope="module") +def page(tmp_path_factory): + out = tmp_path_factory.mktemp("man") / "bandsaunter.1" + subprocess.run([sys.executable, str(GENERATOR), str(out)], + check=True, capture_output=True) + return out.read_text() + + +def test_every_setting_is_documented(page): + """A setting the manual does not mention is one nobody can look up.""" + missing = [s.key for s in st.SETTINGS if s.key not in page] + assert not missing, f"settings missing from the manual: {missing}" + + +def test_every_flag_is_documented(page): + missing = [f for s in st.SETTINGS for f in s.flags + s.off_flags + if f.replace("-", "\\-") not in page and f not in page] + assert not missing, f"flags missing from the manual: {missing}" + + +def test_every_setting_explains_itself_in_plain_words(page): + """The guidance is the point of the manual: what it is, when to change it.""" + for s in st.SETTINGS: + assert s.guidance, f"{s.key} has no plain-language guidance" + assert len(s.guidance) > 80, f"{s.key}'s guidance says too little" + # The first sentence has to stand on its own for someone skimming. + assert s.guidance.rstrip().endswith("."), s.key + + +def test_the_commands_and_the_keys_are_documented(page): + for word in ("scan", "bands", "config", "transcribe", "devices", + "profiles", "analyze"): + assert f".B {word}\n" in page, f"command {word} undocumented" + for section in ("SYNOPSIS", "DESCRIPTION", "COMMANDS", "OPTIONS", + "SETTINGS", "FILES", "ENVIRONMENT", "EXAMPLES"): + assert f".SH {section}" in page + + +@pytest.mark.skipif(not shutil.which("groff"), reason="groff not installed") +def test_it_renders_without_complaint(page, tmp_path): + """Troff is unforgiving: an unescaped leading dot silently eats a line.""" + src = tmp_path / "bandsaunter.1" + src.write_text(page) + proc = subprocess.run(["groff", "-man", "-Tutf8", "-ww", "-z", str(src)], + capture_output=True, text=True) + assert proc.returncode == 0, proc.stderr + assert not proc.stderr.strip(), proc.stderr + + +@pytest.mark.skipif(not shutil.which("groff"), reason="groff not installed") +def test_the_guidance_survives_into_the_rendered_page(page, tmp_path): + src = tmp_path / "bandsaunter.1" + src.write_text(page) + rendered = subprocess.run(["groff", "-man", "-Tutf8", str(src)], + capture_output=True, text=True).stdout + flat = " ".join(rendered.replace("\b", "").split()) + # A sentence from one setting's guidance, chosen because it is the one a + # newcomer most needs: what the squelch actually is. + assert "This is the squelch knob." in flat