ka9q-python 3.8.0__tar.gz → 3.9.0__tar.gz

{ka9q_python-3.8.0/ka9q_python.egg-info → ka9q_python-3.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.8.0
+Version: 3.9.0
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G
@@ -28,6 +28,8 @@ Requires-Dist: numpy>=1.24.0
 Provides-Extra: dev
 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"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -294,6 +296,7 @@ It auto-skips if `../ka9q-radio` is not present, so CI environments without the
 For detailed information, please refer to the documentation in the `docs/` directory:
 
 - **[API Reference](docs/API_REFERENCE.md)**: Full details on all classes, methods, and functions.
+- **[TUI Guide](docs/TUI_GUIDE.md)**: Launching and using the `ka9q tui` Textual terminal UI.
 - **[RTP Timing Support](docs/RTP_TIMING_SUPPORT.md)**: Guide to RTP timing and synchronization.
 - **[Architecture](docs/ARCHITECTURE.md)**: Overview of the library's design and structure.
 - **[Installation Guide](docs/INSTALLATION.md)**: Detailed installation instructions.

{ka9q_python-3.8.0 → ka9q_python-3.9.0}/README.md

@@ -259,6 +259,7 @@ It auto-skips if `../ka9q-radio` is not present, so CI environments without the
 For detailed information, please refer to the documentation in the `docs/` directory:
 
 - **[API Reference](docs/API_REFERENCE.md)**: Full details on all classes, methods, and functions.
+- **[TUI Guide](docs/TUI_GUIDE.md)**: Launching and using the `ka9q tui` Textual terminal UI.
 - **[RTP Timing Support](docs/RTP_TIMING_SUPPORT.md)**: Guide to RTP timing and synchronization.
 - **[Architecture](docs/ARCHITECTURE.md)**: Overview of the library's design and structure.
 - **[Installation Guide](docs/INSTALLATION.md)**: Detailed installation instructions.

{ka9q_python-3.8.0 → ka9q_python-3.9.0}/docs/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to ka9q-python will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.9.0] - 2026-04-14
+
+### Added - `ka9q` CLI and Textual TUI
+
+- **`ka9q` console script** (`ka9q.cli`) with `list` / `query` / `set` / `tui`
+  subcommands and a shared `SET_VERBS` vocabulary so the CLI and TUI accept
+  identical parameter names and values.
+- **Textual TUI** (`ka9q.tui`, opt-in via `pip install ka9q-python[tui]`):
+  8-panel live view (Tuning, Frontend/GPSDO, Signal/Levels, Filter/FFT,
+  Demod, Options/Squelch, Input/Status, Output/RTP) with `control`-style
+  one-letter keybindings. Updates come from a passive `listen_status()`
+  worker plus a 1 Hz `poll_status()` tick so values refresh even when the
+  channel is idle.
+- **Typed status decoder** (`ka9q.status`): `ChannelStatus`,
+  `FrontendStatus`, `PllStatus`, `FmStatus`, `SpectrumStatus`,
+  `Filter2Status`, `OpusStatus` dataclasses plus `decode_status_packet()`,
+  all re-exported from `ka9q`.
+- **New `RadiodControl` methods**: `poll_status(ssrc, timeout)` for active
+  SSRC-tagged polls, and `listen_status(callback, duration, ssrcs)` for
+  passive multicast receive.
+- **Docs**: [TUI Guide](TUI_GUIDE.md) covering launch, update cadence,
+  per-panel field reference (including where GPSDO discipline and ADC
+  overrange counters surface), keybinding table, and troubleshooting.
+
 ## [3.4.0] - 2024-12-30
 
 ### Added - Web UI Interactive Control 🎛️

ka9q_python-3.9.0/docs/TUI_GUIDE.md

