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

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

@@ -1,5 +1,72 @@
 # Changelog
 
+## [3.15.0] - 2026-05-21
+
+### Added
+
+- **F16LE / F16BE RTP payload decoding** in `parse_rtp_samples` for radiod's
+  float16 output mode (encodings 6 and 9).  Both audio and IQ paths.
+- **G.711 µ-law / A-law decoders** for encodings 10 and 11 — pure-numpy
+  table-based, no `audioop` dependency (which was removed in Python 3.13).
+- **`OpusDecoder` class** in `ka9q.stream` for OPUS / OPUS_VOIP payloads
+  (encodings 3 and 7).  Lazy-imports `opuslib`; install via
+  `pip install ka9q-python[opus]`.  Maintains codec state across calls so
+  packet-loss concealment works end-to-end — one instance per stream SSRC.
+- New `opus` optional dependency in `pyproject.toml` (`opuslib>=3.0`).
+
+### Fixed
+
+- **`RadiodControl.set_agc(attack_rate=...)` was unreachable.**  It encoded
+  `StatusType.AGC_ATTACK_RATE`, which does not exist in ka9q-radio's
+  `status.h` or in `ka9q/types.py` — any call passing `attack_rate=` raised
+  `AttributeError`.  Replaced with a working `threshold:` kwarg backed by
+  `AGC_THRESHOLD` (which radiod actually decodes in
+  `decode_radio_commands()`).
+- **Removed 6 stale duplicate `set_*` methods.**  In a single class, second
+  defs silently shadow firsts — so callers were already using the correct
+  versions further down the file.  The dead first defs of `set_squelch`,
+  `set_pll`, `set_output_channels`, `set_independent_sideband`,
+  `set_envelope_detection`, and `set_opus_bitrate` are gone.  One of them
+  (`set_opus_bitrate`) referenced a non-existent `StatusType.OPUS_BITRATE`
+  — the working second def uses the correct `OPUS_BIT_RATE`.
+
+### Tooling / pinning
+
+- Pin advanced from ka9q-radio `f78cff9c` (1.0.0-22) to `d555f1853422`.
+  Drift report confirms zero TLV-tag, encoding-enum, demod-type, or
+  window-type changes across the 68 intervening upstream commits — only
+  packaging, hydrasdr-driver, and internal C-struct refactors.  Existing
+  ka9q-python state (`types.py`, `decode_status_packet`, `SpectrumStream`,
+  every `set_*` method) was already covering the full HEAD protocol
+  surface; this release brings the recorded compatibility tag in line.
+
+### Tests
+
+- Fixed pre-existing `tests/test_filter_edges.py::_bare_control` helper
+  that did not initialise the `client_id` attribute added with v3.14.0
+  per-(client,radiod) multicast destinations.
+
+## [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.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.14.1
+Version: 3.15.0
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G
@@ -30,6 +30,8 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Provides-Extra: tui
 Requires-Dist: textual>=0.50; extra == "tui"
+Provides-Extra: opus
+Requires-Dist: opuslib>=3.0; extra == "opus"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file

{ka9q_python-3.14.1 → ka9q_python-3.15.0}/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.15.0}/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.15.0}/ka9q/compat.py

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

{ka9q_python-3.14.1 → ka9q_python-3.15.0}/ka9q/control.py

@@ -973,23 +973,27 @@ class RadiodControl:
         logger.info(f"Setting sample rate for SSRC {ssrc} to {sample_rate} Hz")
         self.send_command(cmdbuffer)
     
