python-aidot-cameras 0.7.25__tar.gz → 0.7.27__tar.gz

{python_aidot_cameras-0.7.25/src/python_aidot_cameras.egg-info → python_aidot_cameras-0.7.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.7.25
+Version: 0.7.27
 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
@@ -122,6 +122,9 @@ chosen to work out of the box; override only when tuning.
 | `AIDOT_SPROP_DIR` | Directory where captured SPS/PPS (sprop) parameter sets are cached. Set this to a writable path (e.g. for Home Assistant) if the default location is read-only. | `<package dir>` |
 | `AIDOT_DISABLE_HIGHPORT_FIX` | If set (any value), disables the DTLS high-port `USE-CANDIDATE` nomination fix and falls back to upstream aioice behavior (used to measure the baseline connect rate). | unset (fix enabled) |
 | `AIDOT_FAST_CONNECT` | Enables LAN-direct "fast connect" mode (STUN-only, skips several cloud signaling waits) when set to a truthy value. | unset (off) |
+| `AIDOT_SDES_ADAPTIVE` | Adaptive fast-with-fallback for the SDES keepalive loop: try the fast path first (skip livePlay waits + TURN relay pre-alloc) 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 for a camera. Truthy value enables. | unset (off) |
+| `AIDOT_SDES_FAST_LIVEPLAY` | Truthy value skips the `livePlayResp` blocking wait for eligible SDES cameras (~4.5 s faster cold start), while keeping the full ICE/SCTP handshake. Role-reversal models (A001064 PTZ) are always excluded. Soak-validated; opt-in. | unset (off) |
+| `AIDOT_SERVE_RELAY` | Holds 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_MAX_CONCURRENT_OPENS` | Caps how many stream opens run concurrently. | `2` |
 | `AIDOT_MAX_CONCURRENT_STREAMS` | Caps how many cameras stream at once. | `3` |
 | `AIDOT_STREAM_IDLE_S` | Seconds of stream idle before an idle release. | `120` |
@@ -131,6 +134,7 @@ chosen to work out of the box; override only when tuning.
 | `AIDOT_BUSY_RETRY_S` | Delay, in seconds, before retrying when a camera reports busy. | `45` |
 | `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_GOP_PLI_S` | Interval, in seconds, between PLI (keyframe) requests. | `2.0` |
+| `AIDOT_SDES_PLI_GAPS` | Comma-separated second offsets for the early PLI (keyframe-request) burst on SDES cameras, to pull the first keyframe in faster on cold start. | `0,1.5,2,3` |
 | `AIDOT_AUDIO_TARGET_DBFS` | Target loudness (dBFS) for two-way audio normalization. | `-15` |
 | `AIDOT_AUDIO_MAXGAIN_DB` | Maximum gain (dB) applied by the audio normalizer. | `30` |
 | `AIDOT_AUDIO_MINGAIN_DB` | Minimum gain (dB) applied by the audio normalizer. | `-12` |

{python_aidot_cameras-0.7.25 → python_aidot_cameras-0.7.27}/README.md

@@ -95,6 +95,9 @@ chosen to work out of the box; override only when tuning.
 | `AIDOT_SPROP_DIR` | Directory where captured SPS/PPS (sprop) parameter sets are cached. Set this to a writable path (e.g. for Home Assistant) if the default location is read-only. | `<package dir>` |
 | `AIDOT_DISABLE_HIGHPORT_FIX` | If set (any value), disables the DTLS high-port `USE-CANDIDATE` nomination fix and falls back to upstream aioice behavior (used to measure the baseline connect rate). | unset (fix enabled) |
 | `AIDOT_FAST_CONNECT` | Enables LAN-direct "fast connect" mode (STUN-only, skips several cloud signaling waits) when set to a truthy value. | unset (off) |
+| `AIDOT_SDES_ADAPTIVE` | Adaptive fast-with-fallback for the SDES keepalive loop: try the fast path first (skip livePlay waits + TURN relay pre-alloc) 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 for a camera. Truthy value enables. | unset (off) |
+| `AIDOT_SDES_FAST_LIVEPLAY` | Truthy value skips the `livePlayResp` blocking wait for eligible SDES cameras (~4.5 s faster cold start), while keeping the full ICE/SCTP handshake. Role-reversal models (A001064 PTZ) are always excluded. Soak-validated; opt-in. | unset (off) |
+| `AIDOT_SERVE_RELAY` | Holds 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_MAX_CONCURRENT_OPENS` | Caps how many stream opens run concurrently. | `2` |
 | `AIDOT_MAX_CONCURRENT_STREAMS` | Caps how many cameras stream at once. | `3` |
 | `AIDOT_STREAM_IDLE_S` | Seconds of stream idle before an idle release. | `120` |
@@ -104,6 +107,7 @@ chosen to work out of the box; override only when tuning.
 | `AIDOT_BUSY_RETRY_S` | Delay, in seconds, before retrying when a camera reports busy. | `45` |
 | `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_GOP_PLI_S` | Interval, in seconds, between PLI (keyframe) requests. | `2.0` |
+| `AIDOT_SDES_PLI_GAPS` | Comma-separated second offsets for the early PLI (keyframe-request) burst on SDES cameras, to pull the first keyframe in faster on cold start. | `0,1.5,2,3` |
 | `AIDOT_AUDIO_TARGET_DBFS` | Target loudness (dBFS) for two-way audio normalization. | `-15` |
 | `AIDOT_AUDIO_MAXGAIN_DB` | Maximum gain (dB) applied by the audio normalizer. | `30` |
 | `AIDOT_AUDIO_MINGAIN_DB` | Minimum gain (dB) applied by the audio normalizer. | `-12` |

{python_aidot_cameras-0.7.25 → python_aidot_cameras-0.7.27}/pyproject.toml

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

{python_aidot_cameras-0.7.25 → python_aidot_cameras-0.7.27}/src/aidot/camera/client.py

@@ -1959,6 +1959,8 @@ class CameraMixin(_CameraControlsMixin):
         serve_relay: Optional[bool] = None,
         stream_idle_s: Optional[float] = None,
         sdes_fast_liveplay: Optional[bool] = None,
+        sdes_skip_turn: Optional[bool] = None,
+        sdes_adaptive: Optional[bool] = None,
     ) -> None:
         """Start a persistent stream that keeps the camera session alive.
 
@@ -2009,6 +2011,10 @@ class CameraMixin(_CameraControlsMixin):
             self._stream_idle_opt = stream_idle_s
         if sdes_fast_liveplay is not None:
             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_adaptive is not None:
+            self._sdes_adaptive_opt = sdes_adaptive
         if self._stream_task is not None and not self._stream_task.done():
             return
         self._keepalive_rtsp_url = rtsp_push_url
@@ -2218,19 +2224,46 @@ class CameraMixin(_CameraControlsMixin):
         # media (see end of loop).
         _pacer = ReconnectPacer(_MIN_DELAY, _MAX_DELAY)
 
+        # Adaptive fast-with-fallback (default on): the first open tries the fast
+        # path (skip livePlay waits + TURN relay pre-allocation) with a SHORT
+        # timeout/grace so a non-LAN camera fails quickly; on no media we latch
+        # _fast_failed and the remaining opens this loop use the full, patient
+        # relay path.  Makes fast-by-default safe regardless of camera reachability.
+        _adaptive = self._resolve_sdes_adaptive()
+        _FAST_OPEN_TIMEOUT = 45.0
+        _FAST_GRACE = 40.0
+        # Per-device cache: once a fast attempt has failed for this camera (e.g. a
+        # strict-NAT / non-LAN camera that genuinely needs the relay), remember it
+        # so later views skip the fast attempt entirely instead of re-paying the
+        # ~40s fast timeout on every fresh keepalive loop. Latches for the client's
+        # lifetime; an integration reload / restart re-probes the fast path.
+        _fast_failed = bool(getattr(self, "_fast_path_unavailable", False))
+
         while self._streaming_active:
             if self._serve_relay is not None:
                 # Clear any stale backend from a prior session; the open below
                 # points the relay at this session's fresh internal ffmpeg port.
                 self._serve_relay.set_backend(None)
+            _use_fast = self._adaptive_next_fast(_adaptive, _fast_failed)
+            if _adaptive:
+                self._fast_attempt_override = _use_fast
             try:
                 session = await self.async_open_webrtc_stream(
                     rtsp_push_url=self._keepalive_rtsp_url,
-                    timeout=120.0,
+                    timeout=(_FAST_OPEN_TIMEOUT if _use_fast else 120.0),
                 )
             except asyncio.CancelledError:
+                self._fast_attempt_override = None
                 return
             except Exception as exc:
+                self._fast_attempt_override = None
+                if _use_fast:
+                    _fast_failed = self._adaptive_after_attempt(True, False, _fast_failed)
+                    self._fast_path_unavailable = True  # cache across views
+                    _LOGGER.info(
+                        "SDES adaptive[%s]: fast open failed (%.0fs) - "
+                        "falling back to full relay path", self.device_id,
+                        _FAST_OPEN_TIMEOUT)
                 _delay = _pacer.fail_delay()
                 _LOGGER.warning(
                     "SDES keepalive: stream open failed for %s (retry in %.0fs): %s",
@@ -2242,6 +2275,7 @@ class CameraMixin(_CameraControlsMixin):
                     return
                 continue
 
+            self._fast_attempt_override = None
             self._stream_session = session
             # Don't block solely on wait_done(): the SDES ffmpeg reads RTP over a
             # UDP socket with no input timeout, so when a battery camera tears the
@@ -2276,6 +2310,7 @@ class CameraMixin(_CameraControlsMixin):
                         session.last_media_monotonic,
                         _started_at,
                         time.monotonic(),
+                        grace=(_FAST_GRACE if _use_fast else 60.0),
                     ):
                         _stalled = True
                         break
@@ -2327,12 +2362,22 @@ class CameraMixin(_CameraControlsMixin):
             except Exception:
                 _LOGGER.debug("camera %s: swallowed exception", '_sdes_keepalive_loop', exc_info=True)
 
+            # Adaptive bookkeeping: a fast attempt that never delivered media
+            # latches the loop onto the full relay path for its remaining opens.
+            _healthy = session.last_media_monotonic > 0.0
+            if _use_fast and not _healthy and not _fast_failed:
+                _LOGGER.info(
+                    "SDES adaptive[%s]: fast attempt delivered no media - "
+                    "falling back to full relay path", self.device_id)
+            _fast_failed = self._adaptive_after_attempt(_use_fast, _healthy, _fast_failed)
+            if _use_fast and not _healthy:
+                self._fast_path_unavailable = True  # cache across views
+
             if self._streaming_active:
                 # Escalate backoff only when the session never delivered media
                 # (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.
-                _healthy = session.last_media_monotonic > 0.0
                 try:
                     await asyncio.sleep(_pacer.session_end_delay(healthy=_healthy))
                 except asyncio.CancelledError:
@@ -2556,9 +2601,77 @@ class CameraMixin(_CameraControlsMixin):
         opt = getattr(self, "_sdes_fast_liveplay_opt", None)
         if opt is not None:
             return bool(opt)
+        ov = getattr(self, "_fast_attempt_override", None)
+        if ov is not None:
+            return bool(ov)
         return os.environ.get("AIDOT_SDES_FAST_LIVEPLAY", "").strip().lower() in (
             "1", "true", "yes", "on")
 
+    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.
+
+        Before building the offer the SDES path does two synchronous RFC-5766
+        Allocate round-trips (audio + video) to the cloud TURN server so the
+        offer's c=/m= can carry a relay address - ~2-3 s of pure cold-start
+        latency.  On a LAN the camera's host candidate wins and that relay is
+        never used, so skipping it shaves the latency - at the cost of no relay
+        fallback for a camera on a different segment / behind strict NAT (the
+        same trade-off ``AIDOT_FAST_CONNECT`` already makes for DTLS, and which
+        is force-disabled for SDES because it *also* skips the SCTP-arming
+        waits; this flag skips ONLY the relay pre-allocation, leaving the rest
+        of the SDES handshake intact).
+
+        Per-camera ``sdes_skip_turn`` (set via start_keepalive) wins; else the
+        ``AIDOT_SDES_SKIP_TURN_PREALLOC`` env (truthy = 1/true/yes/on), default
+        off.  Only consulted for SDES cameras."""
+        opt = getattr(self, "_sdes_skip_turn_opt", None)
+        if opt is not None:
+            return bool(opt)
+        ov = getattr(self, "_fast_attempt_override", None)
+        if ov is not None:
+            return bool(ov)
+        return os.environ.get("AIDOT_SDES_SKIP_TURN_PREALLOC", "").strip().lower() in (
+            "1", "true", "yes", "on")
+
+    def _resolve_sdes_adaptive(self) -> bool:
+        """Whether the SDES keepalive loop drives the fast path adaptively
+        (opt-in, default OFF): try fast-first (skip the livePlay waits + TURN
+        relay pre-allocation, with a short timeout), and fall back to the full,
+        patient relay path if the fast attempt delivers no media.
+
+        This makes "fast by default" safe for cameras of unknown reachability:
+        a LAN-direct camera gets the fast connect; a remote / strict-NAT camera
+        loses one short fast attempt, then connects via the full relay path.
+
+        Default OFF pending real-world fast-failure-rate data: a fast *failure*
+        costs ~40 s (the grace) before fallback while success saves only ~7 s, so
+        until the failure rate is known on real fleets this stays opt-in.
+
+        Per-camera ``sdes_adaptive`` (via start_keepalive) wins; else the
+        ``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."""
+        opt = getattr(self, "_sdes_adaptive_opt", None)
+        if opt is not None:
+            return bool(opt)
+        return os.environ.get("AIDOT_SDES_ADAPTIVE", "").strip().lower() in (
+            "1", "true", "yes", "on")
+
+    @staticmethod
+    def _adaptive_next_fast(adaptive: bool, fast_failed: bool) -> bool:
+        """Whether the next SDES open attempt should use the fast path: only when
+        adaptive mode is on and the fast path has not already failed this loop."""
+        return bool(adaptive) and not bool(fast_failed)
+
+    @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
+        delivers no media, so the loop stays on the full relay path (no
+        oscillation) until it restarts fresh on the next view."""
+        return bool(fast_failed) or (bool(use_fast) and not bool(healthy))
+
     def _maybe_start_serve_relay(self, serve_url: Optional[str]) -> "Optional[_ServeRelay]":
         """Hold the public serve port via a _ServeRelay so an eager go2rtc pull
         connects-and-waits instead of hitting ECONNREFUSED during the ~16-25s
@@ -6818,7 +6931,15 @@ class CameraMixin(_CameraControlsMixin):
         # AIDOT_FAST_CONNECT skips this blocking pre-allocation (LAN-direct mode):
         # the offer goes out immediately with host/srflx candidates and the LAN
         # path connects without waiting on a cloud TURN Allocate round-trip.
-        if _sdes_turn_entries and not _fast_connect:
+        # AIDOT_SDES_SKIP_TURN_PREALLOC (experimental, opt-in) does the same skip
+        # for SDES specifically, where _fast_connect is force-off (see
+        # _resolve_sdes_skip_turn).  Either way the cost is instrumented below so
+        # the saving is measurable: grep ``signaling-wait[`` for sdes-turn-prealloc.
+        _skip_turn_prealloc = self._resolve_sdes_skip_turn()
+        _turn_t0 = time.monotonic()
+        _turn_did = False
+        if _sdes_turn_entries and not _fast_connect and not _skip_turn_prealloc:
+            _turn_did = True
             try:
                 import re as _re_pre
                 import hashlib as _hlk_pre
@@ -6855,6 +6976,16 @@ class CameraMixin(_CameraControlsMixin):
                             )
             except Exception as _pre_exc:
                 _LOGGER.warning("TURN pre-allocation error: %s", _pre_exc)
