python-aidot-cameras 0.11.11__tar.gz → 0.11.13__tar.gz

{python_aidot_cameras-0.11.11/python_aidot_cameras.egg-info → python_aidot_cameras-0.11.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.11.11
+Version: 0.11.13
 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.11.13/aidot/__init__.py

@@ -0,0 +1,137 @@
+"""AiDot camera and device library."""
+
+import logging as _logging
+import time as _time
+
+from .client import AidotClient
+from .device_client import DeviceClient
+from .discover import Discover
+from .exceptions import (
+    AidotAuthFailed,
+    AidotAuthTokenExpired,
+    AidotCameraBusy,
+    AidotError,
+    AidotNotLogin,
+    AidotOSError,
+    AidotUserOrPassIncorrect,
+    HTTPError,
+    InvalidHost,
+    InvalidURL,
+)
+
+# Cap the noisy external/vendored loggers so enabling DEBUG on the parent
+# ``aidot`` logger to diagnose the integration does not unleash a flood that,
+# on a microSD Home Assistant host, can starve the recorder with log I/O.
+#
+# The vendored aiortc RTP receiver/sender log every media packet at DEBUG, so
+# capping them at INFO removes that flood while leaving the diagnostically
+# valuable DEBUG (DTLS, SCTP/DCEP, ICE connection state) flowing.
+#
+# The external ``aioice`` package's flood is different: it logs ICE
+# connectivity-check state transitions at INFO, not DEBUG (aioice is a real
+# dependency, not vendored, so it is not under ``aidot._vendor``). An INFO cap
+# cannot suppress an INFO-level flood, so ``aioice.ice`` and ``aioice.turn``
+# are capped at WARNING instead; aioice emits nothing at WARNING or above, so
+# no real warning is lost. A user who wants the aioice ICE INFO logging back
+# (e.g. to debug connectivity issues) can set that logger's level explicitly -
+# the NOTSET guard below respects it.
+_EXTERNAL_LOGGER_CAPS = {
+    "aidot._vendor.aiortc.rtcrtpreceiver": _logging.INFO,
+    "aidot._vendor.aiortc.rtcrtpsender": _logging.INFO,
+    "aioice.ice": _logging.WARNING,
+    "aioice.turn": _logging.WARNING,
+}
+
+
+def _cap_external_loggers() -> None:
+    """Idempotently apply the caps in ``_EXTERNAL_LOGGER_CAPS``.
+
+    Only touches a logger whose level is still NOTSET, so an explicit level
+    set by the user (before or after this runs) is never overridden.
+    """
+    for _name, _level in _EXTERNAL_LOGGER_CAPS.items():
+        _lg = _logging.getLogger(_name)
+        if _lg.level == _logging.NOTSET:
+            _lg.setLevel(_level)
+
+
+_cap_external_loggers()
+
+# The vendored H.264 decoder logs a WARNING per corrupt/undecodable frame
+# (aidot/_vendor/aiortc/codecs/h264.py:118). A degrading link can therefore
+# log hundreds of identical lines in a few minutes; a live evaluation saw 172
+# in 11 minutes. A level cap cannot help here since the message is already at
+# WARNING, and the message is a corruption canary for a degrading link, so it
+# must not be silenced outright. Instead a rate-limiting filter lets the
+# first WARNING through immediately, suppresses subsequent same-logger
+# WARNINGs within a window, and lets the first WARNING after the window
+# elapses through carrying the suppressed count, so the canary stays visible
+# at a low rate instead of flooding.
+_H264_DECODE_LOGGER_NAME = "aidot._vendor.aiortc.codecs.h264"
+_H264_DECODE_RATE_LIMIT_WINDOW_SECONDS = 30.0
+
+
+class _RateLimitingWarningFilter(_logging.Filter):
+    """Rate-limit WARNING records on the logger it is attached to.
+
+    The first WARNING is let through immediately. Subsequent WARNINGs within
+    ``window_seconds`` of it are suppressed (dropped) but counted. The next
+    WARNING to arrive once the window has elapsed is let through, with its
+    message annotated with how many were suppressed during the window, and a
+    new window begins from that record's time. Records at other levels, and
+    records on other loggers, are never touched.
+
+    ``time_func`` defaults to ``time.monotonic`` but is injectable so tests
+    can drive the window deterministically without real sleeps.
+    """
+
+    def __init__(self, window_seconds: float = _H264_DECODE_RATE_LIMIT_WINDOW_SECONDS, time_func=_time.monotonic) -> None:
+        super().__init__()
+        self._window_seconds = window_seconds
+        self._time_func = time_func
+        self._window_start = None
+        self._suppressed = 0
+
+    def filter(self, record: _logging.LogRecord) -> bool:
+        if record.levelno != _logging.WARNING:
+            return True
+        _now = self._time_func()
+        if self._window_start is None:
+            self._window_start = _now
+            return True
+        if _now - self._window_start < self._window_seconds:
+            self._suppressed += 1
+            return False
+        _suppressed = self._suppressed
+        self._window_start = _now
+        self._suppressed = 0
+        if _suppressed:
+            record.msg = f"{record.getMessage()} (suppressed {_suppressed} similar warning(s) in the last {self._window_seconds:.0f}s)"
+            record.args = ()
+        return True
+
+
+def _install_h264_decode_rate_limit_filter() -> None:
+    """Idempotently attach the rate-limiting filter to the h264 decode logger."""
+    _lg = _logging.getLogger(_H264_DECODE_LOGGER_NAME)
+    if not any(isinstance(_f, _RateLimitingWarningFilter) for _f in _lg.filters):
+        _lg.addFilter(_RateLimitingWarningFilter())
+
+
+_install_h264_decode_rate_limit_filter()
+
+__all__ = [
+    "AidotAuthFailed",
+    "AidotAuthTokenExpired",
+    "AidotCameraBusy",
+    "AidotClient",
+    "AidotError",
+    "AidotNotLogin",
+    "AidotOSError",
+    "AidotUserOrPassIncorrect",
+    "DeviceClient",
+    "Discover",
+    "HTTPError",
+    "InvalidHost",
+    "InvalidURL",
+]

{python_aidot_cameras-0.11.11 → python_aidot_cameras-0.11.13}/aidot/camera/client.py

@@ -97,6 +97,46 @@ _LOGGER = logging.getLogger(__name__)
 _OFFLINE_RECHECK_S = float(os.environ.get("AIDOT_OFFLINE_RECHECK_S", "30"))
 _OFFLINE_PROBE_S = float(os.environ.get("AIDOT_OFFLINE_PROBE_S", "600"))
 
+# DTLS serve loop slow-probe: an idle-but-cloud-online camera (asleep, wedged
+# firmware, ...) never trips the offline pause above (the cloud keeps reporting
+# it reachable), so its failed opens would otherwise retry FOREVER at the
+# pacer's 300s cap - burning a 30s open timeout every attempt and dripping a
+# WARNING each time (see _open_fail_logger).  After
+# AIDOT_DTLS_SLOW_PROBE_THRESHOLD consecutive open failures (keyed on the
+# ReconnectPacer's attempt count - see _in_slow_probe / _probe_interval below -
+# NOT the cloud-offline flag, which this case never sets), the loop widens its
+# retry interval to AIDOT_DTLS_SLOW_PROBE_INTERVAL_S and downgrades the
+# per-attempt WARNING to a periodic INFO summary (_should_log_slow_probe).
+# Resets the instant an open succeeds, via the same ReconnectPacer.reset() the
+# loop already calls on success (attempt -> 0, so _in_slow_probe is false again
+# with no separate state to clear).
+_SLOW_PROBE_THRESHOLD = int(os.environ.get("AIDOT_DTLS_SLOW_PROBE_THRESHOLD", "5"))
+_SLOW_PROBE_INTERVAL_S = float(os.environ.get("AIDOT_DTLS_SLOW_PROBE_INTERVAL_S", "600"))
+_SLOW_PROBE_LOG_EVERY = int(os.environ.get("AIDOT_DTLS_SLOW_PROBE_LOG_EVERY", "6"))
+# Sleep increment for the slow-probe wait: never one blocking
+# asyncio.sleep(interval) call, so stop() is not delayed by up to 10 minutes.
+_SLOW_PROBE_SLEEP_CHUNK_S = float(os.environ.get("AIDOT_DTLS_SLOW_PROBE_CHUNK_S", "5"))
+
+
+def _parse_env_float(name: str, default: float) -> float:
+    """Parse a float env var, falling back to ``default`` on any missing or
+    malformed value (matches the try/except idiom used by
+    _get_webrtc_open_gate / _get_stream_slots below for AIDOT_MAX_CONCURRENT_*
+    rather than raising at import time)."""
+    try:
+        return float(os.environ.get(name, str(default)))
+    except (ValueError, TypeError):
+        return default
+
+
+# DTLS serve-open timeout: how long a single async_open_webrtc_stream() call
+# in the serve loop is allowed to take before giving up. Left at the
+# _async_open_webrtc_stream_impl default (30.0s) so battery cameras that need
+# the full window to wake still work; tunable via
+# AIDOT_DTLS_SERVE_OPEN_TIMEOUT_S for operators who want faster-failing
+# retries against a known-dead camera.
+_DTLS_SERVE_OPEN_TIMEOUT_S = _parse_env_float("AIDOT_DTLS_SERVE_OPEN_TIMEOUT_S", 30.0)
+
 # Strong refs to fire-and-forget tasks: asyncio only keeps weak refs, so a
 # discarded task can be garbage-collected mid-flight. Discarded on completion.
 _BG_TASKS: set = set()
@@ -164,6 +204,39 @@ def _open_gate_delay(last_open_at: float, now: float, open_gate: float) -> float
     return remaining if remaining > 0 else 0.0
 
 
+def _in_slow_probe(attempt: int, threshold: int) -> bool:
+    """True once `attempt` consecutive DTLS open failures have reached
+    `threshold`: the serve loop should stop hammering an idle-but-cloud-online
+    camera at the pacer's normal cadence and fall back to a slow probe."""
+    return attempt >= threshold
+
+
+def _probe_interval(attempt: int, threshold: int, normal_delay: float,
+                     slow_interval: float) -> float:
+    """Effective DTLS-open retry interval for a failed open.
+
+    Below `threshold` consecutive failures this is just the pacer's own
+    `normal_delay` (unchanged jittered-backoff behaviour). At/after `threshold`
+    it widens to (at least) `slow_interval` - well beyond the pacer's own cap -
+    so a camera that is cloud-online but never actually opens is probed
+    roughly every `slow_interval` seconds instead of retried forever at the
+    pacer's max cadence."""
+    if _in_slow_probe(attempt, threshold):
+        return max(normal_delay, slow_interval)
+    return normal_delay
+
+
+def _should_log_slow_probe(attempt: int, threshold: int, log_every: int) -> bool:
+    """True when a slow-probe open failure should be logged: the moment
+    slow-probe is entered, then every `log_every`th attempt after - so a
+    camera stuck for hours doesn't drip a log line on every single probe."""
+    if not _in_slow_probe(attempt, threshold):
+        return False
+    if log_every <= 0:
+        return True
+    return (attempt - threshold) % log_every == 0
+
+
 _FFMPEG_MISSING_MSG = (
     "ffmpeg not found on PATH; install ffmpeg to enable recording/transcoding.\n"
     "  Ubuntu/Debian:    sudo apt install ffmpeg\n"
@@ -845,6 +918,23 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             self.device_id,
         )
 
+    async def _slow_probe_sleep(self, interval: float) -> None:
+        """Sleep `interval` seconds for the DTLS serve loop's slow-probe wait,
+        in `_SLOW_PROBE_SLEEP_CHUNK_S` increments rather than one blocking
+        `asyncio.sleep(interval)` call, re-checking `_streaming_active` each
+        increment.  `interval` can be several minutes; without chunking,
+        `stop()` would have to wait out the whole thing before the loop next
+        checks whether it should keep running.
+        """
+        _t0 = time.monotonic()
+        while True:
+            if not getattr(self, "_streaming_active", False):
+                return
+            _remaining = interval - (time.monotonic() - _t0)
+            if _remaining <= 0:
+                return
+            await asyncio.sleep(min(_SLOW_PROBE_SLEEP_CHUNK_S, _remaining))
+
     # -- Camera helpers ------------------------------------------------------ #
 
     @property
@@ -2976,11 +3066,27 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             _LOGGER.debug("PLI request failed: %s", _pli_exc)
 
     @staticmethod
-    def _install_encoded_tap(receiver, out_q, is_video: bool) -> bool:
+    def _install_encoded_tap(receiver, out_q, is_video: bool, serve: bool = False) -> bool:
         """Tee aiortc's depacketized encoded frames (+ RTP timestamp) into a
         thread-safe queue before decode.  Video frames go as
         ``(bytes, timestamp, is_keyframe)``, audio as ``(bytes, timestamp)``.
-        ``out_q`` is a ``queue.Queue`` (the mux runs in a worker thread)."""
+        ``out_q`` is a ``queue.Queue`` (the mux runs in a worker thread).
+
+        When ``serve`` is set, the served H.264 is muxed as ``-c copy`` straight
+        from this tap, so the vendored decoder's output is discarded (the serve
+        loop uses a no-op on_frame).  In that mode we STOP feeding the decoder
+        queue for video DATA frames: decoding them is pure wasted CPU and the
+        sole source of the per-packet decode-failure warning flood.  The None
+        terminator is STILL forwarded so the decoder thread exits cleanly, and
+        audio is left untouched (drained separately).  We must not instead pass
+        ``on_frame=None`` at the receiver level - the decoder thread would keep
+        running and fill the unbounded track queue with nothing draining it.
+
+        Because decode was the only signal that the served H.264 was corrupt, a
+        cheap keyframe-based canary (no decoding) is kept: it counts frames and
+        keyframes, tracks the longest run with no keyframe, and emits a periodic
+        DEBUG summary.  It is O(1) per frame and stays at DEBUG so a corrupt
+        camera can't recreate the very flood this removes."""
         _qd = getattr(receiver, "_RTCRtpReceiver__decoder_queue", None)
         if _qd is None:
             return False
