diff --git a/README.md b/README.md index 172869d..26f5e8f 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/bandsaunter/transcribe.py b/bandsaunter/transcribe.py index a91ad76..6e1b06a 100644 --- a/bandsaunter/transcribe.py +++ b/bandsaunter/transcribe.py @@ -43,7 +43,9 @@ _ENGINE_NOTES = { "whisper": "pip install openai-whisper", "whisper-cli": "whisper.cpp, no Python dependencies", "vosk": "pip install vosk (small, weaker on noisy audio)", - "pocketsphinx": "apt install pocketsphinx (tiny, poor on radio audio)", + # Debian ships the pocketsphinx tools and library but not the Python + # bindings, so apt does not give a working engine here. + "pocketsphinx": "pip install pocketsphinx (tiny, poor on radio audio)", }