python-aidot-cameras 1.0.0b30__tar.gz → 1.0.0b32__tar.gz

{python_aidot_cameras-1.0.0b30/python_aidot_cameras.egg-info → python_aidot_cameras-1.0.0b32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0b30
+Version: 1.0.0b32
 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
@@ -415,6 +415,7 @@ audio, idle release, the sprop cache path) are documented in
 | `AIDOT_MAX_CONCURRENT_STREAMS` | Caps how many cameras stream at once. | `3` |
 | `AIDOT_FAST_CONNECT` | Enable LAN-direct "fast connect" (STUN-only, skips several cloud signaling waits) when truthy. On-LAN only - off-subnet/strict-NAT viewers must leave it off. | unset (off) |
 | `AIDOT_SDES_SKIP_TURN_PREALLOC` | Skip the SDES TURN relay pre-allocation (~2-3 s of cold-start latency) so signaling goes straight out with the host candidate. Faster on a LAN, at the cost of no relay fallback for a camera on a different segment / behind strict NAT. Experimental, opt-in (truthy = `1`/`true`/`yes`/`on`). | unset (off) |
+| `AIDOT_SDES_CONNECTION_MODE` | Which media path the SDES offer proposes: `auto` (default - every reachable candidate, and ICE priority prefers the LAN with the relay as last resort; measured on the full fleet, six of seven cameras stream direct and only the unit with no route to us rides the relay), `lan` (no relay at all - same lever as `AIDOT_SDES_SKIP_TURN_PREALLOC`, and battery cameras keep the relay regardless because a cloud-woken camera has no other path back), or `relay` (EXPERIMENTAL, and on the reference fleet it does not steer: even with `c=`/`m=` moved to the relay allocation and the WAN permission pre-installed, an A001064 and an A001513 both dialed our host address directly, learning it from our own ICE probes - forcing the relay for real would mean suppressing every direct-path outbound, which is unbuilt). Per-open `sdes_connection_mode` beats the env. Every session reports the path its media actually took as `media_stats().media_path` (`direct`/`relay`). | unset (`auto`) |
 | `AIDOT_SDES_ADAPTIVE` | Adaptive fast-with-fallback for the SDES keepalive loop: try the fast path first and fall back to the full relay path if a fast attempt delivers no media. A per-device cache skips the fast attempt on later views once it has failed. Truthy value enables. Ignored for battery cameras, where the fast path cannot win and its short grace truncates the cold start. | unset (off) |
 | `AIDOT_SDES_FAST_LIVEPLAY` | Don't block on the `livePlayResp` wait for eligible SDES cameras (~4.5 s faster cold start). Role-reversal models (A001064 PTZ) always excluded for correctness. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_SDES_NACK` | Ask the camera to resend video RTP packets that never arrived (RTCP Generic NACK). A camera losing packets on a weak link otherwise delivers truncated H.264 slices, which a browser's WebRTC decoder conceals but Media Source Extensions treats as fatal. Measured on an A001064 at ~1-2% loss: 98.4% of losses recovered against none at all without it. Costs nothing on a clean link, where no requests are generated. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b32}/README.md

@@ -375,6 +375,7 @@ audio, idle release, the sprop cache path) are documented in
 | `AIDOT_MAX_CONCURRENT_STREAMS` | Caps how many cameras stream at once. | `3` |
 | `AIDOT_FAST_CONNECT` | Enable LAN-direct "fast connect" (STUN-only, skips several cloud signaling waits) when truthy. On-LAN only - off-subnet/strict-NAT viewers must leave it off. | unset (off) |
 | `AIDOT_SDES_SKIP_TURN_PREALLOC` | Skip the SDES TURN relay pre-allocation (~2-3 s of cold-start latency) so signaling goes straight out with the host candidate. Faster on a LAN, at the cost of no relay fallback for a camera on a different segment / behind strict NAT. Experimental, opt-in (truthy = `1`/`true`/`yes`/`on`). | unset (off) |
