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

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

@@ -1,5 +1,42 @@
 # Changelog
 
+## [3.13.0] - 2026-05-08
+
+### Added
+
+- **`MultiStream` channel-lifetime support**: closes the gap from 3.10.0 where
+  `RadiodControl.{create_channel,ensure_channel,tune}` accepted a `lifetime=`
+  kwarg but `MultiStream.add_channel()` did not, leaving MultiStream-based
+  clients (psk-recorder, hfdl-recorder, hf-timestd) unable to opt into
+  radiod's channel self-destruct timer for crash-resilient cleanup.
+  - `MultiStream.add_channel(..., lifetime=None)` — optional kwarg, forwarded
+    to the internal `ensure_channel` call. Stored per-slot.
+  - **Drop/restore path now re-applies lifetime**: `_attempt_restore` reads
+    the stored slot lifetime and passes it to `ensure_channel`. Previously,
+    a channel that radiod self-destructed and MultiStream restored would
+    silently lose its LIFETIME until the next external keep-alive — the
+    most dangerous failure mode now closed.
+  - `MultiStream.set_channel_lifetime(ssrc, lifetime)` — keep-alive method
+    that updates both the wire (via `RadiodControl.set_channel_lifetime`)
+    and the slot's stored lifetime, so the value survives subsequent
+    drop/restore cycles.
+
+### Backward Compatibility
+
+- Default behavior unchanged: omitting `lifetime` produces a packet with no
+  LIFETIME tag (ChannelSlot.lifetime defaults to None). Existing MultiStream
+  callers see no change in wire behavior.
+
+### Tests
+
+- 5 new unit tests in `tests/test_lifetime.py::TestMultiStreamLifetime` cover:
+  forward-on-add, lifetime=None default, restore-reapplies-lifetime,
+  set_channel_lifetime updates slot+wire, set_channel_lifetime is a no-op for
+  unknown SSRC. 258 unit tests still green.
+
+---
+
+
 ## [3.12.0] - 2026-05-07
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.12.0
+Version: 3.13.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.12.0 → ka9q_python-3.13.0}/ka9q/__init__.py

@@ -56,7 +56,7 @@ Lower-level usage (explicit control):
         )
         print(f"Created channel with SSRC: {ssrc}")
 """
-__version__ = '3.12.0'
+__version__ = '3.13.0'
 __author__ = 'Michael Hauan AC0G'
 
 from .control import RadiodControl, allocate_ssrc

{ka9q_python-3.12.0 → ka9q_python-3.13.0}/ka9q/multi_stream.py

@@ -81,6 +81,7 @@ class _ChannelSlot:
     last_packet_time: float = 0.0
     dropped: bool = False
     first_rtp_timestamp: Optional[int] = None
+    lifetime: Optional[int] = None
 
 
 class MultiStream:
@@ -132,6 +133,7 @@ class MultiStream:
         low_edge: Optional[float] = None,
         high_edge: Optional[float] = None,
         kaiser_beta: Optional[float] = None,
+        lifetime: Optional[int] = None,
     ) -> ChannelInfo:
         """Provision a channel and register it for reception.
 
@@ -142,6 +144,15 @@ class MultiStream:
         preset's default passband. None = use preset defaults. See
         RadiodControl.ensure_channel for the full semantics.
 