-    def set_agc(self, ssrc: int, enable: bool, hangtime: Optional[float] = None, 
+    def set_agc(self, ssrc: int, enable: bool, hangtime: Optional[float] = None,
                 headroom: Optional[float] = None, recovery_rate: Optional[float] = None,
-                attack_rate: Optional[float] = None):
+                threshold: Optional[float] = None):
         """
-        Configure AGC (Automatic Gain Control) for a channel
-        
+        Configure AGC (Automatic Gain Control) for a channel.
+
+        radiod exposes four AGC knobs: enable, hangtime, headroom, recovery_rate,
+        and threshold. There is no separate "attack rate" — see radio_status.c
+        decode_radio_commands().
+
         Args:
             ssrc: SSRC of the channel
             enable: Enable/disable AGC (True=enabled, False=manual gain)
-            hangtime: AGC hang time in seconds (optional)
-            headroom: Target headroom in dB (optional)
-            recovery_rate: AGC recovery rate (optional)
-            attack_rate: AGC attack rate (optional)
+            hangtime: AGC hang time in seconds
+            headroom: Target headroom in dB (positive; radiod negates internally)
+            recovery_rate: AGC recovery rate in dB/sec
+            threshold: AGC threshold in dB
         """
         cmdbuffer = bytearray()
         cmdbuffer.append(CMD)
-        
+
         encode_int(cmdbuffer, StatusType.AGC_ENABLE, 1 if enable else 0)
         if hangtime is not None:
             encode_float(cmdbuffer, StatusType.AGC_HANGTIME, hangtime)
@@ -997,14 +1001,14 @@ class RadiodControl:
             encode_float(cmdbuffer, StatusType.HEADROOM, headroom)
         if recovery_rate is not None:
             encode_float(cmdbuffer, StatusType.AGC_RECOVERY_RATE, recovery_rate)
-        if attack_rate is not None:
-            encode_float(cmdbuffer, StatusType.AGC_ATTACK_RATE, attack_rate)
-        
+        if threshold is not None:
+            encode_float(cmdbuffer, StatusType.AGC_THRESHOLD, threshold)
+
         encode_int(cmdbuffer, StatusType.OUTPUT_SSRC, ssrc)
         encode_int(cmdbuffer, StatusType.COMMAND_TAG, secrets.randbits(31))
         encode_eol(cmdbuffer)
-        
-        logger.info(f"Setting AGC for SSRC {ssrc}: enable={enable}, hangtime={hangtime}, headroom={headroom}")
+
+        logger.info(f"Setting AGC for SSRC {ssrc}: enable={enable}")
         self.send_command(cmdbuffer)
     
     def set_gain(self, ssrc: int, gain_db: float):
@@ -1710,138 +1714,6 @@ class RadiodControl:
         logger.info(f"Setting LIFETIME for SSRC {ssrc} to {lifetime} frames")
         self.send_command(cmdbuffer)
 