+| `AIDOT_SDES_CONNECTION_MODE` | Which media path the SDES offer proposes: `auto` (default - every reachable candidate, and ICE priority prefers the LAN with the relay as last resort; measured on the full fleet, six of seven cameras stream direct and only the unit with no route to us rides the relay), `lan` (no relay at all - same lever as `AIDOT_SDES_SKIP_TURN_PREALLOC`, and battery cameras keep the relay regardless because a cloud-woken camera has no other path back), or `relay` (EXPERIMENTAL, and on the reference fleet it does not steer: even with `c=`/`m=` moved to the relay allocation and the WAN permission pre-installed, an A001064 and an A001513 both dialed our host address directly, learning it from our own ICE probes - forcing the relay for real would mean suppressing every direct-path outbound, which is unbuilt). Per-open `sdes_connection_mode` beats the env. Every session reports the path its media actually took as `media_stats().media_path` (`direct`/`relay`). | unset (`auto`) |
 | `AIDOT_SDES_ADAPTIVE` | Adaptive fast-with-fallback for the SDES keepalive loop: try the fast path first and fall back to the full relay path if a fast attempt delivers no media. A per-device cache skips the fast attempt on later views once it has failed. Truthy value enables. Ignored for battery cameras, where the fast path cannot win and its short grace truncates the cold start. | unset (off) |
 | `AIDOT_SDES_FAST_LIVEPLAY` | Don't block on the `livePlayResp` wait for eligible SDES cameras (~4.5 s faster cold start). Role-reversal models (A001064 PTZ) always excluded for correctness. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_SDES_NACK` | Ask the camera to resend video RTP packets that never arrived (RTCP Generic NACK). A camera losing packets on a weak link otherwise delivers truncated H.264 slices, which a browser's WebRTC decoder conceals but Media Source Extensions treats as fatal. Measured on an A001064 at ~1-2% loss: 98.4% of losses recovered against none at all without it. Costs nothing on a clean link, where no requests are generated. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b32}/aidot_cameras/camera/client.py

@@ -566,6 +566,36 @@ _SERVE_REORDER_QUEUE = int(os.environ.get("AIDOT_SERVE_REORDER_QUEUE", "500"))
 #: failure this is meant to prevent.
 _SERVE_MAX_DELAY_US = int(os.environ.get("AIDOT_SERVE_MAX_DELAY_US", "500000"))
 
+#: How long (seconds) the serve ffmpeg waits with NO packets on any RTP socket
+#: before its SDP input errors out ("Error during demuxing: Operation timed
+#: out") and the serve dies.  ffmpeg's own default is 10 s (READ_PACKET_TIMEOUT_S,
+#: applied through the sdp demuxer's ``listen_timeout`` option).  Measured on an
+#: A001064 (2026-08-24/25): the camera episodically stops transmitting for
+#: >=10 s mid-session, and every reopen afterwards succeeds immediately, so the
+#: link recovers on a 10-20 s scale.  A mains camera therefore gets 30 s to ride
+#: the gap out; a battery camera keeps ffmpeg's 10 s default, because its stops
+#: are real sleeps that only a reopen (with its wake) ends - waiting longer just
+#: freezes the picture.  ``AIDOT_SERVE_INPUT_TIMEOUT_S`` overrides both.
+_SERVE_INPUT_TIMEOUT_MAINS_S = 30
+_SERVE_INPUT_TIMEOUT_BATTERY_S = 10
+
+
+def _resolve_serve_input_timeout_s(is_battery: bool) -> int:
+    """Seconds the serve's SDP input tolerates total silence before erroring.
+
+    Pure policy (unit-testable): the env override wins for every camera; else
+    mains rides out a transmit gap and battery keeps the fast default.
+    """
+    _env = os.environ.get("AIDOT_SERVE_INPUT_TIMEOUT_S")
+    if _env:
+        try:
+            return max(1, int(_env))
+        except ValueError:
+            pass
+    return (_SERVE_INPUT_TIMEOUT_BATTERY_S if is_battery
+            else _SERVE_INPUT_TIMEOUT_MAINS_S)
+
+
 #: How long to wait after a camera answers -50002 / -50015 ("no free session").
 #: Both loops used to wait _MAX_DELAY (300s) on the belief that the camera
 #: "releases slowly". Measured 2026-08-07 on an A001064: reopening 2s after a