@@ -0,0 +1,148 @@
+# ka9q TUI Guide
+
+A Textual-based terminal UI for monitoring and controlling a live
+`radiod` channel. Modeled on ka9q-radio's ncurses `control` program:
+eight panels of channel state and one-letter keybindings that drive the
+same setters as `ka9q set`.
+
+## Install
+
+The TUI dependency (`textual`) ships as an optional extra:
+
+```bash
+pip install -e ".[tui]"
+# or, for development:
+pip install -e ".[dev,tui]"
+```
+
+## Launch
+
+```bash
+# Watch a specific SSRC (recommended)
+ka9q tui bee1-hf-status.local --ssrc 14095000
+
+# Or discover interactively — the TUI latches onto the first SSRC
+# seen on the status multicast
+ka9q tui bee1-hf-status.local
+
+# Pin a network interface when the host is multi-homed
+ka9q tui bee1-hf-status.local --ssrc 14095000 --interface eth0
+```
+
+Find SSRCs first with `ka9q list HOST`.
+
+## Update cadence
+
+radiod emits per-channel status packets in two situations:
+
+1. **On change** — when any setter modifies the channel.
+2. **On poll** — in response to a status-request command.
+
+The TUI uses both:
+
+- A background thread runs `RadiodControl.listen_status()` and pushes
+  any status packet for the focused SSRC onto an internal queue
+  ([tui.py:38-62](../ka9q/tui.py#L38-L62)). This captures change-driven
+  updates and anything triggered by other clients (e.g. a running
+  `control` instance).
+- A 1 Hz timer calls `poll_status(ssrc, timeout=0.8)` in a worker
+  thread ([tui.py:412-421](../ka9q/tui.py#L412-L421)), so values
+  refresh every second even when the channel is idle.
+- The UI drains the queue and repaints every 200 ms
+  ([tui.py:399](../ka9q/tui.py#L399)).
+
+A one-shot `poll_status(timeout=2.0)` fires at mount to populate the
+panels immediately.
+
+## Panels
+
+Grid layout (3×3, last cell blank):
+
+| Panel | Source fields |
+|---|---|
+| **Tuning** | Carrier, first/second LO, shift, channel filter edges, frontend filter edges, Doppler |
+| **Frontend / GPSDO** | Description, input sample rate, AD bits, real/complex, **`calibrate_ppm`**, **`gpsdo_reference_hz`** (10 MHz reference), `ad_over`, `samples_since_over`, LNA/MIX/IF gains, RF gain/atten/AGC |
+| **Signal / Levels** | IF power (dBFS), RF level cal, input dBm, baseband power, noise density, S/N₀, S/N + bandwidth, output level |
+| **Filter / FFT** | Kaiser β, blocksize, FIR length, drops, noise BW, optional Filter2 block |
+| **Demod** | Mode + demod name, plus mode-specific block (FM SNR / peak dev / PL tone / de-emphasis; linear AGC / ISB / envelope / PLL; spectrum RBW / bins / window / FFT N) |
+| **Options / Squelch** | Lock, SNR squelch enable, open/close thresholds, ISB, envelope, AGC, FM threshold-extend |
+| **Input / Status** | GPS time, cmd count, input sample rate, samples in, ADC overrange counters, status destination + interval |
+| **Output / RTP** | SSRC, output rate, channels, encoding, TTL, destination, sample count, packet counters, errors, max delay, Opus parameters when present |
+
+A "—" means the field is absent from the latest status packet — many
+fields depend on frontend/demod type (RX888 vs Airspy; linear vs FM vs
+spectrum), so not every cell is populated for every channel.
+
+### Where GPSDO and ADC governance show up
+
+- **GPSDO discipline**: `Frontend / GPSDO` panel — `Calibrate: ±x.xxx
+  ppm` is the frontend's fractional-frequency error vs. its 10 MHz
+  reference, and `Ref (10M): …` is the measured reference frequency.
+- **ADC overranges**: both `Frontend / GPSDO` and `Input / Status` show
+  `AD over` (total clip count) and `samples_since_over` (how long ago
+  the last clip occurred, in samples at the input sample rate).
+
+## Keybindings
+
+Modeled after `control`. Parameter keys open a single-line modal
+prompt; toggle keys act immediately.
+
+| Key | Action | Setter |
+|---|---|---|
+| `f` | Carrier frequency (Hz) | `set_frequency` |
+| `p` | Preset / mode | `set_preset` |
+| `S` | Sample rate (Hz) | `set_sample_rate` |
+| `s` | Squelch open (dB) | `set_squelch` |
+| `G` | RF gain (dB) | `set_rf_gain` |
+| `A` | RF attenuation (dB) | `set_rf_attenuation` |
+| `g` | Linear gain (dB) | `set_gain` |
+| `H` | Headroom (dB) | `set_headroom` |
+| `L` | AGC threshold (dB) | `set_agc_threshold` |
+| `R` | AGC recovery (dB/s) | `set_agc_recovery_rate` |
+| `T` | AGC hang time (s) | `set_agc_hangtime` |
+| `P` | PLL bandwidth (Hz) | `set_pll` |
+| `K` | Kaiser β | `set_kaiser_beta` |
+| `e` | Output encoding (S16LE, F32LE, OPUS…) | `set_output_encoding` |
+| `b` | Opus bitrate (bps) | `set_opus_bitrate` |
+| `t` | PL tone (Hz, 0 off) | `set_pl_tone` |
+| `D` | Demod type (linear/fm/wfm/spect) | `set_demod_type` |
+| `l` | Toggle channel lock | `set_lock` |
+| `i` | Toggle independent sideband | `set_independent_sideband` |
+| `v` | Toggle envelope detection | `set_envelope_detection` |
+| `x` | Toggle FM threshold-extend | `set_fm_threshold_extension` |
+| `?` / `h` | Show help overlay | — |
+| `q` | Quit | — |
+
+Prompt keys dispatch through `SET_VERBS` in
+[cli.py:163](../ka9q/cli.py#L163), so any value accepted by `ka9q set`
+is also accepted in the modal — the TUI and CLI share one vocabulary.
+
+If a setter raises, the header line shows `ERR: …` instead of dimming
+the panels, so you can see the failure without losing context.
+
+## Under the hood
+
+- [tui.py](../ka9q/tui.py) — app, panels, keybindings, status worker.
+- [control.py `listen_status`](../ka9q/control.py) — passive receive on
+  the status multicast.
+- [control.py `poll_status`](../ka9q/control.py) — active poll (sends a
+  command tagged with the target SSRC and waits for the matching
+  status reply).
+- [status.py `ChannelStatus`](../ka9q/status.py) — the typed dataclass
+  every panel reads from.
+
+## Troubleshooting
+
+**Nothing updates / panels stay blank.** Confirm the SSRC exists:
+`ka9q query HOST --ssrc N` should print a status. If `query` works but
+the TUI doesn't, the status multicast may be reaching the control
+socket but not the passive listener — check `--interface` on multi-homed
+hosts.
+
+**All values are "—".** The SSRC is receiving packets but they lack
+populated TLVs. Usually this means the channel is in an unusual demod
+state; pressing `p` and re-setting the preset forces radiod to emit a
+full status.
+
+**Key does nothing.** Parameter keys require a focused SSRC. Pass
+`--ssrc` explicitly or wait for the listener to latch onto one.

{ka9q_python-3.8.0 → ka9q_python-3.9.0}/ka9q/__init__.py

@@ -56,7 +56,7 @@ Lower-level usage (explicit control):
         )
         print(f"Created channel with SSRC: {ssrc}")
 """
-__version__ = '3.8.0'
+__version__ = '3.9.0'
 __author__ = 'Michael Hauan AC0G'
 
 from .control import RadiodControl, allocate_ssrc
@@ -68,6 +68,16 @@ from .discovery import (
     ChannelInfo
 )
 from .types import StatusType, Encoding, DemodType, WindowType
+from .status import (
+    FrontendStatus,
+    ChannelStatus,
+    PllStatus,
+    FmStatus,
+    SpectrumStatus,
+    Filter2Status,
+    OpusStatus,
+    decode_status_packet,
+)
 from .exceptions import Ka9qError, ConnectionError, CommandError, ValidationError
 from .rtp_recorder import (
     RTPRecorder,
@@ -114,6 +124,16 @@ __all__ = [
     'Encoding',
     'DemodType',
     'WindowType',
+
+    # Typed status
+    'FrontendStatus',
+    'ChannelStatus',
+    'PllStatus',
+    'FmStatus',
+    'SpectrumStatus',
+    'Filter2Status',
+    'OpusStatus',
+    'decode_status_packet',
     
     # Exceptions
     'Ka9qError',

ka9q_python-3.9.0/ka9q/cli.py

@@ -0,0 +1,338 @@
+"""
+``ka9q`` command-line tool.
+
+Subcommands mirror the things the Textual TUI does, so the CLI and TUI
+share one vocabulary:
+
+    ka9q list    HOST                              List channels (via discovery)
+    ka9q query   HOST --ssrc N [--field path] [--json] [--watch]
+    ka9q set     HOST --ssrc N PARAM VALUE         Change a parameter
+    ka9q tui     HOST                              Launch the Textual TUI
+
+Every ``set`` verb maps to a :class:`RadiodControl` setter, and every
+``query --field`` path is one of the dotted paths produced by
+:meth:`ChannelStatus.field_names`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from dataclasses import is_dataclass, asdict
+from typing import Any, Optional
+
+from .control import RadiodControl
+from .discovery import discover_channels
+from .status import ChannelStatus
+from .types import DemodType, Encoding, WindowType
+
+
+# ---------------------------------------------------------------------------
+# Rendering helpers
+# ---------------------------------------------------------------------------
+
+def _fmt_hz(v: Optional[float]) -> str:
+    if v is None:
+        return "—"
+    if abs(v) >= 1e6:
+        return f"{v/1e6:.6f} MHz"
+    if abs(v) >= 1e3:
+        return f"{v/1e3:.3f} kHz"
+    return f"{v:+.1f} Hz"
+
+
+def _render_status_text(st: ChannelStatus) -> str:
+    fe = st.frontend
+    L = []
+    L.append(f"SSRC:         {st.ssrc}")
+    L.append(f"Description:  {st.description or '—'}")
+    L.append(f"Preset / Mode: {st.preset or '—'} ({st.demod_name})")
+    L.append("")
+    L.append("[Tuning]")
+    L.append(f"  Carrier:     {_fmt_hz(st.frequency)}")
+    L.append(f"  First LO:    {_fmt_hz(st.first_lo)}   lock={fe.lock}")
+    L.append(f"  Second LO:   {_fmt_hz(st.second_lo)}")
+    L.append(f"  Shift:       {_fmt_hz(st.shift)}")
+    if st.doppler:
+        L.append(f"  Doppler:     {_fmt_hz(st.doppler)} @ {st.doppler_rate} Hz/s")
+    L.append(f"  Filter:      {_fmt_hz(st.low_edge)} .. {_fmt_hz(st.high_edge)}  (β={st.kaiser_beta})")
+    L.append(f"  FE filter:   {_fmt_hz(fe.fe_low_edge)} .. {_fmt_hz(fe.fe_high_edge)}")
+    L.append("")
+    L.append("[Frontend / GPSDO]")
+    L.append(f"  Input rate:  {fe.input_samprate} Hz  ({fe.ad_bits_per_sample} bits, real={fe.isreal})")
+    if fe.calibrate is not None:
+        L.append(f"  Calibrate:   {fe.calibrate:+.3e}  ({fe.calibrate_ppm:+.3f} ppm)")
+        L.append(f"  Implied 10 MHz ref: {fe.gpsdo_reference_hz:.3f} Hz")
+    L.append(f"  Overranges:  {fe.ad_over}  samples since: {fe.samples_since_over}")
+    L.append(f"  Gains:       LNA={fe.lna_gain} MIX={fe.mixer_gain} IF={fe.if_gain} "
+             f"RFgain={fe.rf_gain} RFatten={fe.rf_atten} RFAGC={fe.rf_agc}")
+    L.append(f"  IF power:    {fe.if_power} dBFS  cal={fe.rf_level_cal} dB  "
+             f"→ input {fe.input_power_dbm} dBm" if fe.if_power is not None else
+             "  IF power:    —")
+    L.append("")
+    L.append("[Signal / Levels]")
+    L.append(f"  Baseband:    {st.baseband_power} dB   Noise density: {st.noise_density} dB/Hz")
+    L.append(f"  Output lvl:  {st.output_level} dB   S/N0: {st.snr_per_hz} dB-Hz   "
+             f"S/N: {st.snr} dB  BW={st.bandwidth} Hz")
+    L.append("")
+    L.append("[Filter / FFT]")
+    L.append(f"  Blocksize:   {st.filter_blocksize}  FIR len: {st.filter_fir_length}  "
+             f"drops: {st.filter_drops}  noise_bw: {st.noise_bw}")
+    if st.filter2.blocking:
+        L.append(f"  Filter2:     blk={st.filter2.blocking} size={st.filter2.blocksize} "
+                 f"fir={st.filter2.fir_length} β={st.filter2.kaiser_beta}")
+    L.append("")
+    if st.demod_type == DemodType.FM_DEMOD:
+        L.append("[FM]")
+        L.append(f"  SNR: {st.fm.fm_snr}  peak dev: {st.fm.peak_deviation} Hz  "
+                 f"PL tone: {st.fm.pl_tone}/{st.fm.pl_deviation}")
+        L.append(f"  De-emph TC: {st.fm.deemph_tc}  gain: {st.fm.deemph_gain}  "
+                 f"thr-ext: {st.fm.threshold_extend}")
+    elif st.demod_type == DemodType.LINEAR_DEMOD:
+        L.append("[Linear]")
+        L.append(f"  AGC: {st.agc_enable}  gain: {st.gain}  headroom: {st.headroom}  "
+                 f"hang: {st.agc_hangtime}s  recov: {st.agc_recovery_rate} dB/s  "
+                 f"thresh: {st.agc_threshold} dB")
+        L.append(f"  ISB: {st.independent_sideband}   Envelope: {st.envelope}")
+        p = st.pll
+        L.append(f"  PLL: enable={p.enable} lock={p.lock} sq={p.square}  "
+                 f"BW={p.bw} Hz  Δf={p.freq_offset} Hz  φ={p.phase}  "
+                 f"SNR={p.snr} dB  wraps={p.wraps}")
+    elif st.demod_type in (DemodType.SPECT_DEMOD, DemodType.SPECT2_DEMOD):
+        sp = st.spectrum
+        L.append("[Spectrum]")
+        L.append(f"  RBW: {sp.resolution_bw} Hz  bins: {sp.bin_count}  crossover: {sp.crossover} Hz")
+        L.append(f"  FFT N: {sp.fft_n}  window: {sp.window_type}  overlap: {sp.overlap}  "
+                 f"avg: {sp.avg}  shape: {sp.shape}")
+    L.append("")
+    L.append("[Squelch / Options]")
+    L.append(f"  SNR-sq: {st.snr_squelch_enable}   open: {st.squelch_open}   close: {st.squelch_close}")
+    L.append(f"  Lock: {st.lock}")
+    L.append("")
+    L.append("[Output]")
+    L.append(f"  rate={st.output_samprate} ch={st.output_channels} enc={st.encoding_name} "
+             f"ttl={st.output_ttl}")
+    L.append(f"  dest={st.output_data_dest_socket}")
+    L.append(f"  samples={st.output_samples} pkts={st.output_data_packets} "
+             f"meta={st.output_metadata_packets} errs={st.output_errors}")
+    if st.opus.bit_rate:
+        L.append(f"  Opus: {st.opus.bit_rate} bps  dtx={st.opus.dtx}  app={st.opus.application} "
+                 f"bw={st.opus.bandwidth} fec={st.opus.fec}")
+    if st.tp1 is not None or st.tp2 is not None:
+        L.append(f"  TP1={st.tp1}  TP2={st.tp2}")
+    return "\n".join(L)
+
+
+def _json_default(o: Any) -> Any:
+    if is_dataclass(o):
+        return asdict(o)
+    raise TypeError(f"not json-serializable: {type(o).__name__}")
+
+
+# ---------------------------------------------------------------------------
+# ``set`` verb dispatch
+# ---------------------------------------------------------------------------
+
+def _coerce_bool(v: str) -> bool:
+    return v.lower() in ("1", "true", "yes", "on", "y", "t")
+
+
+def _coerce_encoding(v: str) -> int:
+    try:
+        return int(v)
+    except ValueError:
+        return getattr(Encoding, v.upper())
+
+
+def _coerce_demod(v: str) -> int:
+    try:
+        return int(v)
+    except ValueError:
+        return getattr(DemodType, v.upper() if v.upper().endswith("_DEMOD") else v.upper() + "_DEMOD")
+
+
+def _coerce_window(v: str) -> int:
+    try:
+        return int(v)
+    except ValueError:
+        return getattr(WindowType, v.upper() if v.upper().endswith("_WINDOW") else v.upper() + "_WINDOW")
+
+
+# (param-name → callable(control, ssrc, raw_value))
+SET_VERBS = {
+    "frequency":       lambda c, s, v: c.set_frequency(s, float(v)),
+    "preset":          lambda c, s, v: c.set_preset(s, v),
+    "mode":            lambda c, s, v: c.set_preset(s, v),
+    "sample-rate":     lambda c, s, v: c.set_sample_rate(s, int(v)),
+    "samprate":        lambda c, s, v: c.set_sample_rate(s, int(v)),
+    "low-edge":        lambda c, s, v: c.set_filter(s, low_edge=float(v)),
+    "high-edge":       lambda c, s, v: c.set_filter(s, high_edge=float(v)),
+    "kaiser-beta":     lambda c, s, v: c.set_kaiser_beta(s, float(v)),
+    "shift":           lambda c, s, v: c.set_shift_frequency(s, float(v)),
+    "gain":            lambda c, s, v: c.set_gain(s, float(v)),
+    "output-level":    lambda c, s, v: c.set_output_level(s, float(v)),
+    "headroom":        lambda c, s, v: c.set_headroom(s, float(v)),
+    "agc":             lambda c, s, v: c.set_agc(s, _coerce_bool(v)),
+    "agc-hangtime":    lambda c, s, v: c.set_agc_hangtime(s, float(v)),
+    "agc-recovery":    lambda c, s, v: c.set_agc_recovery_rate(s, float(v)),
+    "agc-threshold":   lambda c, s, v: c.set_agc_threshold(s, float(v)),
+    "rf-gain":         lambda c, s, v: c.set_rf_gain(s, float(v)),
+    "rf-atten":        lambda c, s, v: c.set_rf_attenuation(s, float(v)),
+    "squelch-open":    lambda c, s, v: c.set_squelch(s, enable=True, open_snr_db=float(v)),
+    "squelch-close":   lambda c, s, v: c.set_squelch(s, enable=True, close_snr_db=float(v)),
+    "snr-squelch":     lambda c, s, v: c.set_squelch(s, enable=_coerce_bool(v)),
+    "pll":             lambda c, s, v: c.set_pll(s, enable=_coerce_bool(v)),
+    "pll-bw":          lambda c, s, v: c.set_pll(s, enable=True, bandwidth_hz=float(v)),
+    "pll-square":      lambda c, s, v: c.set_pll(s, enable=True, square=_coerce_bool(v)),
+    "isb":             lambda c, s, v: c.set_independent_sideband(s, _coerce_bool(v)),
+    "envelope":        lambda c, s, v: c.set_envelope_detection(s, _coerce_bool(v)),
+    "channels":        lambda c, s, v: c.set_output_channels(s, int(v)),
+    "encoding":        lambda c, s, v: c.set_output_encoding(s, _coerce_encoding(v)),
+    "demod-type":      lambda c, s, v: c.set_demod_type(s, _coerce_demod(v)),
+    "pl-tone":         lambda c, s, v: c.set_pl_tone(s, float(v)),
+    "threshold-extend":lambda c, s, v: c.set_fm_threshold_extension(s, _coerce_bool(v)),
+    "lock":            lambda c, s, v: c.set_lock(s, _coerce_bool(v)),
+    "description":     lambda c, s, v: c.set_description(s, v),
+    "first-lo":        lambda c, s, v: c.set_first_lo(s, float(v)),
+    "status-interval": lambda c, s, v: c.set_status_interval(s, int(v)),
+    "max-delay":       lambda c, s, v: c.set_max_delay(s, int(v)),
+    "opus-bitrate":    lambda c, s, v: c.set_opus_bitrate(s, int(v)),
+    "opus-dtx":        lambda c, s, v: c.set_opus_dtx(s, _coerce_bool(v)),
+    "opus-application":lambda c, s, v: c.set_opus_application(s, int(v)),
+    "opus-bandwidth":  lambda c, s, v: c.set_opus_bandwidth(s, int(v)),
+    "opus-fec":        lambda c, s, v: c.set_opus_fec(s, int(v)),
+    "window":          lambda c, s, v: c.set_spectrum(s, window_type=_coerce_window(v)),
+    "destination":     lambda c, s, v: c.set_destination(s, *_parse_addr(v)),
+}
+
+
+def _parse_addr(v: str):
+    if ":" in v:
+        a, p = v.rsplit(":", 1)
+        return a, int(p)
+    return v, 5004
+
+
+# ---------------------------------------------------------------------------
+# Command handlers
+# ---------------------------------------------------------------------------
+
+def cmd_list(args: argparse.Namespace) -> int:
+    channels = discover_channels(args.host, timeout=args.timeout)
+    if args.json:
+        print(json.dumps([asdict(c) if is_dataclass(c) else c.__dict__ for c in channels],
+                         default=_json_default, indent=2))
+        return 0
+    if not channels:
+        print("No channels discovered.", file=sys.stderr)
+        return 1
+    print(f"{'SSRC':>10}  {'Frequency':>14}  {'Preset':<8}  Dest")
+    for c in channels:
+        freq = getattr(c, "frequency", None) or getattr(c, "frequency_hz", None)
+        ssrc = getattr(c, "ssrc", "?")
+        preset = getattr(c, "preset", "") or ""
+        dest = getattr(c, "data_dest", "") or getattr(c, "destination", "") or ""
+        print(f"{ssrc:>10}  {(freq or 0)/1e6:>13.6f}M  {preset:<8}  {dest}")
+    return 0
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    with RadiodControl(args.host) as control:
+        def show(st: ChannelStatus):
+            if args.field:
+                v = st.get_field(args.field)
+                if args.json:
+                    print(json.dumps({args.field: v}, default=_json_default))
+                else:
+                    print(v if v is not None else "")
+            elif args.json:
+                print(json.dumps(st.to_dict(), default=_json_default, indent=2))
+            else:
+                print(_render_status_text(st))
+                print()
+
+        if args.watch:
+            # Passive listener — radiod multicasts periodically.
+            ssrcs = {args.ssrc} if args.ssrc else None
+            try:
+                control.listen_status(show, ssrcs=ssrcs)
+            except KeyboardInterrupt:
+                return 0
+        else:
+            if args.ssrc is None:
+                print("--ssrc required (or use --watch without --ssrc to see all)", file=sys.stderr)
+                return 2
+            st = control.poll_status(args.ssrc, timeout=args.timeout)
+            show(st)
+    return 0
+
+
+def cmd_set(args: argparse.Namespace) -> int:
+    verb = args.param.lower()
+    if verb not in SET_VERBS:
+        print(f"Unknown parameter '{verb}'. Known: {', '.join(sorted(SET_VERBS))}", file=sys.stderr)
+        return 2
+    with RadiodControl(args.host) as control:
+        SET_VERBS[verb](control, args.ssrc, args.value)
+    return 0
+
+
+def cmd_tui(args: argparse.Namespace) -> int:
+    try:
+        from .tui import run_tui
+    except ImportError as exc:
+        print(f"TUI unavailable: {exc}\nInstall with: pip install ka9q-python[tui]", file=sys.stderr)
+        return 2
+    return run_tui(args.host, ssrc=args.ssrc, interface=args.interface)
+
+
+# ---------------------------------------------------------------------------
+# Top-level parser
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ka9q",
+        description="Control and monitor ka9q-radio channels.",
+    )
+    p.add_argument("--interface", help="Network interface for multicast (optional)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pl = sub.add_parser("list", help="Discover channels on HOST")
+    pl.add_argument("host")
+    pl.add_argument("--timeout", type=float, default=3.0)
+    pl.add_argument("--json", action="store_true")
+    pl.set_defaults(func=cmd_list)
+
+    pq = sub.add_parser("query", help="Query a channel's full status")
+    pq.add_argument("host")
+    pq.add_argument("--ssrc", type=int)
+    pq.add_argument("--field", help="Dotted path, e.g. 'frontend.calibrate' or 'pll.lock'")
+    pq.add_argument("--json", action="store_true")
+    pq.add_argument("--watch", action="store_true", help="Stream passive status updates")
+    pq.add_argument("--timeout", type=float, default=2.0)
+    pq.set_defaults(func=cmd_query)
+
+    ps = sub.add_parser("set", help="Set a channel parameter")
+    ps.add_argument("host")
+    ps.add_argument("--ssrc", type=int, required=True)
+    ps.add_argument("param", help=f"One of: {', '.join(sorted(SET_VERBS))}")
+    ps.add_argument("value")
+    ps.set_defaults(func=cmd_set)
+
+    pt = sub.add_parser("tui", help="Launch the Textual TUI")
+    pt.add_argument("host")
+    pt.add_argument("--ssrc", type=int, help="Focus a specific SSRC at startup")
+    pt.set_defaults(func=cmd_tui)
+
+    return p
+
+
+def main(argv: Optional[list] = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())