@@ -2990,6 +3096,12 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         if getattr(_qd, "_aidot_tapped", False):
             return True
         _orig_put = _qd.put
+        _skip_decode = bool(serve and is_video)
+        # Served-stream health canary (video-only): observed without decoding.
+        _canary = {"frames": 0, "keyframes": 0, "gap": 0, "max_gap": 0} if _skip_decode else None
+        if _canary is not None:
+            _qd._aidot_serve_canary = _canary
+        _CANARY_LOG_EVERY = 300  # frames (~10-20s of H.264); DEBUG summary cadence
 
         def _tap_put(task, *a, **k):
             try:
@@ -2998,12 +3110,34 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     _d = getattr(_enc, "data", None)
                     _ts = getattr(_enc, "timestamp", None)
                     if _d and _ts is not None:
-                        _item = ((bytes(_d), int(_ts), _h264_has_keyframe(bytes(_d)))
-                                 if is_video else (bytes(_d), int(_ts)))
+                        _b = bytes(_d)
+                        _kf = _h264_has_keyframe(_b) if is_video else False
+                        _item = (_b, int(_ts), _kf) if is_video else (_b, int(_ts))
                         try:
                             out_q.put_nowait(_item)
                         except Exception:
                             pass  # full -> drop (PLI re-arms a GOP)
