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

{python_aidot_cameras-0.15.7/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.7
+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.7 → 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.7 → 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.7"
+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.7 → 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.7
+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.7 → python_aidot_cameras-0.15.8}/python_aidot_cameras.egg-info/SOURCES.txt

@@ -152,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_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"