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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0b30
+Version: 1.0.0b31
 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.0b31}/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.0b31}/aidot_cameras/camera/client.py

@@ -3540,6 +3540,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 +3617,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 +4704,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 +4760,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.0b31}/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.0b31}/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.0b31}/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:

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b31}/aidot_cameras/camera/sdes_open.py

@@ -260,6 +260,98 @@ def _env_positive(name: str, cast=int, off=None):
     return value if value > 0 else off
 
 
+def _turn_entry_ips(entries) -> set:
+    """The server addresses named by ICE entries' ``Uris`` lists.
+
+    Entries look like ``{"Uris": ["stun:3.230.182.123:3478",
+    "turn:3.230.182.123:5349?transport=udp"], ...}``.  The address is what
+    media source classification needs; scheme, port and query are noise.
+    """
+    ips = set()
+    for entry in entries or ():
+        for uri in (entry.get("Uris") or ()):
+            body = str(uri).split(":", 1)[-1]
+            host = body.split("?", 1)[0].rsplit(":", 1)[0].strip("[]")
+            if host:
+                ips.add(host)
+    return ips
+
+
+def _classify_media_path(src_ip, turn_ips) -> "Optional[str]":
+    """"direct" or "relay" for a media source address, or None when unknown.
+
+    Media arriving FROM a TURN server address is relayed - that covers both
+    shapes on this fleet: the camera's own allocation on the vendor TURN (the
+    relayed A001513's media arrives from the TURN address on the camera's
+    allocation port, so the PORT must not participate) and a Data Indication
+    through ours.  Anything else came to us directly.
+    """
+    if not src_ip:
+        return None
+    return "relay" if src_ip in turn_ips else "direct"
+
+
+def _sdes_offer_media_endpoint(mode: str, default_ip: str, default_port: int,
+                               relay_addr, public_ip):
+    """Where the offer's c=/m= points for one media section: (ip, port, is_relay).
+
+    This fleet's firmware nominates by dialing c=/m=, not by reading candidate
+    lines - measured 2026-08-24, an A001064 and an A001513 both dialed direct
+    with only the relay candidate on offer.  So forcing the relay means moving
+    c=/m= to the allocation, which was this path's ORIGINAL design (see the
+    allocation helper's comment) before it was backed out over dropped media.
+
+    The missing piece back then was the permission: the camera's packets reach
+    the TURN server from the house WAN address - OUR srflx address - and
+    without a CreatePermission for it the relay drops everything.  Relay mode
+    therefore requires a known public_ip; without one (or without an
+    allocation) it falls back to the direct endpoint, because a stream on the
+    wrong path beats no stream.
+    """
+    if mode == "relay" and relay_addr and public_ip:
+        return relay_addr[0], relay_addr[1], True
+    return default_ip, default_port, False
+
+
+def _sdes_offer_candidate_lines(mode: str, local_ip: str, port: int,
+                                public_ip, relay_addr) -> str:
+    """The a=candidate block for one media section, shaped by the mode.
+
+    ``auto``  - host + srflx (when a public IP is known) + relay (when the
+                pre-allocation succeeded), in that priority order.  This is the
+                shipped behaviour: the LAN wins by ICE priority (host
+                2130706431 > srflx 1694498815 > relay 16777215) and the relay
+                is the last resort - measured on the full fleet 2026-08-24,
+                six of seven cameras direct and only the unit with no route to
+                us on the relay.
+    ``lan``   - host + srflx only.  Normally moot (lan mode also skips the
+                relay pre-allocation, so there is no relay_addr to omit), but
+                enforced here too so the two levers cannot disagree.
+    ``relay`` - the relay candidate ONLY, so an ICE-speaking camera has
+                nothing else to nominate.  The relay address must still never
+                appear in c=/m= - TURN drops every camera packet without a
+                CreatePermission for the camera's public address, which is
+                unknown - so candidate lines are the entire steering surface,
+                and firmware that ignores ICE and dials c=/m= directly cannot
+                be steered.  With no allocation to offer this falls back to
+                the auto block: an offer with zero candidates is a session
+                that cannot start, and a stream on the wrong path beats no
+                stream.
+    """
+    host = f"a=candidate:1 1 udp 2130706431 {local_ip} {port} typ host\r\n"
+    srflx = (f"a=candidate:2 1 udp 1694498815 {public_ip} {port}"
+             f" typ srflx raddr {local_ip} rport {port}\r\n"
+             if public_ip else "")
+    relay = (f"a=candidate:3 1 udp 16777215 {relay_addr[0]} {relay_addr[1]}"
+             f" typ relay raddr {local_ip} rport {port}\r\n"
+             if relay_addr else "")
+    if mode == "relay" and relay:
+        return relay
+    if mode == "lan":
+        return host + srflx
+    return host + srflx + relay
+
+
 def _sdes_offer_bandwidth_kbps():
     """A receive-bandwidth ceiling for the offer, in kbps, or None for none."""
     return _env_positive("AIDOT_SDES_OFFER_BANDWIDTH_KBPS")
@@ -1864,6 +1956,13 @@ class _SdesOpenMixin:
         # _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()
+        # Which media path to offer (auto | lan | relay).  Resolved once per
+        # open; the candidate blocks below are built from it.  A receipt goes
+        # out whenever it is not the default, because a run that cannot show
+        # the knob was applied cannot tell a result from a coincidence.
+        _conn_mode = self._resolve_sdes_connection_mode()
+        if _conn_mode != "auto" and _status:
+            _status(f"SDES: connection mode {_conn_mode}")
         _turn_t0 = time.monotonic()
         _turn_did = False
         if _sdes_turn_entries and not _fast_connect and not _skip_turn_prealloc:
@@ -1990,10 +2089,18 @@ class _SdesOpenMixin:
         # for the camera's public IP which is unknown; relay in c= causes TURN to
         # drop every camera packet.  Relay is still in a=candidate: for ICE.
         # For LAN cameras (_public_ip is None) fall back to local_ip directly.
-        _offer_audio_ip   = _public_ip or local_ip
-        _offer_audio_port = audio_port
-        _offer_video_ip   = _public_ip or local_ip
-        _offer_video_port = video_port
+        _offer_audio_ip, _offer_audio_port, _relay_in_c_a = _sdes_offer_media_endpoint(
+            _conn_mode, _public_ip or local_ip, audio_port,
+            _relay_addrs.get(_audio_sock), _public_ip)
+        _offer_video_ip, _offer_video_port, _relay_in_c_v = _sdes_offer_media_endpoint(
+            _conn_mode, _public_ip or local_ip, video_port,
+            _relay_addrs.get(_video_sock), _public_ip)
+        _relay_in_c = _relay_in_c_a or _relay_in_c_v
+        if _conn_mode == "relay" and not _relay_in_c and _status:
+            _status("SDES: relay mode fell back to the direct endpoint"
+                    " (no allocation or no public ip)")
+        elif _relay_in_c and _status:
+            _status("SDES: c=/m= at the relay allocation (relay mode)")
         _bundle_hdr_line = (
             "a=group:BUNDLE 0 1 2\r\n" if _dc_probe_fp else "a=group:BUNDLE 0 1\r\n"
         )
@@ -2063,18 +2170,9 @@ class _SdesOpenMixin:
             # the SDP body (confirmed from logcat ground truth 2026-05-22).
             + f"a=ice-ufrag:{_ufrag_a}\r\n"
             f"a=ice-pwd:{_pwd_a}\r\n"
-            f"a=candidate:1 1 udp 2130706431 {local_ip} {audio_port} typ host\r\n"
-            + (
-                f"a=candidate:2 1 udp 1694498815 {_public_ip} {audio_port}"
-                f" typ srflx raddr {local_ip} rport {audio_port}\r\n"
-                if _public_ip else ""
-            )
-            + (
-                f"a=candidate:3 1 udp 16777215 {_relay_addrs[_audio_sock][0]}"
-                f" {_relay_addrs[_audio_sock][1]}"
-                f" typ relay raddr {local_ip} rport {audio_port}\r\n"
-                if _audio_sock in _relay_addrs else ""
-            )
+            + _sdes_offer_candidate_lines(
+                _conn_mode, local_ip, audio_port, _public_ip,
+                _relay_addrs.get(_audio_sock))
             # video m-section
             + f"m=video {_offer_video_port} RTP/SAVPF {_video_pt_list}\r\n"
             f"c=IN IP4 {_offer_video_ip}\r\n"