@@ -630,6 +660,7 @@ def _build_sdes_serve_cmd(
     audio_gain_db: float = -8.0,
     push_video_only: bool = False,
     video_decoder: Optional[list] = None,
+    input_timeout_s: Optional[int] = None,
 ) -> list:
     """Build the ffmpeg argv for the SDES bridge serve.
 
@@ -778,6 +809,13 @@ def _build_sdes_serve_cmd(
         # 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),
+        # Input silence tolerance: the sdp demuxer's ``listen_timeout`` doubles
+        # as its packet-read timeout (READ_PACKET_TIMEOUT_S, ffmpeg default
+        # 10 s).  See _resolve_serve_input_timeout_s for the mains/battery
+        # policy.  Input option, so it must sit before -i; None keeps ffmpeg's
+        # default (no behavior change for callers that do not opt in).
+        *(["-listen_timeout", str(int(input_timeout_s))]
+          if input_timeout_s is not None else []),
         "-i", sdp_path,
         *dest_args,
     ]
@@ -3540,6 +3578,7 @@ class CameraMixin(_CameraControlsMixin, _CameraSdMixin, _WebRTCOpenMixin, _SdesO
         stream_idle_s: Optional[float] = None,
         sdes_fast_liveplay: Optional[bool] = None,
         sdes_skip_turn: Optional[bool] = None,
+        sdes_connection_mode: Optional[str] = None,
         sdes_adaptive: Optional[bool] = None,
         sdes_audio_gain_db: Optional[float] = None,
     ) -> None:
@@ -3616,6 +3655,8 @@ class CameraMixin(_CameraControlsMixin, _CameraSdMixin, _WebRTCOpenMixin, _SdesO
             self._sdes_fast_liveplay_opt = sdes_fast_liveplay
         if sdes_skip_turn is not None:
             self._sdes_skip_turn_opt = sdes_skip_turn
+        if sdes_connection_mode is not None:
+            self._sdes_connection_mode_opt = sdes_connection_mode
         if sdes_adaptive is not None:
             self._sdes_adaptive_opt = sdes_adaptive
         if self._stream_task is not None and not self._stream_task.done():
@@ -4701,6 +4742,33 @@ class CameraMixin(_CameraControlsMixin, _CameraSdMixin, _WebRTCOpenMixin, _SdesO
             )
         return False
 
+    def _resolve_sdes_connection_mode(self) -> str:
+        """Which media path the session should offer: auto, lan, or relay.
+
+        ``auto`` (default) offers every reachable candidate and lets ICE
+        priority prefer the LAN, with the relay as last resort - the shipped
+        behaviour, verified on the full fleet (six of seven direct, only the
+        unreachable unit relayed).  ``lan`` drops the relay entirely (routed
+        through _resolve_sdes_skip_turn so the battery force-keep applies).
+        ``relay`` offers only the relay candidate and force-keeps the
+        pre-allocation.
+
+        Per-open ``sdes_connection_mode`` wins; else AIDOT_SDES_CONNECTION_MODE;
+        else auto.  Anything unrecognised is auto - this is read while opening
+        a stream, and a typo must not stop video.
+        """
+        for raw in (getattr(self, "_sdes_connection_mode_opt", None),
+                    os.environ.get("AIDOT_SDES_CONNECTION_MODE")):
+            if raw is None:
+                continue
+            mode = str(raw).strip().lower()
+            if mode in ("auto", "lan", "relay"):
+                return mode
+            _LOGGER.warning(
+                "camera %s: unknown sdes_connection_mode %r; using auto",
+                getattr(self, "device_id", "?"), raw)
+        return "auto"
+
     def _resolve_sdes_skip_turn(self) -> bool:
         """EXPERIMENTAL (opt-in, default off): skip the blocking SDES TURN relay
         pre-allocation, for cameras reachable LAN-direct.
