python-aidot-cameras 0.15.6__tar.gz → 0.15.8__tar.gz

{python_aidot_cameras-0.15.6/python_aidot_cameras.egg-info → python_aidot_cameras-0.15.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.15.6
+Version: 0.15.8
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT

{python_aidot_cameras-0.15.6 → python_aidot_cameras-0.15.8}/aidot_cameras/camera/client.py

@@ -365,6 +365,18 @@ def _is_self_referential_source(source: str, stream_name: str) -> bool:
     return path == stream_name
 
 
+#: Packets the serve's demuxer may hold while it waits for a gap to fill.  A
+#: keyframe on an A001064 is 146-190 KB - roughly 130 packets - so anything
+#: smaller than a few hundred cannot ride out a burst that arrives out of order.
+#: Env-overridable because the right value depends on the link, not on us.
+_SERVE_REORDER_QUEUE = int(os.environ.get("AIDOT_SERVE_REORDER_QUEUE", "500"))
+
+#: How long (microseconds) the demuxer waits for a missing packet before moving
+#: on.  Bounded on purpose: waiting forever turns loss into a stall, which is the
+#: failure this is meant to prevent.
+_SERVE_MAX_DELAY_US = int(os.environ.get("AIDOT_SERVE_MAX_DELAY_US", "500000"))
+
+
 def _build_sdes_serve_cmd(
     *,
     sdp_path: str,
@@ -470,9 +482,26 @@ def _build_sdes_serve_cmd(
         # 2 s analyzeduration: the camera sends SPS+PPS+IDR in the first burst;
         # 15 s consumed nearly all packets during analysis.  PLI re-arms an IDR
         # every 5 s so parameters always re-arrive.
-        "-fflags", "+nobuffer+genpts",
+        #
+        # ``discardcorrupt`` is the loss half of this: both ends of this path are
+        # wireless (the camera, and typically the host), so RTP arrives with real
+        # gaps.  Measured on the reference install: `RTP: missed N packets` with
+        # ZERO drops on every socket in the path, which means the packets were
+        # lost before they ever reached the box.  Without this ffmpeg passes the
+        # damaged frame downstream and then backs its input queue up behind the
+        # reordering it thinks it needs - "max delay reached. need to consume
+        # packet" - and the serve eventually dies, taking every viewer with it.
+        # A brief artefact is a far better outcome than a dropped stream.
+        "-fflags", "+nobuffer+genpts+discardcorrupt",
         "-analyzeduration", "2000000",
         "-probesize", "500000",
+        # Reordering headroom.  The default (-1) leaves the demuxer with almost
+        # none, so a burst that arrives out of order reads as loss.  A keyframe
+        # here is 146-190 KB - about 130 packets - so the queue has to be able to
+        # hold more than one of them, and max_delay bounds how long it will wait
+        # before giving up on a gap rather than stalling the pipeline.
+        "-reorder_queue_size", str(_SERVE_REORDER_QUEUE),
+        "-max_delay", str(_SERVE_MAX_DELAY_US),
         "-i", sdp_path,
         *dest_args,
     ]

{python_aidot_cameras-0.15.6 → python_aidot_cameras-0.15.8}/aidot_cameras/camera/sdes_open.py

@@ -3637,7 +3637,16 @@ class _SdesOpenMixin:
                                 if not _sdes_probe_received:
                                     _sdes_probe_received = True
                                     _last_hb_ts = _time_br.time()  # HB fires in 10s
-                                if not hasattr(_bridge_fn, '_tutk_seq'):
+                                # Guard on a counter that is actually assigned.
+                                # This used to test `_tutk_seq`, a name nothing
+                                # ever set, so hasattr was False on EVERY packet
+                                # and both counters were reset to 0 each time -
+                                # every synthesized packet went out with
+                                # sequence number 1.  ffmpeg reads a constant
+                                # sequence as a stream of discontinuities and
+                                # reports `RTP: missed N packets` for loss that
+                                # never happened.
+                                if not hasattr(_bridge_fn, '_tutk_seq_v'):
                                     _bridge_fn._tutk_seq_a = 0
                                     _bridge_fn._tutk_seq_v = 0
                                 if _tk_audio:

{python_aidot_cameras-0.15.6 → python_aidot_cameras-0.15.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-aidot-cameras"
-version = "0.15.6"
+version = "0.15.8"
 description = "Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)"
 readme = "README.md"
 license = "MIT"

{python_aidot_cameras-0.15.6 → python_aidot_cameras-0.15.8/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.15.6
+Version: 0.15.8
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT

{python_aidot_cameras-0.15.6 → python_aidot_cameras-0.15.8}/python_aidot_cameras.egg-info/SOURCES.txt

@@ -78,6 +78,7 @@ tests/test_battery_detection.py
 tests/test_battery_evidence_corroboration.py
 tests/test_battery_skip_turn.py
 tests/test_ble_gateway.py
+tests/test_bridge_state_sentinels.py
 tests/test_constants_imports_resolve.py
 tests/test_deferred_hardening.py
 tests/test_device_login_guard.py
@@ -151,6 +152,7 @@ tests/test_sdp_narrowing_properties.py
 tests/test_sdp_payload_type_narrowing.py
 tests/test_security_hardening.py
 tests/test_serializable_login_info.py
+tests/test_serve_loss_tolerance.py
 tests/test_serve_relay.py
 tests/test_session_stats.py
 tests/test_shared_house_seam.py

python_aidot_cameras-0.15.8/tests/test_bridge_state_sentinels.py

@@ -0,0 +1,68 @@
+"""Lazy-init guards on the bridge must name a variable something actually sets.
+
+The bridge keeps its per-session state as attributes on its own function object
+and initialises them with `if not hasattr(_bridge_fn, 'X')`. That idiom fails
+silently when `X` is not the attribute the block goes on to assign: the guard is
+true on every packet, so the state resets every packet, and nothing raises.
+
+It happened. The TUTK-to-RTP synthesis guarded on `_tutk_seq` while assigning
+`_tutk_seq_a` and `_tutk_seq_v`, so both sequence counters reset on every packet
+and every synthesized RTP packet carried sequence number 1. ffmpeg reads a
+constant sequence as a stream of discontinuities and logs `RTP: missed N
+packets` - loss that never happened, on a hop where the kernel counters showed
+zero drops. Measured on the box: 0 drops on every socket in the path while
+ffmpeg reported 21 new missed-packet lines in one window.
+
+These tests read the source because the bridge is one long closure that cannot
+be called in isolation.
+"""
+import inspect
+import re
+
+from aidot_cameras.camera import sdes_open
+
+_SRC = inspect.getsource(sdes_open)
+
+
+def _assigned_attrs() -> set:
+    """Every `_bridge_fn.X = ...` attribute assigned anywhere in the module."""
+    return set(re.findall(r"_bridge_fn\.([A-Za-z_][A-Za-z0-9_]*)\s*=[^=]", _SRC))
+
+
+def test_every_hasattr_sentinel_is_a_name_something_assigns():
+    guarded = set(re.findall(r"hasattr\(_bridge_fn,\s*'([^']+)'\)", _SRC))
+    assigned = _assigned_attrs()
+    orphans = sorted(guarded - assigned)
+    assert not orphans, (
+        "these hasattr guards name attributes nothing ever assigns, so they are "
+        f"true on every packet and reset their state each time: {orphans}"
+    )
+
+
+def test_the_tutk_sequence_counters_survive_between_packets():
+    """The specific regression: a constant RTP sequence number.
+
+    Pin the guard to a counter the block assigns, so a reset-per-packet cannot
+    come back by renaming one side of the pair.
+    """
+    block = re.search(
+        r"if not hasattr\(_bridge_fn,\s*'([^']+)'\):\s*\n"
+        r"\s*_bridge_fn\._tutk_seq_a = 0\s*\n"
+        r"\s*_bridge_fn\._tutk_seq_v = 0",
+        _SRC,
+    )
+    assert block, "the TUTK sequence init block moved - re-point this test"
+    sentinel = block.group(1)
+    assert sentinel in ("_tutk_seq_a", "_tutk_seq_v"), (
+        f"the guard tests {sentinel!r}, which is not one of the counters it "
+        "initialises - the counters will reset on every packet and every "
+        "synthesized packet will carry the same sequence number"
+    )
+
+
+def test_the_counters_increment_rather_than_being_reassigned():
+    """Both counters must advance from their previous value, not restart."""
+    for name in ("_tutk_seq_a", "_tutk_seq_v"):
+        assert re.search(
+            rf"_bridge_fn\.{name} = \(_bridge_fn\.{name} \+ 1\) & 0xFFFF", _SRC
+        ), f"{name} no longer advances from its own previous value"

python_aidot_cameras-0.15.8/tests/test_serve_loss_tolerance.py

@@ -0,0 +1,70 @@
+"""The serve must ride out real packet loss instead of dying on it.
+
+Both ends of this path are usually wireless - the camera, and the Home Assistant
+host - so RTP genuinely arrives with gaps. Measured on the reference install:
+ffmpeg logged `RTP: missed N packets` while every socket in the path showed ZERO
+kernel drops, which means those packets were lost before they ever reached the
+box. Nothing in the code can recover them.
+
+What the code controls is what happens next. Without reordering headroom the
+demuxer treats a burst that arrives out of order as loss; without a bounded
+max_delay it stalls waiting ("max delay reached. need to consume packet") and
+backs its input queue up until the serve dies, dropping every attached viewer.
+A brief artefact is a far better outcome than a dropped stream.
+"""
+import pytest
+
+from aidot_cameras.camera.client import (
+    _SERVE_MAX_DELAY_US,
+    _SERVE_REORDER_QUEUE,
+    _build_sdes_serve_cmd,
+)
+
+_DESTINATIONS = [
+    pytest.param({"rtsp_push_url": "rtsp://127.0.0.1:8554/cam"}, id="push"),
+    pytest.param({"rtsp_push_url": "http://127.0.0.1:18981/cam.ts"}, id="http-listen"),
+    pytest.param({"output_path": "/tmp/cam.ts"}, id="file"),
+    pytest.param({}, id="null-drain"),
+]
+
+
+def _cmd(**kwargs):
+    return _build_sdes_serve_cmd(sdp_path="/tmp/x.sdp", **kwargs)
+
+
+@pytest.mark.parametrize("dest", _DESTINATIONS)
+def test_every_destination_gets_the_loss_tolerance_args(dest):
+    """The input side is shared, so loss tolerance must not depend on the sink."""
+    cmd = _cmd(**dest)
+    assert "-reorder_queue_size" in cmd
+    assert cmd[cmd.index("-reorder_queue_size") + 1] == str(_SERVE_REORDER_QUEUE)
+    assert "-max_delay" in cmd
+    assert cmd[cmd.index("-max_delay") + 1] == str(_SERVE_MAX_DELAY_US)
+    fflags = cmd[cmd.index("-fflags") + 1]
+    assert "discardcorrupt" in fflags, fflags
+
+
+def test_the_reorder_queue_clears_a_keyframe():
+    # 146-190 KB of keyframe is ~130 packets at MTU. A queue that cannot hold
+    # more than one keyframe's worth reads an out-of-order burst as loss.
+    assert _SERVE_REORDER_QUEUE >= 260
+
+
+def test_max_delay_is_bounded():
+    """Unbounded waiting turns loss into the stall this is meant to prevent."""
+    assert 0 < _SERVE_MAX_DELAY_US <= 2_000_000
+
+
+@pytest.mark.parametrize("dest", _DESTINATIONS)
+def test_the_low_latency_flags_survive(dest):
+    """Tolerance must not be bought by silently reintroducing buffering."""
+    fflags = _cmd(**dest)[_cmd(**dest).index("-fflags") + 1]
+    assert "nobuffer" in fflags and "genpts" in fflags, fflags
+
+
+def test_the_args_sit_before_the_input():
+    """Demuxer options after -i apply to the output and are silently ignored."""
+    cmd = _cmd(rtsp_push_url="rtsp://127.0.0.1:8554/cam")
+    i = cmd.index("-i")
+    for opt in ("-reorder_queue_size", "-max_delay", "-fflags"):
+        assert cmd.index(opt) < i, f"{opt} must precede -i to affect the input"