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

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

@@ -1,5 +1,57 @@
 # 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
+
+- **`RadiodStream`: multi-interface multicast join (parity with
+  `MultiStream`).**  Extends Rob Robinett's `e3acb6a` fix from
+  `multi_stream.py` to `stream.py` so the per-stream `RadiodStream`
+  socket also joins on every local IPv4 interface instead of the
+  single one the kernel picks via `INADDR_ANY`.  Without this, a
+  `RadiodStream` consumer of a co-located radiod with `ttl=0` (or any
+  output that arrives on a non-default-route interface) silently
+  received zero packets.  Most visible to clients that use the
+  per-stream API directly (codar-sounder, hf-timestd's legacy T6
+  path) rather than the shared `MultiStream` socket.
+
+### Refactor
+
+- The helper that enumerates IPv4 interfaces and calls
+  `IP_ADD_MEMBERSHIP` on each is factored into a new package-private
+  `ka9q/_multicast.py` module.  Both `multi_stream.py` and `stream.py`
+  now import from it.  Same behaviour, one implementation.
+  `rtp_recorder.RtpRecorder` still uses the single-interface join —
+  separate fix.
+
+### Tests
+
+- 8 new in `tests/test_multicast_helpers.py`: enumerator behaviour,
+  per-interface join failure handling (one interface failing doesn't
+  abort the loop), empty-enumeration safety, both stream classes
+  pulling the helper from the shared module.
+
 ## [3.14.0] - 2026-05-13
 
 ### Added