-    def set_squelch(self, ssrc: int, open_threshold: Optional[float] = None,
-                    close_threshold: Optional[float] = None, snr_squelch: Optional[bool] = None):
-        """
-        Set squelch parameters for a channel
-        
-        Args:
-            ssrc: SSRC of the channel
-            open_threshold: Squelch open threshold in dB (optional)
-            close_threshold: Squelch close threshold in dB (optional)
-            snr_squelch: Enable SNR-based squelch (optional)
-        """
-        cmdbuffer = bytearray()
-        cmdbuffer.append(CMD)
-        
-        if open_threshold is not None:
-            encode_float(cmdbuffer, StatusType.SQUELCH_OPEN, open_threshold)
-        if close_threshold is not None:
-            encode_float(cmdbuffer, StatusType.SQUELCH_CLOSE, close_threshold)
-        if snr_squelch is not None:
-            encode_int(cmdbuffer, StatusType.SNR_SQUELCH, 1 if snr_squelch else 0)
-        
-        encode_int(cmdbuffer, StatusType.OUTPUT_SSRC, ssrc)
-        encode_int(cmdbuffer, StatusType.COMMAND_TAG, secrets.randbits(31))
-        encode_eol(cmdbuffer)
-        
-        logger.info(f"Setting squelch for SSRC {ssrc}")
-        self.send_command(cmdbuffer)
-
-    def set_pll(self, ssrc: int, enable: Optional[bool] = None, 
-                bandwidth: Optional[float] = None, square: Optional[bool] = None):
-        """
-        Set PLL parameters for a channel
-        
-        Args:
-            ssrc: SSRC of the channel
-            enable: Enable/disable PLL (optional)
-            bandwidth: PLL bandwidth in Hz (optional)
-            square: Enable square-wave PLL output (optional)
-        """
-        cmdbuffer = bytearray()
-        cmdbuffer.append(CMD)
-        
-        if enable is not None:
-            encode_int(cmdbuffer, StatusType.PLL_ENABLE, 1 if enable else 0)
-        if bandwidth is not None:
-            encode_float(cmdbuffer, StatusType.PLL_BW, bandwidth)
-        if square is not None:
-            encode_int(cmdbuffer, StatusType.PLL_SQUARE, 1 if square else 0)
-        
-        encode_int(cmdbuffer, StatusType.OUTPUT_SSRC, ssrc)
-        encode_int(cmdbuffer, StatusType.COMMAND_TAG, secrets.randbits(31))
-        encode_eol(cmdbuffer)
-        
-        logger.info(f"Setting PLL for SSRC {ssrc}")
-        self.send_command(cmdbuffer)
-
-    def set_output_channels(self, ssrc: int, channels: int):
-        """
-        Set number of output channels (mono/stereo)
-        
-        Args:
-            ssrc: SSRC of the channel
-            channels: Number of channels (1=mono, 2=stereo)
-        """
-        cmdbuffer = bytearray()
-        cmdbuffer.append(CMD)
-        
-        encode_int(cmdbuffer, StatusType.OUTPUT_CHANNELS, channels)
-        encode_int(cmdbuffer, StatusType.OUTPUT_SSRC, ssrc)
-        encode_int(cmdbuffer, StatusType.COMMAND_TAG, secrets.randbits(31))
-        encode_eol(cmdbuffer)
-        
-        logger.info(f"Setting output channels for SSRC {ssrc} to {channels}")
-        self.send_command(cmdbuffer)
-
-    def set_independent_sideband(self, ssrc: int, enable: bool):
-        """
-        Enable/disable independent sideband (ISB) mode
-        
-        Args:
-            ssrc: SSRC of the channel
-            enable: Enable ISB mode
-        """
-        cmdbuffer = bytearray()
-        cmdbuffer.append(CMD)
-        
-        encode_int(cmdbuffer, StatusType.INDEPENDENT_SIDEBAND, 1 if enable else 0)
-        encode_int(cmdbuffer, StatusType.OUTPUT_SSRC, ssrc)
-        encode_int(cmdbuffer, StatusType.COMMAND_TAG, secrets.randbits(31))
-        encode_eol(cmdbuffer)
-        
-        logger.info(f"Setting ISB for SSRC {ssrc} to {enable}")
-        self.send_command(cmdbuffer)
-
-    def set_envelope_detection(self, ssrc: int, enable: bool):
-        """
-        Enable/disable envelope detection for AM
-        
-        Args:
-            ssrc: SSRC of the channel
-            enable: Enable envelope detection
-        """
-        cmdbuffer = bytearray()
-        cmdbuffer.append(CMD)
-        
-        encode_int(cmdbuffer, StatusType.ENVELOPE, 1 if enable else 0)
-        encode_int(cmdbuffer, StatusType.OUTPUT_SSRC, ssrc)
-        encode_int(cmdbuffer, StatusType.COMMAND_TAG, secrets.randbits(31))
-        encode_eol(cmdbuffer)
-        
-        logger.info(f"Setting envelope detection for SSRC {ssrc} to {enable}")
-        self.send_command(cmdbuffer)
-
-    def set_opus_bitrate(self, ssrc: int, bitrate: int):
-        """
-        Set Opus codec bitrate
-        
-        Args:
-            ssrc: SSRC of the channel
-            bitrate: Bitrate in bits per second (6000-510000)
-        """
-        cmdbuffer = bytearray()
-        cmdbuffer.append(CMD)
-        
-        encode_int(cmdbuffer, StatusType.OPUS_BITRATE, bitrate)
-        encode_int(cmdbuffer, StatusType.OUTPUT_SSRC, ssrc)
-        encode_int(cmdbuffer, StatusType.COMMAND_TAG, secrets.randbits(31))
-        encode_eol(cmdbuffer)
-        
-        logger.info(f"Setting Opus bitrate for SSRC {ssrc} to {bitrate}")
-        self.send_command(cmdbuffer)
-    
     def _setup_status_listener(self):
         """Set up socket to listen for status responses"""
         # Create a separate socket for receiving status messages

