.\" Generated by packaging/make-man.py -- do not edit by hand. .TH BANDSAUNTER 1 "2026-09-04" "bandsaunter 2026-09-04_02" "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 waterfall Draw a waterfall for every recording in a directory that produced no readable words. See .B WATERFALLS below. .TP .B devices List attached receivers. .TP .B profiles List saved profiles. .TP .B adsb Listen to aircraft on 1090 MHz and write down everything they say. See .B AIRCRAFT below. .TP .B flights Read an ADS-B log back: the report, the map for Google Earth and the animation. See .B AIRCRAFT below. .TP .B analyze Identify a signal in an already-recorded file, decode Morse from it, or write out the picture it turns out to be. .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, trunk, carrier, noise. .RS .PP Which kinds of transmission are worth keeping: speech, Morse, data, trunking control channels, plain unmodulated carriers, and noise. Most people want voice, cw and digital. Add carrier if you are hunting beacons or interference sources, trunk if you are collecting control channels for a decoder, 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 Trunking .TP .B --skip-control / --keep-control --no-skip-control Skip trunk control channels \[em] spot a trunked system's control channel and move straight on. .br Setting name \fBskip_control\fR, default \fByes\fR. .RS .PP Trunked radio systems -- the kind police, fire and large businesses use -- keep one frequency transmitting a data stream around the clock. It tells the radios which channel to jump to for each conversation; it carries no speech and it never goes quiet. To a scanner it looks like a very strong, very interesting signal, so without this setting the receiver parks on it, records the whole record limit of buzzing, and finds it again on the next sweep. With this on it is recognised within a second or two, named on screen, and skipped. Leave it on unless you are deliberately collecting control channel data to feed to a decoder. .RE .TP .B --control-seconds Control channel patience \[em] unbroken carrier a digital-voice look-alike must hold (s). .br Setting name \fBcontrol_seconds\fR, default \fB20 s\fR. .br Accepts: at least 1. .RS .PP Only matters for P25, DMR and NXDN. On those systems the control channel and an ordinary digital conversation look identical for the first few seconds, and the only thing that tells them apart is that the conversation eventually pauses and the control channel never does. This is how long a signal has to keep going without a break before it is judged to be a control channel. Raise it if digital voice calls are being skipped by mistake; lower it if you are tired of waiting out control channels. It has no effect on the older Motorola and EDACS systems, which are recognised immediately from their symbol rate. .RE .TP .B --lockout-control / --no-lockout-control Lock out control channels \[em] add every control channel found to the lock-out list. .br Setting name \fBlockout_control\fR, default \fBno\fR. .RS .PP Write each control channel into the lock-out list as it is found, so the scanner stops even looking at it. Skipping one already costs only a second or two, so this is worth turning on mainly if you scan the same band constantly and want the list built for you. With 'Remember lock-outs' also on, the entries are saved to your settings file and survive a restart. .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 --images / --no-images Decode pictures \[em] save SSTV, weather satellite and shortwave fax pictures as PNG. .br Setting name \fBdecode_images\fR, default \fByes\fR. .RS .PP Three of the things a receiver can hear are pictures: the weather satellites on 137 MHz, amateur slow-scan television, and the shortwave weather fax stations. All three are images sent as sound, so they arrive in the same recordings everything else does. Each is recognised by its own header rather than guessed at, so this costs a moment per recording and finds nothing where there is nothing. What it does find is written as a PNG beside the audio. .RE .TP .B --waterfall / --no-waterfall Draw a waterfall \[em] picture every capture that produced no readable words. .br Setting name \fBwaterfall\fR, default \fByes\fR. .RS .PP Most of what a scanner records cannot be turned into words: a data burst, a keyed carrier, a pager, a control channel, a stretch of something unidentified. A waterfall shows the shape of a signal rather than its meaning -- how wide it is, how long it lasted, whether it was keyed, swept, hopping or steady, and whether it was one signal or three side by side -- so every capture that produced no readable words gets one drawn beside it as a PNG. Where the raw IQ was kept it draws the radio spectrum; otherwise the demodulated audio, and it says on the picture which it is. .RE .TP .B --waterfall-min-chars Words that count as readable \[em] a transcript shorter than this counts as no transcript. .br Setting name \fBwaterfall_min_chars\fR, default \fB5\fR. .br Accepts: at least 0, at most 200. .RS .PP How much transcript counts as having read a capture. Under this, the recogniser found a word or two of nothing in particular, and a picture of the signal is worth more than the word. .RE .TP .B --morse / --no-morse Decode CW to text \[em] decode keyed carriers as Morse. .br 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. Every capture is tried once it has finished, whatever the modulation was called, because most of the Morse on the air is a repeater or a beacon giving its callsign in a burst of a second or two; a callsign read out of one goes to the same lookup and the same map as a spoken one. .RE .TP .B --decode-data / --no-decode-data Decode data signals \[em] read the packets out of anything carrying data. .br Setting name \fBdecode_data\fR, default \fByes\fR. .RS .PP Read what a data signal actually says. A great deal of what a scanner finds is not speech: doorbells, tyre-pressure sensors, weather stations, remote controls, paging, packet radio. Each one is sliced into its pulses, the line code worked out from the pulse lengths alone, and the bits reported -- with the packet named where its framing says what it is, and the message printed in full where the protocol carries one. The check that keeps it honest is repetition: these transmitters send the same packet several times over, and bits that come back identical every time did not come from noise. Turn it off to save a little processing on a busy band. .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 Callsigns .TP .B --callsign-lookup / --no-callsign-lookup --offline-callsigns Look callsigns up \[em] ask the licence database who a callsign belongs to. .br Setting name \fBcallsign_lookup\fR, default \fByes\fR. .RS .PP When someone gives their callsign, look it up and say who they are. The data is the FCC's own published licence register, which carries the licensee's name, the town they are licensed in and the coordinates that put them on the map. Only the callsign is sent, and each one is asked about once and then remembered, so this costs almost nothing. Turn it off if you would rather the scan reached the network for nothing at all -- callsigns are still picked out of the transcripts, and the prefix still says which country and which US district they belong to. .RE .TP .B --kml Map file \[em] KML map of where the stations heard are licensed (blank = none). .br Setting name \fBkml_file\fR, default \fBcallsigns.kml\fR. .RS .PP The name of a map file, kept in the output directory, of everyone who identified themselves. Each station is one pin: the callsign, who holds the licence, where they are licensed, and every frequency and time you heard them. It is added to as the scan runs and again by later scans, so it builds up into a picture of what you can hear from where you are. KML is the format Google Earth uses; QGIS, Marble and OsmAnd read it too. Leave it blank if you do not want the map. .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. .PP The same plan names what is heard. Beside every frequency on the display, and in the line\-per\-hit output, is the band it falls in: a signal at 421 MHz is labelled .IR "70 cm Amateur" , one at 462.5625 MHz is .IR "GMRS / FRS" , and 162.55 MHz is .IR "NOAA Weather Radio" . Where several allocations overlap, the narrowest wins, because it says the most \[em] 146.52 MHz is named as the 2 m simplex calling channel rather than as the whole 2 m band. The name is written into each recording's sidecar as well, so it stays with the capture. .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. .PP Two runs never write anything back. .B \-\-no\-config has no settings file to write to, since the point of it is to leave the saved settings alone; and .B \-\-simulate is looking at an invented band, whose frequencies would be nonsense in a real settings file. Both still lock out for the run in hand, and say so. .SH THE LIVE DISPLAY The display is redrawn in place several times a second, so it has to fit the window. On a short terminal the optional parts are given up in order \[em] the spectrum row, then the list of recorded signals, then the key hints, and last of all the receiver panel, which says nothing that changes. What is never given up is the sweep line and, while one is running, the recording. .PP Resizing the window redraws everything from a blank screen. The frame that was on it was drawn for a window that no longer exists, and the text above it has been reflowed by the terminal in any case, so what was printed before the scan started \[em] the sweep plan and the settings summary \[em] scrolls away at that point. .PP .B \-\-plain prints one line per hit instead and needs none of this, which is what to use when the output is going into a pipe or a log. .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 TRUNKED SYSTEMS Police, fire and large business radio in the US mostly runs on .IR trunked systems. Instead of giving each department its own frequency, the system owns a pool of channels and hands one out for each conversation as it happens. To make that work, one frequency in the pool is given over entirely to a data stream that runs day and night, telling every radio in the fleet where to go next. That frequency is the .IR "control channel" . .PP A control channel is the worst thing a scanner can find. It is loud, it is perfectly steady, it never stops, and there is nothing on it to listen to \[em] just a harsh buzz. A scanner without special handling parks on it for the whole record limit, saves the file, and then finds it again on the next sweep, for as long as it is left running. .PP bandsaunter recognises one from the shape of the signal, names the system on screen, deletes what it captured and moves on, usually within a second or two. What it looks for is a constant\-envelope data stream that never pauses, at a symbol rate belonging to a known trunking standard: .RS .PP 3600 baud two\-level \[em] Motorola SMARTNET / SmartZone (Type I and II). .br 9600 baud two\-level \[em] EDACS and ProVoice. .br 1200 baud two\-level \[em] MPT\-1327. .br 4800 baud four\-level \[em] P25 or DMR Tier III. .br 2400 baud four\-level \[em] NXDN and NEXEDGE. .RE .PP The first two are recognised at once: nothing else transmits at those rates without pausing. The others share their shape with an ordinary digital voice call on the same system, so they are only called a control channel once the carrier has run unbroken for .B \-\-control\-seconds (20 s by default) \[em] long enough that a real conversation would have taken a breath. Raise that figure if digital voice calls are being skipped by mistake. .PP Being inside a band where trunking is common raises confidence but is never required: trunking is licensed on business pairs all over the spectrum. .PP Use .B \-\-keep\-control to record control channels anyway, which is what you want if you are feeding them to a decoder. Use .B \-\-lockout\-control to have each one written into the lock\-out list as it is found, so the scanner stops looking at it at all; with .B \-\-save\-lockouts on, that list survives a restart. .SH TRANSCRIPTS Anything the content check identifies as voice is passed to a speech recogniser, and the words are written to a .I _transcription.txt beside the recording. Only voice: running a recogniser over Morse or a data burst costs seconds and produces nothing. .PP One transcript per transmission, and none is ever overwritten \[em] the timestamp is part of the name, so two overs on one frequency cannot land on the same file. .PP With .B \-\-combine there is one recording per frequency, so there is one transcript per frequency, and each over is appended to it with the time it was heard. An unattended receiver keeps adding to that file night after night rather than starting it over. .PP A capture with nothing recognisable in it produces no file at all, rather than a directory of placeholders. No voice-activity filter runs inside the recogniser \[em] one throws away the single-word overs between transmissions, which on a scanner are the replies worth having. Instead the whole capture is asked once whether anything in it rises above its own noise, and refused before a recogniser sees it if nothing does. That check can veto a capture but never trim one, so a short reply in the middle of a quiet channel survives it. .PP .BR saunterbrowse (1) reads these back, and lists any callsigns it finds in them with the licence they belong to. .PP A callsign in a transcript is not written the way it is printed. A recogniser has never heard of the phonetic alphabet: it writes what the words sounded like, breaks the callsign wherever the speaker paused, joins the words back up, hyphenates them, or drops a hesitation into the middle of the run. So "KU 0W", "kilo uniform zero whiskey", "Whiskey\-One\-Alpha\-Whiskey", "WhiskeyOneAlphaWhiskey" and "whiskey one alpha, uh, whiskey" are all read back as the callsigns they are, and "alfa", "juliett" and "whisky" count alongside the official spellings. .PP Two shapes are recognised. An amateur callsign is a prefix, a district digit and a suffix; everything else the FCC licenses is written the other way round, the letters first and then the digits, so WQVF960 and WXG204 are read as the GMRS and business licences they are. .PP Nothing is joined across a slash: a suffix says where the station is, not what it is called, so .I W1AW/B is W1AW. .SH WATERFALLS Most of what a scanner records cannot be turned into words: a data burst, a keyed carrier, a pager, a control channel, a stretch of something unidentified. A waterfall says something about every signal there is, because it shows the shape of the thing rather than its meaning \[em] how wide it is, how long it lasted, whether it was keyed, swept, hopping or steady, and whether it was one signal or three side by side. .PP So every capture that produced no readable words is drawn beside the audio as a PNG: no voice, or voice the recogniser came back from with fewer than .B \-\-waterfall\-min\-chars characters, which is what a recogniser handed something that is not speech reliably does. Time runs down the picture and frequency across it, with the frequency scale on top, the seconds down the left and a caption underneath saying what the capture was. .PP A capture with Morse in it is never counted as readable, however long the transcript. A station identifying itself in CW over an FM carrier is transcribed as a string of digits, one per tone, which clears any bar and says nothing; the ident is in the Morse text and the signal is only visible as a picture. .PP The caption also says what the picture is *of*, and that matters. Where the raw IQ was kept this draws the radio spectrum around the tuned frequency, which is the waterfall an operator would have been watching. Where only the audio was kept \[em] the usual case, since IQ is off by default \[em] it draws the demodulated audio instead: after an FM detector the frequency axis is no longer radio frequency, and a picture that did not say so would be a lie told in a convincing font. .PP .B bandsaunter waterfall does the same for a directory already recorded, drawing only what cannot be read unless .B \-\-all is given, and skipping what it has already drawn unless .B \-\-redraw is. .B \-\-check\-morse runs the CW decoder over the recordings it was about to skip, for sidecars written before the decoder could hear an ident over an FM carrier, and draws \[em] and records the ident in \[em] the ones that have one. .SH CW AND IDENTIFICATION Every capture is offered to a CW decoder once it has finished, whatever the classifier made of it. Most of the Morse on the air is not a conversation: it is a repeater, a beacon or an unattended transmitter saying who it is and stopping, which is four to six characters and over in a second or two. That burst is a fraction of a capture named after whatever filled the rest of it, so waiting for the label to say "CW" missed it. .PP Nor does that station key its carrier. On the land-mobile bands the carrier stays up and the ident is an audio tone keyed inside it, which a detector looking for a keyed carrier sees as a carrier that never stops. So the recorded audio is searched as well, a few seconds at a time, because the decoder takes its tone and its key-down threshold from the whole of whatever it is handed: a half-minute recording with five seconds of keying in the middle measures both from the other twenty-five. A mark far longer than any dash is read as the transmission the ident was sent over rather than as a character the window sliced, which is what used to take the first and last letter of every such ident \[em] and with them the callsign, one word with no gap in it to survive the drop. .PP A reading made only of one-element characters is refused. E and T are the only two, so a decode of nothing but those can hardly be wrong \[em] there is nothing in it to get wrong \[em] and no station has ever identified itself that way. .PP Short is therefore the normal case rather than the awkward one. A decode of two or three characters is believed on its timing alone \[em] every element within a third of a unit of one or three, every character resolving to something in the table, and the keyed tone standing at least 20 dB above the rest of its band. That last one is what separates an ident from a blip: with four elements the dot length is fitted to those very elements, so noise lands on the grid as neatly as keying does, and only the tone tells them apart. One keyed element is refused, because a single pulse is an E or a T whether a person sent it or the squelch opened on a click. .PP The other half of a short decode is knowing what was cut off. A capture opens when the squelch does, which is in the middle of an element as often as not, and half a character is not a smaller reading of what was sent \[em] it is a different one, and a K with its first dash missing is an A. So the character at a sliced end is dropped, and so is the rest of the word it was in, because what is left of that word can read as a whole one: .I K1AA caught halfway through is .IR K1A , which belongs to somebody else. The full text is still reported; it is the identification that is held to the stricter standard. .PP What survives goes to the same callsign lookup and the same map as a spoken one. Word gaps in Morse are not joined across, because the sender chose them: .I "KU0W K" is a station signing off, not a callsign one letter longer. .SH DECODING DATA A great deal of what a scanner finds is not speech. Doorbells, tyre\-pressure sensors, weather stations, remote controls, paging and packet radio all carry words or numbers that a receiver can read, and .B bandsaunter reads them. .PP Whatever the modulation, a data signal comes down to the same shape once it has been sliced: a train of alternating runs whose lengths carry the information. On\-off keying gives that directly \[em] the carrier is up or it is down \[em] and two\-level FSK gives the same thing from the discriminator, one tone or the other. So both are reduced to runs and everything after that is shared. .PP What the runs mean is the line code, and it is worked out from the runs alone rather than being configured: .TP .B PWM The pulse carries the bit and the gap or the period holds still. Nearly every cheap 433 MHz remote, and everything built on an EV1527 or PT2262. .TP .B PPM The pulse holds still and the gap carries the bit. The other half of the same market. .TP .B Manchester Every bit is a transition in the middle of its own period, so runs come in only two lengths. .TP .B NRZ The level is held for as many symbol periods as there are bits. What a framed protocol sits on top of. .PP Four\-level FSK \[em] C4FM, as P25, DMR and NXDN use it \[em] is recognised as such and read as symbols rather than being sliced down the middle, which would give bits that mean nothing. Where a frame sync word appears the system is named outright. .SH PROTOCOLS THAT CAN BE READ IN FULL Two carry their own framing and checksums, so a frame either passes or it does not, and one that passes is not a guess. .TP .B POCSAG Paging, at 512, 1200 or 2400 baud. The rate is not announced anywhere in the signal, so all three are tried and the one whose sync word appears is the right one. Each codeword is checked, and a single bit error is corrected, against the BCH code the standard puts there for the purpose. The address, the function letter and the message text are all reported. .TP .B "AX.25 / APRS" Amateur packet on 1200 baud AFSK. The frame check has to come out right before a frame is reported at all. The sender's callsign, the digipeater path and the payload are shown \[em] and the callsign goes onto the map with the rest. .SH BELIEVING A DECODE A decoder that always returns something is worse than useless: noise sliced at a threshold produces runs, and runs produce bits. Three things guard against that. .PP The runs have to quantise to the line code's own grid, and a decode whose runs are scattered is thrown away. Most of the bursts in a capture have to decode the same way, because a data signal is data all the way through and one lucky window among eight is a coincidence. And, much the strongest, the packet has to repeat \[em] these transmitters send the same thing three to ten times over, and bits that come back identical every time did not come from noise. .PP A bare reading with none of that behind it, where the runs merely happened to land on a grid, is reported as nothing at all rather than as a bit string with a low number beside it that somebody will read anyway. .PP A decode that does have repeats or a checksum behind it outranks the content check: 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. .SH PICTURES Three of the things a receiver can hear are images rather than sounds. All three are analogue, all three encode brightness as a frequency, and all three arrive as the audio the scanner already records \[em] so they are looked for in every recording and written out as PNG beside it. .TP .B SSTV Slow-scan television, on 14.230 MHz and 144.5 MHz and wherever else amateurs send it. A transmission opens with a VIS header that says which mode follows, and that header is what is looked for: no header, no picture. Martin M1 and M2, Scottie S1, S2 and DX, and Robot 36 and 72 are decoded, in colour. .TP .B "APT" The NOAA weather satellites on 137 MHz, which spend a fifteen-minute pass sending one continuous picture. A 2400 Hz tone carries the brightness, two lines a second, 2080 words to a line, with both of the satellite's sensors in every line. The whole frame is written, and each sensor again on its own. .TP .B "HF fax" The weather charts the shortwave stations have sent for decades, in single sideband between 2 and 20 MHz. A transmission opens with a phasing signal \[em] twenty or so lines that are black but for a pulse at the start of each \[em] and that is what says where a line begins and how long one is. .PP None of the three is guessed at, which is what makes it safe to try them on every recording: each is recognised by a header or a phasing signal that nothing else on the air sends. A decoder without one draws static beautifully, and a directory of beautifully rendered static is worse than an empty one. .PP A picture keeps its capture whatever the content check made of it. A satellite is a steady tone with a wobble on it and an SSTV transmission is a whistle: neither is speech and neither has symbol structure, so both were being thrown away as "no signal content" having already been recognised. .PP Pictures take minutes rather than seconds \[em] two minutes for SSTV, fifteen for a satellite pass \[em] so .B \-\-record has to be long enough or what arrives is the top of one. A partial picture is kept and labelled as partial rather than discarded. .PP .BR saunterbrowse (1) marks these in the list and gives the path of the file. .PP GRIB, which is sometimes asked about in the same breath, is not a modulation: it is the binary format the weather models are published in, and it travels by satellite data link and by e-mail rather than as something a receiver can demodulate. Where a decoded byte stream begins with its magic number it is named as such; nothing here fetches or renders one. .SH AIRCRAFT .B bandsaunter adsb parks the receiver on 1090 MHz and reads the Mode S extended squitter that every airliner overhead broadcasts twice a second: the aircraft's address, its callsign, its altitude, its position and its speed, unencrypted, to nobody in particular. .PP It is a command of its own because ADS-B does not fit through the scanner. The signalling is a megabit a second, which needs at least two megasamples a second of raw receiver output; the scan path decimates everything to a channel twelve and a half kilohertz wide long before any decoder sees it. .PP Every frame carries a 24-bit checksum, so there is no threshold here and nothing to disbelieve: a frame either passes or is dropped. A position takes two frames \[em] the encoding sends a fraction of a zone, and one frame alone is ambiguous by hundreds of miles \[em] so an aircraft is placed once an even and an odd frame have both arrived, about a second apart. .PP An aircraft is overhead for four minutes and then gone, so everything heard is written down as it arrives: a JSON Lines log, one object per frame, in .I adsb_