ka9q-python 3.14.1__tar.gz → 3.14.2__tar.gz

{ka9q_python-3.14.1 → ka9q_python-3.14.2}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [3.14.2] - 2026-05-14
+
+### Added
+
+- **`rtp_to_wallclock()` gains optional `wallclock_hint_sec` parameter.**
+  When supplied, the function uses the hint to disambiguate the 32-bit
+  RTP wrap epoch instead of calling `time.time()`.  Authority-aware
+  callers (those with access to an hf-timestd `rtp_to_utc_offset_ns`)
+  can now keep the labeling path off the chrony-disciplined system
+  clock, per the METROLOGY.md §4.5 RTP-reference invariant.  The hint
+  only needs ±period/2 accuracy (≥6 hours at typical sample rates).
+  When omitted, the function falls back to `time.time()` for backward
+  compatibility — existing callers are unaffected.
+
+### Tests
+
+- 3 new in `tests/test_rtp_recorder.py`: hint bypasses `time.time()`
+  entirely; hint at a different wrap epoch correctly overrides system
+  clock; default path still consults `time.time()` when no hint is
+  given.
+
 ## [3.14.1] - 2026-05-14
 
 ### Fixed

{ka9q_python-3.14.1/ka9q_python.egg-info → ka9q_python-3.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.14.1
+Version: 3.14.2
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G

{ka9q_python-3.14.1 → ka9q_python-3.14.2}/docs/API_REFERENCE.md

@@ -727,7 +727,11 @@ Dataclass: `packets_received`, `packets_dropped`,
 
 ```python
 parse_rtp_header(data: bytes) -> Optional[RTPHeader]
-rtp_to_wallclock(rtp_timestamp: int, channel: ChannelInfo) -> Optional[float]
+rtp_to_wallclock(
+    rtp_timestamp: int,
+    channel: ChannelInfo,
+    wallclock_hint_sec: Optional[float] = None,
+) -> Optional[float]
 ```
 
 `rtp_to_wallclock()` returns `None` unless `channel.gps_time` and
@@ -735,6 +739,17 @@ rtp_to_wallclock(rtp_timestamp: int, channel: ChannelInfo) -> Optional[float]
 `channel.chain_delay_correction_ns` is set (see below), it is
 subtracted from the computed wallclock.
 
+The `wallclock_hint_sec` parameter (v3.14.2+) lets callers supply an
+approximate UTC reference for 32-bit RTP wrap-epoch disambiguation
+without falling back to `time.time()`. Authority-aware callers
+(e.g. those reading `rtp_to_utc_offset_ns` from an `hf-timestd`
+authority.json) should pass this hint to keep the labeling path off
+the chrony-disciplined system clock (METROLOGY.md §4.5 RTP-reference
+invariant). The hint only needs ±period/2 accuracy (≥6 hours at
+typical sample rates), so even a coarse value is sufficient. When
+omitted, the function falls back to `time.time()` for backward
+compatibility.
+
 ---
 
 ## L6 BPSK PPS Calibration

{ka9q_python-3.14.1 → ka9q_python-3.14.2}/ka9q/__init__.py

@@ -56,7 +56,7 @@ Lower-level usage (explicit control):
         )
         print(f"Created channel with SSRC: {ssrc}")
 """
-__version__ = '3.14.1'
+__version__ = '3.14.2'
 __author__ = 'Michael Hauan AC0G'
 
 from .control import RadiodControl, allocate_ssrc

{ka9q_python-3.14.1 → ka9q_python-3.14.2}/ka9q/rtp_recorder.py

@@ -124,7 +124,11 @@ def parse_rtp_header(data: bytes) -> Optional[RTPHeader]:
     )
 
 
-def rtp_to_wallclock(rtp_timestamp: int, channel: ChannelInfo) -> Optional[float]:
+def rtp_to_wallclock(
+    rtp_timestamp: int,
+    channel: ChannelInfo,
+    wallclock_hint_sec: Optional[float] = None,
+) -> Optional[float]:
     """
     Convert RTP timestamp to Unix wall-clock time
 