+        if _skip_turn_prealloc and _sdes_turn_entries:
+            _status(
+                "AIDOT_SDES_SKIP_TURN_PREALLOC: skipping TURN relay"
+                " pre-allocation (~2-3s) - host/srflx candidates only, LAN-direct"
+            )
+        _LOGGER.info(
+            "signaling-wait[%s] sdes-turn-prealloc elapsed=%dms allocated=%d skipped=%s",
+            self.device_id,
+            int((time.monotonic() - _turn_t0) * 1000),
+            len(_relay_addrs), bool(_skip_turn_prealloc))
 
         # --- DTLS certificate for m=application probe ----------------------- #
         # PreCon cameras (sptPreconn=1) need SESSION_MODE_REQ via SCTP datachannel.

{python_aidot_cameras-0.7.25 → python_aidot_cameras-0.7.27/src/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.7.25
+Version: 0.7.27
 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
@@ -122,6 +122,9 @@ chosen to work out of the box; override only when tuning.
 | `AIDOT_SPROP_DIR` | Directory where captured SPS/PPS (sprop) parameter sets are cached. Set this to a writable path (e.g. for Home Assistant) if the default location is read-only. | `<package dir>` |
 | `AIDOT_DISABLE_HIGHPORT_FIX` | If set (any value), disables the DTLS high-port `USE-CANDIDATE` nomination fix and falls back to upstream aioice behavior (used to measure the baseline connect rate). | unset (fix enabled) |
 | `AIDOT_FAST_CONNECT` | Enables LAN-direct "fast connect" mode (STUN-only, skips several cloud signaling waits) when set to a truthy value. | unset (off) |
+| `AIDOT_SDES_ADAPTIVE` | Adaptive fast-with-fallback for the SDES keepalive loop: try the fast path first (skip livePlay waits + TURN relay pre-alloc) 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 for a camera. Truthy value enables. | unset (off) |
+| `AIDOT_SDES_FAST_LIVEPLAY` | Truthy value skips the `livePlayResp` blocking wait for eligible SDES cameras (~4.5 s faster cold start), while keeping the full ICE/SCTP handshake. Role-reversal models (A001064 PTZ) are always excluded. Soak-validated; opt-in. | unset (off) |
+| `AIDOT_SERVE_RELAY` | Holds 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_MAX_CONCURRENT_OPENS` | Caps how many stream opens run concurrently. | `2` |
 | `AIDOT_MAX_CONCURRENT_STREAMS` | Caps how many cameras stream at once. | `3` |
 | `AIDOT_STREAM_IDLE_S` | Seconds of stream idle before an idle release. | `120` |
@@ -131,6 +134,7 @@ chosen to work out of the box; override only when tuning.
 | `AIDOT_BUSY_RETRY_S` | Delay, in seconds, before retrying when a camera reports busy. | `45` |
 | `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_GOP_PLI_S` | Interval, in seconds, between PLI (keyframe) requests. | `2.0` |
+| `AIDOT_SDES_PLI_GAPS` | Comma-separated second offsets for the early PLI (keyframe-request) burst on SDES cameras, to pull the first keyframe in faster on cold start. | `0,1.5,2,3` |
 | `AIDOT_AUDIO_TARGET_DBFS` | Target loudness (dBFS) for two-way audio normalization. | `-15` |
 | `AIDOT_AUDIO_MAXGAIN_DB` | Maximum gain (dB) applied by the audio normalizer. | `30` |
 | `AIDOT_AUDIO_MINGAIN_DB` | Minimum gain (dB) applied by the audio normalizer. | `-12` |

{python_aidot_cameras-0.7.25 → python_aidot_cameras-0.7.27}/src/python_aidot_cameras.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ tests/test_live_stream_param.py
 tests/test_motion_poll.py
 tests/test_no_undefined_names.py
 tests/test_post_merge_hardening.py
+tests/test_sdes_adaptive.py
 tests/test_sdes_fast_liveplay.py
 tests/test_sdes_idle_release.py
 tests/test_sdes_sprop.py

python_aidot_cameras-0.7.27/tests/test_sdes_adaptive.py

@@ -0,0 +1,126 @@
+"""Unit tests for the SDES adaptive fast-with-fallback controller.
+
+The adaptive controller (default on) makes "fast by default" safe regardless of
+camera reachability: the SDES keepalive loop tries the fast path first (skip the
+livePlay waits + TURN relay pre-allocation, short timeout/grace) and falls back
+to the full relay path if a fast attempt delivers no media. These tests lock the
+decision state-machine and the resolver precedence so the wiring is verifiable
+without a camera; the real media/stability effect is validated by live soak.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src"))
+
+import aidot.camera.client as cc
+
+_CAM = next(v for v in vars(cc).values()
+            if isinstance(v, type) and "_resolve_sdes_adaptive" in v.__dict__)
+
+
+def _cam():
+    return _CAM.__new__(_CAM)
+
+
+# --- _resolve_sdes_adaptive: opt-in, default OFF --------------------------- #
+
+def test_adaptive_default_off(monkeypatch):
+    monkeypatch.delenv("AIDOT_SDES_ADAPTIVE", raising=False)
+    assert _cam()._resolve_sdes_adaptive() is False
+
+
+def test_adaptive_env_enables(monkeypatch):
+    for val in ("1", "true", "TRUE", "yes", "on", " On "):
+        monkeypatch.setenv("AIDOT_SDES_ADAPTIVE", val)
+        assert _cam()._resolve_sdes_adaptive() is True, val
+
+
+def test_adaptive_env_falsey_stays_off(monkeypatch):
+    for val in ("0", "false", "no", "off", "", "anything"):
+        monkeypatch.setenv("AIDOT_SDES_ADAPTIVE", val)
+        assert _cam()._resolve_sdes_adaptive() is False, val
+
+
+def test_adaptive_kwarg_wins_over_env(monkeypatch):
+    monkeypatch.setenv("AIDOT_SDES_ADAPTIVE", "1")
+    cam = _cam()
+    cam._sdes_adaptive_opt = False  # start_keepalive(sdes_adaptive=False)
+    assert cam._resolve_sdes_adaptive() is False
+
+
+# --- decision state machine ------------------------------------------------ #
+
+def test_next_fast_only_when_adaptive_and_not_failed():
+    assert _CAM._adaptive_next_fast(True, False) is True
+    assert _CAM._adaptive_next_fast(True, True) is False   # latched off
+    assert _CAM._adaptive_next_fast(False, False) is False  # adaptive off
+
+
+def test_after_attempt_latches_on_fast_nomedia():
+    # a fast attempt that delivered no media latches fast_failed
+    assert _CAM._adaptive_after_attempt(True, False, False) is True
+    # a fast attempt that delivered media does NOT latch
+    assert _CAM._adaptive_after_attempt(True, True, False) is False
+    # a full attempt (use_fast False) never latches, regardless of media
+    assert _CAM._adaptive_after_attempt(False, False, False) is False
+    # once latched, it stays latched (no oscillation back to fast)
+    assert _CAM._adaptive_after_attempt(False, True, True) is True
+
+
+def test_full_lifecycle_fast_then_fallback_sticks():
+    adaptive, failed = True, False
+    # attempt 1: fast, no media -> latch
+    use_fast = _CAM._adaptive_next_fast(adaptive, failed)
+    assert use_fast is True
+    failed = _CAM._adaptive_after_attempt(use_fast, False, failed)
+    assert failed is True
+    # attempt 2: must be full now, and stays full even after a healthy session
+    use_fast = _CAM._adaptive_next_fast(adaptive, failed)
+    assert use_fast is False
+    failed = _CAM._adaptive_after_attempt(use_fast, True, failed)
+    assert failed is True
+
+
+# --- per-attempt override feeds the fast resolvers ------------------------- #
+
+def test_override_drives_skip_turn_resolver(monkeypatch):
+    monkeypatch.delenv("AIDOT_SDES_SKIP_TURN_PREALLOC", raising=False)
+    cam = _cam()
+    cam._fast_attempt_override = True
+    assert cam._resolve_sdes_skip_turn() is True
+    cam._fast_attempt_override = False
+    assert cam._resolve_sdes_skip_turn() is False
+
+
+def test_explicit_opt_beats_override(monkeypatch):
+    # an explicit user opt must win over the adaptive per-attempt override
+    cam = _cam()
+    cam._sdes_skip_turn_opt = False
+    cam._fast_attempt_override = True
+    assert cam._resolve_sdes_skip_turn() is False
+
+
+def test_cache_makes_next_view_skip_fast():
+    # A camera that previously failed the fast path latches _fast_path_unavailable,
+    # so the next keepalive loop starts already-failed and skips the fast attempt
+    # (no repeated ~40s fast timeout per fresh view). A fresh camera tries fast.
+    cached = _cam()
+    cached._fast_path_unavailable = True
+    init_failed = bool(getattr(cached, "_fast_path_unavailable", False))
+    assert init_failed is True
+    assert _CAM._adaptive_next_fast(True, init_failed) is False
+
+    fresh = _cam()
+    init_fresh = bool(getattr(fresh, "_fast_path_unavailable", False))
+    assert init_fresh is False
+    assert _CAM._adaptive_next_fast(True, init_fresh) is True
+
+
+def test_override_respects_role_reversal_exclusion(monkeypatch):
+    from types import SimpleNamespace
+    monkeypatch.delenv("AIDOT_SDES_FAST_LIVEPLAY", raising=False)
+    cam = _cam()
+    cam.info = SimpleNamespace(model_id="LK.IPC.A001064")
+    cam._fast_attempt_override = True  # adaptive would try fast...
+    # ...but the role-reversal model is excluded from fast-liveplay regardless
+    assert cam._resolve_sdes_fast_liveplay() is False