+                        if _canary is not None:
+                            _canary["frames"] += 1
+                            if _kf:
+                                _canary["keyframes"] += 1
+                                _canary["gap"] = 0
+                            else:
+                                _canary["gap"] += 1
+                                if _canary["gap"] > _canary["max_gap"]:
+                                    _canary["max_gap"] = _canary["gap"]
+                            if _canary["frames"] % _CANARY_LOG_EVERY == 0:
+                                _LOGGER.debug(
+                                    "serve h264 canary: frames=%d keyframes=%d"
+                                    " max_keyframe_gap=%d cur_gap=%d",
+                                    _canary["frames"], _canary["keyframes"],
+                                    _canary["max_gap"], _canary["gap"],
+                                )
+                    if _skip_decode:
+                        # Discarded decode: don't feed the decoder for served
+                        # video data frames (see docstring).  Terminator (task
+                        # is None) still falls through to _orig_put below.
+                        return None
             except Exception:
                 _LOGGER.debug("swallowed exception in %s", '_tap_put', exc_info=True)
             return _orig_put(task, *a, **k)
@@ -3017,6 +3151,12 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
 
         Called repeatedly until the video tap lands; _install_encoded_tap is
         idempotent per receiver, so audio isn't re-wrapped across retries.
+
+        This runs only from the DTLS serve loop, whose on_frame is a no-op and
+        whose output is muxed as H.264 copy from the video tap - so the video
+        tap is installed with serve=True to skip the discarded decode (see
+        _install_encoded_tap).  Audio keeps feeding its decoder (drained
+        separately).
         """
         got_v = False
         got_a = False
@@ -3025,7 +3165,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             if _tr is None:
                 continue
             if _tr.kind == "video" and not got_v:
-                got_v = self._install_encoded_tap(_r, vq, True)
+                got_v = self._install_encoded_tap(_r, vq, True, serve=True)
             elif _tr.kind == "audio" and not got_a:
                 got_a = self._install_encoded_tap(_r, aq, False)
         return got_v
@@ -3379,7 +3519,9 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     return
             _last_open_at = loop.time()
             try:
-                session = await self.async_open_webrtc_stream(on_frame=lambda _f: None)
+                session = await self.async_open_webrtc_stream(
+                    on_frame=lambda _f: None, timeout=_DTLS_SERVE_OPEN_TIMEOUT_S,
+                )
             except asyncio.CancelledError:
                 return
             except AidotCameraBusy as busy:
@@ -3419,6 +3561,35 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                 continue
             except Exception as exc:
                 _delay = _pacer.fail_delay()
+                _attempt = _pacer.attempt
+                _cloud_offline = (
+                    (not self.status.online)
+                    and getattr(self, "_cloud_online_explicit", False)
+                )
+                # Slow-probe throttle: an idle-but-cloud-online camera never
+                # sets _cloud_offline (the cloud keeps reporting it reachable),
+                # so without this it would retry forever at the pacer's cap.
+                # Keyed purely on the pacer's consecutive-failure count, not
+                # the offline flag - a genuinely offline camera already gets a
+                # comparable slow cadence (with early-resume) from
+                # _backoff_or_offline_pause below, so this only engages the
+                # part of the space that pause doesn't already cover.
+                if _in_slow_probe(_attempt, _SLOW_PROBE_THRESHOLD) and not _cloud_offline:
+                    _delay = _probe_interval(
+                        _attempt, _SLOW_PROBE_THRESHOLD, _delay, _SLOW_PROBE_INTERVAL_S)
+                    if _should_log_slow_probe(
+                        _attempt, _SLOW_PROBE_THRESHOLD, _SLOW_PROBE_LOG_EVERY
+                    ):
+                        _LOGGER.info(
+                            "DTLS serve: %s still failing to open after %d"
+                            " attempts - slow-probing every %.0fs (last error: %s)",
+                            self.device_id, _attempt, _delay, exc,
+                        )
+                    try:
+                        await self._slow_probe_sleep(_delay)
+                    except asyncio.CancelledError:
+                        return
+                    continue
                 self._open_fail_logger()(
                     "DTLS serve: open failed for %s (retry %.0fs): %s",
                     self.device_id, _delay, exc,
@@ -3429,6 +3600,9 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     return
                 continue
 
+            # Resetting the pacer's attempt count also clears slow-probe state:
+            # it derives purely from _pacer.attempt, so _in_slow_probe reads
+            # false again on the very next failure sequence.
             _pacer.reset()
             _not_ready_burst = 0  # clean open: reset the encoder-cold burst
             self._stream_session = session

{python_aidot_cameras-0.11.11 → python_aidot_cameras-0.11.13}/aidot/camera/protocol.py

@@ -458,6 +458,13 @@ class ReconnectPacer:
         self._rand = rand  # forwarded to next_backoff; injectable for tests
         self._attempt = 0
 
+    @property
+    def attempt(self) -> int:
+        """Consecutive-failure count (read-only). Callers that need to escalate
+        beyond this pacer's own cap (see the DTLS serve loop's slow-probe
+        throttle) key off this instead of duplicating the counter."""
+        return self._attempt
+
     def fail_delay(self) -> float:
         """Delay after a failed OPEN (no session established): the current attempt's
         backoff, then escalate - so the first failure waits exactly ``base``."""

{python_aidot_cameras-0.11.11 → python_aidot_cameras-0.11.13}/aidot/camera/sdes.py

@@ -34,6 +34,7 @@ class SdesSession:
         cmd_chan=None,
         talk_state=None,
         media_progress=None,
+        teardown_requested=None,
     ) -> None:
         self._proc       = proc
         self._sdp_path   = sdp_path
@@ -47,6 +48,19 @@ class SdesSession:
         # that stopped sending (battery teardown ~49-72s) and reconnect - ffmpeg
         # itself never exits on a dead UDP input, so wait_done() alone would hang.
         self._media_progress = media_progress if media_progress is not None else [0.0]
+        # 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-
+        # fallback abort - all in sdes_open.py).  The bridge observe loop reads
+        # it to tell an expected signal death (SIGTERM/SIGKILL from our own
+        # teardown - a battery cam's ffmpeg cannot exit on a dead UDP input) from
+        # an unexpected ffmpeg crash, so only the latter logs at WARNING.  A
+        # plain list (not threading.Event) matches the _proc_holder /
+        # _media_progress sharing pattern already used with the bridge thread;
+        # list item assignment is atomic under the GIL.
+        self._teardown_requested = (
+            teardown_requested if teardown_requested is not None else [False]
+        )
         # Mutable one-element list shared with the bridge thread.  Bridge sets
         # [0] to a callable(cmd, payload) once the SCTP channel is up.
         self._cmd_chan   = cmd_chan if cmd_chan is not None else [None]
@@ -203,6 +217,10 @@ class SdesSession:
                 await asyncio.sleep(0.3)
             self._talk_state["stop"] = True
             self._talk_state["provider"] = None
+        # Flag this as a locally-initiated teardown BEFORE signalling ffmpeg, so
+        # the bridge thread's observe loop never races a look at a stale False
+        # if it polls the exit code immediately after terminate()/kill().
+        self._teardown_requested[0] = True
         self._proc.terminate()
         _stop_loop = asyncio.get_running_loop()
         try:

{python_aidot_cameras-0.11.11 → python_aidot_cameras-0.11.13}/aidot/camera/sdes_open.py

@@ -46,6 +46,41 @@ def _sdes_echo_wait_timeout(skip_liveplay: bool) -> float:
     return 0.0 if skip_liveplay else 2.0
 
 
+def _classify_ffmpeg_exit(rc: int, teardown_requested: bool) -> int:
+    """Log level for the bridge observe loop's "ffmpeg exited" line.
+
+    Teardown here is SIGTERM-first with a SIGKILL fallback (SdesSession.stop(),
+    the cold-open _reap(), the key-restart proc replace, and the DTLS-fallback
+    abort). A battery camera's ffmpeg cannot exit promptly on a dead UDP input,
+    so a normal locally-initiated stop routinely ends in a signal death (rc < 0,
+    e.g. -9 SIGKILL / -15 SIGTERM) - expected, and should not warn.  Any other
+    non-zero exit - a signal death with no teardown in flight, or a positive
+    ffmpeg error code even during teardown - is unexpected and stays loud.
+    Pure function so the policy is unit-testable without a live bridge thread.
+    """
+    if rc < 0 and teardown_requested:
+        return logging.DEBUG
+    return logging.WARNING
+
+
+def _bridge_should_break(rc, teardown_requested: bool) -> bool:
+    """Whether the bridge observe loop should end on this poll() result.
+
+    rc is the held proc's poll() result (None while it is still running).
+    Ending the loop is only correct when ffmpeg has actually exited AND no
+    locally-initiated teardown is in flight for it: a non-None rc seen while
+    teardown_requested is True is the key-restart window (or any other
+    flagged local kill) - the OLD proc's exit, not a reason to stop.  That
+    window always resolves promptly one of two ways, so skipping the break
+    here cannot hang the bridge thread: either the key-restart repoints
+    _proc_holder[0] at the live new proc (next poll() is None again), or a
+    genuine teardown closes the loopback sockets, which makes the loop's
+    select() raise and exit via its own except-break.  Pure function so the
+    policy is unit-testable without a live bridge thread.
+    """
+    return rc is not None and not teardown_requested
+
+
 class _SdesOpenMixin:
     async def _open_sdes_stream(self, **kwargs) -> "SdesSession":
         """Allocate-and-hand-off wrapper around _open_sdes_stream_impl.