@@ -133,6 +137,15 @@ def rtp_to_wallclock(rtp_timestamp: int, channel: ChannelInfo) -> Optional[float
     Args:
         rtp_timestamp: RTP timestamp from packet header
         channel: ChannelInfo with gps_time, rtp_timesnap, sample_rate
+        wallclock_hint_sec: Approximate UTC seconds, used solely to
+            disambiguate the 32-bit RTP wrap epoch (see below).  Must be
+            within ±period/2 of true UTC (period = 2**32 / sample_rate
+            seconds, ≥6 hours for typical sample rates).  When omitted,
+            falls back to ``time.time()`` — convenient but couples the
+            result to the host system clock.  Callers that have an
+            hf-timestd authority offset available should pass it
+            explicitly to keep the labeling path off the chrony-disciplined
+            system clock (METROLOGY.md §4.5 RTP-reference invariant).
 
     Returns:
         Unix timestamp (seconds) or None if timing info unavailable
@@ -149,10 +162,10 @@ def rtp_to_wallclock(rtp_timestamp: int, channel: ChannelInfo) -> Optional[float
 
         We disambiguate by picking the wrap-epoch count ``k`` (full
         2**32-sample periods elapsed since the snapshot) that places
-        the resulting wall-clock time closest to the local system
-        clock.  System clock stays within seconds of true UTC even
-        under hostile conditions, and the wrap ambiguity period is
-        hours, so this is robust without tight NTP discipline.
+        the resulting wall-clock time closest to ``wallclock_hint_sec``
+        (or ``time.time()`` if no hint was given).  Either source needs
+        only ±period/2 accuracy, so this stays robust even when the
+        hinting reference is loose.
 
         Observed on bee1 2026-05-08: long-running SSRCs caused TSL3
         SHM samples stuck at the snapshot's wall-clock time, ~12.4 h
@@ -181,7 +194,10 @@ def rtp_to_wallclock(rtp_timestamp: int, channel: ChannelInfo) -> Optional[float
     # value closest to the system clock.  Exact when sys clock is
     # within ±period/2 of true UTC.
     period_ns = BILLION * 0x100000000 // channel.sample_rate
-    sys_now_ns = int(time.time() * BILLION)
+    if wallclock_hint_sec is not None:
+        sys_now_ns = int(wallclock_hint_sec * BILLION)
+    else:
+        sys_now_ns = int(time.time() * BILLION)
     diff_ns = sys_now_ns - base_wall_ns
     if period_ns > 0:
         # Round-to-nearest of diff_ns / period_ns (Python `//` is

{ka9q_python-3.14.1 → ka9q_python-3.14.2/ka9q_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.14.1
+Version: 3.14.2
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G

{ka9q_python-3.14.1 → ka9q_python-3.14.2}/pyproject.toml

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

{ka9q_python-3.14.1 → ka9q_python-3.14.2}/tests/test_rtp_recorder.py

@@ -118,3 +118,67 @@ def test_rtp_to_wallclock_returns_none_when_timing_missing():
     assert rtp_to_wallclock(1000, channel) is None
     channel = _channel(48000, None, 1000)
     assert rtp_to_wallclock(1000, channel) is None
+
+
+def test_rtp_to_wallclock_hint_bypasses_system_clock():
+    """When `wallclock_hint_sec` is provided, time.time() must NOT be
+    consulted.  This is the RTP-reference invariant: authority-aware
+    callers can disambiguate the wrap epoch without coupling to the
+    host system clock."""
+    sample_rate = 96000
+    gps_time_ns = 1234567890000000000
+    channel = _channel(sample_rate, gps_time_ns, 1000)
+    snapshot_wall = (gps_time_ns + BILLION * (GPS_UTC_OFFSET - 18)) / BILLION
+
+    period_sec = 0x100000000 / sample_rate
+    target_rtp = (1000 + 0x100000000) & 0xFFFFFFFF
+    expected = snapshot_wall + period_sec
+
+    # Pin time.time() to something WAY OFF (1 year earlier) — if the
+    # function ignores the hint and consults the system clock anyway,
+    # the wrap-epoch math will pick k=0 and the result will be wrong.
+    bogus_now = expected - 365 * 86400.0
+    with patch("ka9q.rtp_recorder.time.time", return_value=bogus_now) as mock_time:
+        result = rtp_to_wallclock(target_rtp, channel, wallclock_hint_sec=expected)
+        assert result == pytest.approx(expected, abs=1e-3)
+        # Strict: hint path must not call time.time() at all.
+        mock_time.assert_not_called()
+
+
+def test_rtp_to_wallclock_hint_picks_correct_epoch():
+    """Hint at a different wrap epoch from the system clock → result
+    follows the hint, proving the function uses the hint for k-selection."""
+    sample_rate = 12000  # WSPR-band rate; period ≈ 99 hours
+    gps_time_ns = 1234567890000000000
+    channel = _channel(sample_rate, gps_time_ns, 1000)
+    snapshot_wall = (gps_time_ns + BILLION * (GPS_UTC_OFFSET - 18)) / BILLION
+    period_sec = 0x100000000 / sample_rate
+
+    # RTP value aliased to ~snapshot, but actually 2 wraps later.
+    target_rtp = (1000 + 2 * 0x100000000) & 0xFFFFFFFF
+    expected = snapshot_wall + 2 * period_sec
+
+    # System clock at the snapshot wall (would pick k=0); hint says
+    # ~2 periods later (correct k=2).
+    with patch("ka9q.rtp_recorder.time.time", return_value=snapshot_wall):
+        result = rtp_to_wallclock(target_rtp, channel, wallclock_hint_sec=expected)
+        assert result == pytest.approx(expected, abs=1e-3)
+
+
+def test_rtp_to_wallclock_hint_omitted_falls_back_to_system_clock():
+    """Default path (no hint) preserves legacy behavior for
+    backwards compatibility — the hint parameter is purely additive."""
+    sample_rate = 48000
+    gps_time_ns = 1234567890000000000
+    channel = _channel(sample_rate, gps_time_ns, 1000)
+    snapshot_wall = (gps_time_ns + BILLION * (GPS_UTC_OFFSET - 18)) / BILLION
+    period_sec = 0x100000000 / sample_rate
+
+    target_rtp = (1000 + 0x100000000) & 0xFFFFFFFF
+    expected = snapshot_wall + period_sec
+
+    # No hint → must consult time.time() to land on k=1.
+    with patch("ka9q.rtp_recorder.time.time", return_value=expected) as mock_time:
+        result = rtp_to_wallclock(target_rtp, channel)
+        assert result == pytest.approx(expected, abs=1e-3)
+        mock_time.assert_called()