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

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

@@ -1,5 +1,20 @@
 # Changelog
 
+## [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.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.15.0
+Version: 3.15.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.15.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.15.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.15.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.15.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.15.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.15.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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.15.0
+Version: 3.15.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.15.1}/pyproject.toml

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