@@ -2086,18 +2184,9 @@ class _SdesOpenMixin:
             + "a=rtcp-mux\r\n"
             f"a=ice-ufrag:{_ufrag_v}\r\n"
             f"a=ice-pwd:{_pwd_v}\r\n"
-            f"a=candidate:1 1 udp 2130706431 {local_ip} {video_port} typ host\r\n"
-            + (
-                f"a=candidate:2 1 udp 1694498815 {_public_ip} {video_port}"
-                f" typ srflx raddr {local_ip} rport {video_port}\r\n"
-                if _public_ip else ""
-            )
-            + (
-                f"a=candidate:3 1 udp 16777215 {_relay_addrs[_video_sock][0]}"
-                f" {_relay_addrs[_video_sock][1]}"
-                f" typ relay raddr {local_ip} rport {video_port}\r\n"
-                if _video_sock in _relay_addrs else ""
-            )
+            + _sdes_offer_candidate_lines(
+                _conn_mode, local_ip, video_port, _public_ip,
+                _relay_addrs.get(_video_sock))
             # m=application SCTP DataChannel section for SDES cameras.
             # Ground truth from real Leedarson app logcat (2026-05-22):
             #   m=application 9 SCTP webrtc-datachannel
@@ -2563,18 +2652,9 @@ class _SdesOpenMixin:
                 "a=rtcp-mux\r\n"
                 f"a=ice-ufrag:{_ufrag_a}\r\n"
                 f"a=ice-pwd:{_pwd_a}\r\n"
-                f"a=candidate:1 1 udp 2130706431 {local_ip} {audio_port} typ host\r\n"
-                + (
-                    f"a=candidate:2 1 udp 1694498815 {_public_ip} {audio_port}"
-                    f" typ srflx raddr {local_ip} rport {audio_port}\r\n"
-                    if _public_ip else ""
-                )
-                + (
-                    f"a=candidate:3 1 udp 16777215 {_relay_addrs[_audio_sock][0]}"
-                    f" {_relay_addrs[_audio_sock][1]}"
-                    f" typ relay raddr {local_ip} rport {audio_port}\r\n"
-                    if _audio_sock in _relay_addrs else ""
-                )
+                + _sdes_offer_candidate_lines(
+                    _conn_mode, local_ip, audio_port, _public_ip,
+                    _relay_addrs.get(_audio_sock))
                 + f"m=video {_ans_video_port} RTP/SAVPF 96 97\r\n"
                 f"c=IN IP4 {_ans_video_ip}\r\n"
                 "a=sendonly\r\n"
@@ -2588,18 +2668,9 @@ class _SdesOpenMixin:
                 "a=rtcp-mux\r\n"
                 f"a=ice-ufrag:{_ufrag_v}\r\n"
                 f"a=ice-pwd:{_pwd_v}\r\n"
-                f"a=candidate:1 1 udp 2130706431 {local_ip} {video_port} typ host\r\n"
-                + (
-                    f"a=candidate:2 1 udp 1694498815 {_public_ip} {video_port}"
-                    f" typ srflx raddr {local_ip} rport {video_port}\r\n"
-                    if _public_ip else ""
-                )
-                + (
-                    f"a=candidate:3 1 udp 16777215 {_relay_addrs[_video_sock][0]}"
-                    f" {_relay_addrs[_video_sock][1]}"
-                    f" typ relay raddr {local_ip} rport {video_port}\r\n"
-                    if _video_sock in _relay_addrs else ""
-                )
+                + _sdes_offer_candidate_lines(
+                    _conn_mode, local_ip, video_port, _public_ip,
+                    _relay_addrs.get(_video_sock))
             )
             _compressed_sdp_ans = _compress_sdp_req(_relay_answer_sdp)
 
@@ -3777,6 +3848,17 @@ class _SdesOpenMixin:
                 )
             return _perm_ok
 
+        # Relay mode only: the camera dials our relay allocation, and its
+        # packets arrive at the TURN server from the house WAN address - OUR
+        # public address - so that address needs a permission or the path is a
+        # black hole.  Deliberately NOT done outside relay mode: a permission
+        # for our own srflx caused TURN self-loop Data Indications and STUN
+        # echo storms when it was installed indiscriminately (see the warning
+        # in the allocation helper).  In relay mode nothing of ours is sent to
+        # our own allocation, so the loop has no driver.
+        if _relay_in_c and _public_ip:
+            _turn_install_permissions([(_public_ip, 9)], "relay-mode WAN")
+
         if _cam_ice_ufrag and _cam_ice_pwd and _cam_ice_cands:
             _turn_install_permissions(_cam_ice_cands, "setup")
 
