ka9q-python 3.13.0__tar.gz → 3.14.0__tar.gz

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## [3.14.0] - 2026-05-13
+
+### Added
+
+- **`RadiodControl(client_id=...)` for per-client deterministic multicast
+  destinations.**  Closes the CONTRACT v0.3 §7 gap where the spec said
+  "ka9q-python derives the multicast destination" but the implementation
+  never did, so every client on a given radiod landed on radiod's
+  config-file default group.  Two clients with no operator action are now
+  guaranteed to use distinct multicast addresses without per-client
+  derivation code.
+  - New `client_id: Optional[str] = None` kwarg on
+    `RadiodControl.__init__`.  When set, `ensure_channel(destination=None)`
+    auto-derives a `239.x.y.z` address via
+    `generate_multicast_ip(client_id, radiod_host=self.status_address)`.
+  - Destination precedence inside `ensure_channel`:
+    `(1) explicit destination=` >
+    `(2) derived from (client_id, status_address)` >
+    `(3) None → radiod's config default`.
+  - Multi-radiod handling falls out of the hash: a `psk-recorder` instance
+    pointing at `bee1-hf-status.local` derives a different address from
+    one pointing at `bee3-hf-status.local`.
+  - Multi-client handling falls out of the hash: `psk-recorder` and
+    `wspr-recorder` on the same radiod derive different addresses.
+  - `MultiStream._attempt_restore` inherits the behavior because it reuses
+    the same `RadiodControl` instance (and thus the same `client_id`).
+    Restoration after a radiod restart re-creates each channel on the
+    same per-client multicast group it was on before.
+  - Because `allocate_ssrc` already hashes `destination` into the SSRC,
+    per-client destinations produce per-client SSRCs — radiod's channel
+    table cleanly separates concurrent clients.
+
+### Backward Compatibility
+
+- Default behavior unchanged: `RadiodControl(status)` without `client_id`
+  preserves pre-3.14 semantics — `destination=None` flows through, radiod
+  uses its config-file default, every channel from that radiod shares one
+  multicast group.  Clients opt in by passing `client_id="<name>"`.
+
+### Tests
+
+- 9 new unit tests in `tests/test_client_id_destination.py` cover:
+  client_id default-None / set / stored; precedence (explicit wins over
+  derived, no client_id → None); uniqueness invariants (same client on
+  two radiods → distinct; two clients on one radiod → distinct;
+  same client + same radiod → repeatable); SSRC divergence per client.
+  134 offline unit tests pass.
+
 ## [3.13.0] - 2026-05-08
 
 ### Added

{ka9q_python-3.13.0/ka9q_python.egg-info → ka9q_python-3.14.0}/PKG-INFO

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

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/ka9q/__init__.py

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

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/ka9q/compat.py

@@ -12,4 +12,4 @@ Usage:
     print(f"Compatible with ka9q-radio at {KA9Q_RADIO_COMMIT}")
 """
 
-KA9Q_RADIO_COMMIT: str = "5498aefd6fd4be7d4ff2f5e33c9b310ecd3b8574"
+KA9Q_RADIO_COMMIT: str = "f78cff9cc8c7fa33ea49aac9176d9263c535a332"

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/ka9q/control.py

@@ -691,18 +691,35 @@ class RadiodControl:
     """
     
     def __init__(self, status_address: str, max_commands_per_sec: int = 100,
-                 interface: Optional[str] = None):
+                 interface: Optional[str] = None,
+                 client_id: Optional[str] = None):
         """
         Initialize radiod control
-        
+
         Args:
             status_address: mDNS name or IP:port of radiod status stream
             max_commands_per_sec: Maximum commands per second (rate limiting)
             interface: IP address of network interface for multicast (e.g., '192.168.1.100').
                       Required on multi-homed systems. If None, uses INADDR_ANY (0.0.0.0).
+            client_id: Identity string for this client application
+                      (e.g. ``"psk-recorder"``, ``"hf-timestd"``).  When set,
+                      :py:meth:`ensure_channel` derives a per-(client, radiod)
+                      multicast destination via
+                      :py:func:`ka9q.generate_multicast_ip` whenever the
+                      caller does not supply an explicit ``destination=``.
+                      Same client_id + same radiod -> same destination
+                      (all of that client's channels share one multicast
+                      group); different client_id OR different radiod ->
+                      distinct destinations (peer clients on one station
+                      never collide; one client targeting two radiods
+                      sees one destination per radiod).  ``None`` (default)
+                      preserves pre-3.14 behavior: when no ``destination=``
+                      is passed, radiod uses its config-file default and
+                      every client lands on the same group.
         """
         self.status_address = status_address
         self.interface = interface
