bandsaunter/tests/test_transcribe.py
The Dust Council 739a2faaf4 Detect callsigns in transcripts, and say whose they are
Under the transcript, headed DETECTED CALLSIGNS:, every callsign heard in
it with the name and location on its licence.

Finding them is not one regular expression over the text as written.  A
speech recogniser is poor at callsigns -- they are not words, they are
said one character at a time -- so it breaks them wherever the speaker
paused and writes the phonetic alphabet down verbatim.  The recording that
prompted this has "Alright, KU 0W" in it, with a space; spelled out it
would have been "kilo uniform zero whiskey".  All three forms read back to
KU0W.

Not inventing them matters more.  A run of words is accepted only when
none of its parts is an ordinary English word: "or 3. Can you open 4" and
"CC1 boy", both from real transcripts here, fit the shape once the
punctuation is gone and are not callsigns.  A single token said in one
breath is still trusted, because W1BOY is a perfectly good callsign, and a
lone "a" or "i" cannot start a join or "a B4U player" becomes AB4U.
Across the 126 transcripts in the recordings directory that turns three
candidates into the one that was actually said.

Lookups use the FCC's own licence data at callook.info -- no account, no
key, the callsign the only thing sent.  They never delay the display: the
entry reads "looking up" and fills itself in, and results are cached under
~/.cache so a net recorded night after night is looked up once.
--no-lookup contacts nothing and still describes a callsign from its own
structure, the ITU prefix giving the country and the digit the US
district, which is also all there is to say for callsigns outside the US.
--callsigns prints everyone who identified themselves and where they were
heard.

Also asked: are transcripts appended to, or overwritten, when another
transmission arrives on the same frequency?  Neither could be shown from
reading the code alone, so there are now three tests that run real scans
and look at the files.  By default each transmission has a transcript of
its own -- the timestamp is in the name, so two overs cannot land on one
file.  With --combine there is one recording per frequency and therefore
one transcript, opened for append with the time of each over; a second
scan into the same directory adds to it rather than starting it over,
which is the case the last of the three tests covers.

The browser and callsign tests refuse to reach the network at all.  One
test did, quietly, and passed -- visible only because the assertion it
failed printed a real operator's address.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016PsWPTweCT6pwxKngvVxcg
2026-08-22 15:41:02 -07:00

493 lines
21 KiB
Python

