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

Correct the pocketsphinx instruction and document the apt/pip boundary

Browse source 
Debian ships the pocketsphinx tools and library but not the Python bindings,
so "apt install pocketsphinx" did not give a working engine. It comes from
pip like the others.

Also explains in the README why no recogniser can be a package dependency:
Policy forbids anything in the archive from requiring software outside it,
and a postinst that fetched from PyPI would break offline and reproducible
installs. Notes that a pip --user install still works with a .deb-installed
bandsaunter, since the user site directory is on the system interpreter's
path -- checked against the built package rather than assumed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
The Dust Council 2026-08-21 21:13:22 -07:00
parent 52fe16123f
commit 16f3128690
2 changed files with 34 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

35
README.md
View file

@ -59,7 +59,7 @@ be built.
| **required** | PyYAML | `python3-yaml` | `python3-pyyaml` | `python-yaml` | settings file and profiles |
| *recommended* | eSpeak NG | `espeak-ng` | `espeak-ng` | `espeak-ng` | clearer spoken timestamps |
| *optional* | rtl-sdr tools | `rtl-sdr` | `rtl-sdr` | `rtl-sdr` | `rtl_test` and friends for diagnosis |
| *optional* | faster-whisper | pip only | pip only | AUR | transcribing speech to text |
| *optional* | a speech recogniser | **pip only** | **pip only** | AUR | transcribing speech to text |
| *optional* | Matplotlib | `python3-matplotlib` | `python3-matplotlib` | `python-matplotlib` | nothing yet; reserved for plots |
Two notes on the optional ones:
@ -69,9 +69,9 @@ timestamps come from a built-in formant synthesiser, so that feature works on
a machine with nothing else installed. With it they are clearer and render
about three times faster.
**Speech recognition is not packaged for Debian** and can only come from pip.
Transcription is off by default and says so plainly when no recogniser is
present, so this never blocks an install:
**No speech recogniser is packaged for Debian.** `faster-whisper`, `vosk` and
the pocketsphinx Python bindings are all absent from the archive, so
transcription can only be installed with pip:
```bash
pip install faster-whisper # best on radio audio, ~120 MB
@ -79,6 +79,33 @@ pip install vosk # ~10 MB plus a 40 MB model, weaker on noise
bandsaunter transcribe --engines
```
That is why transcription is `Suggests:` rather than `Depends:` in the
package. Debian Policy forbids anything in the archive from requiring
software outside it, and a `postinst` that reaches out to PyPI would break
offline and reproducible installs — so a package simply cannot pull these in.
Transcription is therefore off by default and reports plainly when no
recogniser is present, rather than the install failing or the feature
appearing broken.
Mixing the two is nonetheless fine here. Modern Debian marks the system
Python as externally managed (PEP 668), so a pip install lands in your user
site directory:
```bash
pip install --user faster-whisper # ~/.local/lib/python3.x/site-packages
```
which is on `sys.path` for the system interpreter. A bandsaunter installed
from the `.deb` into `/usr/lib/python3/dist-packages` picks it up with no
further configuration — verified, not assumed. A virtual environment works
too, as long as bandsaunter runs inside it.
If you would rather keep everything under apt, the only route is packaging a
recogniser for Debian yourself. That is a real undertaking for whisper: it
would mean packaging ctranslate2, tokenizers, onnxruntime and their
dependencies, several of which are large C++ or Rust projects. It is why
none of them are there.
### Other distributions
```bash