@@ -3909,6 +3991,12 @@ class _SdesOpenMixin:
         # bridge on the first video RTP packet so the ffmpeg SDP can be narrowed
         # to the matching single codec before ffmpeg is launched.
         _first_video_pt: list = [None]
+        _media_path: list = [None]
+        # Every TURN server address this session could be relayed through:
+        # our allocations plus the ICE entries themselves - the camera can
+        # arrive via its OWN vendor allocation even when ours was skipped.
+        _bridge_turn_ips = ({a[0] for a in _relay_addrs.values()}
+                            | _turn_entry_ips(_sdes_turn_entries))
         # Fallback for the above, filled from the camera's negotiated answer SDP
         # when the wait below expires without a single video packet. Kept in a
         # list for the same reason as _first_video_pt: the serve-restart path
@@ -5504,6 +5592,9 @@ class _SdesOpenMixin:
                                 if len(_bpkt) >= 12:
                                     _bridge_fn._cam_video_ssrc = _st_br.unpack_from(
                                         '!I', _bpkt, 8)[0]
+                                if _media_path[0] is None:
+                                    _media_path[0] = _classify_media_path(
+                                        _bsrc[0], _bridge_turn_ips)
                                 _bridge_fn._cam_srtp_src  = _bsrc
                                 _bridge_fn._cam_srtp_sock = _bs
                                 if getattr(_bridge_fn, '_first_video_ts',
@@ -6618,6 +6709,7 @@ class _SdesOpenMixin:
             talk_state=_talk_state,
             media_progress=_media_progress,
             media_counts=_media_counts,
+            media_path=_media_path,
             teardown_requested=_teardown_holder,
             first_video_pt=_first_video_pt,
             first_audio_pt=_first_audio_pt,

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b31}/pyproject.toml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0b30
+Version: 1.0.0b31
 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.0b31}/python_aidot_cameras.egg-info/SOURCES.txt

@@ -145,6 +145,7 @@ tests/test_logging_caps.py
 tests/test_login_connect_deadline.py
 tests/test_login_reconnect_backoff.py
 tests/test_media_counted_only_when_plaintext.py
+tests/test_media_path_is_reported.py
 tests/test_media_socket_rcvbuf.py
 tests/test_media_wait_floor.py
 tests/test_motion_poll.py
@@ -191,6 +192,7 @@ tests/test_sd_playback.py
 tests/test_sdes_adaptive.py
 tests/test_sdes_avio_dispatch.py
 tests/test_sdes_bridge_break_gate.py
+tests/test_sdes_connection_mode.py
 tests/test_sdes_echo_wait_timeout.py
 tests/test_sdes_fast_liveplay.py
 tests/test_sdes_ffmpeg_stderr_log.py

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b31}/tests/test_env_seams.py

@@ -128,11 +128,12 @@ def test_sdes_media_stats_defaults_and_counts():
     sess._media_progress = progress
     sess._first_video_pt = vpt
     sess._first_audio_pt = apt
+    sess._media_path = [None]
 
     stats = sess.media_stats()
     assert stats == {
         "packets": 0, "bytes": 0, "last_media_monotonic": 0.0,
-        "video_pt": None, "audio_pt": None,
+        "video_pt": None, "audio_pt": None, "media_path": None,
     }
 
     # bridge-thread updates are visible through the shared lists

{python_aidot_cameras-1.0.0b30 → python_aidot_cameras-1.0.0b31}/tests/test_hwaccel_probe.py

@@ -29,7 +29,7 @@ from aidot_cameras.camera import hwaccel
 @pytest.fixture(autouse=True)
 def _isolate(tmp_path, monkeypatch):
     """Per-test cache dir and clean memo state."""
-    monkeypatch.setattr(hwaccel, "_SPROP_DIR", str(tmp_path))
+    monkeypatch.setenv("AIDOT_SPROP_DIR", str(tmp_path))
     monkeypatch.setattr(hwaccel, "_cache_mem", {})
     monkeypatch.setattr(hwaccel, "_identity_memo", None)
     monkeypatch.setattr(hwaccel, "_decoders_memo", None)