"""Speech to text: the engine plumbing, and how captures reach it."""
import sys
import time
from datetime import datetime
from pathlib import Path
import numpy as np
import re
import pytest
from bandsaunter import transcribe as tr
from bandsaunter.config import ScanConfig
from bandsaunter.ranges import parse_range_list
from bandsaunter.scanner import Scanner, ScannerCallbacks
from bandsaunter.simulator import SimulatedDevice, VirtualTransmitter as V
@pytest.fixture
def fake_engine(monkeypatch):
"""A recogniser that reports what it was given, so the plumbing is testable
on a machine with none installed."""
seen = []
def engine(audio, rate, model, language):
seen.append({"samples": audio.size, "rate": rate, "model": model,
"language": language})
return tr.Transcript(text="this is the transcribed text",
engine="fake", language=language or "en")
monkeypatch.setitem(tr._DISPATCH, "fake", engine)
monkeypatch.setattr(tr, "ENGINES", ("fake",) + tr.ENGINES)
monkeypatch.setattr(tr, "_is_present", lambda name: name == "fake")
return seen
def _speech(seconds=3.0, rate=16000):
import sys
sys.path.insert(0, str(Path(__file__).parent))
from speech import synth_speech
return synth_speech(seconds, rate, 120, 0)
# ---------------------------------------------------------------------------
# Engines
# ---------------------------------------------------------------------------
def test_no_engine_reports_rather_than_failing(monkeypatch):
"""Every capture failing noisily would be worse than saying so once."""
monkeypatch.setattr(tr, "_is_present", lambda name: False)
assert tr.available_engine() is None
assert tr.transcribe(np.zeros(1000, np.float32), 16000) is None
def test_engine_listing_is_complete():
listed = {name for name, _, _ in tr.describe_engines()}
assert listed == set(tr.ENGINES)
for _, _, how in tr.describe_engines():
assert how, "every engine should say how to get it"
def test_a_failing_engine_is_reported_not_raised(monkeypatch):
def boom(audio, rate, model, language):
raise RuntimeError("model file is corrupt")
monkeypatch.setitem(tr._DISPATCH, "fake", boom)
monkeypatch.setattr(tr, "_is_present", lambda name: name == "fake")
result = tr.transcribe(np.zeros(16000, np.float32), 16000, engine="fake")
assert result is not None and not result
assert "corrupt" in result.note
def test_audio_is_resampled_to_what_the_engines_expect(fake_engine):
for rate in (8000, 16000, 32000, 48000):
tr.transcribe(np.zeros(int(rate * 2), np.float32), rate, engine="fake")
assert [s["samples"] for s in fake_engine] == [32000] * 4
def test_the_model_and_language_reach_the_engine(fake_engine):
tr.transcribe(np.zeros(16000, np.float32), 16000, engine="fake",
model="small.en", language="fr")
assert fake_engine[-1]["model"] == "small.en"
assert fake_engine[-1]["language"] == "fr"
# ---------------------------------------------------------------------------
# The worker
# ---------------------------------------------------------------------------
def _drain(worker, timeout=20.0):
worker.close(timeout=timeout)
def test_worker_writes_a_transcript_beside_the_recording(tmp_path, fake_engine):
worker = tr.TranscriptionWorker(engine="fake")
worker.start()
out = tmp_path / "0146.520000MHz--2026-08-21_12_00_00-nfm_transcription.txt"
worker.submit(_speech(), 16000, out, datetime(2026, 8, 21, 12, 0, 0),
146.52e6)
_drain(worker)
assert out.exists()
assert "transcribed text" in out.read_text()
assert worker.written == 1
def test_worker_appends_with_a_timestamp_when_combining(tmp_path, fake_engine):
worker = tr.TranscriptionWorker(engine="fake")
worker.start()
out = tmp_path / "0146.520000MHz_transcription.txt"
for minute in (0, 5, 9):
worker.submit(_speech(), 16000, out,
datetime(2026, 8, 21, 12, minute, 0), 146.52e6,
append=True)
_drain(worker)
lines = out.read_text().strip().split("\n")
assert len(lines) == 3
assert lines[0].startswith("[2026-08-21 12:00:00] ")
assert lines[2].startswith("[2026-08-21 12:09:00] ")
def test_nothing_recognised_writes_no_file_at_all(tmp_path, monkeypatch):
"""A directory of placeholder files is worse than no file."""
monkeypatch.setitem(tr._DISPATCH, "fake",
lambda a, r, m, l: tr.Transcript(text="", engine="fake"))
monkeypatch.setattr(tr, "_is_present", lambda name: name == "fake")
worker = tr.TranscriptionWorker(engine="fake")
worker.start()
out = tmp_path / "quiet_transcription.txt"
worker.submit(np.zeros(16000, np.float32), 16000, out, datetime.now(), 1e6)
_drain(worker)
assert not out.exists()
assert not list(tmp_path.iterdir())
assert worker.empty == 1 and worker.written == 0
def test_whitespace_only_speech_writes_no_file(tmp_path, monkeypatch):
monkeypatch.setitem(tr._DISPATCH, "fake",
lambda a, r, m, l: tr.Transcript(text=" \n ",
engine="fake"))
monkeypatch.setattr(tr, "_is_present", lambda name: name == "fake")
worker = tr.TranscriptionWorker(engine="fake")
worker.start()
out = tmp_path / "blank_transcription.txt"
worker.submit(np.zeros(16000, np.float32), 16000, out, datetime.now(), 1e6)
_drain(worker)
assert not out.exists() and worker.empty == 1
def test_an_empty_result_adds_no_line_when_combining(tmp_path, monkeypatch):
"""Combined transcripts must not fill up with empty timestamps."""
texts = iter(["something was said", "", "and something else"])
monkeypatch.setitem(tr._DISPATCH, "fake",
lambda a, r, m, l: tr.Transcript(text=next(texts),
engine="fake"))
monkeypatch.setattr(tr, "_is_present", lambda name: name == "fake")
worker = tr.TranscriptionWorker(engine="fake")
worker.start()
out = tmp_path / "0146.520000MHz_transcription.txt"
for minute in (0, 5, 9):
worker.submit(np.zeros(16000, np.float32), 16000, out,
datetime(2026, 8, 21, 12, minute, 0), 1e6, append=True)
_drain(worker)
lines = out.read_text().strip().split("\n")
assert len(lines) == 2, lines
assert "12:00:00" in lines[0] and "12:09:00" in lines[1]
def test_worker_does_not_hold_up_the_caller(tmp_path, monkeypatch):
"""Recognition takes seconds; a scan must not wait for it."""
def slow(audio, rate, model, language):
time.sleep(1.0)
return tr.Transcript(text="eventually", engine="fake")
monkeypatch.setitem(tr._DISPATCH, "fake", slow)
monkeypatch.setattr(tr, "_is_present", lambda name: name == "fake")
worker = tr.TranscriptionWorker(engine="fake")
worker.start()
started = time.perf_counter()
for i in range(3):
worker.submit(_speech(), 16000, tmp_path / f"{i}.txt", datetime.now(),
1e6)
assert time.perf_counter() - started < 0.5, "submitting blocked"
_drain(worker)
assert worker.written == 3
def test_a_full_queue_is_counted_not_blocked(tmp_path, monkeypatch):
def slow(audio, rate, model, language):
time.sleep(0.4)
return tr.Transcript(text="x", engine="fake")
monkeypatch.setitem(tr._DISPATCH, "fake", slow)
monkeypatch.setattr(tr, "_is_present", lambda name: name == "fake")
worker = tr.TranscriptionWorker(engine="fake", max_queue=2)
worker.start()
accepted = sum(worker.submit(_speech(0.5), 16000, tmp_path / f"{i}.txt",
datetime.now(), 1e6) for i in range(12))
assert accepted < 12 and worker.dropped > 0
_drain(worker)
def test_empty_audio_is_not_submitted(tmp_path, fake_engine):
worker = tr.TranscriptionWorker(engine="fake")
worker.start()
assert not worker.submit(np.zeros(0, np.float32), 16000,
tmp_path / "x.txt", datetime.now(), 1e6)
_drain(worker)
assert worker.written == 0
# ---------------------------------------------------------------------------
# Through a scan
# ---------------------------------------------------------------------------
def _scan(tmp_path, transmitters, **over):
cfg = ScanConfig(ranges=parse_range_list("146.4M-146.6M"),
output_dir=str(tmp_path), record_seconds=4.0,
hang_seconds=1.0, threshold_db=12, dwell_seconds=0.05,
max_cycles=1, revisit_seconds=0.2, transcribe=True,
transcribe_engine="fake")
for k, v in over.items():
setattr(cfg, k, v)
hits = []
scanner = Scanner(cfg, device=SimulatedDevice(transmitters=transmitters).open(),
callbacks=ScannerCallbacks(on_record_end=hits.append))
scanner.prepare()
scanner.run()
return scanner, [h for h in hits if h.kept]
def test_a_voice_capture_is_transcribed(tmp_path, fake_engine, monkeypatch):
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(tmp_path, [V(146_520_000, "nfm", 0.4, 12_500, "v")])
assert hits and hits[0].category == "voice"
written = list(tmp_path.glob("*_transcription.txt"))
assert written, "no transcript written"
assert written[0].stem.startswith(hits[0].filename)
assert "transcribed text" in written[0].read_text()
def test_morse_and_data_are_not_transcribed(tmp_path, fake_engine, monkeypatch):
"""Running a recogniser over CW or a data burst wastes seconds per capture."""
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(tmp_path, [
V(146_520_000, "fsk4", 0.4, 12_500, "data", baud=4800, deviation=1800)])
assert hits and hits[0].category == "digital"
assert not list(tmp_path.glob("*_transcription.txt"))
def test_short_captures_are_skipped(tmp_path, fake_engine, monkeypatch):
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(tmp_path, [V(146_520_000, "nfm", 0.4, 12_500, "v")],
transcribe_min_seconds=60.0)
assert hits
assert not list(tmp_path.glob("*_transcription.txt"))
def test_the_transcript_is_recorded_in_the_metadata(tmp_path, fake_engine,
monkeypatch):
import json
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(tmp_path, [V(146_520_000, "nfm", 0.4, 12_500, "v")])
meta = json.loads(Path(hits[0].meta_path).read_text())
assert meta["hit"]["transcript_path"].endswith("_transcription.txt")
assert "transcribed text" in meta["hit"]["transcript"]
def test_the_metadata_never_names_a_transcript_that_was_not_written(
tmp_path, monkeypatch):
"""Recording a path for a file that never appears would be a lie."""
import json
monkeypatch.setitem(tr._DISPATCH, "fake",
lambda a, r, m, l: tr.Transcript(text="", engine="fake"))
monkeypatch.setattr(tr, "_is_present", lambda name: name == "fake")
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(tmp_path, [V(146_520_000, "nfm", 0.4, 12_500, "v")])
assert hits
assert not list(tmp_path.glob("*_transcription.txt"))
meta = json.loads(Path(hits[0].meta_path).read_text())
assert not meta["hit"].get("transcript_path")
def test_combined_recordings_get_one_transcript_per_frequency(tmp_path,
fake_engine,
monkeypatch):
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(
tmp_path, [V(146_520_000, "nfm", 0.4, 12_500, "v")],
combine_by_frequency=True, announce_timestamps=False,
record_seconds=2.0, max_cycles=3, revisit_seconds=0.05)
assert len(hits) >= 2
written = list(tmp_path.glob("*_transcription.txt"))
assert len(written) == 1, written
lines = written[0].read_text().strip().split("\n")
assert len(lines) == len(hits)
assert all(line.startswith("[") for line in lines)
def test_transcription_off_writes_nothing(tmp_path, fake_engine, monkeypatch):
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(tmp_path, [V(146_520_000, "nfm", 0.4, 12_500, "v")],
transcribe=False)
assert hits
assert not list(tmp_path.glob("*_transcription.txt"))
def test_missing_engine_says_so_once(tmp_path, monkeypatch):
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: None)
notes = []
cfg = ScanConfig(ranges=parse_range_list("146.4M-146.6M"),
output_dir=str(tmp_path), record_seconds=2.0,
threshold_db=12, max_cycles=1, transcribe=True)
scanner = Scanner(cfg,
device=SimulatedDevice(transmitters=[
V(146_520_000, "nfm", 0.4, 12_500, "v")]).open(),
callbacks=ScannerCallbacks(on_status=notes.append))
scanner.prepare()
scanner.run()
assert any("no speech recogniser" in n for n in notes), notes
assert scanner.transcriber is None
# ---------------------------------------------------------------------------
# Installed engines, when there are any
# ---------------------------------------------------------------------------
INSTALLED = tr.available_engine()
needs_engine = pytest.mark.skipif(INSTALLED is None,
reason="no speech recogniser installed")
@needs_engine
def test_an_installed_engine_recognises_synthesised_speech():
"""Round trip: say something, then read it back off the audio."""
from bandsaunter.announce import say
audio = say("one two three four five six seven eight nine", 16000)
result = tr.transcribe(audio, 16000, engine="auto",
model="base.en", language="en")
assert result is not None
assert not result.note, result.note
# Engines are free to write numbers as digits, and whisper does.
text = result.text.lower()
spelled = ("one", "two", "three", "four", "five", "six", "seven",
"eight", "nine")
hits = sum((word in text) or (str(i) in text)
for i, word in enumerate(spelled, 1))
assert hits >= 4, f"only {hits} of nine numbers recognised: {result.text!r}"
@needs_engine
@pytest.mark.parametrize("rate", [8000, 16000, 32000])
def test_an_installed_engine_copes_with_any_rate(rate):
from bandsaunter.announce import say
audio = say("testing one two three", rate)
result = tr.transcribe(audio, rate, engine="auto", model="base.en",
language="en")
assert result is not None and not result.note, result.note
@needs_engine
def test_silence_produces_no_transcript_rather_than_invention():
result = tr.transcribe(np.zeros(16000 * 3, np.float32), 16000,
engine="auto", model="base.en", language="en")
assert result is not None
assert not result.text.strip(), f"invented {result.text!r} from silence"
@pytest.mark.skipif(not tr._is_present("vosk"), reason="vosk not installed")
def test_vosk_falls_back_when_given_a_whisper_model_name():
"""The model setting is shared with whisper, whose names are not paths."""
from bandsaunter.announce import say
result = tr.transcribe(say("one two three", 16000), 16000, engine="vosk",
model="base.en", language="en")
assert result is not None
assert not result.note, result.note
@pytest.mark.skipif(not tr._is_present("vosk"), reason="vosk not installed")
def test_vosk_accepts_the_plain_language_code():
"""Vosk names its models by region and rejects a bare "en"."""
from bandsaunter.announce import say
result = tr.transcribe(say("one two three", 16000), 16000, engine="vosk",
language="en")
assert result is not None and not result.note, result.note
# --- packaged engine and models -------------------------------------------
def test_a_packaged_model_is_used_in_place_of_its_name(tmp_path, monkeypatch):
""""base.en" should mean the copy on this machine when one is installed."""
monkeypatch.setattr(tr, "MODEL_DIR", tmp_path)
(tmp_path / "base.en").mkdir()
assert tr.resolve_model("base.en") == str(tmp_path / "base.en")
def test_an_unpackaged_model_keeps_its_name_to_be_downloaded(tmp_path, monkeypatch):
monkeypatch.setattr(tr, "MODEL_DIR", tmp_path)
assert tr.resolve_model("small.en") == "small.en"
assert tr.resolve_model("") == ""
def test_an_explicit_model_directory_wins_over_the_packaged_one(tmp_path, monkeypatch):
packaged = tmp_path / "packaged"
(packaged / "base.en").mkdir(parents=True)
monkeypatch.setattr(tr, "MODEL_DIR", packaged)
mine = tmp_path / "base.en"
mine.mkdir()
assert tr.resolve_model(str(mine)) == str(mine)
def test_the_vendored_engine_is_searched_after_the_system_one(tmp_path, monkeypatch):
"""Anything apt provides must still win; the vendor copy fills a gap."""
monkeypatch.setattr(sys, "path", list(sys.path))
monkeypatch.setattr(tr, "VENDOR_DIR", tmp_path)
tr._add_vendor_path()
assert sys.path[-1] == str(tmp_path)
def test_the_vendor_path_is_added_once(tmp_path, monkeypatch):
monkeypatch.setattr(sys, "path", list(sys.path))
monkeypatch.setattr(tr, "VENDOR_DIR", tmp_path)
tr._add_vendor_path()
tr._add_vendor_path()
assert sys.path.count(str(tmp_path)) == 1
def test_a_missing_vendor_directory_is_not_added(tmp_path, monkeypatch):
monkeypatch.setattr(sys, "path", list(sys.path))
monkeypatch.setattr(tr, "VENDOR_DIR", tmp_path / "absent")
tr._add_vendor_path()
assert str(tmp_path / "absent") not in sys.path
# ---------------------------------------------------------------------------
# Two transmissions on one frequency
# ---------------------------------------------------------------------------
def test_each_transmission_gets_a_transcript_of_its_own(tmp_path, fake_engine,
monkeypatch):
"""The default is one file per transmission, named after it. Nothing is
overwritten because nothing is shared: the timestamp is in the name, so
two overs on one frequency cannot land on one file."""
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(tmp_path, [V(146_520_000, "nfm", 0.4, 12_500, "v")],
record_seconds=2.0, max_cycles=3,
revisit_seconds=0.05)
assert len(hits) >= 2, "only one transmission was captured"
texts = sorted(tmp_path.glob("*_transcription.txt"))
assert len(texts) == len(hits), [p.name for p in texts]
for path in texts:
assert "transcribed text" in path.read_text()
# One transmission, one line. More than one would mean two captures
# had collided on a single name.
assert len(path.read_text().strip().split("\n")) == 1, path.name
def test_combining_appends_every_over_to_one_file(tmp_path, fake_engine,
monkeypatch):
"""With --combine there is one recording per frequency, so there is one
transcript per frequency, and each over is added to the end of it with the
time it was heard."""
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
scanner, hits = _scan(tmp_path, [V(146_520_000, "nfm", 0.4, 12_500, "v")],
combine_by_frequency=True,
announce_timestamps=False, record_seconds=2.0,
max_cycles=3, revisit_seconds=0.05)
assert len(hits) >= 2
texts = list(tmp_path.glob("*_transcription.txt"))
assert len(texts) == 1, [p.name for p in texts]
lines = [ln for ln in texts[0].read_text().strip().split("\n") if ln]
assert len(lines) == len(hits)
for line in lines:
assert re.match(r"^\[\d{4}-\d\d-\d\d \d\d:\d\d:\d\d\] ", line), line
def test_a_later_run_never_truncates_an_earlier_transcript(tmp_path,
fake_engine,
monkeypatch):
"""The question this answers: can a later transmission on the same
frequency wipe out an earlier one's words? The combined file is opened
for append, and it is the only transcript two captures ever share, so an
unattended receiver adds to it night after night rather than starting it
over."""
monkeypatch.setattr("bandsaunter.scanner.available_engine", lambda: "fake")
args = dict(combine_by_frequency=True, announce_timestamps=False,
record_seconds=2.0, max_cycles=2, revisit_seconds=0.05)
tx = [V(146_520_000, "nfm", 0.4, 12_500, "v")]
_scan(tmp_path, tx, **args)
combined = next(iter(tmp_path.glob("*_transcription.txt")))
before = combined.read_text()
assert before.strip()
_scan(tmp_path, tx, **args) # a second run into the same directory
after = combined.read_text()
assert after.startswith(before), "the earlier transcript was overwritten"
assert len(after) > len(before), "the later over was not added"