python-aidot-cameras 1.0.0b2__tar.gz → 1.0.0b4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0b2
+Version: 1.0.0b4
 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,33 @@ 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.
 
+## Known characteristics
+
+Two behaviours that are measured, understood as far as the evidence allows, and
+not going to change in this release. Neither is a fault to report.
+
+**Recorded video is retrievable only from cloud storage.** Whether a camera
+records to the cloud or to its own SD card is per-camera, not per-model, and the
+device reports it as `IsSupportPlayback`. This library retrieves cloud
+recordings (`async_get_cloud_recordings`, `async_open_cloud_playback`) and has
+no SD-card equivalent, so a camera storing to a card records normally and
+nothing here can play it back. On the reference fleet that is four of seven
+cameras. The vendor's own commands for it are identified but their responses
+have never been decoded; see `docs/ROAD-TO-1.0.md` item 6.
+
+**The A001064 (PTZ) streams at roughly 2.2 Mbps, about 24% above the vendor
+app.** Measured from a capture of the app on the same camera: it takes about
+1796 Kbps on HD and about 866 Kbps on SD. An earlier version of this note
+repeated a figure of 225-500 Kbps for the app - that was never measured here,
+and the capture contradicts it at both quality settings.
+
+So the practical difference is a quarter more bandwidth at equivalent quality,
+plus a roughly 2:1 saving that the app's SD control achieves and this library's
+does not. The command sent here is byte-for-byte the app's, in-band and
+mid-session on the same transport, and it does not change the rate; the app's
+does. Streaming is correct either way and the cost is bandwidth, which matters
+on a metered or congested link.
+
 ## Local (LAN) control and account ownership
 
 Local control over the devices' TCP:10000 channel - both the light/plug protocol

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

@@ -35,6 +35,33 @@ 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.
 
+## Known characteristics
+
+Two behaviours that are measured, understood as far as the evidence allows, and
+not going to change in this release. Neither is a fault to report.
+
+**Recorded video is retrievable only from cloud storage.** Whether a camera
+records to the cloud or to its own SD card is per-camera, not per-model, and the
+device reports it as `IsSupportPlayback`. This library retrieves cloud
+recordings (`async_get_cloud_recordings`, `async_open_cloud_playback`) and has
+no SD-card equivalent, so a camera storing to a card records normally and
+nothing here can play it back. On the reference fleet that is four of seven
+cameras. The vendor's own commands for it are identified but their responses
+have never been decoded; see `docs/ROAD-TO-1.0.md` item 6.
+
+**The A001064 (PTZ) streams at roughly 2.2 Mbps, about 24% above the vendor
+app.** Measured from a capture of the app on the same camera: it takes about
+1796 Kbps on HD and about 866 Kbps on SD. An earlier version of this note
+repeated a figure of 225-500 Kbps for the app - that was never measured here,
+and the capture contradicts it at both quality settings.
+
+So the practical difference is a quarter more bandwidth at equivalent quality,
+plus a roughly 2:1 saving that the app's SD control achieves and this library's
+does not. The command sent here is byte-for-byte the app's, in-band and
+mid-session on the same transport, and it does not change the rate; the app's
+does. Streaming is correct either way and the cost is bandwidth, which matters
+on a metered or congested link.
+
 ## Local (LAN) control and account ownership
 
 Local control over the devices' TCP:10000 channel - both the light/plug protocol

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

@@ -2391,6 +2391,88 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         )
         return None
 
+    async def async_get_recent_recordings(self, total: int = 10) -> "List[dict]":
+        """The camera's most recent cloud event recordings.
+
+        A second listing API, and the one the vendor app actually uses on its
+        event page. Captured 2026-04-05:
+
+            POST /api/ipc/playback/getRecentEventRecordingList
+                 {"deviceIds": [...], "total": 3}
+
+        **Both listings work; the zeros were the account** (measured
+        2026-08-11). Every fleet run had reported zero events from every camera
+        through this call AND through `async_get_cloud_recordings`, which read
+        as two broken listings. On the OWNER account, on the same fleet, ninety
+        minutes after a run that reported zero: this call returns the full count
+        it asks for on six of seven cameras, and the range query returns a full
+        first page against server totals of 121-1517 over thirty days. The
+        seventh camera has no events by any method.
+
+        The fleet runs use a shared-home member. The same runs report no cloud
+        thumbnail either, and the owner/member thumbnail split was measured
+        separately on 2026-08-09 - so an account seeing neither is behaving as
+        the member, not meeting a defect. Read a zero from this method as a
+        question about the account before reading it as a fault.
+
+        Two shape differences from every other call in this class, and both
+        would break the usual handling:
+
+        * the response is a BARE JSON ARRAY, not the ``{"code": ..., "data":
+          ...}`` envelope, so there is no code to check and no ``data`` to
+          unwrap;
+        * there is no pagination - ``total`` is "how many do you want", not a
+          page size.
+
+        Each item carries ``eventUuid``, ``eventTime`` (epoch ms), ``deviceId``,
+        ``deviceName``, ``eventCodeList``, ``eventDescList`` and ``picUrl``.
+        Filtered to THIS camera, because the app asks for a whole house at once
+        and the reply is not per-device.
+        """
+        import aiohttp
+
+        body = {"deviceIds": [self.device_id], "total": max(1, int(total))}
+
+        async def _fetch():
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    f"{self._aidot_v32_base}/playback/getRecentEventRecordingList",
+                    json=body,
+                    headers=self._aidot_headers(),
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as resp:
+                    return await resp.json(content_type=None)
+
+        try:
+            data = await _fetch()
+            # The auth check reads a dict; a list is already a success here.
+            if isinstance(data, dict):
+                if self._is_auth_error(data) and await self._async_refresh_auth_token():
+                    data = await _fetch()
+            if isinstance(data, dict):
+                # An envelope means an error, since success is a bare array.
+                _LOGGER.warning(
+                    "getRecentEventRecordingList code=%s msg=%s for %s",
+                    data.get("code"), data.get("desc") or data.get("msg"),
+                    self.device_id,
+                )
+                return []
+            if not isinstance(data, list):
+                return []
+            mine = [e for e in data
+                    if isinstance(e, dict)
+                    and e.get("deviceId") in (None, self.device_id)]
+            _LOGGER.info(
+                "getRecentEventRecordingList for %s: %d of %d event(s)",
+                self.device_id, len(mine), len(data),
+            )
+            return mine
+        except Exception as exc:
+            _LOGGER.warning(
+                "getRecentEventRecordingList failed for %s: %s",
+                self.device_id, exc)
+            return []
+
     async def async_get_cloud_recordings(
         self,
         start_ts: int,
@@ -2403,6 +2485,14 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
 
         start_ts / end_ts: Unix timestamps in milliseconds.
         page: 1-indexed page number (the server uses 1-based pagination).
+        The server caps a page at 10 items whatever ``page_size`` says -
+        measured 2026-08-11 across seven cameras, and the vendor's own client
+        hard-overwrites the field to 10 (5 for a multi-device request), so it
+        is the server's rule rather than a quirk of one account. A caller that
+        asks for 30 gets 10 and no indication that it was truncated, which is
+        how the Home Assistant browser came to show 10 events out of 1517.
+        Page; do not raise ``page_size``. ``data.total`` in the reply is the
+        true count for the window, and is correct even on a one-item page.
         Returns list of dicts from the server (each has eventUuid, eventDesc, picUrl, etc.).
 
         Uses /api/ipc/playback/eventRecordingList (confirmed from EventListRepos.java).
@@ -2456,6 +2546,106 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             )
             return []
 
+    async def async_count_cloud_recordings(
+        self, start_ts: int, end_ts: int
+    ) -> Optional[int]:
+        """How many cloud events a window holds, in one request.
+
+        The listing endpoint reports the window's true ``total`` alongside
+        whatever page it serves, and that total is correct even on a one-item
+        page - measured 2026-08-11 across seven cameras. So a count costs one
+        request, where counting by paging costs one per ten events: a day
+        holding 1517 events is 152 requests, and a seven-day view that counts
+        by paging fires hundreds every time it is opened.
+
+        Returns None when the call fails. A caller must not read that as zero -
+        "the server did not answer" and "the window is empty" lead to opposite
+        conclusions in a UI, and collapsing them is a defect this project has
+        had to fix before.
+        """
+        import aiohttp
+
+        _body = {
+            "deviceIds": [self.device_id],
+            "pageNum":   1,
+            "pageSize":  1,
+            "recordSta": start_ts,
+            "recordEnd": end_ts,
+        }
+
+        async def _fetch():
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    f"{self._aidot_v32_base}/playback/eventRecordingList",
+                    json=_body,
+                    headers=self._aidot_headers(),
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as resp:
+                    return await resp.json(content_type=None)
+
+        try:
+            body = await _fetch()
+            if self._is_auth_error(body) and await self._async_refresh_auth_token():
+                body = await _fetch()
+            if not isinstance(body, dict) or body.get("code") != 200:
+                _LOGGER.debug(
+                    "eventRecordingList count for %s: %s", self.device_id, body)
+                return None
+            total = (body.get("data") or {}).get("total")
+            return int(total) if isinstance(total, int) else None
+        except Exception as exc:
+            _LOGGER.debug(
+                "eventRecordingList count failed for %s: %s", self.device_id, exc)
+            return None
+
+    async def async_get_cloud_plan(self) -> Optional[dict]:
+        """The camera's cloud recording subscription, or None.
+
+        Answers the question an empty event list cannot: whether there are no
+        events, or no longer a plan under which events would be kept. Measured
+        2026-08-11 on seven cameras - an active plan reads
+
+            {"packageName": "AI Protection ", "packageType": 1,
+             "subscribeStatus": 1, "startTime": <ms>, "endTime": <ms>,
+             "expiredDays": 15, "videoLength": 60}
+
+        Times are epoch milliseconds. ``videoLength`` is the clip length in
+        seconds.
+
+        Returns None on any failure rather than an empty dict: the caller's
+        question is "is there a plan", and {} answers it wrong.
+
+        Source: the vendor app's own JS bundle -
+        GET /api/ipc/recordPlanController/getPackageInfoByDevId?deviceId=
+        """
+        import aiohttp
+
+        async def _fetch():
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    f"{self._aidot_v32_base}/recordPlanController"
+                    "/getPackageInfoByDevId",
+                    params={"deviceId": self.device_id},
+                    headers=self._aidot_headers(),
+                    timeout=aiohttp.ClientTimeout(total=15),
+                ) as resp:
+                    return await resp.json(content_type=None)
+
+        try:
+            body = await _fetch()
+            if self._is_auth_error(body) and await self._async_refresh_auth_token():
+                body = await _fetch()
+            if not isinstance(body, dict) or body.get("code") != 200:
+                _LOGGER.debug(
+                    "getPackageInfoByDevId for %s: %s", self.device_id, body)
+                return None
+            data = body.get("data")
+            return data if isinstance(data, dict) and data else None
+        except Exception as exc:
+            _LOGGER.debug(
+                "getPackageInfoByDevId failed for %s: %s", self.device_id, exc)
+            return None
+
     async def async_get_event_video_media(
         self, event_uuid: str
     ) -> Optional[tuple[str, str]]:
@@ -2465,6 +2655,14 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         most browsers handle direct MP4 more reliably than HLS with signed CDN
         segments.  Falls back to whatever is available.
 
+        **That preference has never once been exercised.** Measured 2026-08-11
+        on the owner account, three cameras across three model families
+        (A001064, A001513, A000088): every reply carried exactly ONE entry, and
+        it was type 2. So playback here is HLS in practice, and anything built
+        on it should be designed for HLS rather than for the MP4 this docstring
+        would lead a reader to expect. The branch is kept because it costs
+        nothing and the field exists in the app's own decoder.
+
         From CloudPlaybackFragment.java / EventListRepos.java:
           POST /api/ipc/playback/getEventVideoUrl
           body: {deviceId, eventList: [{eventUuid}]}
@@ -3477,6 +3675,22 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     rtsp_push_url=self._keepalive_rtsp_url,
                     timeout=(_FAST_OPEN_TIMEOUT if _use_fast else 120.0),
                     reuse_peer_id=_loop_peer_id,
+                    # Ask for talk so THIS session can carry it. async_speak
+                    # reuses _stream_session only when it is talk-capable, and
+                    # an SDES session that did not ask never gets a return audio
+                    # track - so without this every press-to-talk opened a
+                    # second camera session alongside the live view, and the
+                    # camera holds a viewer slot for about 120 s after one ends.
+                    #
+                    # This changes the SDP offer on the path every SDES live
+                    # view takes, which is the kind of change that has caused
+                    # fleet-wide blackouts here, so it rests on evidence rather
+                    # than reasoning: the release harness has opened all seven
+                    # cameras talk-capable across three fleet runs with no
+                    # streaming regression. The flag reaches only the offer
+                    # (audio sendrecv + a=ssrc) and the shared talk state; it
+                    # does not touch the rtsp_push branch this loop uses.
+                    talk=True,
                 )
             except asyncio.CancelledError:
                 self._fast_attempt_override = None

python_aidot_cameras-1.0.0b4/aidot_cameras/camera/sd_events.py

