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

{python_aidot_cameras-1.0.0b29/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.0b29
+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.0b29 → 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.0b29 → python_aidot_cameras-1.0.0b31}/aidot_cameras/__main__.py

@@ -77,6 +77,7 @@ import aiohttp
 
 from .client import AidotClient
 from .cloud_auth import (  # noqa: F401  (re-exported for callers and tests)
+    CloudAuthUnavailable,
     _install_token_cache,
     _make_client,
     _read_token_file,
@@ -86,8 +87,6 @@ from .const import CONF_DEVICE_LIST, CONF_ID, CONF_MODEL_ID, CONF_NAME
 
 _LOGGER = logging.getLogger("aidot.go2rtc")
 
-DEFAULT_COUNTRY = os.environ.get("AIDOT_COUNTRY", "US")
-
 
 def _env_bool(name: str) -> bool | None:
     """Tri-state env flag: '1' -> True, '0' -> False, unset -> None (library default)."""
@@ -131,7 +130,11 @@ def _go2rtc_source(dev_id: str, is_sdes: bool) -> str:
 async def cmd_list() -> int:
     """Print device id + transport for every camera, plus paste-ready go2rtc YAML."""
     async with aiohttp.ClientSession() as session:
-        client = await _make_client(session)
+        # CloudAuthUnavailable is the library-side signal; a CLI exits on it.
+        try:
+            client = await _make_client(session)
+        except CloudAuthUnavailable as exc:
+            sys.exit(str(exc))
         cams = await _cameras(client)
         if not cams:
             print("No IPC cameras found on this account.")
@@ -158,7 +161,10 @@ async def cmd_list() -> int:
 async def cmd_stream(dev_id: str, output_url: str) -> int:
     """Open one camera's keepalive and push/serve it to ``output_url``."""
     async with aiohttp.ClientSession() as session:
-        client = await _make_client(session)
+        try:
+            client = await _make_client(session)
+        except CloudAuthUnavailable as exc:
+            sys.exit(str(exc))
         cams = await _cameras(client)
         device = next((d for d in cams if d[CONF_ID] == dev_id), None)
         if device is None:

{python_aidot_cameras-1.0.0b29 → 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.0b29 → 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.0b29 → 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
 
 
@@ -2950,6 +2960,12 @@ def decode_remb_bitrate(pkt: bytes) -> int:
     return mantissa << exp
 
 
+#: RTPFB feedback message types (RFC 4585 s6.1, RFC 5104 s4.2).
+_RTPFB_PT = 205
+_FMT_NACK = 1
+_FMT_TMMBR = 3
+
+
 def build_nack(sender_ssrc: int, media_ssrc: int, lost_seqs: "list") -> bytes:
     """An RTCP Generic NACK (RFC 4585 s6.2.1) asking for ``lost_seqs`` again.
 
@@ -2985,7 +3001,7 @@ def build_nack(sender_ssrc: int, media_ssrc: int, lost_seqs: "list") -> bytes:
             i += 1
         fci.append(struct.pack("!HH", pid, blp))
 
-    pkt = (struct.pack("!BBH", 0x80 | 1, 205, 0)
+    pkt = (struct.pack("!BBH", 0x80 | _FMT_NACK, _RTPFB_PT, 0)
            + struct.pack("!II", sender_ssrc & 0xFFFFFFFF,
                          media_ssrc & 0xFFFFFFFF)
            + b"".join(fci))
@@ -2993,12 +3009,6 @@ def build_nack(sender_ssrc: int, media_ssrc: int, lost_seqs: "list") -> bytes:
     return pkt[:2] + struct.pack("!H", len(pkt) // 4 - 1) + pkt[4:]
 
 
-#: RTPFB feedback message types (RFC 4585 s6.1, RFC 5104 s4.2).
-_RTPFB_PT = 205
-_FMT_NACK = 1
-_FMT_TMMBR = 3
-
-
 def build_tmmbr(sender_ssrc: int, media_ssrc: int, bitrate_bps: int,
                 overhead: int = 60) -> bytes:
     """A TMMBR (RFC 5104 s4.2.1) telling ``media_ssrc`` not to exceed a rate.

{python_aidot_cameras-1.0.0b29 → 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: