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

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

@@ -1,5 +1,127 @@
 # Changelog
 
+## [3.16.1] - 2026-05-24
+
+### Fixed
+
+- **`ChannelInfo` anchor pair is now atomic** (`channel-info`).  Adds
+  `ChannelInfo.get_anchor()` / `update_anchor()` — a tuple-based
+  atomic snapshot of `(gps_time, rtp_timesnap)`.  `rtp_to_wallclock`
+  now reads the pair via `get_anchor` (single GIL-atomic attribute
+  access) instead of two separate reads; `StatusListener` writes via
+  `update_anchor` (single tuple assignment).
+
+  Why: the `StatusListener` introduced in 3.16.0 refreshes the anchor
+  in place at sub-second cadence (~450 ms on a busy host).  Direct
+  sequential reads of `channel.gps_time` followed by
+  `channel.rtp_timesnap` could land between the listener's two writes
+  and yield a torn pair off by one listener-cadence interval.
+  `rtp_to_wallclock` then returned a wall-time off by that much —
+  usually harmless, but consumers comparing against an external time
+  reference with a tight gate (e.g. hf-timestd's T5 LB-1421 NMEA
+  disambig at ±0.5 s) could be pushed across the threshold and fall
+  back to a chrony walk that itself fails during a post-restart
+  cascade.
+
+  Backward compatible: constructor kwargs (`gps_time=`,
+  `rtp_timesnap=`) and direct field reads are unchanged; consumers
+  that need the pair transactionally must call `get_anchor`.  Adds
+  5 new tests (atomic update, construction-time seed, mixed-None
+  handling, listener path, 50-iteration consistency smoke test).
+
+### Performance
+
+- **`RadiodStream`: `SO_RCVBUF` raised 0 → 64 MB** (`stream.py`).
+  Mirrors the 3.16.0-cycle `multi_stream.py` change on the
+  single-channel path.  Previously `RadiodStream` sockets fell back
+  to the kernel default (`rmem_default`, typically 16 MB on hosts
+  with sigmond's `rule_kernel_rcvbuf_adequate` provisioning) and were
+  vulnerable to GIL-stall packet loss with no other consumer competing
+  to drain the buffer.  64 MB matches the `MultiStream` cap; sigmond
+  provisions `net.core.rmem_max=128 MB` (after kernel doubling), so
+  the request is honored.  Observed on bee1 2026-05-23 closing a
+  140 ms-stall-induced `gap=13440` resequencer event on hf-timestd's
+  T6 dedicated stream.
+
+- **`MultiStream`: `SO_RCVBUF` raised 8 MB → 64 MB** (`multi_stream.py`).
+  Observed 412 M UDP `RcvbufErrors` on B4-100 since boot, driven by
+  GIL contention preventing Python receiver threads from draining the
+  kernel-doubled 16 MB sockets.  Bigger absorber → more headroom
+  across GIL stalls before packets are dropped.  After applying:
+  socket `rb` shows 134217728 (128 MB visible after kernel doubling)
+  and recv-Q sits at ~50 KB in steady state (was hitting 14 MB / 16
+  MB before).  Requires `net.core.rmem_max >= 64 MB` to be honored —
+  provisioned by sigmond in
+  `/etc/sysctl.d/99-wspr-recorder.conf` alongside this change.
+
+## [3.16.0] - 2026-05-23
+
+### Added
+
+- **`StatusListener` — continuous STATUS multicast listener.**  New
+  `ka9q.status_listener.StatusListener` class subscribes to radiod's
+  STATUS multicast (port 5006) in a background thread and refreshes
+  `ChannelInfo.gps_time` / `.rtp_timesnap` on every broadcast.  Replaces
+  the previous one-shot `discover_channels` anchor capture, which
+  froze the timing anchor at SSRC discovery — leaving `rtp_to_wallclock`
+  to project forward from a host-clock value that drifts at the
+  chrony slew rate (~3.8 µs/s on a typical disciplined host).
+
+  Mutates the registered `ChannelInfo` in place so callers holding a
+  reference (e.g. hf-timestd's cached `_t6_channel_info`) see fresh
+  values immediately.  Supports per-SSRC and wildcard callbacks for
+  explicit notification.  Uses `SO_REUSEPORT` so it can coexist with
+  `RadiodControl`'s own status socket without stealing tune/discover
+  responses — multicast packets are delivered to every joined socket.
+
+  Opt-in via `RadiodControl.start_status_listener()`; closing the
+  control object stops the listener.  See class docstring for usage.
+
+- **`RadiodControl.start_status_listener(...)` / `.stop_status_listener(...)`
+  / `.status_listener` property** — convenience wiring to attach a
+  `StatusListener` to an existing control session.  Listener is
+  stopped automatically by `RadiodControl.close()`.
+
+### Why this exists
+
+Before this release, every ka9q-python consumer (hf-timestd, codar,
+psk, hfdl, wspr, wsprdaemon-client, gpsdo-monitor) labeled data via
+`rtp_to_wallclock(rtp, channel)` with a ChannelInfo whose
+`gps_time`/`rtp_timesnap` were captured once at SSRC discovery.
+For long-running services this meant labels drifted from GPSDO truth
+at the host-clock slew rate — on bee1 (`chrony` slewing at
+~3.8 µs/s), labels accumulated ~330 ms of drift per day.
+
+The chrony SHM-push side of hf-timestd's BPSK PPS path (HPPS / HFPS)
+manifested this most visibly: TS-1 source reported tracking with
+1 ns standard deviation but drifted at the host slew rate, blocking
+DASI2 grant deployment.  Faster anchor refresh closes the drift.
+
+### Backwards compatibility
+
+- All existing tests pass unchanged.  The listener is **opt-in** —
+  consumers that don't call `start_status_listener()` see no behavior
+  change.
+- `ChannelInfo` is unchanged structurally; only its mutability
+  contract is clarified (the timing fields were always documented as
+  "the latest snapshot", which is now true continuously rather than
+  once).
+
+## [3.15.1] - 2026-05-21
+
+### Fixed
+
+- **`ka9q.__version__` was stale.**  v3.15.0's wheel correctly identified
+  itself as `3.15.0` in dist-info, but the `__version__` string baked
+  into `ka9q/__init__.py` still read `'3.14.2'` — the in-package
+  introspection answer was wrong for every consumer.  The fix replaces
+  the hardcoded literal with `importlib.metadata.version("ka9q-python")`,
+  so `__version__` now always tracks the installed dist-info — drift
+  between release version and code-reported version is no longer
+  possible.  Falls back to `"0.0.0+unknown"` on import error or when
+  the package is not installed (e.g. running from a source tree
+  without an editable install).
+
 ## [3.15.0] - 2026-05-21
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.15.0
+Version: 3.16.1
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G
@@ -62,7 +62,8 @@ Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, S
 
 ## Features
 
-- **Complete radiod API** — all 110+ TLV status/command parameters exposed, generated from ka9q-radio's C headers
+- **Complete radiod API** — all 117 TLV status/command parameters exposed, generated from ka9q-radio's C headers
+- **Every radiod RTP encoding decoded** — `S16LE/BE`, `F32LE/BE`, `F16LE/BE`, `MULAW`, `ALAW` via pure-NumPy `parse_rtp_samples()`; `OPUS` / `OPUS_VOIP` via the optional `OpusDecoder` (install with `[opus]` extra)
 - **Four stream abstractions** — `RTPRecorder` (raw packets), `RadiodStream` (samples + gap handling), `ManagedStream` (self-healing single channel), `MultiStream` (shared socket, many SSRCs)
 - **Typed status decoder** — `ChannelStatus`, `FrontendStatus`, `PllStatus`, etc. with dotted-path field access
 - **Precise RTP timing** — GPS_TIME / RTP_TIMESNAP for sample-accurate wallclock timestamps
@@ -78,6 +79,19 @@ Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, S
 pip install ka9q-python
 ```
 
+Optional extras:
+
+| Extra | Adds | Needed for |
+|-------|------|------------|
+| `tui` | `textual` | `ka9q tui` interactive terminal UI |
+| `opus` | `opuslib` | decoding `OPUS` / `OPUS_VOIP` RTP payloads via `OpusDecoder` |
+| `dev`  | `pytest`, `pytest-cov` | running the test suite |
+
+```bash
+pip install "ka9q-python[opus]"          # one extra
+pip install "ka9q-python[tui,opus]"      # multiple
+```
+
 Or install from source:
 
 ```bash

{ka9q_python-3.15.0 → ka9q_python-3.16.1}/README.md

@@ -23,7 +23,8 @@ Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, S
 
 ## Features
 
-- **Complete radiod API** — all 110+ TLV status/command parameters exposed, generated from ka9q-radio's C headers
+- **Complete radiod API** — all 117 TLV status/command parameters exposed, generated from ka9q-radio's C headers
+- **Every radiod RTP encoding decoded** — `S16LE/BE`, `F32LE/BE`, `F16LE/BE`, `MULAW`, `ALAW` via pure-NumPy `parse_rtp_samples()`; `OPUS` / `OPUS_VOIP` via the optional `OpusDecoder` (install with `[opus]` extra)
 - **Four stream abstractions** — `RTPRecorder` (raw packets), `RadiodStream` (samples + gap handling), `ManagedStream` (self-healing single channel), `MultiStream` (shared socket, many SSRCs)
 - **Typed status decoder** — `ChannelStatus`, `FrontendStatus`, `PllStatus`, etc. with dotted-path field access
 - **Precise RTP timing** — GPS_TIME / RTP_TIMESNAP for sample-accurate wallclock timestamps
@@ -39,6 +40,19 @@ Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, S
 pip install ka9q-python
 ```
 
+Optional extras:
+
+| Extra | Adds | Needed for |
+|-------|------|------------|
+| `tui` | `textual` | `ka9q tui` interactive terminal UI |
+| `opus` | `opuslib` | decoding `OPUS` / `OPUS_VOIP` RTP payloads via `OpusDecoder` |
+| `dev`  | `pytest`, `pytest-cov` | running the test suite |
+
+```bash
+pip install "ka9q-python[opus]"          # one extra
+pip install "ka9q-python[tui,opus]"      # multiple
+```
+
 Or install from source:
 
 ```bash

{ka9q_python-3.15.0 → ka9q_python-3.16.1}/docs/API_REFERENCE.md

@@ -150,7 +150,7 @@ Tuning & filter:
 
 Gain / AGC:
 - `set_gain(ssrc, gain_db)`
-- `set_agc(ssrc, enable, hangtime=None, recovery_rate=None, threshold=None)`
+- `set_agc(ssrc, enable, hangtime=None, headroom=None, recovery_rate=None, threshold=None)`
 - `set_agc_hangtime(ssrc, seconds)`
 - `set_agc_recovery_rate(ssrc, db_per_sec)`
 - `set_agc_threshold(ssrc, threshold_db)`
@@ -286,20 +286,20 @@ for the full list — they mirror ka9q-radio's `status.h`.
 
 RTP output encoding (integer values match ka9q-radio's `rtp.h`):
 
-| Name | Value | Notes |
-|---|---|---|
-| `NO_ENCODING` | 0 | radiod default |
-| `S16LE` | 1 | Signed 16-bit little-endian PCM |
-| `S16BE` | 2 | Signed 16-bit big-endian PCM |
-| `OPUS` | 3 | Opus audio |
-| `F32LE` | 4 | 32-bit float LE (also `Encoding.F32`) |
-| `AX25` | 5 | Packet radio |
-| `F16LE` | 6 | 16-bit float LE (also `Encoding.F16`) |
-| `OPUS_VOIP` | 7 | Opus with `APPLICATION_VOIP` |
-| `F32BE` | 8 | 32-bit float BE |
-| `F16BE` | 9 | 16-bit float BE |
-| `MULAW` | 10 | μ-law |
-| `ALAW` | 11 | A-law |
+| Name | Value | Decoded by | Notes |
+|---|---|---|---|
+| `NO_ENCODING` | 0 | `parse_rtp_samples` | radiod default → treated as F32LE |
+| `S16LE` | 1 | `parse_rtp_samples` | Signed 16-bit little-endian PCM |
+| `S16BE` | 2 | `parse_rtp_samples` | Signed 16-bit big-endian PCM |
+| `OPUS` | 3 | `OpusDecoder` (extra) | Opus audio — needs `[opus]` install extra |
+| `F32LE` | 4 | `parse_rtp_samples` | 32-bit float LE (also `Encoding.F32`) |
+| `AX25` | 5 | (caller handles bytes) | Packet radio — framed protocol, not samples |
+| `F16LE` | 6 | `parse_rtp_samples` | 16-bit float LE (also `Encoding.F16`) |
+| `OPUS_VOIP` | 7 | `OpusDecoder` (extra) | Opus with `APPLICATION_VOIP` |
+| `F32BE` | 8 | `parse_rtp_samples` | 32-bit float BE |
+| `F16BE` | 9 | `parse_rtp_samples` | 16-bit float BE |
+| `MULAW` | 10 | `parse_rtp_samples` | G.711 µ-law (table-based, pure NumPy) |
+| `ALAW` | 11 | `parse_rtp_samples` | G.711 A-law (table-based, pure NumPy) |
 
 ### `DemodType`
 
@@ -417,6 +417,57 @@ Derived properties:
 
 ## Streams
 
+### `parse_rtp_samples()`
+
+Source: [stream.py](../ka9q/stream.py). Decodes one RTP payload to a
+NumPy sample array. Shared by `RadiodStream` and `MultiStream`.
+
+```python
+parse_rtp_samples(
+    payload: bytes,
+    encoding: int,        # any Encoding.* value
+    is_iq: bool,          # True → complex64 output; False → float32
+) -> np.ndarray | None
+```
+
+Covers every linear-PCM encoding radiod's `pt_from_info()` can grant:
+`NO_ENCODING`, `S16LE`, `S16BE`, `F32LE`, `F32BE`, `F16LE`, `F16BE`,
+`MULAW`, `ALAW`. G.711 µ-law / A-law use table-based NumPy decoders
+(no `audioop` dependency — that module is removed in Python 3.13).
+Unsupported encodings log a warning and fall back to F32LE.
+
+Returns `None` for `OPUS`, `OPUS_VOIP` (use `OpusDecoder` below), and
+`AX25` (framed protocol data, handle the bytes yourself).
+
+### `OpusDecoder`
+
+Source: [stream.py](../ka9q/stream.py). Optional Opus payload decoder
+for radiod's `OPUS` / `OPUS_VOIP` streams. Requires the `[opus]`
+install extra (`pip install ka9q-python[opus]`, which pulls
+`opuslib`).
+
+```python
+OpusDecoder(sample_rate: int = 48000, channels: int = 1)
+```
+
+- `decode(payload: bytes, *, fec: bool = False) -> np.ndarray` —
+  one Opus frame → float32 PCM, normalised to ±1.0. Stereo output is
+  interleaved L,R,L,R,…. Empty payload triggers one frame of
+  packet-loss concealment.
+- `sample_rate` / `channels` properties expose the codec config.
+
+Maintain one `OpusDecoder` instance per stream SSRC so the internal
+codec state — and therefore PLC — works correctly across packets.
+`sample_rate` must be one of 8000/12000/16000/24000/48000.
+
+```python
+from ka9q.stream import OpusDecoder
+
+dec = OpusDecoder(sample_rate=48000, channels=1)
+for payload in opus_payloads:
+    samples = dec.decode(payload)  # float32, mono
+```
+
 ### `RadiodStream`
 
 Source: [stream.py](../ka9q/stream.py). Continuous-sample consumer

{ka9q_python-3.15.0 → ka9q_python-3.16.1}/docs/ARCHITECTURE.md

@@ -77,6 +77,17 @@ to handle out-of-order RTP. Hands each batch to an
 `on_samples(samples, quality)` callback. Does **not** heal radiod
 restarts — a restart produces a lasting silence.
 
+`stream.py` also exposes two payload-decoder helpers shared by every
+stream class:
+
+- `parse_rtp_samples(payload, encoding, is_iq)` — decodes every
+  linear-PCM encoding radiod emits (`S16LE/BE`, `F32LE/BE`,
+  `F16LE/BE`, `MULAW`, `ALAW`) to NumPy in pure Python, no
+  `audioop` (gone in Py 3.13).
+- `OpusDecoder(sample_rate, channels)` — decodes `OPUS` / `OPUS_VOIP`
+  via the optional `opuslib` dependency (`pip install ka9q-python[opus]`).
+  One instance per SSRC so codec state and PLC stay coherent.
+
 ### 3. `ManagedStream` ([managed_stream.py](../ka9q/managed_stream.py))
 
 High-level self-healing wrapper around `RadiodStream`. A background

{ka9q_python-3.15.0 → ka9q_python-3.16.1}/docs/INSTALLATION.md

@@ -41,6 +41,18 @@ pip install -e ".[dev]"
 
 This includes pytest and other testing tools.
 
+### Optional Extras
+
+`ka9q-python` defines three optional dependency groups:
+
+| Extra | Adds | Needed for |
+|-------|------|------------|
+| `dev` | `pytest`, `pytest-cov` | running the test suite |
+| `tui` | `textual` | the `ka9q tui` interactive terminal UI |
+| `opus` | `opuslib` | decoding `OPUS` / `OPUS_VOIP` RTP payloads with `ka9q.stream.OpusDecoder` |
+
+Combine as needed, e.g. `pip install -e ".[dev,opus]"`.
+
 ## For Use in Other Applications
 
 ### In requirements.txt
@@ -98,7 +110,7 @@ python3 -c "import ka9q; print(f'ka9q version {ka9q.__version__} installed succe
 
 Expected output (version will match whatever is installed):
 ```
-ka9q version 3.9.0 installed successfully
+ka9q version 3.15.0 installed successfully
 ```
 
 After installation, the `ka9q` command-line tool is also on your `PATH`:
@@ -131,7 +143,8 @@ Package works with Python's built-in networking. Use IP addresses instead of `.l
 - `numpy >= 1.24.0`
 
 ### Optional (for enhanced functionality)
-- `textual` — required for `ka9q tui`. Not pulled in by the base install; install with `pip install textual` (or bundle it into your deployment requirements).
+- `textual` — required for `ka9q tui`. Install via the `[tui]` extra or `pip install textual` directly.
+- `opuslib` — required to decode `OPUS` / `OPUS_VOIP` RTP payloads via `ka9q.stream.OpusDecoder`. Install via the `[opus]` extra or `pip install opuslib`. (Linear-PCM encodings — `S16LE/BE`, `F32LE/BE`, `F16LE/BE`, `MULAW`, `ALAW` — are decoded in pure NumPy and need no extra dependency.)
 - `avahi-utils` (Linux) — faster mDNS hostname resolution
 - `control` from ka9q-radio — fallback path for channel discovery
 
@@ -187,11 +200,13 @@ pip uninstall ka9q
 ```bash
 pip install build
 python3 -m build
+# or, with uv:
+uv build
 ```
 
-This creates:
-- `dist/ka9q-1.0.0-py3-none-any.whl` (wheel)
-- `dist/ka9q-1.0.0.tar.gz` (source distribution)
+This creates (filenames track the current version in `pyproject.toml`):
+- `dist/ka9q_python-X.Y.Z-py3-none-any.whl` (wheel)
+- `dist/ka9q_python-X.Y.Z.tar.gz` (source distribution)
 
 ### Upload to PyPI (maintainers only)
 ```bash

{ka9q_python-3.15.0 → ka9q_python-3.16.1}/docs/MULTI_STREAM.md

@@ -254,10 +254,16 @@ Based on the current source ([`ka9q/multi_stream.py`](../ka9q/multi_stream.py)):
 - **No `remove_channel()` in the public API.** To remove a channel,
   stop the `MultiStream`, rebuild it with the remaining channels, and
   start again. For long-lived recorders this has been acceptable.
-- **Opus encoded streams** — `parse_rtp_samples()` must understand
-  the encoding. S16LE/S16BE (1/2) and F32LE (4) are the well-tested
-  paths; if you need Opus, verify against
-  [`ka9q/stream.py`](../ka9q/stream.py).
+- **Linear-PCM encodings** are decoded by `parse_rtp_samples()` in
+  pure NumPy: `S16LE/BE`, `F32LE/BE`, `F16LE/BE`, `MULAW`, `ALAW`.
+  All radiod-emitted sample encodings work out of the box.
+- **Opus** (`OPUS`, `OPUS_VOIP`) is a framed codec, not raw samples
+  — `parse_rtp_samples()` returns `None` for those payloads. Wrap
+  the stream with `ka9q.stream.OpusDecoder` (requires the `[opus]`
+  install extra) to recover float32 PCM, keeping one decoder
+  instance per SSRC so packet-loss concealment works.
+- **AX25** (encoding 5) is framed protocol data, also not samples —
+  `parse_rtp_samples()` returns `None`. Handle the bytes yourself.
 - **`samples_per_packet=320` default** assumes the typical 12 kHz /
   26.67 ms RTP packetization used by radiod. If your channels run
   at a different packet cadence, set it explicitly.

{ka9q_python-3.15.0 → ka9q_python-3.16.1}/ka9q/__init__.py

@@ -56,7 +56,15 @@ Lower-level usage (explicit control):
         )
         print(f"Created channel with SSRC: {ssrc}")
 """
-__version__ = '3.14.2'
+try:
+    from importlib.metadata import version as _pkg_version, PackageNotFoundError as _PkgNotFound
+    try:
+        __version__ = _pkg_version("ka9q-python")
+    except _PkgNotFound:
+        __version__ = "0.0.0+unknown"
+    del _pkg_version, _PkgNotFound
+except ImportError:
+    __version__ = "0.0.0+unknown"
 __author__ = 'Michael Hauan AC0G'
 
 from .control import RadiodControl, allocate_ssrc
@@ -107,6 +115,7 @@ from .managed_stream import (
 )
 from .multi_stream import MultiStream
 from .spectrum_stream import SpectrumStream
+from .status_listener import StatusListener, StatusListenerStats
 
 __all__ = [
     # Control
@@ -170,6 +179,10 @@ __all__ = [
     # Spectrum Stream (FFT bin data receiver)
     'SpectrumStream',
 
+    # Continuous STATUS listener (live timing anchor refresh)
+    'StatusListener',
+    'StatusListenerStats',
+
     # Utilities
     'generate_multicast_ip',
     'ChannelMonitor',