+        self.client_id = client_id
         self.socket = None
         self._status_sock = None  # Cached status listener socket for tune()
         self._status_sock_lock = None  # Will be initialized when needed
@@ -1363,8 +1380,16 @@ class RadiodControl:
             agc_enable: Enable automatic gain control (0=off, 1=on, default: 0)
             gain: Manual gain in dB (default: 0.0). Only used when agc_enable=0
             destination: RTP destination multicast address (optional).
-                        If not specified, uses radiod's default from config file.
-                        If specified, becomes part of the channel identity (SSRC).
+                        Precedence: (1) explicit ``destination=`` wins;
+                        (2) otherwise if the RadiodControl was constructed
+                        with ``client_id=``, this method derives a
+                        deterministic ``239.x.y.z`` address from the
+                        (client_id, status_address) pair so each peer
+                        client on a station gets its own multicast group;
+                        (3) otherwise (``destination=None`` and no
+                        ``client_id``), radiod's config-file default is
+                        used.  The resolved address becomes part of the
+                        channel identity (SSRC).
             encoding: Output encoding (0=none, 4=F32, etc.) - see Encoding class
             timeout: Maximum time to wait for channel verification (default: 5.0s)
             frequency_tolerance: Acceptable frequency deviation in Hz (default: 1.0)
@@ -1418,15 +1443,32 @@ class RadiodControl:
             applications requesting the same parameters will share the same
             channel, reducing radiod resource usage.
         """
+        from .addressing import generate_multicast_ip
         from .discovery import ChannelInfo, discover_channels
-        
+
         # Validate inputs
         _validate_frequency(frequency_hz)
         _validate_sample_rate(sample_rate)
         _validate_gain(gain)
         _validate_preset(preset)
         _validate_timeout(timeout)
-        
+
+        # CONTRACT v0.3 §7: when the RadiodControl was constructed with a
+        # client_id and the caller didn't pass an explicit destination,
+        # derive a deterministic per-(client, radiod) multicast address.
+        # This makes peer clients on the same host land on distinct
+        # multicast groups without per-client derivation code.  An
+        # explicit destination= still wins (e.g. operator override).
+        if destination is None and self.client_id:
+            destination = generate_multicast_ip(
+                unique_id=self.client_id,
+                radiod_host=self.status_address,
+            )
+            logger.debug(
+                "ensure_channel: derived destination=%s for client_id=%r "
+                "radiod=%r", destination, self.client_id, self.status_address,
+            )
+
         # Compute deterministic SSRC from parameters (including radiod identity)
         ssrc = allocate_ssrc(
             frequency_hz=frequency_hz,

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/ka9q/multi_stream.py

@@ -134,6 +134,7 @@ class MultiStream:
         high_edge: Optional[float] = None,
         kaiser_beta: Optional[float] = None,
         lifetime: Optional[int] = None,
+        timeout: float = 5.0,
     ) -> ChannelInfo:
         """Provision a channel and register it for reception.
 
@@ -153,6 +154,18 @@ class MultiStream:
         ``set_channel_lifetime()`` (or by calling
         RadiodControl.set_channel_lifetime directly on the SSRC).
 
+        ``timeout`` is forwarded to ``ensure_channel`` and bounds the
+        wait for radiod's status-message ACK confirming the channel
+        was created.  The default 5 s is fine for an idle radiod, but
+        when many producers register channels in quick succession
+        (e.g. a multi-client deployment restarting) radiod can stall
+        long enough that 5 s isn't enough — observed on bee1 2026-05-08
+        as the T6 BPSK PPS channel timing out and crashing
+        timestd-core-recorder, which in turn left TSL3 SHM stale.
+        Callers in latency-sensitive setups should pass a longer
+        value (10-30 s) so a brief radiod-busy window doesn't fail
+        the whole channel registration.
+
         Returns the ChannelInfo from ensure_channel().
         """
         channel_info = self._control.ensure_channel(
@@ -166,6 +179,7 @@ class MultiStream:
             high_edge=high_edge,
             kaiser_beta=kaiser_beta,
             lifetime=lifetime,
+            timeout=timeout,
         )
 
         addr = channel_info.multicast_address

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/ka9q/rtp_recorder.py

@@ -127,34 +127,72 @@ def parse_rtp_header(data: bytes) -> Optional[RTPHeader]:
 def rtp_to_wallclock(rtp_timestamp: int, channel: ChannelInfo) -> Optional[float]:
     """
     Convert RTP timestamp to Unix wall-clock time
