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

tests/test_browse.py

@@ -19,6 +19,7 @@ from rich.console import Console
 
 from bandsaunter.browse import (Browser, Player, PLAYERS, Keyboard, main,
                                 scan_directory)
+from bandsaunter.callsign import CallsignBook
 
 
 # -- fixtures ----------------------------------------------------------------
@@ -51,6 +52,7 @@ def make_capture(directory: Path, mhz: float, when: str, mode: str,
 @pytest.fixture
 def library(tmp_path):
     """A small recordings directory covering the cases that render differently."""
+    # The transcript names a callsign, as a real one from a net would.
     make_capture(tmp_path, 146.52, "2026-08-22_10_00_00", "nfm", 4.0,
                  transcript="Net control, this is W1AW, standing by.",
                  meta={"category": "voice", "snr_db": 21.5,
@@ -68,6 +70,20 @@ def library(tmp_path):
     return tmp_path
 
 
+@pytest.fixture(autouse=True)
+def no_network(monkeypatch):
+    """No test in this file may contact the licence database.
+
+    One did, silently, and passed -- it was only visible because the assertion
+    it failed printed a real operator's address.  A stub that is forgotten
+    should fail loudly rather than work.
+    """
+    def refuse(self, call):
+        raise AssertionError(f"a test tried to look up {call} for real")
+
+    monkeypatch.setattr(CallsignBook, "_request", refuse)
+
+
 def browser(directory, width=100, height=30, player=None) -> Browser:
     console = Console(width=width, height=height, force_terminal=True)
     return Browser(directory, console=console,
@@ -655,3 +671,172 @@ def test_the_output_directory_is_found_without_being_told(monkeypatch,
     monkeypatch.setenv("BANDSAUNTER_OUTPUT", str(tmp_path))
     from bandsaunter.browse import default_directory
     assert default_directory() == tmp_path
+
+
+# -- detected callsigns ------------------------------------------------------
+
+class StubBook(CallsignBook):
+    """Answers lookups from a dict, so no test touches the network."""
+
+    def __init__(self, answers=None, tmp=None, **kw):
+        self.answers = answers or {}
+        self.requested = []
+        super().__init__(cache=(tmp or Path("/nonexistent")) / "c.json", **kw)
+
+    def _request(self, call):
+        self.requested.append(call)
+        if call not in self.answers:
+            raise OSError("offline")
+        return self.answers[call]
+
+
+KU0W = {
+    "status": "VALID", "type": "PERSON", "name": "ROD R GOWDY",
+    "current": {"callsign": "KU0W", "operClass": "EXTRA"},
+    "previous": {"callsign": ""}, "trustee": {"callsign": ""},
+    "address": {"line2": "TUCSON, AZ 85742"},
+    "location": {"gridsquare": "DM42lj"},
+    "otherInfo": {"expiryDate": "08/09/2034"},
+}
+
+
+@pytest.fixture
+def net(tmp_path):
+    """A directory whose transcript names a callsign, and a stubbed lookup."""
+    make_capture(tmp_path, 146.52, "2026-08-22_10_00_00", "nfm", 4.0,
+                 transcript="Net control, this is KU 0W, standing by.",
+                 meta={"category": "voice", "classification": "NFM voice"})
+    return tmp_path
+
+
+def net_browser(directory, tmp, answers=None, **kw):
+    b = browser(directory, **kw)
+    b.book = StubBook(answers if answers is not None else {"KU0W": KU0W},
+                      tmp=tmp)
+    return b
+
+
+def test_callsigns_are_listed_under_the_transcript(net, tmp_path):
+    b = net_browser(net, tmp_path)
+    b.book.get("KU0W")
+    b.book.wait(5)
+    out = frame(b)
+    head, _, rest = out.partition("recordings in")
+    assert "DETECTED CALLSIGNS:" in head
+    assert "KU0W" in head
+    assert "Rod R Gowdy" in head and "Tucson, AZ" in head
+    # Under the words, not above them.
+    assert head.index("standing by") < head.index("DETECTED CALLSIGNS:")
+
+
+def test_a_callsign_broken_by_the_recogniser_is_still_found(net, tmp_path):
+    """The transcript says "KU 0W"; the licence is under KU0W."""
+    cap = scan_directory(net)[0]
+    assert cap.callsigns == ["KU0W"]
+
+
+def test_the_lookup_is_shown_as_pending_before_it_lands(net, tmp_path):
+    class Slow(StubBook):
+        def _request(self, call):
+            time.sleep(1.0)
+            return super()._request(call)
+
+    b = browser(net)
+    b.book = Slow({"KU0W": KU0W}, tmp=tmp_path)
+    assert "looking up" in frame(b)
+
+
+def test_a_transcript_with_no_callsign_has_no_block(tmp_path):
+    make_capture(tmp_path, 146.52, "2026-08-22_10_00_00", "nfm",
+                 transcript="the meeting is at seven on the fourth Saturday",
+                 meta={"category": "voice"})
+    assert "DETECTED CALLSIGNS" not in frame(browser(tmp_path))
+
+
+def test_a_callsign_that_cannot_be_looked_up_still_appears(net, tmp_path):
+    """Offline, the prefix still says which country and district it is."""
+    b = net_browser(net, tmp_path, answers={})
+    b.book.get("KU0W")
+    b.book.wait(5)
+    out = frame(b)
+    assert "KU0W" in out and "United States" in out
+
+
+def test_the_callsigns_survive_a_transcript_too_long_for_the_panel(tmp_path):
+    """Whatever else is squeezed, the callsigns stay: they are the part of the
+    panel that cannot be recovered by listening to the recording."""
+    make_capture(tmp_path, 146.52, "2026-08-22_10_00_00", "nfm",
+                 transcript="KU0W " + " ".join(f"word{i}" for i in range(400)),
+                 meta={"category": "voice"})
+    b = net_browser(tmp_path, tmp_path, height=22)
+    b.book.get("KU0W")
+    b.book.wait(5)
+    out = frame(b)
+    assert "DETECTED CALLSIGNS:" in out and "Rod R Gowdy" in out
+    assert "more line(s)" in out
+
+
+def test_the_reader_shows_them_at_the_end_of_the_words(tmp_path):
+    make_capture(tmp_path, 146.52, "2026-08-22_10_00_00", "nfm",
+                 transcript="KU0W " + " ".join(f"word{i}" for i in range(400)),
+                 meta={"category": "voice"})
+    b = net_browser(tmp_path, tmp_path, height=22)
+    b.book.get("KU0W")
+    b.book.wait(5)
+    b.handle("t")
+    assert "DETECTED CALLSIGNS" not in frame(b), "shown beside the middle"
+    b.handle("end")
+    assert "DETECTED CALLSIGNS:" in frame(b)
+
+
+def test_the_frame_still_fits_with_callsigns(net, tmp_path):
+    for height in (16, 20, 24, 40):
+        b = net_browser(net, tmp_path, height=height)
+        b.book.get("KU0W")
+        b.book.wait(5)
+        lines = frame(b).rstrip("\n").split("\n")
+        assert len(lines) <= height, f"{len(lines)} lines in {height}"
+
+
+def test_callsigns_are_found_once_per_recording(net):
+    cap = scan_directory(net)[0]
+    assert cap._calls is None
+    first = cap.callsigns
+    assert cap._calls is not None
+    assert cap.callsigns is first
+
+
+# -- the callsign command line -----------------------------------------------
+
+def test_callsigns_flag_reports_where_each_was_heard(net, capsys, monkeypatch):
+    monkeypatch.setattr("bandsaunter.browse.CallsignBook",
+                        lambda **kw: StubBook({"KU0W": KU0W}, tmp=net, **kw))
+    assert main(["--callsigns", str(net)]) == 0
+    out = capsys.readouterr().out
+    assert "KU0W" in out and "Rod R Gowdy" in out
+    assert "heard on" in out and "146.52 MHz" in out
+
+
+def test_callsigns_flag_says_so_when_there_are_none(tmp_path, capsys):
+    make_capture(tmp_path, 856.5625, "2026-08-22_11_00_00", "fsk", 2.0,
+                 meta={"category": "trunk"})
+    assert main(["--callsigns", str(tmp_path)]) == 1
+    assert "no callsigns" in capsys.readouterr().out
+
+
+def test_no_lookup_contacts_nothing(net, capsys, monkeypatch):
+    """The flag has to mean it: nothing leaves the machine."""
+    made = []
+
+    class Watching(StubBook):
+        def _request(self, call):
+            made.append(call)
+            return super()._request(call)
+
+    monkeypatch.setattr("bandsaunter.browse.CallsignBook",
+                        lambda **kw: Watching({"KU0W": KU0W}, tmp=net, **kw))
+    assert main(["--callsigns", "--no-lookup", str(net)]) == 0
+    out = capsys.readouterr().out
+    assert made == [], "a request was made with --no-lookup"
+    assert "KU0W" in out
+    assert "United States" in out, "the prefix should still be described"