@@ -167,6 +202,16 @@ class _SdesOpenMixin:
             _cleanup.callback(_run)
 
         def _reap(p):
+            # This is a locally-initiated kill (cold open cancelled/raised
+            # before hand-off) - flag it so the bridge observe loop treats the
+            # resulting signal death as expected, not a WARNING-worthy crash.
+            # Set first (before the kill/reap below), matching the other
+            # kill sites, so the bridge thread can never observe the exit
+            # code with the flag still False.
+            try:
+                _teardown_holder[0] = True
+            except Exception:
+                pass
             try:
                 p.kill()
             except Exception:
@@ -2084,6 +2129,14 @@ class _SdesOpenMixin:
         # Proc holder: set to the ffmpeg Popen object after launch so the
         # bridge thread can poll for exit without a NameError race.
         _proc_holder: list = [None]
+        # Teardown holder: [0] flips True the moment ANY locally-initiated
+        # ffmpeg-kill path fires (_reap() above on a cancelled cold open, the
+        # key-restart proc replace, or the DTLS-fallback abort below - plus
+        # SdesSession.stop() once the session is handed off, via the
+        # teardown_requested= kwarg at construction).  The bridge observe loop
+        # reads it via _classify_ffmpeg_exit() to demote an expected signal
+        # death (our own SIGTERM/SIGKILL) from an unexpected ffmpeg crash.
+        _teardown_holder: list = [False]
         # Camera's actual video payload type (96=H.264 / 97=H.265), set by the
         # bridge on the first video RTP packet so the ffmpeg SDP can be narrowed
         # to the matching single codec before ffmpeg is launched.