{ka9q_python-3.14.1 → ka9q_python-3.15.0}/ka9q/multi_stream.py

@@ -201,12 +201,21 @@ class MultiStream:
         ssrc = channel_info.ssrc
         is_iq = preset.lower() in ("iq", "spectrum")
 
+        # Use the encoding radiod actually granted (channel_info.encoding)
+        # rather than the encoding we requested. radiod silently downgrades
+        # F32 → S16 for some IQ-channel configurations; storing the requested
+        # value caused parse_rtp_samples to decode upstream bytes with the
+        # wrong dtype and produce NaN-poisoned garbage. The granted encoding
+        # is authoritative. Fall back to the caller's value if channel_info
+        # doesn't carry an encoding (or carries 0 = "none/default").
+        granted_encoding = getattr(channel_info, 'encoding', 0) or encoding
+
         slot = _ChannelSlot(
             channel_info=channel_info,
             frequency_hz=frequency_hz,
             preset=preset,
             sample_rate=sample_rate,
-            encoding=encoding,
+            encoding=granted_encoding,
             is_iq=is_iq,
             resequencer=PacketResequencer(
                 buffer_size=self._resequence_buffer_size,

{ka9q_python-3.14.1 → ka9q_python-3.15.0}/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.15.0}/ka9q/stream.py

@@ -41,6 +41,7 @@ from .discovery import ChannelInfo
 from .rtp_recorder import RTPHeader, parse_rtp_header, rtp_to_wallclock
 from .resequencer import PacketResequencer, RTPPacket
 from .stream_quality import GapSource, GapEvent, StreamQuality
+from .types import Encoding
 
 logger = logging.getLogger(__name__)
 
@@ -48,16 +49,54 @@ logger = logging.getLogger(__name__)
 SampleCallback = Callable[[np.ndarray, StreamQuality], None]
 
 
+# G.711 µ-law and A-law decode tables (ITU-T G.711). Each maps a uint8 byte
+# to its signed 16-bit linear PCM equivalent. Precomputed once at import.
+def _build_mulaw_table() -> np.ndarray:
+    out = np.empty(256, dtype=np.int16)
+    for i in range(256):
+        u = ~i & 0xFF
+        sign = u & 0x80
+        exponent = (u >> 4) & 0x07
+        mantissa = u & 0x0F
+        sample = ((mantissa << 3) + 0x84) << exponent
+        sample -= 0x84
+        out[i] = -sample if sign else sample
+    return out
+
+
+def _build_alaw_table() -> np.ndarray:
+    out = np.empty(256, dtype=np.int16)
+    for i in range(256):
+        a = i ^ 0x55
+        sign = a & 0x80
+        exponent = (a >> 4) & 0x07
+        mantissa = a & 0x0F
+        if exponent == 0:
+            sample = (mantissa << 4) + 8
+        else:
+            sample = ((mantissa << 4) + 0x108) << (exponent - 1)
+        out[i] = -sample if sign else sample
+    return out
+
+
+_MULAW_TABLE = _build_mulaw_table()
+_ALAW_TABLE = _build_alaw_table()
+
+
 def parse_rtp_samples(
     payload: bytes, encoding: int, is_iq: bool
 ) -> Optional[np.ndarray]:
     """Parse RTP payload samples based on encoding.
 
-    Shared by RadiodStream and MultiStream.
+    Shared by RadiodStream and MultiStream. Covers every linear-PCM encoding
+    radiod can grant: NO_ENCODING/S16LE/S16BE/F32LE/F32BE/F16LE/F16BE plus
+    G.711 MULAW/ALAW.  OPUS (3/7) requires libopus and is handled by
+    ``OpusDecoder`` in this module — not by this raw-sample helper.  AX25 (5)
+    is a framed protocol, not audio samples, and is also out of scope here.
 
     Args:
         payload: Raw RTP payload bytes (after header).
-        encoding: Channel encoding (0=none/F32LE, 1=S16LE, 2=S16BE, 4=F32LE, 8=F32BE).
+        encoding: Channel encoding from ``ka9q.types.Encoding``.
         is_iq: True for IQ (complex) mode, False for audio (real) mode.
 
     Returns:
@@ -65,29 +104,124 @@ def parse_rtp_samples(
         or None on error.
     """
     try:
+        floats = _decode_to_float32(payload, encoding, is_iq=is_iq)
+        if floats is None:
+            return None
         if is_iq:
-            floats = np.frombuffer(payload, dtype=np.float32)
+            # radiod silently downgrades F32 → S16 for some IQ-channel
+            # configurations (high sample rate + wide filter); confirmed on
+            # bee1 2026-05-15 for T6/TSL3 BPSK PPS channel (encoding=4
+            # requested, encoding=2 granted, decoded as F32LE → NaN-poisoned
+            # input, TSL3 dark). Honor the granted encoding above.
             if len(floats) % 2 != 0:
-                logger.warning(f"Odd number of floats in IQ payload: {len(floats)}")
+                logger.warning(f"Odd number of samples in IQ payload: {len(floats)}")
                 return None
             samples = floats[0::2] + 1j * floats[1::2]
             return samples.astype(np.complex64)
-        else:
-            if encoding == 2:
-                int16_samples = np.frombuffer(payload, dtype='>i2')
-                return (int16_samples / 32768.0).astype(np.float32)
-            elif encoding == 1:
-                int16_samples = np.frombuffer(payload, dtype='<i2')
-                return (int16_samples / 32768.0).astype(np.float32)
-            elif encoding == 8:
-                return np.frombuffer(payload, dtype='>f4').astype(np.float32)
-            else:
-                return np.frombuffer(payload, dtype=np.float32)
+        return floats
     except Exception as e:
         logger.error(f"Failed to parse payload: {e}")
         return None
 
 
+def _decode_to_float32(payload: bytes, encoding: int, *, is_iq: bool = False) -> Optional[np.ndarray]:
+    """Decode raw RTP payload bytes to a flat float32 sample array.
+
+    For IQ the caller interleaves; for audio the array is the output directly.
+    Returns None for encodings this helper does not cover (OPUS, AX25).
+    The ``is_iq`` flag only affects the wording of the fallback warning so
+    callers can grep for IQ-specific decode anomalies (the bee1 TSL3 case).
+    """
+    if encoding in (Encoding.NO_ENCODING, Encoding.F32LE):
+        return np.frombuffer(payload, dtype='<f4').astype(np.float32, copy=False)
+    if encoding == Encoding.F32BE:
+        return np.frombuffer(payload, dtype='>f4').astype(np.float32, copy=False)
+    if encoding == Encoding.S16LE:
+        return np.frombuffer(payload, dtype='<i2').astype(np.float32) / 32768.0
+    if encoding == Encoding.S16BE:
+        return np.frombuffer(payload, dtype='>i2').astype(np.float32) / 32768.0
+    if encoding == Encoding.F16LE:
+        return np.frombuffer(payload, dtype='<f2').astype(np.float32)
+    if encoding == Encoding.F16BE:
+        return np.frombuffer(payload, dtype='>f2').astype(np.float32)
+    if encoding == Encoding.MULAW:
+        idx = np.frombuffer(payload, dtype=np.uint8)
+        return (_MULAW_TABLE[idx].astype(np.float32) / 32768.0)
+    if encoding == Encoding.ALAW:
+        idx = np.frombuffer(payload, dtype=np.uint8)
+        return (_ALAW_TABLE[idx].astype(np.float32) / 32768.0)
+    if encoding in (Encoding.OPUS, Encoding.OPUS_VOIP):
+        # Opus payloads are codec frames, not raw samples — caller must use
+        # ka9q.stream.OpusDecoder (requires libopus / opuslib).
+        return None
+    if encoding == Encoding.AX25:
+        # AX25 is a framed protocol — bytes are the payload, not samples.
+        return None
+    kind = "IQ" if is_iq else "audio"
+    logger.warning(f"Unsupported {kind} encoding {encoding}, falling back to F32LE")
+    return np.frombuffer(payload, dtype='<f4').astype(np.float32, copy=False)
+
+
+class OpusDecoder:
+    """Optional Opus → float32 decoder for radiod OPUS / OPUS_VOIP streams.
+
+    Requires the ``opuslib`` package (``pip install ka9q-python[opus]`` or
+    ``pip install opuslib``).  Maintains internal codec state across calls so
+    packet-loss concealment works end-to-end; create one instance per stream
+    SSRC and feed it each RTP payload in order.
+
+    Example::
+
+        dec = OpusDecoder(sample_rate=48000, channels=1)
+        for payload in opus_payloads:
+            samples = dec.decode(payload)  # float32, mono
+    """
+
+    def __init__(self, sample_rate: int = 48000, channels: int = 1):
+        try:
+            import opuslib  # type: ignore
+        except ImportError as exc:
+            raise RuntimeError(
+                "Opus decoding requires opuslib — install with "
+                "'pip install ka9q-python[opus]' or 'pip install opuslib'"
+            ) from exc
+        if sample_rate not in (8000, 12000, 16000, 24000, 48000):
+            raise ValueError(
+                f"Opus sample_rate must be one of 8000/12000/16000/24000/48000; got {sample_rate}"
+            )
+        if channels not in (1, 2):
+            raise ValueError(f"Opus channels must be 1 or 2; got {channels}")
+        self._sample_rate = sample_rate
+        self._channels = channels
+        self._dec = opuslib.Decoder(sample_rate, channels)
+        # 120 ms is the largest Opus frame; allocate per-call.
+        self._max_frame_samples = (sample_rate * 120) // 1000
+
+    @property
+    def sample_rate(self) -> int:
+        return self._sample_rate
+
+    @property
+    def channels(self) -> int:
+        return self._channels
+
+    def decode(self, payload: bytes, *, fec: bool = False) -> np.ndarray:
+        """Decode one Opus RTP payload to float32 PCM samples.
+
+        For stereo streams the result is interleaved L,R,L,R,…  Empty payload
+        triggers packet-loss concealment (one frame of silence/extrapolation).
+        """
+        if not payload and not fec:
+            # Generate one PLC frame of typical Opus duration (20 ms).
+            n_samples = (self._sample_rate * 20) // 1000
+        else:
+            n_samples = self._max_frame_samples
+        pcm = self._dec.decode(payload, n_samples, decode_fec=fec)
+        # opuslib returns bytes of int16 little-endian; convert to float32 [-1,1].
+        int16s = np.frombuffer(pcm, dtype='<i2')
+        return int16s.astype(np.float32) / 32768.0
+
+
 class RadiodStream:
     """
     High-level interface to a radiod IQ/audio stream.

{ka9q_python-3.14.1 → ka9q_python-3.15.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: f78cff9cc8c7
+Validated against ka9q-radio commit: d555f1853422
 
 DO NOT EDIT MANUALLY — run: python scripts/sync_types.py --apply
 """

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.14.1
+Version: 3.15.0
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G
@@ -30,6 +30,8 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Provides-Extra: tui
 Requires-Dist: textual>=0.50; extra == "tui"
+Provides-Extra: opus
+Requires-Dist: opuslib>=3.0; extra == "opus"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file

{ka9q_python-3.14.1 → ka9q_python-3.15.0}/ka9q_python.egg-info/SOURCES.txt

@@ -85,6 +85,7 @@ tests/test_monitor.py
 tests/test_multicast_helpers.py
 tests/test_multihomed.py
 tests/test_native_discovery.py
+tests/test_parse_rtp_samples_iq.py
 tests/test_performance_fixes.py
 tests/test_protocol_compat.py
 tests/test_remove_channel.py

{ka9q_python-3.14.1 → ka9q_python-3.15.0}/ka9q_python.egg-info/requires.txt

@@ -4,5 +4,8 @@ numpy>=1.24.0
 pytest>=7.0.0
 pytest-cov>=4.0.0
 
+[opus]
+opuslib>=3.0
+
 [tui]
 textual>=0.50

{ka9q_python-3.14.1 → ka9q_python-3.15.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
-f78cff9cc8c7fa33ea49aac9176d9263c535a332
+d555f1853422ecc551ac7e4064b9d9cfdb743764

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ka9q-python"
-version = "3.14.1"
+version = "3.15.0"
 description = "Python interface for ka9q-radio control and monitoring"
 readme = "README.md"
 authors = [
@@ -37,6 +37,9 @@ dev = [
 tui = [
     "textual>=0.50",
 ]
+opus = [
+    "opuslib>=3.0",
+]
 
 [project.scripts]
 ka9q = "ka9q.cli:main"

{ka9q_python-3.14.1 → ka9q_python-3.15.0}/tests/test_filter_edges.py

@@ -38,6 +38,7 @@ def _bare_control() -> RadiodControl:
     c._command_window_start = time.time()
     c._rate_limit_lock = threading.Lock()
     c.metrics = MagicMock()
+    c.client_id = None
     return c
 
 

ka9q_python-3.15.0/tests/test_parse_rtp_samples_iq.py

@@ -0,0 +1,118 @@
+"""Tests for parse_rtp_samples IQ-encoding handling.
+
+Regression coverage for the 2026-05-15 fix where the IQ branch of
+parse_rtp_samples ignored the encoding parameter and always decoded as
+F32LE — so when radiod silently downgraded a channel to S16 the bytes
+mis-decoded into ~1e34 garbage and occasional NaN. See discussion in
+hf-timestd's TSL3-dark investigation.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from ka9q.stream import parse_rtp_samples
+
+
+def _iq_payload(samples_re, samples_im, *, dtype: str, byteorder: str) -> bytes:
+    """Interleaved (re, im) sample bytes in the requested dtype/byteorder."""
+    interleaved = np.empty(2 * len(samples_re), dtype=dtype)
+    interleaved[0::2] = samples_re
+    interleaved[1::2] = samples_im
+    # numpy dtype string already encodes byteorder in dtype param;
+    # the wire format is whatever np.frombuffer reads with the same dtype.
+    return interleaved.tobytes()
+
+
+def test_iq_f32le_default_encoding_0():
+    re = np.array([0.5, -0.25, 0.0], dtype='<f4')
+    im = np.array([-0.5, 0.25, 1.0], dtype='<f4')
+    payload = _iq_payload(re, im, dtype='<f4', byteorder='<')
+    samples = parse_rtp_samples(payload, encoding=0, is_iq=True)
+    assert samples is not None
+    np.testing.assert_allclose(samples.real, re, rtol=0, atol=1e-7)
+    np.testing.assert_allclose(samples.imag, im, rtol=0, atol=1e-7)
+
+
+def test_iq_f32le_encoding_4():
+    re = np.array([0.1, 0.2], dtype='<f4')
+    im = np.array([-0.1, -0.2], dtype='<f4')
+    payload = _iq_payload(re, im, dtype='<f4', byteorder='<')
+    samples = parse_rtp_samples(payload, encoding=4, is_iq=True)
+    assert samples is not None
+    np.testing.assert_allclose(samples.real, re, rtol=0, atol=1e-7)
+
+
+def test_iq_f32be_encoding_8():
+    re = np.array([0.5, -0.5], dtype='>f4')
+    im = np.array([0.25, -0.25], dtype='>f4')
+    payload = _iq_payload(re, im, dtype='>f4', byteorder='>')
+    samples = parse_rtp_samples(payload, encoding=8, is_iq=True)
+    assert samples is not None
+    np.testing.assert_allclose(samples.real, [0.5, -0.5], rtol=0, atol=1e-7)
+    np.testing.assert_allclose(samples.imag, [0.25, -0.25], rtol=0, atol=1e-7)
+
+
+def test_iq_s16le_encoding_1():
+    re = np.array([16384, -16384], dtype='<i2')   # ±0.5
+    im = np.array([8192, -8192], dtype='<i2')     # ±0.25
+    payload = _iq_payload(re, im, dtype='<i2', byteorder='<')
+    samples = parse_rtp_samples(payload, encoding=1, is_iq=True)
+    assert samples is not None
+    np.testing.assert_allclose(samples.real, [0.5, -0.5], rtol=0, atol=1e-4)
+    np.testing.assert_allclose(samples.imag, [0.25, -0.25], rtol=0, atol=1e-4)
+
+
+def test_iq_s16be_encoding_2_does_not_produce_nan_or_huge():
+    """The bug we're fixing: a real-world S16BE IQ payload like radiod's
+    T6/TSL3 channel was producing NaN and ~1e34 values when decoded as
+    F32LE. Confirm decoding the same bytes as S16BE gives sane samples.
+    """
+    re = np.array([23876, -10000, 32767], dtype='>i2')
+    im = np.array([13433, 25000, -32768], dtype='>i2')
+    payload = _iq_payload(re, im, dtype='>i2', byteorder='>')
+    samples = parse_rtp_samples(payload, encoding=2, is_iq=True)
+    assert samples is not None
+    assert not np.any(np.isnan(samples.real))
+    assert not np.any(np.isnan(samples.imag))
+    assert np.max(np.abs(samples)) <= 2.0  # all should be in [-1.0, +1.0]
+    np.testing.assert_allclose(samples.real, [23876 / 32768.0, -10000 / 32768.0, 32767 / 32768.0], rtol=0, atol=1e-4)
+
+
+def test_iq_odd_sample_count_returns_none():
+    """An odd number of int16 values can't form complete IQ pairs."""
+    payload = np.array([1, 2, 3], dtype='>i2').tobytes()  # 3 int16 = 6 bytes
+    samples = parse_rtp_samples(payload, encoding=2, is_iq=True)
+    assert samples is None
+
+
+def test_iq_unknown_encoding_falls_back_and_warns(caplog):
+    re = np.array([0.1], dtype='<f4')
+    im = np.array([-0.1], dtype='<f4')
+    payload = _iq_payload(re, im, dtype='<f4', byteorder='<')
+    import logging
+    with caplog.at_level(logging.WARNING):
+        samples = parse_rtp_samples(payload, encoding=99, is_iq=True)
+    assert samples is not None
+    assert any('Unsupported IQ encoding' in rec.message for rec in caplog.records)
+
+
+def test_iq_smoking_gun_bit_pattern():
+    """The empirical fingerprint of the bug on bee1 2026-05-15:
+    a 4-byte block 5d 44 34 79 (which is S16BE int16 pair [23876, 13433]
+    — sensible loud-signal IQ) was being decoded as F32LE → 5.85e34.
+    Verify S16BE decoding gives back the original int16 values normalised.
+    """
+    payload = bytes.fromhex('5d44 3479'.replace(' ', ''))
+    samples = parse_rtp_samples(payload, encoding=2, is_iq=True)
+    assert samples is not None
+    assert len(samples) == 1
+    np.testing.assert_allclose(samples.real, [23876 / 32768.0], rtol=0, atol=1e-4)
+    np.testing.assert_allclose(samples.imag, [13433 / 32768.0], rtol=0, atol=1e-4)
+    # The "bug behaviour" reference: decoding the same bytes as F32LE
+    # gives 5.85e34. Document this in the test so a future regression
+    # that re-introduces F32LE-always behaviour will fail with a meaningful
+    # signal.
+    as_f32le = np.frombuffer(payload, dtype='<f4')[0]
+    assert as_f32le > 1e34, "sanity check: bug fingerprint matches"

{ka9q_python-3.14.1 → ka9q_python-3.15.0}/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()