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

Cover every option in the help, the manual and the readme, and say what to install

Browse source 
An audit rather than a feature, prompted by wanting this fit to hand to
somebody else.

Five options had no command-line flag written down in the table the manual
is generated from -- location, hold, schedules, tile_url and speed_unit --
so five flags that exist were missing from the manual.  Four of them did
exist under other names and are now recorded; hold had no flag at all and
has one.

Four switches could be turned off from the command line and not back on:
--no-lookup, --no-basemap, --no-airports and --no-labels had no positive
halves, so an option turned off in the saved settings could not be turned on
again for one run.  All four now have both.

And adsb, which opens the window and draws a map when it stops, could not be
given any of the settings that decide what those look like: no --at, no
--radius, no --tiles, no --map-brightness, no --width, --fps, --trail,
--fade, --stale, --airports or --labels.  It takes all of them now.

The manual had no list of the aircraft options at all -- the ADS-B sections
were hand-written prose -- so five of them appeared nowhere in it.  It now
generates an AIRCRAFT OPTIONS section from the same table the menu and the
flags come from, and the readme carries a table of all thirty-four with
their flags and defaults.  Three tests hold the three of them together: one
that every option records its flag, one that every flag the table claims
actually exists on a command, and one that the readme names them all.

The installing instructions now list every dependency rather than only the
optional ones: the four Python packages with their names in Debian, Fedora
and Arch, and librtlsdr, which is a C library and therefore the one thing
pip cannot bring and a virtual environment cannot supply.  What reaches a
network is written down too -- which host, when, and which file it is cached
in -- since somebody installing this on a metered or air-gapped machine has
to be able to see that nothing is fetched behind their back.  build-repo.sh
needs dpkg-dev and apt-utils, which a minimal system does not have, and now
says so.

Verified rather than asserted: a clean virtual environment, pip install from
this tree, and a real log read back through the installed command.  It pulls
seven wheels rather than the four the page claimed, the other three being
what Rich brings with it.

Also: matplotlib is gone from the readme's dependency table, nothing having
imported it; ffmpeg and Qt are in it, both having been missing; ffmpeg is a
Suggests on the package; and resume.sh is ignored.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg
This commit is contained in:
The Dust Council 2026-09-06 14:12:33 -07:00
parent 6d2436cde1
commit 8ed01f991f
16 changed files with 1012 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

78
INSTALL.md
View file

