python-aidot-cameras 0.12.16__tar.gz → 0.12.17__tar.gz

{python_aidot_cameras-0.12.16/python_aidot_cameras.egg-info → python_aidot_cameras-0.12.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.12.16
+Version: 0.12.17
 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
@@ -171,12 +171,12 @@ 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_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. | unset (off) |
+| `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_DTLS_FAST_LIVEPLAY` | The DTLS (A000088) analogue: skip the `livePlayReq`-echo and `livePlayResp` waits (the dominant LAN cold-start cost) while keeping the full ICE/TURN/DTLS handshake, so remote/relay viewing is unaffected. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_PERSISTENT_MQTT` | Reuse ONE account-level persistent MQTT connection for commands, attribute fetches, and stream-open signaling (matching the official app) instead of connecting per operation. **On by default** (live soaks cut SDES NO_MEDIA from ~57% to ~11-19%); set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_SERVE_RELAY` | Hold the public stream port via an internal relay that proxies to ffmpeg, so the first (cold) view connects instead of failing while ffmpeg can't pre-bind the port. Set to `0` to serve ffmpeg directly. | `1` (enabled) |
-| `AIDOT_LIVESTREAM_PARAM` | Set to `0` to skip the cloud `liveStreamParam` pre-connect that provisions battery cameras' live-stream sessions before signaling (without it, battery cameras like the L2 models reject streaming with `-50019`). | `1` (enabled) |
+| `AIDOT_LIVESTREAM_PARAM` | **No-op (ignored).** Formerly requested the cloud `liveStreamParam` pre-connect for battery cameras. That call provisions the camera toward AWS KVS, so it sends its media there instead of to this library and the live view negotiates and then shows nothing - and battery cameras were the only ones it applied to. Setting it (or `start_keepalive(live_stream_param=True)`) logs one warning and changes nothing. | ignored |
 
 ### Security hardening
 

{python_aidot_cameras-0.12.16 → python_aidot_cameras-0.12.17}/README.md

@@ -140,12 +140,12 @@ 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_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. | unset (off) |
+| `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_DTLS_FAST_LIVEPLAY` | The DTLS (A000088) analogue: skip the `livePlayReq`-echo and `livePlayResp` waits (the dominant LAN cold-start cost) while keeping the full ICE/TURN/DTLS handshake, so remote/relay viewing is unaffected. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_PERSISTENT_MQTT` | Reuse ONE account-level persistent MQTT connection for commands, attribute fetches, and stream-open signaling (matching the official app) instead of connecting per operation. **On by default** (live soaks cut SDES NO_MEDIA from ~57% to ~11-19%); set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
 | `AIDOT_SERVE_RELAY` | Hold the public stream port via an internal relay that proxies to ffmpeg, so the first (cold) view connects instead of failing while ffmpeg can't pre-bind the port. Set to `0` to serve ffmpeg directly. | `1` (enabled) |
-| `AIDOT_LIVESTREAM_PARAM` | Set to `0` to skip the cloud `liveStreamParam` pre-connect that provisions battery cameras' live-stream sessions before signaling (without it, battery cameras like the L2 models reject streaming with `-50019`). | `1` (enabled) |
+| `AIDOT_LIVESTREAM_PARAM` | **No-op (ignored).** Formerly requested the cloud `liveStreamParam` pre-connect for battery cameras. That call provisions the camera toward AWS KVS, so it sends its media there instead of to this library and the live view negotiates and then shows nothing - and battery cameras were the only ones it applied to. Setting it (or `start_keepalive(live_stream_param=True)`) logs one warning and changes nothing. | ignored |
 
 ### Security hardening
 

{python_aidot_cameras-0.12.16 → python_aidot_cameras-0.12.17}/aidot_cameras/camera/client.py

@@ -21,6 +21,7 @@ from ..const import (
 # in-module references (and any external importers) keep resolving.
 from .constants import (
     _LEEDARSON_APP_ID,
+    _LIVE_PLAY_NOT_READY,
     _SMARTHOME_URL_TEMPLATE,
     GETSTREAMCTRL_CMD,  # noqa: F401 - re-exported for back-compat (public pair; unused in-module)
     SDES_SPEAKERSTART_DELAY,  # noqa: F401 - used by the sdes_open mixin; kept re-exported
@@ -33,6 +34,7 @@ from .models import (  # re-exported: data models split into models.py
     CameraDeviceInformation,
     CameraStatusData,
     VideoFrame,
+    _as_int,
 )
 from .tutk import TutkStreamSession  # re-exported (split into tutk.py)
 from .playback import (  # re-exported (split into playback.py)
@@ -906,6 +908,15 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
     # A001513 battery cameras).  Exclude role-reversal models from the flag.
     _NO_FAST_LIVEPLAY_MODELS: frozenset = frozenset({"LK.IPC.A001064"})
 
+    # Models confirmed (2026-05-02) to send TUTK-framed data instead of standard
+    # SRTP: the camera announces an ASCII-printable fake SDES key and sends
+    # packets with a TUTK SFrame header (0xC8 audio / 0xC9 video) and an SSRC
+    # that differs from the one advertised in the SDP.  For these the ffmpeg SDP
+    # uses plain RTP/AVP (no SRTP decryption attempt) and the bridge strips the
+    # TUTK header before forwarding.  Matched by SUBSTRING (see _use_plain_rtp in
+    # sdes_open) so a revision suffix is covered.
+    _PLAIN_RTP_MODELS: frozenset = frozenset({"A001064", "A001513"})
+
     @property
     def _offer_should_include_datachannel(self) -> bool:
         model = getattr(getattr(self, "info", None), "model_id", None)
@@ -917,13 +928,111 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         props = getattr(self, "_raw_device", {}).get("properties") or {}
         return str(props.get("enableSdes", "0")) == "1"
 
+    # Battery / low-power camera models.  ONE list, consumed by
+    # is_battery_camera and (through it) by every battery guard and by the
+    # livePlayReq/webrtcReq ``powerType`` field - it used to be re-typed inline in
+    # three files, which is how a guard drifts out of step with the wire payload.
+    # Source: IpcServiceImpl.java B() - powerType=2 for these models, 1 for wired.
+    # Substring-matched, so a firmware/hardware revision suffix
+    # ("LK.IPC.A001513-1") is covered the way A000088-1 already is on the DTLS
+    # side rather than silently reading as a different, mains-powered model.
+    _BATTERY_MODELS: frozenset = frozenset({"A001513", "A001108", "A001360"})
+
+    def _battery_evidence(self) -> "Optional[bool]":
+        """Does this camera's OWN cloud data say it runs on a battery?
+
+        True when the cloud reports a battery for it, else None ("no evidence" -
+        NOT "mains", since the device-list payload may simply not carry the field
+        yet).  Same signal ``lan_control.is_mains_powered`` inverts: a camera that
+        reports a battery level has a battery.  Never raises - it is read from
+        hot paths - and never returns False, so it can only ever ADD a camera to
+        the battery set, never take a known model out of it.
+        """
+        _raw = getattr(self, "_raw_device", None)
+        _props = _raw.get("properties") if isinstance(_raw, dict) else None
+        if not isinstance(_props, dict):
+            _props = {}
+        # A reported battery level means there is a battery to report.
+        for _key in ("Battery_remaining", "batteryRemaining", "batteryLevel"):
+            if _as_int(_props.get(_key)) is not None:
+                return True
+        # The low-power flag: batteryMode=2 is what a camera that sleeps between
+        # sessions reports (see _async_send_camera_command).  Deliberately NOT
+        # keyed on ``powerType``: that name is also the value we SEND in
+        # livePlayReq, we have never observed the cloud returning it as a device
+        # property, and p2pCache - the field right next to it - reads 2 on every
+        # camera including mains ones.  Reading it here would risk classifying a
+        # mains camera as battery, which would put powerType=2 on ITS wire payload
+        # and can leave an A000088 un-armed.  Evidence has to be unambiguous.
+        if _as_int(_props.get("batteryMode")) == 2:
+            return True
+        # Already-parsed status, for a camera refreshed from an attribute push
+        # rather than from a device-list dict.
+        _status = getattr(self, "status", None)
+        if _as_int(getattr(_status, "battery_remaining", None)) is not None:
+            return True
+        return None
+
     @property
     def is_battery_camera(self) -> bool:
-        """True for battery/low-power models (A001513, A001108, A001360).
-        Source: IpcServiceImpl.java B() - powerType=2 for these models.
+        """True for battery/low-power cameras (powerType=2 in the app's B()).
+
+        Resolved from the camera's own cloud data FIRST (see
+        [[_battery_evidence]]), then from the known-model list
+        ([[_BATTERY_MODELS]]).  Evidence leads because a hardcoded list can only
+        ever name the revisions we have already seen, and a battery camera that
+        is not recognized as one loses every battery protection at once: the SDES
+        TURN relay pre-allocation (its ONLY return path - a camera woken through
+        the cloud has no LAN host candidate), the cloud keep-alive renew, the
+        HTTP wake, and the powerType=2 the camera is told to expect.
+
+        That misdetection presents as "streams from a standalone run but never
+        under Home Assistant", because HA is where the LAN-direct options that
+        strip the relay actually get set - a one-off script leaves them at their
+        (relay-keeping) defaults, so it never trips the guard it is missing.
         """
+        if self._battery_evidence():
+            return True
         model = getattr(getattr(self, "info", None), "model_id", None) or ""
-        return any(m in model for m in ("A001513", "A001108", "A001360"))
+        return any(m in model for m in self._BATTERY_MODELS)
+
+    @property
+    def live_power_type(self) -> int:
+        """The ``powerType`` field for livePlayReq / webrtcReq: 2 battery, 1 wired.
+
+        Source: IpcServiceImpl.java B().  Derived from [[is_battery_camera]] so
+        the value on the wire and the battery guards can never disagree.
+        """
+        return 2 if self.is_battery_camera else 1
+
+    def _note_live_play_resp(self, payload) -> None:
+        """Record the camera's livePlayResp code for this open (loop thread).
+
+        Called from the signaling dispatcher for every livePlayResp matched to
+        this open, whether or not anything is waiting on the future - which
+        matters because ``sdes_fast_liveplay`` is on by default and skips that
+        wait, so this is the only place the code is seen on the SDES path.
+        Best-effort: a malformed payload leaves the record untouched rather than
+        raising into the dispatcher.
+        """
+        try:
+            self._last_live_play_code = _as_int(payload.get("code"))
+        except (AttributeError, TypeError):
+            _LOGGER.debug("camera %s: unparseable livePlayResp payload",
+                          getattr(self, "device_id", "?"), exc_info=True)
+
+    def _live_play_not_ready(self) -> bool:
+        """Did this open's livePlayResp say the camera is not ready to stream?
+
+        ``-50019`` is NOT a refusal on its own - a camera emits it and then
+        recovers via ICE, which is why 0.12.15 stopped treating it as fatal and
+        why nothing here aborts an open on it.  Its value is post-hoc: pair it
+        with "the session then delivered no media" and you have a waking battery
+        camera that was not ready yet, as distinct from a generic failure.  Only
+        the retry delay keys on it (see the SDES keepalive loop) - never the
+        decision to proceed.
+        """
+        return getattr(self, "_last_live_play_code", None) == _LIVE_PLAY_NOT_READY
 
     def _next_dseq(self) -> int:
         """Next livePlayReq dseq (app parity: Q0() starts at 100, increments)."""
@@ -1204,15 +1313,19 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
     async def _async_fetch_live_stream_param(self) -> bool:
         """Provision the camera's live-stream session via the cloud (app parity).
 
-        Battery cameras waking from deep sleep reject the MQTT ``livePlayReq``
-        with code ``-50019`` ("not ready") and then never run ICE - so no media
-        ever flows - unless the app's pre-connect HTTP call has armed the session
-        first.  The official app (``KVSPreConnectStrategy.fetchKvsParams``) POSTs
-        the device id to ``/api/ipc/liveStream/liveStreamParam``; the cloud
-        provisions the session (and brings the camera online) and returns AWS KVS
-        credentials.  We only need the provisioning side effect - the library
-        streams over the proprietary MQTT/SDES path, not AWS KVS - so the returned
-        credentials are ignored.  Best-effort: returns True on HTTP 200.
+        **Not called** - [[_resolve_live_stream_param]] gates this and always says
+        no; see there for why.  Kept, with its request shape locked down by
+        tests/test_live_stream_param.py, so re-enabling it for a camera that
+        demonstrably needs it is a one-line change rather than a rediscovery.
+
+        The official app (``KVSPreConnectStrategy.fetchKvsParams``) POSTs the
+        device id to ``/api/ipc/liveStream/liveStreamParam``; the cloud provisions
+        the session (and brings the camera online) and returns AWS KVS
+        credentials.  Only the provisioning side effect was ever wanted here - the
+        library streams over the proprietary MQTT/SDES path, not AWS KVS - but
+        that side effect is precisely the problem: the camera then sends its media
+        toward KVS and our bridge receives no video RTP.  Best-effort: returns True
+        on HTTP 200.
         """
         url, headers, body = self._live_stream_param_request()
         return await self._async_post_ok(url, headers, body, label="liveStreamParam")
@@ -2700,12 +2813,14 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         to the ``AIDOT_FAST_CONNECT`` env var; ``True``/``False`` override it (e.g.
         from a Home Assistant config-entry option, since HA OS can't set env vars).
 
-        ``live_stream_param`` toggles the battery-camera cloud pre-connect
-        (liveStreamParam), which is **off by default**: it provisions the camera
-        toward AWS KVS and diverts an A001513's media away from the SDES bridge
-        (no video RTP arrives).  Like ``fast_connect`` it overrides the
-        ``AIDOT_LIVESTREAM_PARAM`` env var; set True only to re-enable the
-        pre-connect for a camera that needs it.
+        ``live_stream_param`` is **accepted but ignored** (a no-op kept so an
+        existing caller doesn't break; it logs one warning if set).  It used to
+        request the battery-camera cloud pre-connect, which provisions the camera
+        toward AWS KVS so its media goes there instead of to the SDES bridge - the
+        session negotiates and then serves no video at all.  Battery cameras were
+        the only ones it applied to, i.e. exactly the ones it breaks, so the
+        decision is now made once in ``_resolve_live_stream_param`` and is "no".
+        Stop passing it; live video does not depend on it.
 
         ``serve_relay`` toggles the cold-start serve-port relay (holds the public
         serve port connectable through the WebRTC handshake so an eager go2rtc
@@ -3071,6 +3186,19 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                                                      sdes=True)
         _peer_reuses = 0
 
+        # Wake-readiness retries.  A battery camera that answers livePlayResp with
+        # -50019 and then sends no media was not refusing - it had not finished
+        # waking.  The pacer cannot tell that apart from a degraded camera, so it
+        # escalated the backoff (10s -> 300s) on a camera that would have been
+        # ready seconds later; under a consumer that re-opens per view, that is the
+        # difference between a slow first frame and a live view that never fills
+        # in.  Give it the same bounded fast burst the DTLS serve loop already has
+        # (_retry_policy), then fall back to the pacer so a persistently-cold
+        # camera is still not hammered.  Bounded to _PEERID_MAX_REUSE so the whole
+        # burst stays on ONE peerid: a fresh peerid registers another camera-side
+        # session, which is what wedged the L2 in the first place (0.12.16).
+        _not_ready_burst = 0
+
         while self._streaming_active:
             if self._serve_relay is not None:
                 # Clear any stale backend from a prior session; the open below
@@ -3257,8 +3385,23 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                 # (camera refused / degraded on a rapid reconnect); a session
                 # that streamed fine and then ended (battery teardown, consumer
                 # gone) is a normal lifecycle event and resets to the base interval.
+                # Exception: a battery camera that answered -50019 and then sent
+                # nothing was still waking, not degraded - retry it fast instead.
+                _not_ready_burst = self._next_not_ready_burst(
+                    _healthy, _not_ready_burst)
+                _delay, _fast_retry = self._not_ready_retry_delay(
+                    _not_ready_burst, burst_max=_PEERID_MAX_REUSE)
+                if _fast_retry:
+                    _LOGGER.info(
+                        "SDES %s: camera not ready (waking, livePlayResp %d) and "
+                        "sent no media - fast retry in %.0fs [%d/%d]",
+                        self.device_id, _LIVE_PLAY_NOT_READY, _delay,
+                        _not_ready_burst, _PEERID_MAX_REUSE,
+                    )
+                else:
+                    _delay = _pacer.session_end_delay(healthy=_healthy)
                 try:
-                    await asyncio.sleep(_pacer.session_end_delay(healthy=_healthy))
+                    await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
 
@@ -3609,6 +3752,54 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         except (ValueError, TypeError):
             return -8.0
 
+    def _resolve_live_stream_param(self) -> bool:
+        """Whether to make the cloud ``liveStreamParam`` KVS pre-connect before
+        signaling.  **Always False** - see below; the flag survives only so an
+        existing caller doesn't break.
+
+        The call provisions the camera's live session toward AWS KVS, and the
+        camera then sends its media THERE instead of to our SDES bridge: the
+        session negotiates, the bridge binds, and no video RTP ever arrives.  It
+        is also made for battery cameras ONLY, so the set of cameras it can
+        affect is exactly the set it is known to break.  It was added to cure a
+        ``-50019`` ("not ready") livePlayResp, which 0.12.15 established is
+        benign - mains cameras emit it too and recover via ICE.
+
+        0.12.15 turned it off by default but left the option/env able to turn it
+        back on, which is a foot-gun aimed at one foot: a consumer that surfaces
+        it as a setting (the Home Assistant integration surfaces these options
+        because HA OS cannot set env vars) can re-break every battery camera on
+        the account, and the symptom - a live view that negotiates and then shows
+        nothing, forever - looks nothing like a settings problem.  A standalone
+        run never passes the option, which is exactly why the same library
+        streams an L2 from the CLI and not under HA.
+
+        So the decision now lives here, in one place, and is "no".  Re-enabling
+        it needs a code change plus fresh on-hardware evidence that some camera
+        actually requires it - not a flag flip.  A caller that still asks gets
+        one warning naming the camera, so a stuck install says why in the log
+        instead of silently serving nothing.
+        """
+        if not self.is_battery_camera:
+            # The pre-connect was never made for a mains camera in the first
+            # place; nothing to decide.
+            return False
+        asked = getattr(self, "_live_stream_param_opt", None)
+        if asked is None:
+            asked = os.environ.get("AIDOT_LIVESTREAM_PARAM", "0") != "0"
+        if asked and not getattr(self, "_live_stream_param_warned", False):
+            self._live_stream_param_warned = True
+            _LOGGER.warning(
+                "camera %s: ignoring the liveStreamParam pre-connect request "
+                "(live_stream_param / AIDOT_LIVESTREAM_PARAM).  On a battery "
+                "camera it provisions the session toward AWS KVS and the camera "
+                "sends its media there instead of to this library, so the live "
+                "view negotiates and then serves no video at all.  The setting "
+                "is a no-op - remove it; live video does not depend on it.",
+                self.device_id,
+            )
+        return False
+
     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.
@@ -3665,7 +3856,20 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         ``AIDOT_SDES_ADAPTIVE`` env (truthy = 1/true/yes/on), default off. When
         off, the per-attempt override is never set, so the explicit
         ``sdes_fast_liveplay`` / ``sdes_skip_turn`` opts (or their envs) decide -
-        exactly the pre-adaptive behaviour."""
+        exactly the pre-adaptive behaviour.
+
+        NEVER on for a battery camera, whatever the opt/env say - for those it is
+        all cost and no benefit.  The saving adaptive chases is the TURN relay
+        pre-allocation, and [[_resolve_sdes_skip_turn]] force-KEEPS that for a
+        battery camera (it is the only return path to a cloud-woken camera), while
+        fast-liveplay is already on by default.  So a battery "fast" attempt runs
+        the very same handshake as the patient one and differs only in being given
+        45 s to open and a 40 s media grace - inside the documented 25-70 s battery
+        cold-start window.  A slow-but-healthy wake is then scored as a fast-path
+        failure: it latches ``_fast_path_unavailable``, escalates the backoff, and
+        burns a camera-side session on a device that frees them slowly."""
+        if getattr(self, "is_battery_camera", False):
+            return False
         opt = getattr(self, "_sdes_adaptive_opt", None)
         if opt is not None:
             return bool(opt)
@@ -3789,6 +3993,35 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         adaptive mode is on and the fast path has not already failed this loop."""
         return bool(adaptive) and not bool(fast_failed)
 
+    def _next_not_ready_burst(self, healthy: bool, burst: int) -> int:
+        """Updated wake-readiness burst counter after a session ended.
+
+        Counts up only while a BATTERY camera keeps answering ``-50019`` and then
+        delivering no media; any other outcome resets it to 0.  Scoped to battery
+        cameras because they are the only ones with a wake-readiness state - on a
+        mains camera ``-50019`` is transient noise and the pacer's judgement
+        (something is degraded) is the right one.
+        """
+        if healthy or not self.is_battery_camera:
+            return 0
+        return burst + 1 if self._live_play_not_ready() else 0
+
+    @staticmethod
+    def _not_ready_retry_delay(burst: int, *,
+                               burst_max: int = 3) -> "tuple[float, bool]":
+        """``(delay, is_fast_retry)`` for a wake-readiness retry.
+
+        Shares [[_retry_policy]] with the DTLS serve loop so both paths agree on
+        what "the camera is still warming up" is worth waiting.  Returns
+        ``(0.0, False)`` when the counter is 0 (not a wake-readiness failure) and
+        ``(_, False)`` once the burst is spent, in both cases handing the decision
+        back to the caller's normal pacer.
+        """
+        if burst <= 0:
+            return (0.0, False)
+        delay, fast = _retry_policy("not_ready", burst, burst_max=burst_max)
+        return (delay, bool(fast))
+
     @staticmethod
     def _adaptive_after_attempt(use_fast: bool, healthy: bool, fast_failed: bool) -> bool:
         """Updated ``fast_failed`` after an attempt: latch it once a fast attempt

{python_aidot_cameras-0.12.16 → python_aidot_cameras-0.12.17}/aidot_cameras/camera/constants.py

@@ -88,6 +88,14 @@ GETSTREAMCTRL_CMD = 802
 _STREAM_QUALITY: dict = {"hd": 1, "sd": 5}  # AVIOCTRL_QUALITY_MAX / _MIDDLE
 
 
+# livePlayResp code for "not ready": the camera accepted the request but cannot
+# stream yet (a battery camera still waking).  Explicitly NOT a refusal - mains
+# cameras emit it too and recover via ICE - so no path aborts an open on it.  It
+# is only read after the fact, to tell a waking camera apart from a generically
+# failed session when choosing a retry delay (see _live_play_not_ready).
+_LIVE_PLAY_NOT_READY = -50019
+
+
 # Two-way-audio (talk) / SDES timing constants (moved from client.py)
 TALK_PCM_RATE = 8000
 TALK_PCM_FRAME_BYTES = 320  # 160 samples (20 ms @ 8 kHz) x 2 bytes (s16)