-    
+
     Uses the GPS_TIME/RTP_TIMESNAP timing information from radiod.
-    
+
     Args:
         rtp_timestamp: RTP timestamp from packet header
         channel: ChannelInfo with gps_time, rtp_timesnap, sample_rate
-    
+
     Returns:
         Unix timestamp (seconds) or None if timing info unavailable
+
+    Wraparound handling:
+        RTP timestamps are 32-bit and wrap every 2**32 samples.  At
+        96 kHz that's 12.43 hours; at 16 kHz it's 74.6 hours.  The
+        ``rtp_timesnap``/``gps_time`` pair is captured once at SSRC
+        discovery, so an SSRC alive longer than one wrap period is
+        in a *later* RTP epoch than the snapshot — the naive signed
+        32-bit subtraction is correct only within ±2**31 samples
+        (~6 hours at 96 kHz) of the snapshot, beyond which it
+        silently aliases.
+
+        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.
+
+        Observed on bee1 2026-05-08: long-running SSRCs caused TSL3
+        SHM samples stuck at the snapshot's wall-clock time, ~12.4 h
+        behind.  Chrony filtered every sample and reach fell to 0.
     """
     if channel.gps_time is None or channel.rtp_timesnap is None:
         return None
-    
+
     # Convert GPS nanoseconds to Unix time
     # GPS epoch is Jan 6, 1980; Unix epoch is Jan 1, 1970
     # gps_time is nanoseconds since GPS epoch, so add GPS_UTC_OFFSET (in ns)
     # AND subtract current GPS_LEAP_SECONDS (18s) to align with UTC
     sender_time = channel.gps_time + BILLION * (GPS_UTC_OFFSET - GPS_LEAP_SECONDS)
-    
-    # Add offset from RTP timestamp difference
-    # Cast to int32 for proper wrapping behavior
+
+    # Signed 32-bit RTP delta — correct within ±2**31 samples of
+    # the snapshot.
     rtp_delta = int((rtp_timestamp - channel.rtp_timesnap) & 0xFFFFFFFF)
     if rtp_delta > 0x7FFFFFFF:
         rtp_delta -= 0x100000000
-    
-    time_offset = BILLION * rtp_delta // channel.sample_rate
-    
-    wall_time_ns = sender_time + time_offset
+
+    base_wall_ns = sender_time + (BILLION * rtp_delta // channel.sample_rate)
+
+    # Adjust for wrap epochs.  One period = 2**32 samples =
+    # BILLION * 2**32 // sample_rate ns.  Pick the integer k that
+    # minimises |base_wall_ns + k*period - sys_now_ns| — i.e. the
+    # 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)
+    diff_ns = sys_now_ns - base_wall_ns
+    if period_ns > 0:
+        # Round-to-nearest of diff_ns / period_ns (Python `//` is
+        # floor; bias by half-period before flooring to round).
+        if diff_ns >= 0:
+            k = (diff_ns + period_ns // 2) // period_ns
+        else:
+            k = -(((-diff_ns) + period_ns // 2) // period_ns)
+    else:
+        k = 0
+    wall_time_ns = base_wall_ns + k * period_ns
 
     # Apply L6 BPSK PPS chain-delay calibration if available.
     # This corrects for the end-to-end RF→ADC→DSP→RTP latency

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/ka9q/types.py

@@ -2,7 +2,7 @@
 ka9q-radio protocol types and constants
 
 Auto-generated by scripts/sync_types.py from ka9q-radio C headers.
-Validated against ka9q-radio commit: 5498aefd6fd4
+Validated against ka9q-radio commit: f78cff9cc8c7
 
 DO NOT EDIT MANUALLY — run: python scripts/sync_types.py --apply
 """

{ka9q_python-3.13.0 → ka9q_python-3.14.0/ka9q_python.egg-info}/PKG-INFO

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

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/ka9q_python.egg-info/SOURCES.txt

@@ -67,6 +67,7 @@ tests/__init__.py
 tests/conftest.py
 tests/test_addressing.py
 tests/test_channel_verification.py
+tests/test_client_id_destination.py
 tests/test_create_split_encoding.py
 tests/test_decode_description.py
 tests/test_decode_functions.py

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/ka9q_radio_compat