@@ -4730,6 +4798,15 @@ class CameraMixin(_CameraControlsMixin, _CameraSdMixin, _WebRTCOpenMixin, _SdesO
         candidate on the HA segment."""
         if getattr(self, "is_battery_camera", False):
             return False
+        # The connection mode composes here rather than in a parallel path, so
+        # everything hanging off this resolver (instrumentation, the adaptive
+        # interplay) sees one answer.  relay force-keeps the pre-allocation -
+        # forcing the relay while skipping its allocation would offer nothing.
+        _mode = self._resolve_sdes_connection_mode()
+        if _mode == "lan":
+            return True
+        if _mode == "relay":
+            return False
         opt = getattr(self, "_sdes_skip_turn_opt", None)
         if opt is not None:
             return bool(opt)

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b32}/aidot_cameras/camera/hwaccel.py

@@ -40,7 +40,7 @@ import threading
 import time
 from typing import List, Optional
 
-from .protocol import _SPROP_DIR  # reuse the same per-user cache root
+from .protocol import _sprop_dir  # reuse the same per-user cache root
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -139,7 +139,7 @@ def _ffmpeg_identity() -> str:
 
 
 def _cache_path() -> str:
-    return os.path.join(_SPROP_DIR, "decoders.json")
+    return os.path.join(_sprop_dir(), "decoders.json")
 
 
 def _load_cache() -> dict:
@@ -152,7 +152,7 @@ def _load_cache() -> dict:
 
 def _save_cache(data: dict) -> None:
     try:
-        os.makedirs(_SPROP_DIR, exist_ok=True)
+        os.makedirs(_sprop_dir(), exist_ok=True)
         tmp = _cache_path() + ".tmp"
         with open(tmp, "w") as fh:
             json.dump(data, fh)

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b32}/aidot_cameras/camera/protocol.py

@@ -684,8 +684,18 @@ _XDG_CONFIG_HOME = os.environ.get("XDG_CONFIG_HOME") or os.path.join(
     os.path.expanduser("~"), ".config")
 
 
-_SPROP_DIR = os.environ.get("AIDOT_SPROP_DIR") or os.path.join(
-    _XDG_CONFIG_HOME, "aidot", "sprop")
+def _sprop_dir() -> str:
+    """The sprop cache directory - AIDOT_SPROP_DIR read at CALL time.
+
+    A consumer embedded in a larger process (the Home Assistant integration)
+    can only learn its persistent storage path at setup, after this module is
+    long imported; a module-level snapshot of the env var silently ignored
+    that setting and the cache landed back in the container-ephemeral home
+    directory, so every container recreation cost a startup-churn window.
+    Same lesson as cloud_auth's country default: bind config at call time.
+    """
+    return os.environ.get("AIDOT_SPROP_DIR") or os.path.join(
+        _XDG_CONFIG_HOME, "aidot", "sprop")
 
 
 def _extract_param_sets_from_rtp(pkt: bytes) -> dict:
@@ -740,12 +750,12 @@ def _build_sprop(sps: bytes, pps: bytes) -> str:
 def _sprop_cache_path(devid: str) -> str:
     # `devid` originates from the cloud/device and is interpolated into a
     # filesystem path, so a value containing "/", "\\", ".." or an absolute path
-    # could escape _SPROP_DIR (arbitrary read/write). Reduce it to a safe,
+    # could escape the sprop dir (arbitrary read/write). Reduce it to a safe,
     # collision-resistant filename component.
     safe = re.sub(r"[^A-Za-z0-9_-]", "_", devid or "")
     if not safe or len(devid or "") > 128:
         safe = hashlib.sha256((devid or "").encode("utf-8", "replace")).hexdigest()
-    return os.path.join(_SPROP_DIR, f"{safe}.sprop")
+    return os.path.join(_sprop_dir(), f"{safe}.sprop")
 
 
 def _sprop_unstable_path(devid: str) -> str:
@@ -834,14 +844,14 @@ def _save_sprop(devid: str, sprop: str) -> bool:
                 devid,
             )
             try:
-                os.makedirs(_SPROP_DIR, exist_ok=True)
+                os.makedirs(_sprop_dir(), exist_ok=True)
                 with open(_sprop_unstable_path(devid), "w") as fh:
                     fh.write("parameter sets changed between sessions\n")
                 os.remove(_sprop_cache_path(devid))
             except OSError:
                 pass
             return False
-        os.makedirs(_SPROP_DIR, exist_ok=True)
+        os.makedirs(_sprop_dir(), exist_ok=True)
         tmp = _sprop_cache_path(devid) + ".tmp"
         with open(tmp, "w") as fh:
             fh.write(sprop)
@@ -851,7 +861,7 @@ def _save_sprop(devid: str, sprop: str) -> bool:
         # Surface (don't swallow): if the cache dir isn't writable the whole
         # sprop feature is silently inert.  AIDOT_SPROP_DIR can redirect it.
         _LOGGER.warning("sprop cache write failed (%s): %s - set AIDOT_SPROP_DIR "
-                        "to a writable path", _SPROP_DIR, exc)
+                        "to a writable path", _sprop_dir(), exc)
         return False
 
 

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b32}/aidot_cameras/camera/sdes.py

@@ -53,6 +53,7 @@ class SdesSession(AvioRequestMixin):
         teardown_requested=None,
         first_video_pt=None,
         first_audio_pt=None,
+        media_path=None,
         device_id=None,
         responses=None,
         abort_chan=None,
@@ -81,6 +82,12 @@ class SdesSession(AvioRequestMixin):
         # sent (video 96/97/98, audio 0/8), or None before first media.
         self._first_video_pt = first_video_pt if first_video_pt is not None else [None]
         self._first_audio_pt = first_audio_pt if first_audio_pt is not None else [None]
+        # Shared with the bridge thread: [0] becomes "direct" or "relay" when
+        # the first media packet arrives, classified by its source address
+        # against the session's TURN servers.  The connection mode is only a
+        # preference - the camera decides where to send from - and this is the
+        # receipt that says what actually happened.
+        self._media_path = media_path if media_path is not None else [None]
         # Mutable one-element list shared with the bridge thread: [0] flips True
         # the moment ANY locally-initiated ffmpeg-kill path fires (this stop(),
         # the cold-open _reap(), the key-restart proc replace, or the DTLS-
@@ -229,7 +236,8 @@ class SdesSession(AvioRequestMixin):
         the DTLS path allows.  These counters are the supported substitute:
         non-zero ``packets``/``bytes`` means real media reached the consumer.
 
-        Returns ``{packets, bytes, last_media_monotonic, video_pt, audio_pt}``;
+        Returns ``{packets, bytes, last_media_monotonic, video_pt, audio_pt,
+        media_path}``;
         the payload types are ``None`` until the camera's first packet of that
         kind arrives.
         """
@@ -239,6 +247,7 @@ class SdesSession(AvioRequestMixin):
             "last_media_monotonic": self._media_progress[0],
             "video_pt": self._first_video_pt[0],
             "audio_pt": self._first_audio_pt[0],
+            "media_path": self._media_path[0],
         }
 
     def _drained_stderr_tail(self) -> bytes: