python-aidot-cameras 0.17.2__tar.gz → 1.0.0b2__tar.gz

{python_aidot_cameras-0.17.2/python_aidot_cameras.egg-info → python_aidot_cameras-1.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.17.2
+Version: 1.0.0b2
 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
@@ -66,6 +66,40 @@ Other battery models (A001108, A001360) are recognized in code with the same
 battery handling. See [`docs/CAMERAS.md`](docs/CAMERAS.md#supported-cameras) for
 the authoritative table and per-model notes.
 
+## Local (LAN) control and account ownership
+
+Local control over the devices' TCP:10000 channel - both the light/plug protocol
+and this package's `CameraLanClient` - is accepted **only for the account that
+owns the devices**. A member of a shared home is rejected at the device, even
+though the cloud happily hands that member a full device list, complete with the
+per-device `password` and `aesKey`.
+
+The rejection is easy to misread, because the device answers with a code that
+varies by firmware family and a message that blames the wrong thing:
+
+| Model | Ack |
+| --- | --- |
+| `LK.light.A001493` | 400 `not equal abort user id or password` |
+| `LK.light.A001497`, `LK.plug.A001535` | 4354 `fail` |
+| `LK.IPC.A000088` | 4352 `fail` |
+
+The A001493's message is the honest one: it is the **user id** that does not
+match, not the password. Every credential in the request can be correct and the
+login will still be refused if the `userId` is not the owner's.
+
+Verified 2026-08-08 against ten devices across four model families: every one
+returns 200 for the owning account and one of the codes above for a shared-home
+member.
+
+**If local control never engages, check which account the integration is signed
+in as before looking anywhere else.** A dedicated or secondary login - the sort
+of thing you might use to avoid contending with a phone app over a rotating
+refresh token - will control everything fine through the cloud and never once
+log in locally.
+
+Cameras' live video is unaffected either way: it is WebRTC signaled over cloud
+MQTT and does not use this path.
+
 ## Library install
 
 Install from PyPI (the simplest, recommended method):
@@ -175,6 +209,8 @@ audio, idle release, the sprop cache path) are documented in
 | `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. 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_VIDEO_PT` | Pin the SDES offer to ONE video codec by payload type, so the camera cannot choose. The offer advertises 96 (H264) and 97 (H265) and the camera decides which to send; on an A001064 that means the same request comes back h264 1280x720 most sessions and hevc 2560x1440 occasionally, at a third of the bitrate. Set to `96` for H264 only (measured h264 720p in 4 of 4 sessions). **Do not set it to `97`** - an H265-only offer returned no video at all in 3 of 3 rounds; narrowing to H265 removes the option rather than selecting it. | unset (both offered) |
+| `AIDOT_SDES_VIDEO_PT_ORDER` | Reorder the SDES offer's video codec list without narrowing it, as a comma-separated preference list (`97,96`). RFC 3264 makes the `m=video` payload-type list a preference list, most-preferred first, and ours has always read `96 97` - not by decision, it has simply never been varied. Whatever is named leads and the rest is appended, so this can express a preference and can never produce a narrowed or empty video m-line. **Experimental and untested on hardware:** whether the camera acts on the order is the open question, so the default is deliberately unchanged. | unset (`96 97`) |
 | `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) |

{python_aidot_cameras-0.17.2 → python_aidot_cameras-1.0.0b2}/README.md

@@ -35,6 +35,40 @@ Other battery models (A001108, A001360) are recognized in code with the same
 battery handling. See [`docs/CAMERAS.md`](docs/CAMERAS.md#supported-cameras) for
 the authoritative table and per-model notes.
 
+## Local (LAN) control and account ownership
+
+Local control over the devices' TCP:10000 channel - both the light/plug protocol
+and this package's `CameraLanClient` - is accepted **only for the account that
+owns the devices**. A member of a shared home is rejected at the device, even
+though the cloud happily hands that member a full device list, complete with the
+per-device `password` and `aesKey`.
+
+The rejection is easy to misread, because the device answers with a code that
+varies by firmware family and a message that blames the wrong thing:
+
+| Model | Ack |
+| --- | --- |
+| `LK.light.A001493` | 400 `not equal abort user id or password` |
+| `LK.light.A001497`, `LK.plug.A001535` | 4354 `fail` |
+| `LK.IPC.A000088` | 4352 `fail` |
+
+The A001493's message is the honest one: it is the **user id** that does not
+match, not the password. Every credential in the request can be correct and the
+login will still be refused if the `userId` is not the owner's.
+
+Verified 2026-08-08 against ten devices across four model families: every one
+returns 200 for the owning account and one of the codes above for a shared-home
+member.
+
+**If local control never engages, check which account the integration is signed
+in as before looking anywhere else.** A dedicated or secondary login - the sort
+of thing you might use to avoid contending with a phone app over a rotating
+refresh token - will control everything fine through the cloud and never once
+log in locally.
+
+Cameras' live video is unaffected either way: it is WebRTC signaled over cloud
+MQTT and does not use this path.
+
 ## Library install
 
 Install from PyPI (the simplest, recommended method):
@@ -144,6 +178,8 @@ audio, idle release, the sprop cache path) are documented in
 | `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. 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_VIDEO_PT` | Pin the SDES offer to ONE video codec by payload type, so the camera cannot choose. The offer advertises 96 (H264) and 97 (H265) and the camera decides which to send; on an A001064 that means the same request comes back h264 1280x720 most sessions and hevc 2560x1440 occasionally, at a third of the bitrate. Set to `96` for H264 only (measured h264 720p in 4 of 4 sessions). **Do not set it to `97`** - an H265-only offer returned no video at all in 3 of 3 rounds; narrowing to H265 removes the option rather than selecting it. | unset (both offered) |
+| `AIDOT_SDES_VIDEO_PT_ORDER` | Reorder the SDES offer's video codec list without narrowing it, as a comma-separated preference list (`97,96`). RFC 3264 makes the `m=video` payload-type list a preference list, most-preferred first, and ours has always read `96 97` - not by decision, it has simply never been varied. Whatever is named leads and the rest is appended, so this can express a preference and can never produce a narrowed or empty video m-line. **Experimental and untested on hardware:** whether the camera acts on the order is the open question, so the default is deliberately unchanged. | unset (`96 97`) |
 | `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) |

{python_aidot_cameras-0.17.2 → python_aidot_cameras-1.0.0b2}/aidot_cameras/camera/client.py

@@ -398,6 +398,21 @@ _BUSY_BACKOFF_S = float(os.environ.get("AIDOT_BUSY_BACKOFF_S", "20"))
 _FUTILE_KEEPALIVE_LIMIT = int(os.environ.get("AIDOT_FUTILE_KEEPALIVE_LIMIT", "5"))
 
 
+def _next_no_media_streak(no_media_streak: int, healthy: bool) -> int:
+    """The streak after a keepalive session that was (or was not) healthy.
+
+    The ceiling counts CONSECUTIVE failures, so a session that delivered media
+    resets it to zero. Without that reset the count is cumulative and a camera
+    that merely fails occasionally - five scattered no-media sessions spread
+    across a day, each one separated by sessions that worked - eventually trips
+    a limit meant for cameras that never deliver anything at all, and has its
+    background keepalive stopped for good.
+    """
+    if healthy:
+        return 0
+    return no_media_streak + 1
+
+
 def _should_abandon_keepalive(no_media_streak: int, *, is_battery: bool,
                               limit: int = _FUTILE_KEEPALIVE_LIMIT) -> bool:
     """Should the background keepalive stop reopening this camera?
@@ -1808,13 +1823,22 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                               self.device_id, len(data))
             elif isinstance(body, dict):
                 data = body.get("data") or {}
+                # Keys, never values: this response can carry the per-device
+                # streaming credentials (tutkAccount / tutkPassword - see
+                # docs/DEFERRED_FEATURES.md), and the warning below is logged
+                # at default level, so a whole-body dump lands in every user's
+                # home-assistant.log.  The matched-device log further down
+                # already prints keys only; these two did not.
                 if data:
-                    _LOGGER.debug("batchGetDeviceUserInfo response for %s (status=%d): %s",
-                                  self.device_id, status, body)
+                    _LOGGER.debug(
+                        "batchGetDeviceUserInfo response for %s (status=%d):"
+                        " keys=%s, %d item(s)",
+                        self.device_id, status, sorted(body.keys()), len(data),
+                    )
                 else:
                     _LOGGER.warning(
-                        "batchGetDeviceUserInfo no data for %s (status=%d): %s",
-                        self.device_id, status, body,
+                        "batchGetDeviceUserInfo no data for %s (status=%d): keys=%s",
+                        self.device_id, status, sorted(body.keys()),
                     )
             else:
                 data = {}
@@ -2622,7 +2646,14 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                         _session.wait_done(),
                         timeout=_sdes_snap_seconds + 80,
                     )
-                except (TimeoutError, _asyncio.CancelledError):
+                except _asyncio.CancelledError:
+                    # Not the same event as a timeout.  A timeout means the
+                    # camera was slow and whatever landed in the temp file is
+                    # worth salvaging; a cancellation means the caller is gone,
+                    # so salvaging it (another ffmpeg, up to 15s) is work nobody
+                    # is waiting for and it stops shutdown from completing.
+                    raise
+                except TimeoutError:
                     pass
                 finally:
                     await _session.stop()
@@ -3599,6 +3630,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             # 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
+            _no_media_streak = _next_no_media_streak(_no_media_streak, _healthy)
             if _healthy:
                 # A session that delivered media is a real, cleanly-used session;
                 # the next open should be a fresh one rather than re-offering on a
@@ -3606,9 +3638,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                 _loop_peer_id = self.generate_webrtc_peer_id(
                     live_type=2, stream_id=0, sdes=True)
                 _peer_reuses = 0
-                _no_media_streak = 0
             else:
-                _no_media_streak += 1
                 if _should_abandon_keepalive(
                         _no_media_streak, is_battery=self.is_battery_camera):
                     # Every open so far has cost the camera a wake and returned

{python_aidot_cameras-0.17.2 → python_aidot_cameras-1.0.0b2}/aidot_cameras/camera/lan_control.py

@@ -164,6 +164,26 @@ class CameraLanError(Exception):
     """A local control operation failed (connect, login, or protocol error)."""
 
 
+class CameraLanLoginRejected(CameraLanError):
+    """The device advertised local control and then refused our login.
+
+    Separate from its parent because the two mean opposite things to a caller.
+    A device that does not offer local control is ordinary and should be quiet;
+    a device that offers it, accepts the connection, decrypts our request with
+    its own key, and STILL answers with a non-200 ack is a defect - either in
+    what we send or in the device - and the caller should be able to say so out
+    loud rather than logging it at the same level as "not supported here".
+
+    ``ack`` is the device's own code, because the refusals differ by family and
+    the number is the only handle on which one happened: A000088 cameras answer
+    4352, A001497 lights and A001535 plugs 4354, A001493 lights 400.
+    """
+
+    def __init__(self, message: str, ack: Any = None) -> None:
+        super().__init__(message)
+        self.ack = ack
+
+
 class CameraLanClient:
     """Short-lived local device-control client for one camera.
 
@@ -291,9 +311,13 @@ class CameraLanClient:
             ) from exc
         if ack != 200:
             # The real device rejected our key-authenticated login; stop using
-            # the LAN path and revert to cloud.
+            # the LAN path and revert to cloud.  Raised as the specific type so
+            # a caller can tell this apart from a device that never offered
+            # local control - see CameraLanLoginRejected.
             self._eligible = False
-            raise CameraLanError(f"{self.device_id}: login rejected ack={ack}")
+            raise CameraLanLoginRejected(
+                f"{self.device_id}: login rejected ack={ack}", ack=ack
+            )
         return (resp.get("payload") or {}).get("ascNumber", 1)
 
     # -- public control ---------------------------------------------------- #

{python_aidot_cameras-0.17.2 → python_aidot_cameras-1.0.0b2}/aidot_cameras/camera/protocol.py

@@ -662,8 +662,14 @@ def _load_sprop(devid: str) -> "Optional[str]":
         return None
 
 
-def _save_sprop(devid: str, sprop: str) -> None:
-    """Persist the ``sprop-parameter-sets`` string for ``devid`` (best-effort).
+def _save_sprop(devid: str, sprop: str) -> bool:
+    """Persist the ``sprop-parameter-sets`` for ``devid``.  True if it wrote.
+
+    Returns whether anything was actually cached, because two of the three
+    outcomes here write nothing and the caller announces the write in the only
+    log line this feature has.  An unconditional announcement claims a cache
+    that an unstable camera provably does not have, which is the observable an
+    investigation reads first.
 
     If a DIFFERENT value was already cached, this camera does not keep its
     parameter sets stable: mark it and drop the cache, so nothing is injected
@@ -672,7 +678,7 @@ def _save_sprop(devid: str, sprop: str) -> None:
     loses nothing by the injection being skipped.
     """
     if _sprop_is_unstable(devid):
-        return          # already known unstable; nothing to cache for this camera
+        return False    # already known unstable; nothing to cache for this camera
     try:
         prev = _load_sprop(devid)
         if prev is not None and prev != sprop:
@@ -689,17 +695,19 @@ def _save_sprop(devid: str, sprop: str) -> None:
                 os.remove(_sprop_cache_path(devid))
             except OSError:
                 pass
-            return
+            return False
         os.makedirs(_SPROP_DIR, exist_ok=True)
         tmp = _sprop_cache_path(devid) + ".tmp"
         with open(tmp, "w") as fh:
             fh.write(sprop)
         os.replace(tmp, _sprop_cache_path(devid))
+        return True
     except OSError as exc:
         # 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)
+        return False
 
 
 def _inject_sprop(sdp: str, devid: str) -> str:

{python_aidot_cameras-0.17.2 → python_aidot_cameras-1.0.0b2}/aidot_cameras/camera/sdes.py

@@ -133,12 +133,19 @@ class SdesSession(AvioRequestMixin):
     def talk_supported(self) -> bool:
         """True if two-way audio can be used on this SDES session.
 
-        Requires a talk-capable open (offer advertised sendrecv + a=ssrc).  The
-        camera audio address is filled in by the bridge on first inbound audio;
-        async_start_talk tolerates being called before that - the pump waits for
-        the address before emitting.
+        Requires a talk-capable open (offer advertised sendrecv + a=ssrc) AND a
+        session that is still running.  The camera audio address is filled in by
+        the bridge on first inbound audio; async_start_talk tolerates being
+        called before that - the pump waits for the address before emitting.
+
+        Liveness is part of the answer because the talk state is a plain dict
+        that outlives ffmpeg, while everything that acts on it - the bridge
+        thread that sends SPEAKERSTART, the socket the pump writes to - dies
+        with ffmpeg.  ``async_speak`` reuses the warm session whenever this is
+        true, so answering from the dict alone routed talk into a session that
+        could no longer carry it instead of opening a fresh one.
         """
-        return bool(self._talk_state)
+        return bool(self._talk_state) and self.is_alive
 
     async def async_start_talk(
         self, pcm_provider: "Callable[[], Optional[bytes]]"
@@ -170,10 +177,23 @@ class SdesSession(AvioRequestMixin):
                 target=_run_sdes_talk_pump, args=(self._talk_state,), daemon=True
             )
             self._talk_thread.start()
-        if await _speaker_ack_accepted(waiter, SDES_SPEAKER_ACK_TIMEOUT_S):
+        accepted = await _speaker_ack_accepted(waiter, SDES_SPEAKER_ACK_TIMEOUT_S)
+        # _speaker_ack_accepted is generous by design: it treats an unfamiliar or
+        # absent ack as acceptance, because no genuine refusal has ever been
+        # identified and guessing at one would break working cameras.  That
+        # generosity is about INTERPRETING the camera's answer, and it has
+        # nothing to say about the case where the question was never asked.
+        # `speaker_on` is set on exactly one line - immediately after the bridge
+        # thread dispatches SPEAKERSTART(848) - so a falsy flag here means our
+        # own bridge never sent the command, which happens whenever ffmpeg (and
+        # with it that thread) has already exited.  The ack budget above already
+        # covers SDES_SPEAKERSTART_DELAY, so a live bridge has always set it by
+        # now and this cannot race a working session.
+        if accepted and self._talk_state.get("speaker_on"):
             return True
-        # The camera refused. Stop the microphone rather than stream viewer
-        # audio at a speaker that never opened.
+        # Either the camera refused, or the speaker command never left this
+        # process.  Stop the microphone rather than stream viewer audio at a
+        # speaker that never opened.
         self._talk_state["want_speaker"] = False
         self._talk_state["provider"] = None
         return False