@ -59,6 +59,13 @@ model into a small apt repository under `dist/repo`, so that `apt install
bandsaunter` on every other machine brings transcription with it. See
**Install → From your own apt repository** in the README.
It needs two more tools than `build-deb.sh` does, neither of which is on a
minimal system:
```bash
sudo apt install dpkg-dev apt-utils # dpkg-scanpackages and apt-ftparchive
```
---
## B. Anywhere else: a virtual environment
@ -80,8 +87,10 @@ python3 -m venv .venv
pip install . # a few wheels; under a minute
```
That installs four wheels — numpy, scipy, rich, PyYAML — and puts two commands
on the path, `bandsaunter` and `saunterbrowse`. Nothing is built from source.
That installs seven wheels — numpy, scipy, rich and PyYAML, plus the three
Rich brings with it (Pygments, markdown-it-py, mdurl) — and puts two commands
on the path, `bandsaunter` and `saunterbrowse`. Nothing is built from source,
and it takes under a minute.
Use `pip install -e .` instead if you intend to change the code.
@ -123,21 +132,72 @@ if not.
---
## Optional dependencies
## Every dependency, in one table
Everything below is genuinely optional. The program starts, scans, records,
identifies, decodes Morse and draws waterfalls with none of it, and says
plainly when a feature is unavailable rather than failing.
**Required.** Four Python packages and one system library. The `.deb` and
`pip install` both pull the Python ones in; the system library is the only
thing either way that has to come from your distribution.
| | Debian/Ubuntu/Mint | Fedora | Arch | what needs it |
|---|---|---|---|---|
| Python 3.10+ | `python3` | `python3` | `python` | everything |
| NumPy | `python3-numpy` | `python3-numpy` | `python-numpy` | every signal path, every picture |
| SciPy | `python3-scipy` | `python3-scipy` | `python-scipy` | filtering, demodulation, classifying |
| Rich | `python3-rich` | `python3-rich` | `python-rich` | the menus and the live display |
| PyYAML | `python3-yaml` | `python3-pyyaml` | `python-yaml` | the settings file |
| **librtlsdr** | `librtlsdr0` | `rtl-sdr` | `rtl-sdr` | **talking to the dongle** |
**`librtlsdr` is the one manual dependency that matters.** It is a C library,
not a Python package, so `pip` cannot install it and no virtual environment
brings it with it. bandsaunter opens it with `ctypes` at runtime, trying
`librtlsdr.so.2`, `.so.0`, `.so`, `librtlsdr.dylib`, `rtlsdr.dll` and
`librtlsdr.dll` in that order.
Without it everything that does not touch the hardware still works — reading
logs, drawing maps, decoding recordings, the simulated sky — and anything that
does says so plainly instead of failing:
```sh
sudo apt install librtlsdr0 # Debian, Ubuntu, Mint
sudo dnf install rtl-sdr # Fedora
sudo pacman -S rtl-sdr # Arch
brew install librtlsdr # macOS
```
**Optional.** Everything below is genuinely optional. The program starts,
scans, records, identifies, decodes Morse, draws waterfalls and maps with none
of it, and says plainly when a feature is unavailable rather than failing.
| Install | Gives you | Without it |
|---|---|---|
| `sudo apt install espeak-ng` | clearer spoken timestamps on combined recordings, rendered about three times faster | a built-in formant synthesiser does the same job, less clearly |
| `sudo apt install python3-pyqt6` | the realtime aircraft window (`bandsaunter adsb --window`) | the terminal board still shows every aircraft, and the maps are still drawn afterwards |
| `sudo apt install ffmpeg` | `bandsaunter flights --out sky.mp4` writes a video | a GIF is written instead, and it says so |
| `sudo apt install rtl-sdr` | `rtl_test`, `rtl_sdr` and friends, for diagnosing hardware | nothing missing from bandsaunter itself |
| `sudo apt install espeak-ng` | clearer spoken timestamps on combined recordings, rendered about three times faster | a built-in formant synthesiser does the same job, less clearly |
| `sudo apt install rtl-sdr` | `rtl_test`, `rtl_sdr` and friends, for diagnosing the hardware | nothing missing from bandsaunter itself |
| `pip install faster-whisper` | speech transcription of recorded voice — see [the step-by-step below](#speech-transcription-step-by-step) (~250 MB installed, plus a 148 MB model) | transcription is off; scans report that no recogniser is installed |
| `pip install vosk` | a smaller, weaker recogniser (~10 MB plus a 40 MB model) | as above |
| `sudo apt install python3-pyqt6` | the realtime aircraft window (`bandsaunter adsb --window`) | the terminal board still shows every aircraft, and the maps are still drawn afterwards |
| `pip install openai-whisper` | the reference Whisper, slower and heavier than faster-whisper | as above |
| `pip install pocketsphinx` | a tiny recogniser, poor on radio audio | as above |
| whisper.cpp (`whisper-cli` on the PATH) | transcription with no Python dependencies at all | as above |
| `pip install pyte` | the terminal-resize tests | those tests skip |
| `pip install pytest` | running the test suite | you cannot run the tests |
`bandsaunter transcribe --list` says which recognisers it can actually see,
and which one it would use.
**Nothing is downloaded behind your back.** The things that reach a network do
so only when you ask, and each is cached on disk afterwards:
| What | Where from | When | Kept in |
|---|---|---|---|
| aircraft and route lookups | `api.adsbdb.com`, `hexdb.io` | while listening, unless `--no-lookup` | `~/.cache/bandsaunter/flights.json`, a month |
| amateur callsign lookups | `callook.info`, `api.hamdb.org` | when a scan hears a callsign, unless turned off | `~/.cache/bandsaunter/callsigns.json`, a month |
| map tiles | `tile.openstreetmap.org`, or `--tiles URL` | when a map is drawn, unless `--no-basemap` | `~/.cache/bandsaunter/tiles`, for ever |
| aerodrome positions | `overpass-api.de` | when a map is drawn, unless `--no-airports` | `~/.cache/bandsaunter/airports`, a month |
| flight schedules | the four paid services below | only if you have set a key | a month |
Every request identifies itself as `bandsaunter` and carries nothing but the
question — a callsign, a 24-bit address, or a box of the world. No identity,
no position, no key.
**The aircraft window needs Qt**, and any of four bindings will do — PyQt6,
PyQt5, PySide6 or PySide2 — because distributions disagree about which they