{ka9q_python-3.14.0/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.0
+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.0 → 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.0 → 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.0'
+__version__ = '3.14.2'
 __author__ = 'Michael Hauan AC0G'
 
 from .control import RadiodControl, allocate_ssrc

ka9q_python-3.14.2/ka9q/_multicast.py

@@ -0,0 +1,90 @@
+"""Shared multicast helpers — multi-interface IP_ADD_MEMBERSHIP.
+
+Factored out of ``multi_stream.py`` (Rob Robinett's e3acb6a) so the
+same join-on-every-interface logic can also be used by
+``stream.RadiodStream`` and ``rtp_recorder.RtpRecorder`` without
+duplicating the SIOCGIFADDR enumeration code.
+
+This module is package-private — callers inside ``ka9q`` import the
+two public helpers below; nothing outside the package should rely on
+the symbol names.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import logging
+import socket
+import struct
+from typing import Iterator, List, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+# Linux SIOCGIFADDR — fetch IPv4 of an interface by name.  Used to enumerate
+# every UP IPv4 interface so the multicast group join can be made on each
+# of them.  Without this, joining with INADDR_ANY lets the kernel pick a
+# single interface (typically the default-route one), which misses:
+#
+#   * Loopback-only multicast emitted by a co-located radiod with TTL=0
+#     (packets sit on `lo`; the kernel won't deliver them to a socket
+#     joined on `ens0`).
+#   * Multi-homed stations where one radiod streams on lo and another
+#     on eth: a single receiver should consume both.
+#
+# Joining on EVERY local IPv4 interface lets one socket receive from any
+# radiod source on any path.
+_SIOCGIFADDR = 0x8915
+
+
+def iter_local_ipv4_interfaces() -> Iterator[Tuple[str, str]]:
+    """Yield (ifname, ipv4_addr_str) for every local interface with an IPv4.
+
+    Order is ``socket.if_nameindex()`` order — typically ``'lo'`` first,
+    then ``ens0``/``eth0``/``wlan0``/etc.  Interfaces without an IPv4
+    (IPv6-only, or freshly-created with no addr) are skipped silently.
+    Stays stdlib-only on Linux (no ``netifaces``/``psutil`` dependency).
+    """
+    try:
+        names = socket.if_nameindex()
+    except OSError:
+        return
+    probe = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        for _idx, ifname in names:
+            try:
+                raw = fcntl.ioctl(
+                    probe.fileno(),
+                    _SIOCGIFADDR,
+                    struct.pack("256s", ifname.encode()[:15]),
+                )
+                addr = socket.inet_ntoa(raw[20:24])
+            except OSError:
+                continue
+            yield ifname, addr
+    finally:
+        probe.close()
+
+
+def join_multicast_all_interfaces(sock: socket.socket,
+                                  multicast_address: str) -> List[str]:
+    """Join ``multicast_address`` on every local IPv4 interface.
+
+    Returns the list of interface names where the join succeeded.  Empty
+    list means no interface was usable (extremely rare — even a freshly-
+    booted box has ``lo``).  Per-interface failures are logged at DEBUG
+    and skipped (e.g., a virtual interface without an IPv4).
+    """
+    joined: List[str] = []
+    group = socket.inet_aton(multicast_address)
+    for ifname, ifaddr in iter_local_ipv4_interfaces():
+        mreq = struct.pack("=4s4s", group, socket.inet_aton(ifaddr))
+        try:
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+            joined.append(ifname)
+        except OSError as exc:
+            logger.debug(
+                "multicast join on %s (%s) failed: %s",
+                ifname, ifaddr, exc,
+            )
+    return joined

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

@@ -59,6 +59,9 @@ from .stream_quality import GapEvent, GapSource, StreamQuality
 logger = logging.getLogger(__name__)
 
 
+from ._multicast import join_multicast_all_interfaces
+
+
 @dataclass
 class _ChannelSlot:
     """Per-SSRC state within a MultiStream."""
@@ -322,12 +325,26 @@ class MultiStream:
 
         sock.bind(("0.0.0.0", self._port))
 
-        mreq = struct.pack(
-            "=4s4s",
-            socket.inet_aton(self._multicast_address),
-            socket.inet_aton("0.0.0.0"),
+        # Join the multicast group on EVERY local IPv4 interface, not
+        # via INADDR_ANY (which lets the kernel pick a single interface
+        # — typically the default route — and silently misses radiod
+        # outputs on other paths, e.g. TTL=0 loopback packets from a
+        # co-located radiod).  Helper lives in ka9q._multicast so
+        # stream.RadiodStream uses identical logic.
+        joined = join_multicast_all_interfaces(
+            sock, self._multicast_address,
         )
-        sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+        if not joined:
+            logger.warning(
+                "MultiStream: no interface accepted the multicast "
+                "join for %s — recvfrom() will return nothing",
+                self._multicast_address,
+            )
+        else:
+            logger.debug(
+                "MultiStream: joined %s on interfaces: %s",
+                self._multicast_address, ", ".join(joined),
+            )
         sock.settimeout(1.0)
         return sock
 

{ka9q_python-3.14.0 → 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.0 → ka9q_python-3.14.2}/ka9q/stream.py

@@ -36,6 +36,7 @@ import numpy as np
 from datetime import datetime, timezone
 from typing import Optional, Callable, List
 
+from ._multicast import join_multicast_all_interfaces
 from .discovery import ChannelInfo
 from .rtp_recorder import RTPHeader, parse_rtp_header, rtp_to_wallclock
 from .resequencer import PacketResequencer, RTPPacket
@@ -232,22 +233,34 @@ class RadiodStream:
         
         # Bind to port
         sock.bind(('0.0.0.0', self.channel.port))
-        
-        # Join multicast group
-        mreq = struct.pack(
-            '=4s4s',
-            socket.inet_aton(self.channel.multicast_address),
-            socket.inet_aton('0.0.0.0')
+
+        # Join the multicast group on EVERY local IPv4 interface (lo,
+        # ens0, etc.) — not via INADDR_ANY, which leaves the choice to
+        # the kernel's routing table and silently misses radiod outputs
+        # that arrive on a non-default interface.  Most notably, a
+        # co-located radiod with TTL=0 emits only on `lo`; an
+        # INADDR_ANY join typically resolves to `ens0` and never sees
+        # those packets.  Same helper used by MultiStream (the shared-
+        # socket abstraction) so both classes have identical behaviour.
+        joined = join_multicast_all_interfaces(
+            sock, self.channel.multicast_address,
         )
-        sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
-        
+        if not joined:
+            logger.warning(
+                "RadiodStream: no interface accepted the multicast "
+                "join for %s — recvfrom() will return nothing",
+                self.channel.multicast_address,
+            )
+        else:
+            logger.debug(
+                "RadiodStream: joined %s:%d on interfaces: %s",
+                self.channel.multicast_address, self.channel.port,
+                ", ".join(joined),
+            )
+
         # Timeout for periodic running check
         sock.settimeout(1.0)
-        
-        logger.debug(
-            f"Joined multicast {self.channel.multicast_address}:{self.channel.port}"
-        )
-        
+
         return sock
     
     def _receive_loop(self):

{ka9q_python-3.14.0 → 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.0
+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.0 → ka9q_python-3.14.2}/ka9q_python.egg-info/SOURCES.txt

@@ -36,6 +36,7 @@ examples/tune_example.py
 examples/diagnostics/diagnose_packets.py
 examples/diagnostics/repro_utc_bug.py
 ka9q/__init__.py
+ka9q/_multicast.py
 ka9q/addressing.py
 ka9q/cli.py
 ka9q/compat.py
@@ -81,6 +82,7 @@ tests/test_lifetime.py
 tests/test_listen_multicast.py
 tests/test_managed_stream_recovery.py
 tests/test_monitor.py
+tests/test_multicast_helpers.py
 tests/test_multihomed.py
 tests/test_native_discovery.py
 tests/test_performance_fixes.py

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

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

ka9q_python-3.14.2/tests/test_multicast_helpers.py

@@ -0,0 +1,135 @@
+"""Unit tests for ka9q._multicast helpers.
+
+Locks in the multi-interface IP_ADD_MEMBERSHIP behaviour that both
+MultiStream and RadiodStream rely on for TTL=0 / multi-homed reception.
+Rob Robinett (e3acb6a) introduced the logic inside multi_stream.py;
+this refactor moved it to ka9q._multicast and extended RadiodStream to
+use it too.
+"""
+
+from __future__ import annotations
+
+import socket
+import struct
+import unittest
+from unittest.mock import MagicMock, patch
+
+from ka9q._multicast import (
+    join_multicast_all_interfaces,
+    iter_local_ipv4_interfaces,
+)
+
+
+class TestIterLocalIPv4Interfaces(unittest.TestCase):
+    """`iter_local_ipv4_interfaces` should walk `if_nameindex` and skip
+    interfaces SIOCGIFADDR doesn't answer for."""
+
+    def test_enumerates_via_if_nameindex(self):
+        """Smoke-test: at least one interface must come back on a real host."""
+        ifaces = list(iter_local_ipv4_interfaces())
+        # Every Linux box has 'lo' with 127.0.0.1.  If this list is
+        # empty something is very wrong (privileged container with no
+        # network? broken socket()?).
+        self.assertGreater(len(ifaces), 0)
+        names = [n for n, _ in ifaces]
+        self.assertIn('lo', names)
+        # Find lo and verify it has the expected loopback address.
+        for name, addr in ifaces:
+            if name == 'lo':
+                self.assertEqual(addr, '127.0.0.1')
+                break
+        else:
+            self.fail("lo not present in enumeration")
+
+    def test_handles_if_nameindex_failure(self):
+        """If if_nameindex() raises, we get an empty iterator (not a crash)."""
+        with patch('socket.if_nameindex', side_effect=OSError("no /proc/net")):
+            self.assertEqual(list(iter_local_ipv4_interfaces()), [])
+
+    def test_skips_interfaces_without_ipv4(self):
+        """An interface that has no IPv4 (SIOCGIFADDR errors) is silently
+        skipped — we just don't see it in the output."""
+        # Real-host probe should not include made-up interfaces.
+        ifaces = list(iter_local_ipv4_interfaces())
+        names = [n for n, _ in ifaces]
+        self.assertNotIn('this-interface-does-not-exist', names)
+
+
+class TestJoinMulticastAllInterfaces(unittest.TestCase):
+    """`join_multicast_all_interfaces` must call setsockopt once per
+    enumerated interface and return the names where the join succeeded."""
+
+    def test_joins_each_enumerated_interface(self):
+        sock = MagicMock(spec=socket.socket)
+        sock.setsockopt = MagicMock()
+
+        fake_ifaces = [('lo', '127.0.0.1'),
+                       ('ens0', '192.168.1.50'),
+                       ('tailscale0', '100.64.0.5')]
+        with patch('ka9q._multicast.iter_local_ipv4_interfaces',
+                   return_value=iter(fake_ifaces)):
+            joined = join_multicast_all_interfaces(sock, '239.1.2.3')
+
+        self.assertEqual(joined, ['lo', 'ens0', 'tailscale0'])
+        self.assertEqual(sock.setsockopt.call_count, 3)
+
+        # Verify each setsockopt got the right (group, iface) mreq.
+        for call, (_ifname, ifaddr) in zip(sock.setsockopt.call_args_list, fake_ifaces):
+            args = call.args
+            self.assertEqual(args[0], socket.IPPROTO_IP)
+            self.assertEqual(args[1], socket.IP_ADD_MEMBERSHIP)
+            expected_mreq = struct.pack(
+                "=4s4s",
+                socket.inet_aton('239.1.2.3'),
+                socket.inet_aton(ifaddr),
+            )
+            self.assertEqual(args[2], expected_mreq)
+
+    def test_per_interface_failure_skipped(self):
+        """A setsockopt OSError on one interface skips it but doesn't
+        abort the loop or raise — the other interfaces still join."""
+        sock = MagicMock(spec=socket.socket)
+        # ens0 fails, lo + tailscale0 succeed.
+        def setsockopt_side_effect(level, opt, value):
+            mreq_iface = socket.inet_ntoa(value[4:8])
+            if mreq_iface == '192.168.1.50':
+                raise OSError(99, "Cannot assign requested address")
+            return None
+        sock.setsockopt.side_effect = setsockopt_side_effect
+
+        fake_ifaces = [('lo', '127.0.0.1'),
+                       ('ens0', '192.168.1.50'),
+                       ('tailscale0', '100.64.0.5')]
+        with patch('ka9q._multicast.iter_local_ipv4_interfaces',
+                   return_value=iter(fake_ifaces)):
+            joined = join_multicast_all_interfaces(sock, '239.1.2.3')
+
+        self.assertEqual(joined, ['lo', 'tailscale0'])  # ens0 dropped
+
+    def test_empty_enumeration_returns_empty(self):
+        """No interfaces enumerated → empty join list, no exception."""
+        sock = MagicMock(spec=socket.socket)
+        with patch('ka9q._multicast.iter_local_ipv4_interfaces',
+                   return_value=iter([])):
+            joined = join_multicast_all_interfaces(sock, '239.1.2.3')
+        self.assertEqual(joined, [])
+        sock.setsockopt.assert_not_called()
+
+
+class TestStreamClassesUseHelper(unittest.TestCase):
+    """RadiodStream and MultiStream must both call the shared helper, so a
+    future change to join semantics applies uniformly."""
+
+    def test_radiodstream_imports_helper(self):
+        # Ensure the import succeeded — would raise ImportError at
+        # collection time if the symbol moved.
+        from ka9q import stream
+        self.assertTrue(hasattr(stream, 'join_multicast_all_interfaces'))
+
+    def test_multistream_imports_helper(self):
+        from ka9q import multi_stream
+        self.assertTrue(hasattr(multi_stream, 'join_multicast_all_interfaces'))
+
+
+if __name__ == '__main__':
+    unittest.main()

{ka9q_python-3.14.0 → 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()