@@ -1,3 +1,3 @@
 # ka9q-radio commit that ka9q/types.py was last validated against
 # Updated by: scripts/sync_types.py --apply
-5498aefd6fd4be7d4ff2f5e33c9b310ecd3b8574
+f78cff9cc8c7fa33ea49aac9176d9263c535a332

{ka9q_python-3.13.0 → ka9q_python-3.14.0}/pyproject.toml

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

ka9q_python-3.14.0/tests/test_client_id_destination.py

@@ -0,0 +1,150 @@
+"""RadiodControl(client_id=...) destination-derivation tests.
+
+When ``client_id`` is set, ``ensure_channel(destination=None)`` should
+auto-derive a per-(client, radiod) multicast address so peer clients on
+the same host land on distinct multicast groups without per-client
+derivation code.  Tests mock ``_connect`` and short-circuit
+``create_channel`` to capture the resolved destination without
+requiring a live radiod or running the verify loop.
+"""
+
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from ka9q.addressing import generate_multicast_ip
+from ka9q.control import RadiodControl
+
+
+def _ensure_dest(ctrl: RadiodControl, *, destination=None) -> object:
+    """Drive ensure_channel to ``create_channel`` and return the
+    destination it would have received.  ``create_channel`` raises to
+    short-circuit the post-create verify loop (which would otherwise
+    spin discover_channels for ``timeout`` seconds)."""
+    captured: dict = {}
+
+    def _capture(*_args, **kwargs):
+        captured['destination'] = kwargs.get('destination')
+        raise _ShortCircuit()
+
+    # ensure_channel re-imports discover_channels from ka9q.discovery
+    # *inside* the function body, so the patch target is the
+    # discovery module, not the control module's alias.
+    with patch('ka9q.discovery.discover_channels', return_value={}), \
+         patch.object(ctrl, 'create_channel', side_effect=_capture):
+        try:
+            ctrl.ensure_channel(
+                frequency_hz=14_074_000.0,
+                preset="iq",
+                sample_rate=16000,
+                destination=destination,
+            )
+        except _ShortCircuit:
+            pass
+    return captured.get('destination')
+
+
+class _ShortCircuit(Exception):
+    pass
+
+
+class TestClientIdStored(unittest.TestCase):
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_client_id_default_none(self, _c):
+        ctrl = RadiodControl("radiod.local")
+        self.assertIsNone(ctrl.client_id)
+
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_client_id_stored(self, _c):
+        ctrl = RadiodControl("radiod.local", client_id="psk-recorder")
+        self.assertEqual(ctrl.client_id, "psk-recorder")
+
+
+class TestDestinationPrecedence(unittest.TestCase):
+    """ensure_channel's destination= resolution order:
+        explicit > derived (from client_id+status) > None.
+    """
+
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_explicit_destination_wins_over_client_id(self, _c):
+        ctrl = RadiodControl("radiod.local", client_id="psk-recorder")
+        dest = _ensure_dest(ctrl, destination="239.1.2.3")
+        self.assertEqual(dest, "239.1.2.3")
+
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_no_client_id_keeps_destination_none(self, _c):
+        """Pre-3.14 behavior preserved: no client_id, no explicit
+        destination -> destination=None flows through so radiod uses
+        its config-file default."""
+        ctrl = RadiodControl("radiod.local")
+        dest = _ensure_dest(ctrl, destination=None)
+        self.assertIsNone(dest)
+
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_client_id_derives_destination(self, _c):
+        ctrl = RadiodControl("bee1-hf-status.local", client_id="psk-recorder")
+        expected = generate_multicast_ip(
+            "psk-recorder", radiod_host="bee1-hf-status.local",
+        )
+        dest = _ensure_dest(ctrl, destination=None)
+        self.assertEqual(dest, expected)
+        self.assertTrue(dest.startswith("239."))
+
+
+class TestDestinationUniqueness(unittest.TestCase):
+    """The two invariants the operator-facing design promises:
+      (a) same client on two radiods -> two distinct destinations
+      (b) two clients on one radiod -> two distinct destinations
+    """
+
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_same_client_different_radiods(self, _c):
+        a = RadiodControl("bee1-hf-status.local", client_id="psk-recorder")
+        b = RadiodControl("bee3-hf-status.local", client_id="psk-recorder")
+        self.assertNotEqual(_ensure_dest(a), _ensure_dest(b),
+                            "psk-recorder on radiod-0 vs radiod-1 must use "
+                            "distinct multicast groups")
+
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_different_clients_same_radiod(self, _c):
+        a = RadiodControl("bee1-hf-status.local", client_id="psk-recorder")
+        b = RadiodControl("bee1-hf-status.local", client_id="wspr-recorder")
+        self.assertNotEqual(_ensure_dest(a), _ensure_dest(b),
+                            "psk-recorder and wspr-recorder on one radiod "
+                            "must use distinct multicast groups")
+
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_same_client_same_radiod_repeatable(self, _c):
+        """Restart must bind to the same multicast group."""
+        a = RadiodControl("bee1-hf-status.local", client_id="psk-recorder")
+        b = RadiodControl("bee1-hf-status.local", client_id="psk-recorder")
+        self.assertEqual(_ensure_dest(a), _ensure_dest(b))
+
+
+class TestDestinationParticipatesInSsrc(unittest.TestCase):
+    """allocate_ssrc already hashes destination into the SSRC, so two
+    clients with derived destinations must produce different SSRCs
+    even for identical channel parameters."""
+
+    @patch('ka9q.control.RadiodControl._connect')
+    def test_ssrcs_diverge_per_client(self, _c):
+        from ka9q.control import allocate_ssrc
+
+        params = dict(frequency_hz=14_074_000.0, preset="iq",
+                      sample_rate=16000, agc=False, gain=0.0)
+        psk_dest = generate_multicast_ip("psk-recorder",
+                                          radiod_host="bee1-hf-status.local")
+        wspr_dest = generate_multicast_ip("wspr-recorder",
+                                           radiod_host="bee1-hf-status.local")
+        psk_ssrc = allocate_ssrc(**params, destination=psk_dest,
+                                  radiod_host="bee1-hf-status.local")
+        wspr_ssrc = allocate_ssrc(**params, destination=wspr_dest,
+                                   radiod_host="bee1-hf-status.local")
+        self.assertNotEqual(psk_ssrc, wspr_ssrc,
+                            "Per-client destination must produce per-client "
+                            "SSRC, so radiod's channel table separates them")
+
+
+if __name__ == "__main__":
+    unittest.main()

