ka9q-python 3.10.0__tar.gz → 3.12.0__tar.gz

{ka9q_python-3.10.0 → ka9q_python-3.12.0}/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [3.12.0] - 2026-05-07
+
+### Added
+
+- **Spectrum bin vector decoding**: `decode_status_packet()` now decodes `BIN_DATA` (float32, `SPECT_DEMOD`) and `BIN_BYTE_DATA` (uint8, `SPECT2_DEMOD`) TLV vectors from radiod status packets. New fields on `SpectrumStatus`:
+  - `bin_data: Optional[np.ndarray]` — float32 power values per FFT bin.
+  - `bin_byte_data: Optional[np.ndarray]` — uint8 quantised log-power values.
+  - `bin_power_db` property — returns dB values regardless of source format (10*log10 for float data, `base + byte * step` for byte data).
+
+- **`SpectrumStream`**: new class for receiving real-time FFT spectrum data from radiod. Spectrum data flows over the status multicast channel (port 5006) as TLV vectors, not over RTP. `SpectrumStream` handles channel creation, periodic polling, SSRC filtering, and delivers decoded `ChannelStatus` objects (with populated `spectrum.bin_power_db`) to an `on_spectrum` callback. Supports retuning via `set_frequency()` and context manager usage.
+
+### Documentation
+
+- API_REFERENCE.md: SpectrumStream section, SpectrumStatus bin vector fields, quickstart table updated.
+- ARCHITECTURE.md: module listing, abstraction layer description, threading model updated.
+- RECIPES.md: Recipe 5 covering spectrum display, spectrogram accumulation, frequency axis reconstruction, FFT parameter tuning, and combined audio+spectrum patterns.
+- New `examples/spectrum_example.py`: runnable CLI example for real-time spectrum reception.
+
+### Tests
+
+- 13 new unit tests in `tests/test_spectrum.py` covering float32 and uint8 bin decoding, multi-byte TLV lengths, `bin_power_db` property, combined metadata+bins, edge cases, and import verification.
+
+---
+
+
+## [3.11.0] - 2026-05-06
+
+### Added
+
+- **Channel filter overrides on create / ensure / add_channel**: optional `low_edge`, `high_edge`, and `kaiser_beta` kwargs on `RadiodControl.create_channel()`, `RadiodControl.ensure_channel()`, and `MultiStream.add_channel()` — when specified, the requested filter passband is applied inline with the channel-create command (no transient at preset BW), and on the reuse path of `ensure_channel`, `set_filter` is called so the requested edges are authoritative regardless of the channel's prior state. Previously, callers were stuck with the preset's `low`/`high` values and had to either author a custom radiod preset or call `set_filter` manually after channel creation. Filter edges are not part of the SSRC hash — multiple callers requesting the same channel with different filters reconfigure last-writer-wins, matching the existing model for `gain` / `agc_enable`.
+  - Motivating clients: hf-timestd's BPSK PPS calibrator needs ~±500 Hz to match the TS1 injector's effectively-CW spectrum (the iq preset's ±5 kHz is wrong by an order of magnitude); planned SuperDARN and CODAR-sounder receivers need wider passbands than any single preset provides.
+
+### Backward Compatibility
+
+- Default behavior unchanged: omitting all three kwargs produces a wire packet with no LOW_EDGE / HIGH_EDGE / KAISER_BETA tags, so radiod uses the preset's defaults exactly as before. Reuse path also skips `set_filter` when no filter args are supplied.
+
+### Tests
+
+- 8 new unit tests in `tests/test_filter_edges.py` cover encode-presence on each entry point, encode-absence when omitted, ensure_channel forwarding on the create path, and ensure_channel reuse-path calling set_filter (only when filter args are supplied).
+
+---
+
 ## [3.10.0] - 2026-04-30
 
 ### Added

{ka9q_python-3.10.0/ka9q_python.egg-info → ka9q_python-3.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.10.0
+Version: 3.12.0
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G

{ka9q_python-3.10.0 → ka9q_python-3.12.0}/docs/API_REFERENCE.md

@@ -42,6 +42,7 @@ Pick the highest layer that fits:
 | Continuous samples | [`RadiodStream`](../ka9q/stream.py) | You want numpy arrays with gap-filling |
 | Self-healing samples | [`ManagedStream`](../ka9q/managed_stream.py) | Long-running client that must survive radiod restarts |
 | Many channels, one socket | [`MultiStream`](../ka9q/multi_stream.py) | 10+ channels on the same multicast group |
+| Spectrum / FFT data | [`SpectrumStream`](../ka9q/spectrum_stream.py) | Spectrogram display, band monitoring, signal search |
 
 All layers sit on top of [`RadiodControl`](../ka9q/control.py), which
 speaks the TLV protocol to radiod over multicast UDP.
@@ -396,7 +397,18 @@ Derived properties:
   `deemph_tc`, `deemph_gain`, `threshold_extend`.
 - `SpectrumStatus` — `avg`, `base`, `step`, `shape`, `fft_n`,
   `overlap`, `resolution_bw`, `noise_bw`, `bin_count`, `crossover`,
-  `window_type`.
+  `window_type`, `bin_data`, `bin_byte_data`.
+
+  **Bin vectors** (populated when the status packet contains spectrum
+  data from a `SPECT_DEMOD` or `SPECT2_DEMOD` channel):
+
+  - `bin_data: Optional[np.ndarray]` — float32 I²+Q² power per bin
+    (SPECT_DEMOD). Bin 0 = DC, 1..N/2 = positive, N/2+1..N-1 = negative.
+  - `bin_byte_data: Optional[np.ndarray]` — uint8 quantised log-power
+    (SPECT2_DEMOD). Reconstruct dB with `base + byte * step`.
+  - `bin_power_db -> Optional[np.ndarray]` — **property** that returns
+    dB values regardless of source format (10*log10 for float,
+    base + byte*step for byte). Returns `None` if no bin data is present.
 - `Filter2Status` — `blocking`, `blocksize`, `fir_length`,
   `kaiser_beta`.
 - `OpusStatus` — `bit_rate`, `dtx`, `application`, `bandwidth`, `fec`.
@@ -518,6 +530,82 @@ for freq in (14.074e6, 7.074e6, 3.573e6):
 multi.start()
 ```
 
+### `SpectrumStream`
+
+Source: [spectrum_stream.py](../ka9q/spectrum_stream.py). Receives
+real-time FFT spectrum data from radiod via the status multicast
+channel (port 5006). Unlike audio streams which use RTP, spectrum
+data arrives as `BIN_DATA` or `BIN_BYTE_DATA` TLV vectors inside
+status packets.
+
+```python
+SpectrumStream(
+    control,                     # RadiodControl
+    frequency_hz,                # center frequency (Hz)
+    bin_count=1024,              # number of FFT bins
+    resolution_bw=100.0,         # bin bandwidth (Hz)
+    *,
+    demod_type=DemodType.SPECT2_DEMOD,  # SPECT_DEMOD or SPECT2_DEMOD
+    window_type=None,            # see WindowType (default: Kaiser)
+    kaiser_beta=None,            # Kaiser window shape parameter
+    averaging=None,              # FFTs averaged per response
+    overlap=None,                # window overlap ratio (0.0–1.0)
+    poll_interval_sec=0.1,       # seconds between poll commands
+    on_spectrum=None,            # (ChannelStatus) -> None
+)
+```
+
+- `start() -> int` — create the spectrum channel and begin receiving.
+  Returns the SSRC.
+- `stop()` — stop threads, close socket, remove the channel from radiod.
+- `set_frequency(frequency_hz)` — retune the spectrum center frequency.
+- `ssrc -> Optional[int]` — the allocated SSRC.
+- `frames_received -> int` — count of spectrum frames delivered.
+- Supports `with` (context manager).
+
+The `on_spectrum` callback receives a fully-decoded `ChannelStatus`
+whose `.spectrum.bin_data` or `.spectrum.bin_byte_data` is populated.
+Use `.spectrum.bin_power_db` for a format-independent numpy array of
+dB values.
+
+```python
+from ka9q import RadiodControl, SpectrumStream
+
+def on_spectrum(status):
+    db = status.spectrum.bin_power_db
+    freq = status.frequency
+    rbw = status.spectrum.resolution_bw
+    print(f"{len(db)} bins at {freq/1e6:.3f} MHz, "
+          f"peak {db.max():.1f} dB, floor {db.min():.1f} dB")
+
+with RadiodControl("radiod.local") as ctl:
+    with SpectrumStream(
+        control=ctl,
+        frequency_hz=14.1e6,
+        bin_count=2048,
+        resolution_bw=50.0,
+        on_spectrum=on_spectrum,
+    ) as stream:
+        time.sleep(30)  # receive for 30 seconds
+```
+
+#### How spectrum data flows
+
+Spectrum data uses a completely different path from audio:
+
+| | Audio | Spectrum |
+|---|---|---|
+| Transport | RTP on data multicast (port 5004) | TLV inside status multicast (port 5006) |
+| Packet type | RTP with audio payload | Status packet with `BIN_DATA`/`BIN_BYTE_DATA` vectors |
+| Trigger | Continuous (radiod pushes) | Poll-driven (`SpectrumStream` sends periodic COMMAND packets) |
+| Demod type | `LINEAR_DEMOD`, `FM_DEMOD`, `WFM_DEMOD` | `SPECT_DEMOD` (float32) or `SPECT2_DEMOD` (uint8) |
+
+`SpectrumStream` handles the polling, socket management, SSRC
+filtering, and TLV decoding internally. The callback receives a
+ready-to-use `ChannelStatus` with numpy arrays.
+
+---
+
 ### `StreamQuality`, `GapSource`, `GapEvent`
 
 Source: [stream_quality.py](../ka9q/stream_quality.py). Delivered to

{ka9q_python-3.10.0 → ka9q_python-3.12.0}/docs/ARCHITECTURE.md

@@ -48,6 +48,7 @@ ka9q/
 ├── stream.py           RadiodStream — continuous sample delivery
 ├── managed_stream.py   ManagedStream — self-healing single-channel wrapper
 ├── multi_stream.py     MultiStream — shared-socket multi-SSRC receiver
+├── spectrum_stream.py  SpectrumStream — real-time FFT bin data receiver
 ├── pps_calibrator.py   L6 BPSK PPS chain-delay calibration
 ├── cli.py              `ka9q` console script (list / query / set / tui)
 └── tui.py              Textual TUI panels
@@ -95,6 +96,17 @@ users: wspr-recorder, psk-recorder, hf-timestd.
 
 See [MULTI_STREAM.md](MULTI_STREAM.md) for depth.
 
+### 5. `SpectrumStream` ([spectrum_stream.py](../ka9q/spectrum_stream.py))
+
+Real-time FFT spectrum receiver. Spectrum data takes a different path
+from audio: it arrives as `BIN_DATA` / `BIN_BYTE_DATA` TLV vectors
+inside status packets on port 5006 (not RTP on port 5004).
+`SpectrumStream` creates a `SPECT2_DEMOD` channel, polls radiod
+periodically to trigger fresh FFT output, and delivers decoded
+`ChannelStatus` objects (with `spectrum.bin_power_db` as a numpy
+array) to an `on_spectrum` callback. Use this for spectrogram
+displays, band activity monitors, and signal-search applications.
+
 ---
 
 ## Core: `RadiodControl`
@@ -252,6 +264,7 @@ packet atomically, releases.
 - `MultiStream`: one health thread, one RTP receive thread total
   (shared across all slots).
 - `RadiodStream`: one RTP receive thread.
+- `SpectrumStream`: one status-channel receive thread, one poll thread.
 
 All are daemon threads; `stop()` joins with a 5 s timeout.
 
@@ -331,7 +344,7 @@ socket attributes to `None` in `finally` blocks.
 ### Stream lifecycle
 
 Every streaming class (`RadiodStream`, `ManagedStream`, `MultiStream`,
-`RTPRecorder`) follows the same shape:
+`SpectrumStream`, `RTPRecorder`) follows the same shape:
 
 ```
 __init__ → start() → (threads run) → stop() → (threads join, sockets closed)

{ka9q_python-3.10.0 → ka9q_python-3.12.0}/docs/RECIPES.md

@@ -501,6 +501,190 @@ Until then, use the recipe above.
 
 ---
 
+## Recipe 5 — Spectrum display and spectrogram (FFT bin data)
+
+ka9q-radio’s `radiod` can produce FFT spectrum data in addition to
+demodulated audio. The ka9q-web frontend uses this for its waterfall
+display. `SpectrumStream` gives Python clients the same capability.
+
+### 5.1 How spectrum data differs from audio
+
+Audio streams use RTP packets on the data multicast group (port 5004).
+Spectrum data is completely different:
+
+- It flows over the **status multicast channel** (port 5006), not RTP.
+- It arrives as `BIN_DATA` (float32) or `BIN_BYTE_DATA` (uint8)
+  vectors inside TLV-encoded status packets.
+- It is **poll-driven**: the client sends periodic COMMAND packets to
+  request fresh FFT output; radiod responds with status packets
+  containing the bin vectors.
+- The demodulator type is `SPECT_DEMOD` (float32 output) or
+  `SPECT2_DEMOD` (quantised uint8 output, more compact).
+
+`SpectrumStream` handles all of this internally.
+
+### 5.2 Basic spectrum display
+
+```python
+from ka9q import RadiodControl, SpectrumStream
+
+def on_spectrum(status):
+    db = status.spectrum.bin_power_db      # numpy float32 array
+    freq = status.frequency                # center frequency, Hz
+    rbw = status.spectrum.resolution_bw    # bin width, Hz
+    n = len(db)
+    print(f"{n} bins at {freq/1e6:.3f} MHz, "
+          f"RBW {rbw:.1f} Hz, "
+          f"peak {db.max():.1f} dB, floor {db.min():.1f} dB")
+
+with RadiodControl("bee1-hf-status.local") as ctl:
+    with SpectrumStream(
+        control=ctl,
+        frequency_hz=14.1e6,
+        bin_count=2048,
+        resolution_bw=50.0,
+        on_spectrum=on_spectrum,
+    ) as stream:
+        import time
+        time.sleep(60)  # receive spectrum for 60 seconds
+```
+
+### 5.3 Building a spectrogram
+
+A spectrogram is a time-vs-frequency image where each row is one
+spectrum frame. Accumulate the `bin_power_db` arrays into a 2-D
+matrix:
+
+```python
+import numpy as np
+from ka9q import RadiodControl, SpectrumStream
+
+rows = []
+
+def on_spectrum(status):
+    db = status.spectrum.bin_power_db
+    if db is not None:
+        rows.append(db.copy())
+
+with RadiodControl("bee1-hf-status.local") as ctl:
+    with SpectrumStream(
+        control=ctl,
+        frequency_hz=14.1e6,
+        bin_count=1024,
+        resolution_bw=100.0,
+        averaging=5,
+        on_spectrum=on_spectrum,
+    ) as stream:
+        import time
+        time.sleep(30)
+
+# rows is now a list of 1-D numpy arrays; stack into a 2-D image
+spectrogram = np.array(rows)  # shape: (time_steps, n_bins)
+print(f"Spectrogram: {spectrogram.shape[0]} frames x "
+      f"{spectrogram.shape[1]} bins")
+
+# Render with matplotlib:
+# import matplotlib.pyplot as plt
+# plt.imshow(spectrogram.T, aspect="auto", origin="lower",
+#            cmap="viridis", vmin=-120, vmax=-40)
+# plt.colorbar(label="dB")
+# plt.xlabel("Time (frame)"); plt.ylabel("Bin")
+# plt.show()
+```
+
+### 5.4 FFT parameters
+
+`SpectrumStream` exposes radiod’s full FFT configuration:
+
+| Parameter | Default | Description |
+|---|---|---|
+| `bin_count` | 1024 | Number of frequency bins |
+| `resolution_bw` | 100.0 Hz | Bandwidth per bin |
+| `window_type` | None (radiod default: Kaiser) | FFT window function (see `WindowType`) |
+| `kaiser_beta` | None | Kaiser window shape parameter |
+| `averaging` | None | Number of FFTs averaged per output |
+| `overlap` | None | Window overlap ratio (0.0–1.0) |
+| `demod_type` | `SPECT2_DEMOD` | `SPECT_DEMOD` for float32, `SPECT2_DEMOD` for uint8 |
+| `poll_interval_sec` | 0.1 | Seconds between poll commands |
+
+radiod uses two internal algorithms depending on resolution
+bandwidth relative to a crossover frequency (default 200 Hz):
+
+- **Wideband** (rbw > 200 Hz): operates on raw A/D samples.
+- **Narrowband** (rbw ≤ 200 Hz): downconverts to complex baseband
+  first. Higher resolution but higher CPU cost.
+
+### 5.5 Frequency axis reconstruction
+
+Bin order in the delivered arrays is: bin 0 = DC (center frequency),
+bins 1..N/2 = positive offsets, bins N/2+1..N-1 = negative offsets.
+To build a frequency axis:
+
+```python
+def bin_frequencies(center_hz, bin_count, resolution_bw):
+    """Return frequency axis for spectrum bins (Hz)."""
+    import numpy as np
+    bins = np.arange(bin_count)
+    # Shift so bin 0 = DC is at center
+    offsets = np.where(bins <= bin_count // 2,
+                       bins, bins - bin_count)
+    return center_hz + offsets * resolution_bw
+```
+
+### 5.6 Retuning
+
+`SpectrumStream.set_frequency()` retunes the spectrum channel
+without stopping and restarting:
+
+```python
+stream.start()
+time.sleep(10)
+stream.set_frequency(7.1e6)   # switch to 40m band
+time.sleep(10)
+stream.stop()
+```
+
+### 5.7 Combining spectrum with audio
+
+A common pattern for interactive SDR applications: display a
+spectrogram with `SpectrumStream` and play audio from a selected
+frequency with `ManagedStream`. Both use the same `RadiodControl`:
+
+```python
+from ka9q import RadiodControl, SpectrumStream, ManagedStream
+
+with RadiodControl("radiod.local") as ctl:
+    # Wideband spectrum display
+    spectrum = SpectrumStream(
+        control=ctl,
+        frequency_hz=14.1e6,
+        bin_count=2048,
+        resolution_bw=50.0,
+        on_spectrum=render_waterfall,
+    )
+    spectrum.start()
+
+    # Narrowband audio for a selected signal
+    audio = ManagedStream(
+        control=ctl,
+        frequency_hz=14.074e6,
+        preset="usb",
+        sample_rate=12000,
+        on_samples=play_audio,
+    )
+    audio.start()
+
+    # ... user clicks on waterfall to retune audio ...
+    # ctl.set_frequency(audio.channel.ssrc, new_freq)
+
+    audio.stop()
+    spectrum.stop()
+```
+
+This is the pattern David Gonsalves’ spectrogram client will use.
+
+---
+
 ## Further reading
 
 - [GETTING_STARTED.md](GETTING_STARTED.md) — install, mDNS, multi-homed hosts

ka9q_python-3.12.0/examples/spectrum_example.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+Spectrum display example — receive real-time FFT data from radiod.
+
+Prints per-frame statistics: bin count, center frequency, resolution
+bandwidth, peak power, and noise floor. Demonstrates SpectrumStream,
+which receives spectrum data via the status multicast channel (not RTP).
+
+Usage:
+    python3 spectrum_example.py HOST [--freq HZ] [--bins N] [--rbw HZ]
+                                     [--duration SEC]
+
+Example:
+    python3 spectrum_example.py bee1-hf-status.local --freq 14.1e6
+    python3 spectrum_example.py bee1-hf-status.local --freq 7.0e6 --bins 2048 --rbw 25
+"""
+
+import argparse
+import sys
+import time
+
+import numpy as np
+
+from ka9q import RadiodControl, SpectrumStream
+
+
+def bin_frequencies(center_hz: float, bin_count: int, resolution_bw: float):
+    """Build a frequency axis (Hz) from spectrum metadata."""
+    bins = np.arange(bin_count)
+    offsets = np.where(bins <= bin_count // 2, bins, bins - bin_count)
+    return center_hz + offsets * resolution_bw
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Receive real-time spectrum data from radiod"
+    )
+    parser.add_argument("host", help="radiod status address (e.g. bee1-hf-status.local)")
+    parser.add_argument("--freq", type=float, default=14.1e6,
+                        help="Center frequency in Hz (default: 14.1 MHz)")
+    parser.add_argument("--bins", type=int, default=1024,
+                        help="Number of FFT bins (default: 1024)")
+    parser.add_argument("--rbw", type=float, default=100.0,
+                        help="Resolution bandwidth in Hz (default: 100)")
+    parser.add_argument("--duration", type=float, default=30.0,
+                        help="How long to run in seconds (default: 30)")
+    parser.add_argument("--averaging", type=int, default=None,
+                        help="Number of FFTs to average per frame")
+    parser.add_argument("--interface", type=str, default=None,
+                        help="Network interface IP for multicast")
+    args = parser.parse_args()
+
+    frame_count = 0
+
+    def on_spectrum(status):
+        nonlocal frame_count
+        frame_count += 1
+
+        db = status.spectrum.bin_power_db
+        if db is None:
+            print(f"  frame {frame_count}: no bin data")
+            return
+
+        freq_mhz = (status.frequency or 0) / 1e6
+        rbw = status.spectrum.resolution_bw or args.rbw
+        n = len(db)
+
+        # Find peak bin and its frequency
+        peak_idx = int(np.argmax(db))
+        freqs = bin_frequencies(status.frequency or args.freq, n, rbw)
+        peak_freq_mhz = freqs[peak_idx] / 1e6
+
+        print(
+            f"  frame {frame_count:4d}: "
+            f"{n} bins @ {freq_mhz:.3f} MHz, "
+            f"RBW {rbw:.1f} Hz, "
+            f"peak {db[peak_idx]:.1f} dB at {peak_freq_mhz:.4f} MHz, "
+            f"floor {db.min():.1f} dB"
+        )
+
+    print(f"Connecting to {args.host}...")
+    with RadiodControl(args.host, interface=args.interface) as ctl:
+        print(f"Starting spectrum stream: {args.freq/1e6:.3f} MHz, "
+              f"{args.bins} bins, {args.rbw} Hz/bin")
+
+        kwargs = {}
+        if args.averaging is not None:
+            kwargs["averaging"] = args.averaging
+
+        with SpectrumStream(
+            control=ctl,
+            frequency_hz=args.freq,
+            bin_count=args.bins,
+            resolution_bw=args.rbw,
+            on_spectrum=on_spectrum,
+            **kwargs,
+        ) as stream:
+            print(f"SSRC: {stream.ssrc}")
+            print(f"Receiving for {args.duration} seconds...\n")
+            try:
+                time.sleep(args.duration)
+            except KeyboardInterrupt:
+                print("\nInterrupted.")
+
+        print(f"\nDone. {frame_count} frames received.")
+
+
+if __name__ == "__main__":
+    main()

{ka9q_python-3.10.0 → ka9q_python-3.12.0}/ka9q/__init__.py

@@ -56,7 +56,7 @@ Lower-level usage (explicit control):
         )
         print(f"Created channel with SSRC: {ssrc}")
 """
-__version__ = '3.9.0'
+__version__ = '3.12.0'
 __author__ = 'Michael Hauan AC0G'
 
 from .control import RadiodControl, allocate_ssrc
@@ -106,6 +106,7 @@ from .managed_stream import (
     StreamState,
 )
 from .multi_stream import MultiStream
+from .spectrum_stream import SpectrumStream
 
 __all__ = [
     # Control
@@ -166,6 +167,9 @@ __all__ = [
     # Multi Stream (shared socket, multiple channels)
     'MultiStream',
 
+    # Spectrum Stream (FFT bin data receiver)
+    'SpectrumStream',
+
     # Utilities
     'generate_multicast_ip',
     'ChannelMonitor',

{ka9q_python-3.10.0 → ka9q_python-3.12.0}/ka9q/control.py

@@ -1087,7 +1087,10 @@ class RadiodControl:
                        destination: Optional[str] = None,
                        encoding: int = 0,
                        ssrc: Optional[int] = None,
-                       lifetime: Optional[int] = None) -> int:
+                       lifetime: Optional[int] = None,
+                       low_edge: Optional[float] = None,
+                       high_edge: Optional[float] = None,
+                       kaiser_beta: Optional[float] = None) -> int:
         """
         Create a new channel with specified configuration
         
@@ -1126,6 +1129,16 @@ class RadiodControl:
                   the lifetime to at least Channel_idle_timeout (~20 s) — so
                   callers using a finite lifetime as a crash-safe cleanup
                   must keep polling (e.g. via tune() or set_channel_lifetime).
+            low_edge: Channel filter low edge in Hz, relative to channel
+                  center (typically negative for symmetric IQ filters).
+                  None = use the preset's default. Useful for clients that
+                  need a narrower or wider passband than the preset provides
+                  (e.g. BPSK PPS calibration with a near-CW signal needs a
+                  much narrower filter than the iq preset's default).
+            high_edge: Channel filter high edge in Hz, relative to channel
+                  center. None = use the preset's default. See low_edge.
+            kaiser_beta: Filter window Kaiser beta. None = use radiod default.
+                  Higher beta = sharper transition + more sidelobe rejection.
         
         Returns:
             The SSRC of the created channel (useful when auto-allocated)
@@ -1173,8 +1186,13 @@ class RadiodControl:
             _validate_sample_rate(sample_rate)
         _validate_gain(gain)
         
+        filter_desc = ""
+        if low_edge is not None or high_edge is not None or kaiser_beta is not None:
+            filter_desc = (f", filter=[{low_edge},{high_edge}]"
+                           f"{f' beta={kaiser_beta}' if kaiser_beta is not None else ''}")
         logger.info(f"Creating channel: SSRC={ssrc}, freq={frequency_hz/1e6:.3f} MHz, "
-                   f"demod={preset}, rate={sample_rate}Hz, agc={agc_enable}, gain={gain}dB, enc={encoding}")
+                   f"demod={preset}, rate={sample_rate}Hz, agc={agc_enable}, gain={gain}dB, "
+                   f"enc={encoding}{filter_desc}")
         
         # Build a single command packet with ALL parameters
         # This ensures radiod creates the channel with the correct settings
@@ -1200,7 +1218,21 @@ class RadiodControl:
         if sample_rate:
             encode_int(cmdbuffer, StatusType.OUTPUT_SAMPRATE, sample_rate)
             logger.info(f"Setting sample rate for SSRC {ssrc} to {sample_rate} Hz")
-        
+
+        # Filter edges + Kaiser beta — override the preset defaults inline
+        # with the create command so the channel goes live with the requested
+        # passband from frame zero (no transient at preset BW). Same TLV path
+        # as set_filter().
+        if low_edge is not None:
+            encode_double(cmdbuffer, StatusType.LOW_EDGE, low_edge)
+            logger.info(f"Setting LOW_EDGE for SSRC {ssrc} to {low_edge} Hz")
+        if high_edge is not None:
+            encode_double(cmdbuffer, StatusType.HIGH_EDGE, high_edge)
+            logger.info(f"Setting HIGH_EDGE for SSRC {ssrc} to {high_edge} Hz")
+        if kaiser_beta is not None:
+            encode_float(cmdbuffer, StatusType.KAISER_BETA, kaiser_beta)
+            logger.info(f"Setting KAISER_BETA for SSRC {ssrc} to {kaiser_beta}")
+
         # AGC setting
         encode_int(cmdbuffer, StatusType.AGC_ENABLE, agc_enable)
         logger.info(f"Setting AGC_ENABLE for SSRC {ssrc} to {agc_enable}")
@@ -1306,6 +1338,9 @@ class RadiodControl:
         timeout: float = 5.0,
         frequency_tolerance: float = 1.0,
         lifetime: Optional[int] = None,
+        low_edge: Optional[float] = None,
+        high_edge: Optional[float] = None,
+        kaiser_beta: Optional[float] = None,
     ):
         """
         Ensure a channel exists with the requested characteristics and return it.
@@ -1339,7 +1374,21 @@ class RadiodControl:
                      so the channel's lifetime is refreshed regardless of its
                      prior state. None (default) = don't touch lifetime.
                      See create_channel() for the full unit semantics.
-        
+            low_edge: Optional channel filter low edge in Hz (relative to
+                     channel center). When specified, the requested filter is
+                     applied both to newly-created channels (inline with the
+                     create command) and to reused channels (via set_filter
+                     after the reuse decision), so ensure_channel always
+                     returns a channel with the requested passband.
+                     None (default) = use the preset's filter edges.
+                     Note: filter edges are not part of the channel identity
+                     (they don't participate in SSRC allocation), so a second
+                     caller requesting the same channel with different edges
+                     will reconfigure the filter — last-writer-wins, same
+                     model as gain/AGC.
+            high_edge: See low_edge.
+            kaiser_beta: Optional filter window Kaiser beta. None = radiod default.
+
         Returns:
             ChannelInfo object with verified channel details, ready for RadiodStream
         
@@ -1428,6 +1477,21 @@ class RadiodControl:
                         # set forces it to the requested value.
                         if lifetime is not None:
                             self.set_channel_lifetime(ssrc, int(lifetime))
+                        # Apply filter edges on reuse so the requested
+                        # passband is authoritative regardless of the prior
+                        # channel state. ChannelInfo doesn't expose current
+                        # filter edges (radiod's discovery payload doesn't
+                        # carry them reliably), so we re-send rather than
+                        # compare.
+                        if (low_edge is not None
+                                or high_edge is not None
+                                or kaiser_beta is not None):
+                            self.set_filter(
+                                ssrc,
+                                low_edge=low_edge,
+                                high_edge=high_edge,
+                                kaiser_beta=kaiser_beta,
+                            )
                         return existing
                     else:
                         logger.info(
@@ -1456,6 +1520,9 @@ class RadiodControl:
             encoding=encoding,
             ssrc=ssrc,
             lifetime=lifetime,
+            low_edge=low_edge,
+            high_edge=high_edge,
+            kaiser_beta=kaiser_beta,
         )
         
         # Wait for channel to appear and verify it meets specs