ka9q-python 3.17.0__tar.gz → 3.18.0__tar.gz

{ka9q_python-3.17.0 → ka9q_python-3.18.0}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [3.18.0] - 2026-06-28
+
+### Added
+
+- **`SlotClock` — epoch-aligned slot boundaries in RTP-timestamp space**
+  (`ka9q.slot_clock`). The canonical, drift-immune timing primitive for every
+  sigmond slot/period recorder (psk FT8/FT4, wspr WSPR/FST4W, meteor-scatter,
+  …). Slot boundaries are driven by radiod's GPSDO-disciplined RTP timestamp
+  (which advances exactly once per output sample of real time) rather than a
+  delivered-sample-count projection that silently drifts when the receive path
+  over/under-counts samples — the failure that labels a WAV with a UTC the audio
+  doesn't match and zeroes out decodes on good RF. Boundary stepping is exact
+  integer arithmetic (`cadence_sec * sample_rate` must be integer). Absolute
+  positions are tracked as an unwrapped 64-bit count relative to a monotonic
+  high-water, so harvesting keeps working past the 2³¹-sample signed-32 window
+  (~49.7 h @ 12 kHz / ~9.3 h @ 64 kHz IQ) — a long WSPR run no longer stalls.
+  Exposes `SlotClock`, `Slot`, and `rtp_diff` (Karn signed-32 difference).
+  Pure timing logic — owns no socket, ring, or thread.
+
+### Notes
+
+- This is the release that promotes `SlotClock` (previously parked) to public,
+  consumed API: the sigmond recorders are migrating their slot/period timing
+  onto it so an upstream timing fix lands once instead of being re-patched per
+  client. Pairs with `hamsci_dsp.timing.acquire_anchor_utc` (the shared RTP→UTC
+  anchor) on the sigmond side.
+
 ## [3.17.0] - 2026-06-28
 
 First release marked **Production/Stable** (trove classifier 4 → 5). Folds in