ka9q_python-3.14.0/tests/test_rtp_recorder.py

@@ -0,0 +1,120 @@
+"""
+Tests for RTP recorder functionality
+"""
+from unittest.mock import patch
+
+import pytest
+
+from ka9q.rtp_recorder import rtp_to_wallclock
+from ka9q.discovery import ChannelInfo
+
+
+GPS_UTC_OFFSET = 315964800
+BILLION = 1_000_000_000
+
+
+def _channel(sample_rate, gps_time_ns, rtp_timesnap):
+    return ChannelInfo(
+        ssrc=1234,
+        preset="test",
+        sample_rate=sample_rate,
+        frequency=100.0,
+        snr=0.0,
+        multicast_address="239.1.2.3",
+        port=5004,
+        gps_time=gps_time_ns,
+        rtp_timesnap=rtp_timesnap,
+    )
+
+
+def test_rtp_to_wallclock_basic():
+    """Same RTP as snapshot → exactly GPS+offset; +N samples → +N/sample_rate s."""
+    gps_time_ns = 1234567890000000000   # ~2019
+    channel = _channel(48000, gps_time_ns, 1000)
+    expected_sec = (gps_time_ns + BILLION * (GPS_UTC_OFFSET - 18)) / BILLION
+
+    # Pin system clock close to the channel's wall-clock so the
+    # wrap-disambiguation picks epoch k=0 deterministically.
+    with patch("ka9q.rtp_recorder.time.time", return_value=expected_sec):
+        assert rtp_to_wallclock(1000, channel) == pytest.approx(expected_sec)
+        assert rtp_to_wallclock(1000 + 48000, channel) == pytest.approx(expected_sec + 1.0)
+        # One sample later → +1/48000 s
+        assert rtp_to_wallclock(1001, channel) == pytest.approx(expected_sec + 1 / 48000.0)
+
+
+def test_rtp_to_wallclock_signed_32bit_window():
+    """RTP within ±2**31 samples of snapshot (the natively-correct window)
+    → no wrap adjustment needed regardless of system clock."""
+    gps_time_ns = 1234567890000000000
+    channel = _channel(96000, gps_time_ns, 1000)
+    base_wall = (gps_time_ns + BILLION * (GPS_UTC_OFFSET - 18)) / BILLION
+
+    # 30 minutes ahead at 96 kHz = +30*60*96000 = 172_800_000 samples
+    target_rtp = (1000 + 172_800_000) & 0xFFFFFFFF
+    expected = base_wall + 30 * 60.0
+    with patch("ka9q.rtp_recorder.time.time", return_value=expected):
+        assert rtp_to_wallclock(target_rtp, channel) == pytest.approx(expected)
+
+
+def test_rtp_to_wallclock_wraps_correctly_after_one_period():
+    """After one full RTP wrap (2**32 samples), naive subtraction aliases
+    to ~snapshot.  System-clock disambiguation must return the right
+    wall-clock value one wrap later."""
+    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                              # 12.43 h
+    target_rtp = (1000 + 0x100000000) & 0xFFFFFFFF                       # exactly 1 wrap later
+    expected = snapshot_wall + period_sec
+
+    # System clock at the *expected* time — wrap counter k must be 1.
+    with patch("ka9q.rtp_recorder.time.time", return_value=expected):
+        result = rtp_to_wallclock(target_rtp, channel)
+        assert result == pytest.approx(expected, abs=1e-3)
+
+
+def test_rtp_to_wallclock_wraps_correctly_after_two_periods():
+    """Same idea, two full wraps (~24.86 h after snapshot at 96 kHz)."""
+    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 + 2 * 0x100000000 + 100) & 0xFFFFFFFF             # 2 wraps + 100 samples
+    expected = snapshot_wall + 2 * period_sec + 100 / sample_rate
+
+    with patch("ka9q.rtp_recorder.time.time", return_value=expected):
+        result = rtp_to_wallclock(target_rtp, channel)
+        assert result == pytest.approx(expected, abs=1e-3)
+
+
+def test_rtp_to_wallclock_disambiguator_tolerates_clock_skew():
+    """System clock can be off by hours (NTP not yet locked, holdover,
+    operator skew) and the wrap disambiguator should still pick the
+    right epoch as long as skew is < period/2 (~6 h at 96 kHz)."""
+    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 + 50_000_000) & 0xFFFFFFFF
+    true_wall = snapshot_wall + period_sec + 50_000_000 / sample_rate    # 12.43 h + ~520 s
+
+    # System clock 4 hours off (within ±6 h tolerance window).
+    skewed_now = true_wall - 4 * 3600.0
+    with patch("ka9q.rtp_recorder.time.time", return_value=skewed_now):
+        result = rtp_to_wallclock(target_rtp, channel)
+        assert result == pytest.approx(true_wall, abs=1e-3)
+
+
+def test_rtp_to_wallclock_returns_none_when_timing_missing():
+    channel = _channel(48000, None, None)
+    assert rtp_to_wallclock(1000, channel) is None
+    channel = _channel(48000, 1234567890000000000, None)
+    assert rtp_to_wallclock(1000, channel) is None
+    channel = _channel(48000, None, 1000)
+    assert rtp_to_wallclock(1000, channel) is None