@@ -0,0 +1,134 @@
+"""Decode the camera's recording-list reply (``LISTEVENT_RESP``, 0x319).
+
+Written from the vendor client's own decoder rather than from a capture, so it
+exists before any camera here has answered. What is CONFIRMED from
+``KVSWebRTCChannel``'s 0x319 handler:
+
+  * the reply is matched by the SEQUENCE NUMBER of the request, not by the
+    command alone - the handler's first act is ``if getListSeq != seq: return``;
+  * a four-byte little-endian value is assembled and named ``listEventTotalTime``
+    (its name says time, not count, and this module does not pretend otherwise);
+  * a single byte is read as ``listEventEndFlag`` - the reply is PAGED, and a
+    caller that stops at the first packet gets a truncated list;
+  * a single byte is read as ``listEventCount`` - how many records this packet
+    carries;
+  * records are **twelve bytes each**, copied out with an explicit
+    ``arraycopy(..., 12)``, and each begins with a two-byte year read via
+    ``byteToShort`` - an ``STimeDay``.
+
+**The header is now measured, not inferred (2026-08-11, run 31497241870).** The
+first version of this module used the published TUTK layout - two STimeDays then
+the counters, 24 bytes - and refused to decode the real replies because they
+were shorter than that. Refusing was correct, and it is how the true layout came
+back readable instead of being forced into the wrong one.
+
+Two live replies, and a 12-byte header fits both exactly:
+
+    HASLISTEVENT_RESP  00000000 01000000 0001a800  + 168 bytes
+    LISTEVENT_RESP     00000000 01000000 00010000  + 0 bytes
+
+    channel  uint32 LE   total  uint32 LE   index  end_flag  count  reserved
+
+`count` equals the body length in both - 168 and 0. And 168 is exactly the
+7-day range that was requested, one byte per hour, which is what HASLISTEVENT
+means: a per-hour occupancy map rather than a list. LISTEVENT carries 12-byte
+records in the same body.
+"""
+import struct
+from typing import List, NamedTuple, Optional
+
+#: One record. The size is confirmed from the vendor's own arraycopy.
+EVENT_RECORD_LEN = 12
+
+#: Measured from two live replies, not taken from the published struct - the
+#: published one is 24 bytes and neither reply is that long.
+_HEADER_LEN = 12
+
+
+class SdEvent(NamedTuple):
+    """One recording the camera says it holds."""
+
+    #: UTC, from the record's STimeDay.
+    year: int
+    month: int
+    day: int
+    hour: int
+    minute: int
+    second: int
+    channel: int
+    event: int
+    status: int
+
+    def isoformat(self) -> str:
+        return (f"{self.year:04d}-{self.month:02d}-{self.day:02d}"
+                f"T{self.hour:02d}:{self.minute:02d}:{self.second:02d}Z")
+
+
+class SdEventPage(NamedTuple):
+    """One packet of the paged reply.
+
+    ``end_flag`` is why this is a page and not a list: the camera answers a
+    range in several packets and a caller that reads only the first silently
+    truncates the recording list. Nothing here hides that.
+    """
+
+    events: List[SdEvent]
+    channel: int
+    total: int
+    #: Named page_index / record_count, not index / count: a NamedTuple field
+    #: called `index` or `count` shadows tuple.index() and tuple.count(), so
+    #: `page.count` would stop being callable and read as a number instead.
+    page_index: int
+    end_flag: int
+    record_count: int
+    #: True when the payload length matches the count the header declared.
+    consistent: bool
+    #: Bytes left over after the declared records - non-zero means the layout
+    #: read here is wrong, and says so rather than dropping them.
+    trailing: int
+
+
+def _stimeday(buf: bytes, off: int) -> tuple:
+    year, month, day, _wday, hour, minute, second = struct.unpack_from(
+        "<HBBBBBB", buf, off)
+    return year, month, day, hour, minute, second
+
+
+def decode_event_record(buf: bytes, off: int = 0) -> SdEvent:
+    """One 12-byte record: an STimeDay then channel, event, status, reserved."""
+    year, month, day, hour, minute, second = _stimeday(buf, off)
+    channel, event, status = struct.unpack_from("<BBB", buf, off + 8)
+    return SdEvent(year, month, day, hour, minute, second,
+                   channel, event, status)
+
+
+def decode_list_event_response(payload: bytes) -> Optional[SdEventPage]:
+    """Decode a 0x319 payload, or None if it cannot be one.
+
+    None rather than an exception or a half-filled result: this runs against a
+    reply nobody has seen yet, and "this does not fit" is the answer that keeps
+    the next person honest.
+    """
+    if payload is None or len(payload) < _HEADER_LEN:
+        return None
+    channel, total = struct.unpack_from("<II", payload, 0)
+    index, end_flag, count, _reserved = struct.unpack_from("<BBBB", payload, 8)
+    body = payload[_HEADER_LEN:]
+    usable = len(body) // EVENT_RECORD_LEN
+    # `count` is a BYTE count on HASLISTEVENT (one byte per hour) and a RECORD
+    # count on LISTEVENT. Only the record reading is meaningful here, so the
+    # number of records decoded is bounded by what the body can actually hold
+    # rather than by what the header claims.
+    take = usable
+    events = [decode_event_record(body, i * EVENT_RECORD_LEN)
+              for i in range(take)]
+    return SdEventPage(
+        events=events,
+        channel=channel,
+        total=total,
+        page_index=index,
+        end_flag=end_flag,
+        record_count=count,
+        consistent=(count == len(body)),
+        trailing=len(body) - usable * EVENT_RECORD_LEN,
+    )