{ka9q_python-3.17.0/ka9q_python.egg-info → ka9q_python-3.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.17.0
+Version: 3.18.0
 Summary: Python interface for ka9q-radio control and monitoring
 Author-email: Michael Hauan AC0G <ac0g@hauan.org>
 License: MIT

{ka9q_python-3.17.0 → ka9q_python-3.18.0}/ka9q/__init__.py

@@ -115,6 +115,7 @@ from .managed_stream import (
     StreamState,
 )
 from .multi_stream import MultiStream
+from .slot_clock import SlotClock, Slot, rtp_diff
 from .spectrum_stream import SpectrumStream
 from .status_listener import StatusListener, StatusListenerStats
 
@@ -161,6 +162,11 @@ __all__ = [
     'rtp_to_utc',
     'rtp_to_wallclock',
     
+    # Slot timing (epoch-aligned, RTP-referenced)
+    'SlotClock',
+    'Slot',
+    'rtp_diff',
+
     # Stream API (sample-oriented)
     'RadiodStream',
     'StreamQuality',

ka9q_python-3.18.0/ka9q/slot_clock.py

@@ -0,0 +1,258 @@
+"""SlotClock — epoch-aligned slot boundaries in GPS-true RTP-timestamp space.
+
+The canonical, drift-immune timing primitive shared by every sigmond slot/
+period recorder (psk-recorder FT8/FT4, wspr-recorder WSPR/FST4W, hfdl, …).
+It exists because clients kept re-implementing slot timing on top of a
+*delivered-sample-count* projection, which silently drifts: if the receive
+path ever over- or under-counts samples relative to real time (gap-fill
+accounting, a late anchor, a dropped burst the resequencer mis-sizes), the
+projected UTC runs ahead of or behind the actual RF, the WAV gets a label
+that doesn't match its content, and decode_ft8/wsprd align to the wrong grid
+point → zero decodes on perfectly good audio.  A self-check built from the
+same delivered-count can't catch this — both sides move together.
+
+The fix, and this class's whole premise: **drive boundaries from the RTP
+timestamp radiod stamps on every packet.**  radiod's RTP counter is
+GPS/PPS-disciplined and advances by exactly one per output sample of real
+time, regardless of what the client's delivery bookkeeping does.  So:
+
+  * Anchor ONCE: map a single RTP timestamp to UTC via ``rtp_to_utc``
+    (the §18/METROLOGY RTP-reference rule — the only wall-clock-ish read).
+  * Every slot boundary is an epoch-aligned UTC instant (a multiple of the
+    cadence: FT8 :00/:15/:30/:45, FT4 every 7.5 s, WSPR every 120 s) whose
+    RTP timestamp is computed by integer arithmetic from the anchor.
+  * A slot is *complete* once the stream's latest RTP timestamp has passed
+    the slot's end (plus a small settle).  The sample window to extract is
+    expressed in RTP units, so it's immune to delivered-count drift.
+  * ``cadence_sec * sample_rate`` must be an integer number of samples
+    (true for every real mode: 15·12000, 7.5·12000, 120·12000, …), so
+    boundary-to-boundary stepping is exact integer arithmetic — no float
+    accumulation.
+
+RTP timestamps are unsigned 32-bit and wrap (~99 h at 12 kHz, ~16 h at
+64 kHz IQ).  All differences use Phil Karn's signed-32 technique so a wrap
+is just normal arithmetic.  Absolute RTP positions are tracked as an
+unwrapped 64-bit count off the anchor: a monotonic high-water offset is
+carried, and every wrapped timestamp is unwrapped *relative to that
+high-water* (not relative to the anchor).  This is what makes the offset
+correct for streams that run arbitrarily long past their anchor — a raw
+``anchor``-relative signed-32 diff would alias once the stream is more than
+2**31 samples (~49.7 h @ 12 kHz, ~9.3 h @ 64 kHz IQ) from the anchor, at
+which point ``advance`` would silently stop harvesting slots.  All real
+queries (the latest timestamp, a just-passed boundary) are within one slot
+of the high-water, so the unwrap is unambiguous.
+
+This class is pure timing logic — it owns no socket, ring, or thread.  The
+caller feeds it RTP timestamps and asks which slots are now complete.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass
+from typing import List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def rtp_diff(a: int, b: int) -> int:
+    """Signed 32-bit RTP timestamp difference ``a - b`` (Karn's technique).
+
+    Returns a value in [-2**31, 2**31) so timestamp wraps are handled as
+    ordinary arithmetic: positive => a is ahead of b.
+    """
+    d = (a - b) & 0xFFFFFFFF
+    if d >= 0x80000000:
+        d -= 0x100000000
+    return d
+
+
+@dataclass(frozen=True)
+class Slot:
+    """One completed, epoch-aligned slot.
+
+    index               monotonic slot counter from the anchor (k)
+    start_rtp           RTP timestamp of the first sample of the slot
+    start_utc           UTC of that first sample (epoch-aligned: multiple
+                        of cadence_sec to within <1 sample)
+    n_samples           number of samples in the slot (== cadence_samples)
+    """
+
+    index: int
+    start_rtp: int
+    start_utc: float
+    n_samples: int
+
+
+class SlotClock:
+    """Epoch-aligned slot boundaries tracked in RTP-timestamp space.
+
+    Usage::
+
+        clk = SlotClock(cadence_sec=15.0, sample_rate=12000)
+        clk.anchor(rtp_timestamp=first_rtp, utc=rtp_to_utc(first_rtp, ci))
+        ...
+        # as packets arrive, advance the high-water mark and harvest slots:
+        for slot in clk.advance(latest_rtp_timestamp):
+            samples = ring.extract_rtp(slot.start_rtp, slot.n_samples)
+            ...
+    """
+
+    def __init__(
+        self,
+        cadence_sec: float,
+        sample_rate: int,
+        settle_sec: float = 1.5,
+    ) -> None:
+        cadence_samples = cadence_sec * sample_rate
+        if abs(cadence_samples - round(cadence_samples)) > 1e-6:
+            raise ValueError(
+                f"cadence_sec * sample_rate must be an integer sample count; "
+                f"got {cadence_sec} * {sample_rate} = {cadence_samples}"
+            )
+        self.cadence_sec = float(cadence_sec)
+        self.sample_rate = int(sample_rate)
+        self.cadence_samples = int(round(cadence_samples))
+        self.settle_samples = int(round(settle_sec * sample_rate))
+
+        self._anchor_rtp: Optional[int] = None
+        self._anchor_utc: Optional[float] = None
+        # Absolute (unwrapped) RTP position of the most recent boundary we
+        # have already emitted, as an offset in samples from the anchor.
+        self._next_boundary_off: Optional[int] = None
+        self._next_index: int = 0
+        # Monotonic high-water unwrapped offset from the anchor.  Every
+        # ``offset_of_rtp`` unwraps relative to this (never the bare anchor),
+        # so positions stay correct past the 2**31-sample signed-32 window.
+        self._latest_off: int = 0
+
+    # ── anchoring ────────────────────────────────────────────────────
+
+    @property
+    def anchored(self) -> bool:
+        return self._anchor_rtp is not None
+
+    def reset(self) -> None:
+        """Drop the anchor so the next ``anchor()`` re-establishes the grid.
+
+        The monotonic slot index is preserved.  Callers that key a buffer by
+        ``offset_of_rtp`` MUST also discard that buffer, since offsets are
+        relative to the (now-cleared) anchor.
+        """
+        self._anchor_rtp = None
+        self._anchor_utc = None
+        self._next_boundary_off = None
+        self._latest_off = 0
+
+    def anchor(self, rtp_timestamp: int, utc: float) -> None:
+        """Pin (rtp_timestamp -> utc).  Call once; call again to re-anchor.
+
+        ``utc`` should come from ``ka9q.rtp_to_utc(rtp_timestamp, ci)``
+        so the whole grid is RTP/GPS-referenced.  Re-anchoring preserves the
+        monotonic slot index but recomputes the first upcoming boundary, so a
+        corrected anchor takes effect on the next clean boundary.
+        """
+        self._anchor_rtp = int(rtp_timestamp) & 0xFFFFFFFF
+        self._anchor_utc = float(utc)
+        # The anchor IS offset 0; the unwrap high-water restarts here.
+        self._latest_off = 0
+        # First epoch-aligned boundary at or after the anchor instant.
+        t0 = math.ceil(self._anchor_utc / self.cadence_sec) * self.cadence_sec
+        self._next_boundary_off = int(round((t0 - self._anchor_utc) * self.sample_rate))
+        logger.info(
+            "SlotClock(cadence=%.3fs, sr=%d): anchored rtp=%d utc=%.3f; "
+            "first boundary at utc=%.3f (+%d samples)",
+            self.cadence_sec, self.sample_rate, self._anchor_rtp,
+            self._anchor_utc, t0, self._next_boundary_off,
+        )
+
+    # ── projection helpers ───────────────────────────────────────────
+
+    def utc_of_offset(self, sample_off: int) -> float:
+        """UTC of the sample ``sample_off`` samples after the anchor."""
+        assert self._anchor_utc is not None
+        return self._anchor_utc + sample_off / self.sample_rate
+
+    def rtp_of_offset(self, sample_off: int) -> int:
+        """Wrapped 32-bit RTP timestamp ``sample_off`` samples after anchor."""
+        assert self._anchor_rtp is not None
+        return (self._anchor_rtp + sample_off) & 0xFFFFFFFF
+
+    def offset_of_rtp(self, rtp_timestamp: int) -> int:
+        """Unwrapped 64-bit sample offset from the anchor for a wrapped RTP ts.
+
+        Unwraps relative to the monotonic high-water (``_latest_off``), not the
+        bare anchor, so the result stays correct once the stream is more than
+        2**31 samples past the anchor.  Callers query this only for timestamps
+        near the stream's leading edge (the latest timestamp, or a boundary
+        within the last slot), which are always within one signed-32 window of
+        the high-water — so the unwrap is unambiguous.  Advances the high-water
+        when a query is ahead of it; never rewinds it on a stale/past query.
+        """
+        assert self._anchor_rtp is not None
+        ref_rtp = (self._anchor_rtp + self._latest_off) & 0xFFFFFFFF
+        off = self._latest_off + rtp_diff(rtp_timestamp, ref_rtp)
+        if off > self._latest_off:
+            self._latest_off = off
+        return off
+
+    # ── slot harvesting ──────────────────────────────────────────────
+
+    def advance(self, latest_rtp_timestamp: int) -> List[Slot]:
+        """Return every slot that has fully arrived as of ``latest_rtp``.
+
+        ``latest_rtp_timestamp`` is the RTP timestamp just past the newest
+        sample the caller holds (i.e. first_rtp + samples_buffered).  A slot
+        is complete once latest_rtp has passed slot_end + settle.  Boundaries
+        step by exact integer ``cadence_samples`` so no drift accumulates.
+        """
+        if self._anchor_rtp is None or self._next_boundary_off is None:
+            return []
+        latest_off = self.offset_of_rtp(latest_rtp_timestamp)
+        out: List[Slot] = []
+        while latest_off >= (
+            self._next_boundary_off + self.cadence_samples + self.settle_samples
+        ):
+            start_off = self._next_boundary_off
+            out.append(
+                Slot(
+                    index=self._next_index,
+                    start_rtp=self.rtp_of_offset(start_off),
+                    start_utc=self.utc_of_offset(start_off),
+                    n_samples=self.cadence_samples,
+                )
+            )
+            self._next_boundary_off = start_off + self.cadence_samples
+            self._next_index += 1
+        return out
+
+    # ── RTP-reference re-validation ──────────────────────────────────
+
+    def divergence_sec(self, channel_info, rtp_to_utc) -> Optional[float]:
+        """Grid-vs-GPS divergence at the next boundary, in seconds.
+
+        Recomputes the next boundary's true UTC straight from radiod's
+        (StatusListener-refreshed) ``channel_info`` via ``rtp_to_utc``
+        and compares it to the grid projection.  A sustained nonzero result
+        means the anchor is stale/wrong — the caller should ``anchor()``
+        again off the fresh reference.  Returns None if it can't be computed.
+
+        ``rtp_to_utc`` is passed in (rather than imported) so the caller binds
+        the exact projector it anchored with; ``ka9q.rtp_to_wallclock`` works
+        too as a deprecated alias of the same function.
+        """
+        if self._anchor_rtp is None or self._next_boundary_off is None:
+            return None
+        boundary_rtp = self.rtp_of_offset(self._next_boundary_off)
+        projected = self.utc_of_offset(self._next_boundary_off)
+        try:
+            ref = rtp_to_utc(
+                boundary_rtp, channel_info, wallclock_hint_sec=projected,
+            )
+        except Exception as exc:  # noqa: BLE001 — detection must not crash audio
+            logger.debug("SlotClock divergence check raised: %s", exc)
+            return None
+        if ref is None:
+            return None
+        return projected - ref

{ka9q_python-3.17.0 → ka9q_python-3.18.0/ka9q_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.17.0
+Version: 3.18.0
 Summary: Python interface for ka9q-radio control and monitoring
 Author-email: Michael Hauan AC0G <ac0g@hauan.org>
 License: MIT

{ka9q_python-3.17.0 → ka9q_python-3.18.0}/ka9q_python.egg-info/SOURCES.txt

@@ -49,6 +49,7 @@ ka9q/multi_stream.py
 ka9q/pps_calibrator.py
 ka9q/resequencer.py
 ka9q/rtp_recorder.py
+ka9q/slot_clock.py
 ka9q/spectrum_stream.py
 ka9q/status.py
 ka9q/status_listener.py
@@ -94,6 +95,7 @@ tests/test_protocol_compat.py
 tests/test_remove_channel.py
 tests/test_rtp_recorder.py
 tests/test_security_features.py
+tests/test_slot_clock.py
 tests/test_spectrum.py
 tests/test_ssrc_dest_unit.py
 tests/test_ssrc_encoding_unit.py

{ka9q_python-3.17.0 → ka9q_python-3.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ka9q-python"
-version = "3.17.0"
+version = "3.18.0"
 description = "Python interface for ka9q-radio control and monitoring"
 readme = "README.md"
 authors = [

ka9q_python-3.18.0/tests/test_slot_clock.py

@@ -0,0 +1,145 @@
+"""Unit tests for ka9q.slot_clock.SlotClock."""
+import math
+
+import pytest
+
+from ka9q.slot_clock import SlotClock, Slot, rtp_diff
+
+
+SR = 12000
+
+
+def test_rtp_diff_wrap():
+    assert rtp_diff(10, 5) == 5
+    assert rtp_diff(5, 10) == -5
+    # wrap: 2 just past 0xFFFFFFFE
+    assert rtp_diff(2, 0xFFFFFFFE) == 4
+    assert rtp_diff(0xFFFFFFFE, 2) == -4
+
+
+def test_rejects_non_integer_cadence():
+    # 7.4 s * 12000 = 88800 ok; 7.5*12000=90000 ok; but 0.0001 off must fail
+    SlotClock(7.5, SR)        # ok (90000 samples)
+    SlotClock(15.0, SR)       # ok
+    SlotClock(120.0, SR)      # ok
+    with pytest.raises(ValueError):
+        SlotClock(15.000001, SR)
+
+
+def test_cadence_samples():
+    assert SlotClock(15.0, SR).cadence_samples == 180000
+    assert SlotClock(7.5, SR).cadence_samples == 90000
+    assert SlotClock(120.0, SR).cadence_samples == 1440000
+
+
+def test_boundaries_epoch_aligned():
+    """First boundary lands on a cadence multiple of UTC, regardless of where
+    the anchor falls within a slot."""
+    clk = SlotClock(15.0, SR, settle_sec=0.0)
+    # anchor at an awkward 7.3 s into a slot: utc = 1000.000 ... pick utc not
+    # on a 15 s grid point.
+    anchor_utc = 1_000_000_007.3
+    clk.anchor(rtp_timestamp=0, utc=anchor_utc)
+    # next boundary utc must be a multiple of 15
+    boundary_utc = clk.utc_of_offset(clk._next_boundary_off)
+    assert abs((boundary_utc % 15.0)) < 1e-3 or abs((boundary_utc % 15.0) - 15.0) < 1e-3
+
+
+def test_advance_yields_aligned_slots_no_drift():
+    clk = SlotClock(15.0, SR, settle_sec=1.5)
+    # anchor exactly on a grid point for easy reasoning
+    clk.anchor(rtp_timestamp=1000, utc=1_000_000_005.0)  # 005 -> next boundary 015
+    # feed latest rtp far enough to complete several slots
+    # boundary0 offset = (15-5)*12000 = 120000 ; +cadence+settle to complete
+    slots = []
+    # advance in steps to simulate streaming
+    for secs in range(11, 80, 1):
+        latest_rtp = (1000 + secs * SR) & 0xFFFFFFFF
+        slots.extend(clk.advance(latest_rtp))
+    assert len(slots) >= 3
+    # every slot start_utc is a multiple of 15, and consecutive starts differ
+    # by EXACTLY cadence_samples (no float drift)
+    for s in slots:
+        assert abs(s.start_utc % 15.0) < 1e-3 or abs(s.start_utc % 15.0 - 15.0) < 1e-3
+        assert s.n_samples == 180000
+    for a, b in zip(slots, slots[1:]):
+        assert b.index == a.index + 1
+        # start_utc advances by exactly 15 s
+        assert abs((b.start_utc - a.start_utc) - 15.0) < 1e-9
+
+
+def test_advance_handles_rtp_wrap():
+    clk = SlotClock(15.0, SR, settle_sec=0.5)
+    # anchor near the 32-bit wrap
+    base = 0xFFFFFFFF - 5 * SR  # ~5 s before wrap
+    clk.anchor(rtp_timestamp=base & 0xFFFFFFFF, utc=1_000_000_000.0)
+    got = []
+    for secs in range(1, 60):
+        latest = (base + secs * SR) & 0xFFFFFFFF
+        got.extend(clk.advance(latest))
+    assert len(got) >= 2
+    for a, b in zip(got, got[1:]):
+        assert b.index == a.index + 1
+        assert abs((b.start_utc - a.start_utc) - 15.0) < 1e-9
+
+
+def test_offset_of_rtp_roundtrip():
+    clk = SlotClock(7.5, SR)
+    clk.anchor(rtp_timestamp=12345, utc=1_000.0)
+    off = 90000 * 3 + 17
+    rtp = clk.rtp_of_offset(off)
+    assert clk.offset_of_rtp(rtp) == off
+
+
+def test_long_run_past_signed32_window_keeps_harvesting():
+    """Regression: a stream running past 2**31 samples from the anchor must
+    keep harvesting slots.  A bare anchor-relative signed-32 diff aliases at
+    ~49.7 h @ 12 kHz and silently stops `advance` (real RF, no slots -> 0
+    decodes); the high-water unwrap must carry through it.
+
+    Steps the leading edge in 1-hour jumps (43.2M samples << 2**31, so each
+    individual unwrap is unambiguous) across the ~49.7 h boundary out to 55 h.
+    """
+    clk = SlotClock(15.0, SR, settle_sec=1.5)
+    clk.anchor(rtp_timestamp=0, utc=900_000_000.0)  # multiple of 15 -> boundary0 at offset 0
+    samples_per_hour = 3600 * SR  # 43,200,000  (< 2**31 = 2,147,483,648)
+    boundary_hour = (2 ** 31) / samples_per_hour  # ~49.7 h
+    last_index = -1
+    crossed = False
+    for hour in range(1, 56):
+        latest_off = hour * samples_per_hour
+        latest_rtp = latest_off & 0xFFFFFFFF
+        for s in clk.advance(latest_rtp):
+            # contiguous, monotonic indices and exact 15 s grid throughout
+            assert s.index == last_index + 1
+            assert abs(s.start_utc - (900_000_000.0 + s.index * 15.0)) < 1e-3
+            last_index = s.index
+        if hour > boundary_hour:
+            crossed = True
+            # still producing slots well past the old-bug cutoff
+            assert last_index > int(boundary_hour * 3600 / 15)
+    assert crossed
+    # 55 h / 15 s ≈ 13200 slots; we should be near the end, not stalled early
+    assert last_index > 13000
+
+
+def test_offset_of_rtp_unwraps_past_window():
+    """offset_of_rtp must return the true 64-bit offset past 2**31, not alias."""
+    clk = SlotClock(15.0, SR)
+    clk.anchor(rtp_timestamp=7, utc=900_000_000.0)
+    # walk the high-water forward in sub-2**31 steps to 3 billion samples
+    step = 2 ** 30  # 1,073,741,824
+    off = 0
+    for _ in range(3):
+        off += step
+        assert clk.offset_of_rtp((7 + off) & 0xFFFFFFFF) == off
+    assert off > 2 ** 31  # we genuinely crossed the signed-32 boundary
+
+
+def test_settle_delays_completion():
+    clk = SlotClock(15.0, SR, settle_sec=2.0)
+    clk.anchor(rtp_timestamp=0, utc=900_000_000.0)  # 900000000 % 15 == 0 -> boundary0 at offset 0
+    # slot0 spans [0,180000); completes only after 180000 + settle(24000)
+    assert clk.advance((180000 + 24000 - 1) & 0xFFFFFFFF) == []
+    slots = clk.advance((180000 + 24000 + 1) & 0xFFFFFFFF)
+    assert len(slots) == 1 and slots[0].index == 0