@@ -2110,6 +2163,13 @@ class _SdesOpenMixin:
             _trigger_bsrc       = None    # camera addr for trigger
             _sdes_probe_received = False  # True after first 0xC8 probe from camera
             _last_hb_ts         = 0.0     # time of last AVIO HEARTBEAT send
+            # One-shot guard for the "ffmpeg exited" log below: while the held
+            # proc keeps reporting the same stale exit code across a
+            # teardown-window skip (see _bridge_should_break), only the first
+            # tick logs it.  Reset to False whenever the held proc is next
+            # seen alive (poll() None), so a later, genuine exit of THAT proc
+            # still gets its own line.
+            _br_exit_logged = False
             _lo_a = _socket_br.socket(_socket_br.AF_INET, _socket_br.SOCK_DGRAM)
             _lo_v = _socket_br.socket(_socket_br.AF_INET, _socket_br.SOCK_DGRAM)
             try:
@@ -2120,18 +2180,41 @@ class _SdesOpenMixin:
                         )
                     except Exception:
                         break
-                    # Stop the bridge when ffmpeg exits (normal end or crash).
+                    # Stop the bridge when ffmpeg exits (normal end or crash) -
+                    # but NOT on a stale exit seen during a flagged teardown
+                    # window (key-restart proc replace, stop(), _reap(), the
+                    # DTLS-fallback abort): _bridge_should_break() skips the
+                    # break there, and the loop resolves it either via the
+                    # key-restart's _proc_holder[0] repoint (next poll() None,
+                    # below) or via a genuine teardown closing the loopback
+                    # sockets, which raises out of the select() above.
                     _br_proc = _proc_holder[0]
                     if _br_proc is not None:
                         _br_rc = _br_proc.poll()
                         if _br_rc is not None:
-                            if _br_rc != 0:
+                            _br_teardown_requested = bool(_teardown_holder[0])
+                            if _br_rc != 0 and not _br_exit_logged:
+                                _br_exit_logged = True
                                 import logging as _log_br
-                                _log_br.getLogger(__name__).warning(
+                                _br_level = _classify_ffmpeg_exit(
+                                    _br_rc, _br_teardown_requested
+                                )
+                                _br_msg = (
                                     "SDES bridge: ffmpeg exited with code %d"
-                                    " - stream ended", _br_rc
+                                    " - stopped by teardown"
+                                    if _br_level < _log_br.WARNING else
+                                    "SDES bridge: ffmpeg exited with code %d"
+                                    " - stream ended"
                                 )
-                            break
+                                _log_br.getLogger(__name__).log(
+                                    _br_level, _br_msg, _br_rc
+                                )
+                            if _bridge_should_break(
+                                _br_rc, _br_teardown_requested
+                            ):
+                                break
+                        else:
+                            _br_exit_logged = False
 
                     # AVIO HEARTBEAT (cmd=5156) every 10s, sent as an ENCRYPTED SCTP
                     # DATA chunk (PPID=53) - exactly like LIVING - NOT a raw 0xC8 AVIO
@@ -3634,6 +3717,13 @@ class _SdesOpenMixin:
                         srtp_key_video = _real_key_video
                         _keys_changed = True
                     if _keys_changed:
+                        # Locally-initiated kill (the offered key was wrong;
+                        # restarting ffmpeg with the camera's real key) - flag it
+                        # so the bridge observe loop does not warn on the old
+                        # proc's signal death.  Reset once the NEW proc is live
+                        # (below) so a later, genuine crash of the restarted
+                        # ffmpeg is not silently swallowed as "expected teardown".
+                        _teardown_holder[0] = True
                         proc.terminate()
                         try:
                             proc.wait(timeout=2)
@@ -3682,6 +3772,10 @@ class _SdesOpenMixin:
                         # breaks, and closes the loopback sockets - starving the
                         # restarted ffmpeg (0-frame stream).
                         _proc_holder[0] = proc
+                        # New proc is live and owns the holder; clear the
+                        # teardown flag so this session's NEXT exit (the
+                        # restarted ffmpeg's) is classified fresh.
+                        _teardown_holder[0] = False
                         _status("ffmpeg restarted with camera's SRTP keys")
         except TimeoutError:
             if _cam_echo_received:
@@ -3698,6 +3792,11 @@ class _SdesOpenMixin:
                     f"no webrtcResp in {_sdes_answer_timeout:.0f}s"
                     " - SDES handshake failed; aborting ffmpeg and falling back to DTLS"
                 )
+                # Locally-initiated abort (no answer; giving up on SDES for this
+                # attempt) - flag it so the bridge observe loop does not warn on
+                # the resulting signal death.  Nothing continues to use this
+                # proc/holder afterward, so no reset is needed here.
+                _teardown_holder[0] = True
                 proc.terminate()
                 try:
                     proc.wait(timeout=2)
@@ -3784,4 +3883,5 @@ class _SdesOpenMixin:
             cmd_chan=_cmd_chan,
             talk_state=_talk_state,
             media_progress=_media_progress,
+            teardown_requested=_teardown_holder,
         )

{python_aidot_cameras-0.11.11 → python_aidot_cameras-0.11.13}/pyproject.toml

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

{python_aidot_cameras-0.11.11 → python_aidot_cameras-0.11.13/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.11.11
+Version: 0.11.13
 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