+        ``lifetime`` opts the channel into radiod's self-destruct timer
+        (radiod commit 0f8b622+, see RadiodControl.set_channel_lifetime).
+        The value is stored per-slot so the drop/restore path re-applies
+        it: a channel that radiod self-destructs and we then restore
+        won't silently lose its lifetime. The caller is still
+        responsible for periodic keep-alive via
+        ``set_channel_lifetime()`` (or by calling
+        RadiodControl.set_channel_lifetime directly on the SSRC).
+
         Returns the ChannelInfo from ensure_channel().
         """
         channel_info = self._control.ensure_channel(
@@ -154,6 +165,7 @@ class MultiStream:
             low_edge=low_edge,
             high_edge=high_edge,
             kaiser_beta=kaiser_beta,
+            lifetime=lifetime,
         )
 
         addr = channel_info.multicast_address
@@ -189,6 +201,7 @@ class MultiStream:
             on_stream_dropped=on_stream_dropped,
             on_stream_restored=on_stream_restored,
             deliver_interval=self._deliver_interval,
+            lifetime=lifetime,
         )
         self._slots[ssrc] = slot
 
@@ -224,6 +237,24 @@ class MultiStream:
             f"{self._multicast_address}:{self._port}"
         )
 
+    def set_channel_lifetime(self, ssrc: int, lifetime: int) -> None:
+        """Refresh the LIFETIME tag on one channel and update slot state.
+
+        Suitable as a periodic keep-alive: callers should invoke this on
+        every active SSRC at a cadence shorter than the lifetime so the
+        radiod self-destruct counter never reaches zero. The new value
+        is also stored in the slot, so a subsequent drop/restore will
+        re-apply this value rather than the original ``add_channel``
+        argument.
+
+        No-op if ``ssrc`` is not in this MultiStream.
+        """
+        slot = self._slots.get(ssrc)
+        if slot is None:
+            return
+        self._control.set_channel_lifetime(ssrc, lifetime)
+        slot.lifetime = lifetime
+
     def stop(self) -> None:
         """Stop threads and close socket."""
         if not self._running:
@@ -426,6 +457,7 @@ class MultiStream:
                 preset=slot.preset,
                 sample_rate=slot.sample_rate,
                 encoding=slot.encoding,
+                lifetime=slot.lifetime,
             )
             new_ssrc = channel_info.ssrc
             if new_ssrc != ssrc:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.12.0
+Version: 3.13.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.12.0 → ka9q_python-3.13.0}/pyproject.toml

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

{ka9q_python-3.12.0 → ka9q_python-3.13.0}/tests/test_lifetime.py

@@ -173,3 +173,91 @@ class TestCreateChannelLifetime:
         )
         assert sent
         assert not _has_lifetime_tag(sent[0])
+
+
+class TestMultiStreamLifetime:
+    """MultiStream stores ``lifetime`` per-slot and forwards it to
+    ensure_channel on both the initial add and the drop/restore path,
+    plus exposes a set_channel_lifetime() keep-alive method.
+
+    Asserted at the ``RadiodControl.ensure_channel`` boundary — these
+    tests don't exercise the wire encoding (covered above), they verify
+    that MultiStream wires the kwarg through correctly.
+    """
+
+    def _make_multi_with_mock_control(self, ssrc=12345):
+        from ka9q.multi_stream import MultiStream
+        from ka9q.discovery import ChannelInfo
+
+        control = MagicMock()
+        control.ensure_channel.return_value = ChannelInfo(
+            ssrc=ssrc,
+            preset="iq",
+            sample_rate=12000,
+            frequency=14_074_000.0,
+            snr=0.0,
+            multicast_address="239.1.2.3",
+            port=5004,
+        )
+        multi = MultiStream(control=control)
+        return multi, control
+
+    def test_add_channel_forwards_lifetime(self):
+        multi, control = self._make_multi_with_mock_control()
+        multi.add_channel(
+            frequency_hz=14_074_000.0,
+            preset="iq",
+            sample_rate=12000,
+            lifetime=6000,
+        )
+        kwargs = control.ensure_channel.call_args.kwargs
+        assert kwargs["lifetime"] == 6000
+
+    def test_add_channel_lifetime_none_when_omitted(self):
+        multi, control = self._make_multi_with_mock_control()
+        multi.add_channel(
+            frequency_hz=14_074_000.0,
+            preset="iq",
+            sample_rate=12000,
+        )
+        kwargs = control.ensure_channel.call_args.kwargs
+        assert kwargs["lifetime"] is None
+
+    def test_restore_reapplies_stored_lifetime(self):
+        """A slot added with lifetime=N must re-pass N on _attempt_restore."""
+        multi, control = self._make_multi_with_mock_control()
+        multi.add_channel(
+            frequency_hz=14_074_000.0,
+            preset="iq",
+            sample_rate=12000,
+            lifetime=6000,
+        )
+        ssrc = next(iter(multi._slots))
+        slot = multi._slots[ssrc]
+        slot.dropped = True
+        control.ensure_channel.reset_mock()
+
+        multi._attempt_restore(ssrc, slot)
+
+        kwargs = control.ensure_channel.call_args.kwargs
+        assert kwargs["lifetime"] == 6000
+
+    def test_set_channel_lifetime_updates_slot_and_wire(self):
+        multi, control = self._make_multi_with_mock_control()
+        multi.add_channel(
+            frequency_hz=14_074_000.0,
+            preset="iq",
+            sample_rate=12000,
+            lifetime=6000,
+        )
+        ssrc = next(iter(multi._slots))
+
+        multi.set_channel_lifetime(ssrc, 9000)
+
+        control.set_channel_lifetime.assert_called_once_with(ssrc, 9000)
+        assert multi._slots[ssrc].lifetime == 9000
+
+    def test_set_channel_lifetime_unknown_ssrc_is_noop(self):
+        multi, control = self._make_multi_with_mock_control()
+        multi.set_channel_lifetime(99999, 6000)
+        control.set_channel_lifetime.assert_not_called()