ka9q_python-3.13.0/tests/test_rtp_recorder.py

@@ -1,41 +0,0 @@
-"""
-Tests for RTP recorder functionality
-"""
-import pytest
-from ka9q.rtp_recorder import rtp_to_wallclock
-from ka9q.discovery import ChannelInfo
-
-def test_rtp_to_wallclock():
-    """Test GPS time to Unix time conversion"""
-    # Channel info with mocked timing
-    # GPS Time: 1234567890000000000 ns (random recent-ish GPS time)
-    # This corresponds to some time around 2019
-    gps_time_ns = 1234567890000000000 
-    
-    # Constants from code
-    GPS_UTC_OFFSET = 315964800
-    BILLION = 1_000_000_000
-    
-    channel = ChannelInfo(
-        ssrc=1234,
-        preset="test",
-        sample_rate=48000,
-        frequency=100.0,
-        snr=0.0,
-        multicast_address="239.1.2.3",
-        port=5004,
-        gps_time=gps_time_ns,
-        rtp_timesnap=1000
-    )
-    
-    # Case 1: Same RTP timestamp as snapshot
-    # Result should be exactly GPS time + offset
-    # Expected Unix time = GPS time + Offset - Leap Seconds
-    expected_unix_ns = gps_time_ns + (BILLION * (GPS_UTC_OFFSET - 18))
-    expected_unix_sec = expected_unix_ns / BILLION
-    
-    assert rtp_to_wallclock(1000, channel) == pytest.approx(expected_unix_sec)
-    
-    # Case 2: One second later
-    # 48000 samples later
-    assert rtp_to_wallclock(1000 + 48000, channel) == pytest.approx(expected_unix_sec + 1.0)