python-aidot-cameras 1.0.0rc62__tar.gz → 1.0.0rc63__tar.gz

{python_aidot_cameras-1.0.0rc62/python_aidot_cameras.egg-info → python_aidot_cameras-1.0.0rc63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0rc62
+Version: 1.0.0rc63
 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
@@ -129,15 +129,15 @@ the authoritative table and per-model notes.
 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 lists cloud recordings
-(`async_get_cloud_recordings`) and resolves a playable HLS URL for one
-(`async_get_event_video_media`); for a camera storing to a card it lists the
-on-device recordings (`async_get_sd_recordings`) but cannot play one back, so
-such a camera records normally and nothing here can show you the video. On the
-reference fleet that is four of seven cameras. Playback from the card is closed
-as not feasible; see `docs/CAMERAS.md`, "On-device (SD card) recordings".
+**Recorded video comes from the cloud or from the camera's own SD card.**
+Whether a camera records to the cloud or to its card is per-camera, not
+per-model, and the device reports it as `IsSupportPlayback`. This library lists
+cloud recordings (`async_get_cloud_recordings`) and resolves a playable HLS URL
+for one (`async_get_event_video_media`); for a camera storing to a card it lists
+the on-device recordings (`async_get_sd_recordings`) and plays one
+(`async_open_sd_playback`), on all three models: an SDES camera (A001064,
+A001513) serves it like a live stream, a DTLS camera (A000088) records it to a
+`.ts` file. See `docs/CAMERAS.md`, "On-device (SD card) recordings".
 
 **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
@@ -514,6 +514,22 @@ battery camera asleep, or a model without the feature -- returns `None`, and
 treating that as a set of disabled detectors would report a state the camera
 never claimed. A write refuses outright when there is no current list to echo.
 
+### Playing a recording off the SD card
+
+```python
+listing = await device_client.async_get_sd_recordings(session=live_session)
+await device_client.async_stop_streaming()  # the camera has one media slot
+session = await device_client.async_open_sd_playback(
+    listing.records[-1], output_path="/tmp/clip.ts"
+)
+await session.async_sd_seek(20)  # also async_sd_pause() / async_sd_resume()
+# ... session.stop() when done
+```
+
+The camera sends the clip in real time, from a few seconds before the
+record's listed time. On a DTLS camera (A000088) it can only be recorded to a
+`.ts` file. See `docs/CAMERAS.md`, "Playing a recording".
+
 ### WiFi and SD card
 
 ```python

{python_aidot_cameras-1.0.0rc62 → python_aidot_cameras-1.0.0rc63}/README.md

@@ -79,15 +79,15 @@ the authoritative table and per-model notes.
 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 lists cloud recordings
-(`async_get_cloud_recordings`) and resolves a playable HLS URL for one
-(`async_get_event_video_media`); for a camera storing to a card it lists the
-on-device recordings (`async_get_sd_recordings`) but cannot play one back, so
-such a camera records normally and nothing here can show you the video. On the
-reference fleet that is four of seven cameras. Playback from the card is closed
-as not feasible; see `docs/CAMERAS.md`, "On-device (SD card) recordings".
+**Recorded video comes from the cloud or from the camera's own SD card.**
+Whether a camera records to the cloud or to its card is per-camera, not
+per-model, and the device reports it as `IsSupportPlayback`. This library lists
+cloud recordings (`async_get_cloud_recordings`) and resolves a playable HLS URL
+for one (`async_get_event_video_media`); for a camera storing to a card it lists
+the on-device recordings (`async_get_sd_recordings`) and plays one
+(`async_open_sd_playback`), on all three models: an SDES camera (A001064,
+A001513) serves it like a live stream, a DTLS camera (A000088) records it to a
+`.ts` file. See `docs/CAMERAS.md`, "On-device (SD card) recordings".
 
 **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
@@ -464,6 +464,22 @@ battery camera asleep, or a model without the feature -- returns `None`, and
 treating that as a set of disabled detectors would report a state the camera
 never claimed. A write refuses outright when there is no current list to echo.
 
+### Playing a recording off the SD card
+
+```python
+listing = await device_client.async_get_sd_recordings(session=live_session)
+await device_client.async_stop_streaming()  # the camera has one media slot
+session = await device_client.async_open_sd_playback(
+    listing.records[-1], output_path="/tmp/clip.ts"
+)
+await session.async_sd_seek(20)  # also async_sd_pause() / async_sd_resume()
+# ... session.stop() when done
+```
+
+The camera sends the clip in real time, from a few seconds before the
+record's listed time. On a DTLS camera (A000088) it can only be recorded to a
+`.ts` file. See `docs/CAMERAS.md`, "Playing a recording".
+
 ### WiFi and SD card
 
 ```python

{python_aidot_cameras-1.0.0rc62 → python_aidot_cameras-1.0.0rc63}/aidot_cameras/__init__.py

@@ -37,6 +37,7 @@ from .exceptions import (
     AidotNoWebrtcAnswer,
     AidotOSError,
     AidotPlaintextMqttRefused,
+    AidotSdPlaybackUnavailable,
     AidotStreamOpenError,
     AidotUnknownRegion,
     AidotUserOrPassIncorrect,
@@ -177,6 +178,7 @@ __all__ = [
     "AidotNotLogin",
     "AidotOSError",
     "AidotPlaintextMqttRefused",
+    "AidotSdPlaybackUnavailable",
     "AidotStreamOpenError",
     "AidotUnknownRegion",
     "AidotUserOrPassIncorrect",

{python_aidot_cameras-1.0.0rc62 → python_aidot_cameras-1.0.0rc63}/aidot_cameras/_vendor/aiortc/rtcdtlstransport.py

@@ -6,7 +6,7 @@ import logging
 import os
 import traceback
 from dataclasses import dataclass, field
-from typing import Optional, Protocol, Type, TypeVar, Union
+from typing import Callable, Optional, Protocol, Type, TypeVar, Union  # aidot: Callable
 
 import pylibsrtp
 from cryptography import x509
@@ -253,6 +253,9 @@ class RtpRouter:
         self.mid_table: dict[str, RtpReceiver] = {}
         self.ssrc_table: dict[int, RtpReceiver] = {}
         self.payload_type_table: dict[int, set[RtpReceiver]] = {}
+        # aidot: optional callable shown every RTP packet before routing,
+        # routed or not - SD playback takes H265 this way (see VENDOR.md).
+        self.raw_tap: Optional[Callable[[RtpPacket], None]] = None
 
     def register_receiver(
         self,
@@ -616,6 +619,14 @@ class RTCDtlsTransport(AsyncIOEventEmitter):
             self.__log_debug("x RTP parsing failed: %s", exc)
             return
 
+        # aidot: the raw tap sees the packet whether or not it routes.
+        tap = self._rtp_router.raw_tap
+        if tap is not None:
+            try:
+                tap(packet)
+            except Exception as exc:
+                self.__log_debug("x RTP raw tap failed: %s", exc)
+
         # route RTP packet
         receiver = self._rtp_router.route_rtp(packet)
         if receiver is not None:

{python_aidot_cameras-1.0.0rc62 → python_aidot_cameras-1.0.0rc63}/aidot_cameras/camera/client.py

@@ -6,6 +6,7 @@ import logging
 from urllib.parse import urlparse
 import os
 import time
+import threading
 import asyncio
 import dataclasses
 from typing import TYPE_CHECKING, Any, Callable, List, NamedTuple, Optional, Union
@@ -61,6 +62,7 @@ from .sdes import (
 )  # re-exported (split into sdes.py); also the SDES return type
 from .controls import _CameraControlsMixin
 from .sd_listing import _CameraSdMixin
+from .sd_playback import _CameraSdPlaybackMixin
 from .webrtc_open import _WebRTCOpenMixin
 from .sdes_open import _SdesOpenMixin
 from .protocol import (  # noqa: F401 - used here and/or by the webrtc_open mixin; kept re-exported for back-compat
@@ -120,6 +122,9 @@ from .health import HealthReporter, dtls_snapshot as _dtls_snapshot
 
 _LOGGER = logging.getLogger(__name__)
 
+#: Guards every client's ``_live_dseq``; see ``_next_dseq``.
+_DSEQ_LOCK = threading.Lock()
+
 
 def _is_transient_cloud_error(exc: BaseException) -> bool:
     """True for the network failures a retry is expected to clear.
@@ -860,6 +865,7 @@ def _build_sdes_serve_cmd(
     push_video_only: bool = False,
     video_decoder: Optional[list] = None,
     input_timeout_s: Optional[int] = None,
+    keep_probe_packets: bool = False,
 ) -> list:
     """Build the ffmpeg argv for the SDES bridge serve.
 
@@ -1040,8 +1046,15 @@ def _build_sdes_serve_cmd(
             if _SERVE_ARRIVAL_TS and not max_seconds
             else []
         ),
+        # ``nobuffer`` drops what ffmpeg reads while probing the input (up to
+        # -analyzeduration / -probesize) - latency a live view does not want.
+        # A recording's opening seconds are not latency, they are the clip:
+        # at 2560x1440 H265 the probe took its first ~3 s (A001064,
+        # 2026-10-27), so SD playback keeps them (``keep_probe_packets``).
         "-fflags",
-        "+nobuffer+genpts+discardcorrupt",
+        "+genpts+discardcorrupt"
+        if keep_probe_packets
+        else "+nobuffer+genpts+discardcorrupt",
         "-analyzeduration",
         "2000000",
         "-probesize",
@@ -2428,7 +2441,11 @@ async def _sdes_keepalive_after_session(
 
 
 class CameraMixin(
-    _CameraControlsMixin, _CameraSdMixin, _WebRTCOpenMixin, _SdesOpenMixin
+    _CameraControlsMixin,
+    _CameraSdMixin,
+    _CameraSdPlaybackMixin,
+    _WebRTCOpenMixin,
+    _SdesOpenMixin,
 ):
     """All camera/streaming methods, mixed into DeviceClient via inheritance."""
 
@@ -2770,9 +2787,15 @@ class CameraMixin(
         return getattr(self, "_last_live_play_code", None) == _LIVE_PLAY_NOT_READY
 
     def _next_dseq(self) -> int:
-        """Next livePlayReq dseq (app parity: Q0() starts at 100, increments)."""
-        d = self._live_dseq
-        self._live_dseq += 1
+        """Next livePlayReq dseq (app parity: Q0() starts at 100, increments).
+
+        Taken from the SDES bridge thread (SESSION_MODE, control commands) as
+        well as the event loop (livePlayReq), so read-and-increment is one
+        locked step: a repeated seq is a SESSION_MODE the camera ignores.
+        """
+        with _DSEQ_LOCK:
+            d = self._live_dseq
+            self._live_dseq += 1
         return d
 
     def update_status_from_device(self, device: dict) -> "DeviceStatusData":
@@ -7109,6 +7132,8 @@ class CameraMixin(
         *,
         sdes: bool = False,
         device_id: "Optional[str]" = None,
+        client_class: int = 2,
+        stream: "Optional[int]" = None,
     ) -> str:
         """Generate a peerId for a WebRTC connection.
 
@@ -7191,14 +7216,27 @@ class CameraMixin(
         # smart-home classes (3, 4) that skip the camera's keepalive watchdog,
         # so this changes what we claim to be and nothing about how the session
         # is policed. Screen any future change on EACH model with a patched
-        # build - the A000088's firmware has never been disassembled.
-        # Field 2 = client class + 5 random. '2' is EN_WEBRTC_CLIENT_TYPE_WEB,
-        # what the vendor web app announces. See the note above for why this
-        # is '2' and never '0'. The tail stays random: pinning all six would
-        # make every peer id identical across opens, which is the cross-session
-        # reuse the camera dedups on.
-        rand6 = "2" + os.urandom(3).hex()[1:]
-        version = 1 if sdes else 2
+        # build.
+        #
+        # The class-0 result is explained now (firmware read 2026-10-27, the
+        # same on the A000088, A001064 and A001513): the per-viewer codec
+        # decision reads field2[0] itself and gives H265 only to class 0 or 1,
+        # and only then adds a second, H265 video transceiver. An A000088 that
+        # decides H265 sends its live video there, which the aiortc path
+        # cannot receive - the session is up and empty. SD playback needs that
+        # transceiver on a camera that records H265, so its open passes
+        # ``client_class=0``; live views keep 2.
+        #
+        # ``stream`` is field 5, which the firmware logs as StreamID (0 = main
+        # stream). The transport default it replaces is what every live open
+        # has always sent.
+        # Field 2 = client class + 5 random. The tail stays random: pinning all
+        # six would make every peer id identical across opens, which is the
+        # cross-session reuse the camera dedups on.
+        if not 0 <= client_class <= 9:
+            raise ValueError(f"client_class must be one digit, got {client_class}")
+        rand6 = str(client_class) + os.urandom(3).hex()[1:]
+        version = (1 if sdes else 2) if stream is None else stream
         return f"{session}_{rand6}_{live_type}_{stream_id}_{version}"
 
     async def async_open_webrtc_stream(

{python_aidot_cameras-1.0.0rc62 → python_aidot_cameras-1.0.0rc63}/aidot_cameras/camera/protocol.py

@@ -1788,7 +1788,15 @@ def video_pts_dts(state: dict, pts: int, slack: int) -> tuple:
 
 
 def _dtls_av_mux_run(
-    vq, aq, out_fileobj, progress, stop_flag, *, align_audio_start=False, state=None
+    vq,
+    aq,
+    out_fileobj,
+    progress,
+    stop_flag,
+    *,
+    align_audio_start=False,
+    state=None,
+    video_codec="h264",
 ) -> None:
     """Mux tapped video (H.264 copy) + audio (PCMA->AAC) to ``out_fileobj`` as
     RTP-timestamped MPEG-TS.  Runs in a worker thread; the serve's ffmpeg reads
@@ -1810,7 +1818,14 @@ def _dtls_av_mux_run(
       the serve's timing is unchanged.
     - ``state``, if given, gets ``state["failed"] = True`` when a write failed
       and the mux ended early.
+    - ``video_codec`` is the video stream's codec. None leaves it to the first
+      keyframe: a queue item may carry its codec as a fourth element
+      (``"hevc"`` from the SD playback H265 tap), and a three-element item is
+      H.264. Only with ``align_audio_start``, which writes nothing before the
+      first keyframe, so the stream can still be added then.
     """
+    if video_codec is None and not align_audio_start:
+        raise ValueError("video_codec=None needs align_audio_start")
     import time as _t
     import queue as _q
     from fractions import Fraction
@@ -1880,8 +1895,10 @@ def _dtls_av_mux_run(
     except Exception as exc:
         _LOGGER.warning("DTLS A/V mux: av.open failed: %s", exc)
         return
-    vs = out.add_stream("h264")
-    vs.time_base = Fraction(1, 90000)
+    vs = None
+    if video_codec is not None:
+        vs = out.add_stream(video_codec)
+        vs.time_base = Fraction(1, 90000)
     try:
         adec = av.CodecContext.create("pcm_alaw", "r")
         adec.sample_rate = 8000
@@ -1922,16 +1939,42 @@ def _dtls_av_mux_run(
     # ffmpeg at its input probe so it never bound its -listen port.  One dead
     # write -> exit the thread and leave the queues alone.
     mux_dead = [False]
+    vs_box = [vs]
+    vcodec_box = [video_codec]
 
     def _flush_video():
         while True:
             try:
-                data, ts, kf = vq.get_nowait()
+                item = vq.get_nowait()
             except _q.Empty:
                 break
+            data, ts, kf = item[:3]
+            _codec = item[3] if len(item) > 3 else "h264"
+            if vs_box[0] is not None and video_codec is None:
+                # Lazy mode: a camera sending both tracks must not put the
+                # other codec into this stream. Compared by the name it was
+                # added under: the stream reports its encoder (libx265).
+                if vcodec_box[0] != _codec:
+                    continue
             if not vstarted[0]:
                 if not kf:
                     continue  # begin on a keyframe so the GOP is decodable
+                if vs_box[0] is None:
+                    # The first keyframe says what the recording is.
+                    # The stream is only muxed into, but PyAV opens an
+                    # encoder for it, and x265 prints its banner straight to
+                    # stderr - into Home Assistant's log on every play.
+                    _vs = out.add_stream(
+                        _codec,
+                        options=(
+                            {"x265-params": "log-level=none"}
+                            if _codec == "hevc"
+                            else None
+                        ),
+                    )
+                    _vs.time_base = Fraction(1, 90000)
+                    vs_box[0] = _vs
+                    vcodec_box[0] = _codec
                 vstarted[0] = True
                 v0[0] = ts
             _rel = ts - v0[0]
@@ -1941,7 +1984,7 @@ def _dtls_av_mux_run(
                 # is_resent_video_frame. Dropping costs no media time.
                 continue
             pkt = av.Packet(data)
-            pkt.stream = vs
+            pkt.stream = vs_box[0]
             pkt.pts, pkt.dts = video_pts_dts(_ts_state, _rel, _slack)
             pkt.time_base = Fraction(1, 90000)
             if kf:
@@ -3166,22 +3209,50 @@ class _AvioWaiter:
     look silent.
     """
 
-    def __init__(self, router: "AvioResponseRouter", command: int) -> None:
+    def __init__(self, router: "AvioResponseRouter", command: int, match=None) -> None:
         self._router = router
         self._command = command
+        # Optional predicate on the reply: a command whose replies all share
+        # one AVIO id (RECORD_PLAYCONTROL echoes the playback command in its
+        # payload) can then have several questions out at once.
+        self._match = match
         self._future = _cfutures.Future()
 
+    def _accepts(self, resp) -> bool:
+        if self._match is None:
+            return True
+        try:
+            return bool(self._match(resp))
+        except Exception:
+            return False
+
     def cancel(self) -> None:
         """Withdraw the question - used when the command could not be sent."""
         self._router._forget(self)
 
-    async def result(self, timeout: float) -> "Optional[AvioResponse]":
+    async def result(
+        self, timeout: float, *, keep: bool = False
+    ) -> "Optional[AvioResponse]":
         """The camera's reply, or None if it did not answer within ``timeout``.
 
         None is a real answer, not an error: this firmware may not implement a
         response for every command we send, and a control call must never block
         a view while we find out.
+
+        ``keep`` leaves the question open when the wait times out, so a later
+        call still gets a reply that arrives late. For a one-off question held
+        for a session's life (the PLAY_START reply), not for a command sent
+        repeatedly, whose registrations would pile up.
         """
+        if keep and not self._future.done():
+            try:
+                # Shielded: a timed-out wait must not cancel the future the
+                # bridge thread will still set.
+                return await asyncio.wait_for(
+                    asyncio.shield(asyncio.wrap_future(self._future)), timeout
+                )
+            except TimeoutError:
+                return None
         if self._future.done():
             # A wait that timed out cancels its own wrapper, and that
             # cancellation can propagate down to this future - asking again
@@ -3223,13 +3294,16 @@ class AvioResponseRouter:
         self._lock = threading.Lock()
         self._waiting: "dict[int, list[_AvioWaiter]]" = {}
 
-    def expect(self, command: int) -> _AvioWaiter:
+    def expect(self, command: int, match=None) -> _AvioWaiter:
         """Register interest in the next response carrying ``command``.
 
+        ``match``, when given, narrows that to a response it returns True for;
+        a response no waiter accepts is not answered to anyone.
+
         Call this before sending the request: the camera can answer before the
         sender returns, and a registration made afterwards would miss the reply.
         """
-        waiter = _AvioWaiter(self, command)
+        waiter = _AvioWaiter(self, command, match)
         with self._lock:
             self._waiting.setdefault(command, []).append(waiter)
         return waiter
@@ -3248,11 +3322,15 @@ class AvioResponseRouter:
             with self._lock:
                 queue = self._waiting.get(resp.command)
                 waiter = None
-                while queue:
-                    candidate = queue.pop(0)
-                    if not candidate._future.done():
-                        waiter = candidate
-                        break
+                if queue:
+                    # Oldest first, skipping questions already settled and
+                    # any whose match turns this reply down.
+                    queue[:] = [w for w in queue if not w._future.done()]
+                    for candidate in queue:
+                        if candidate._accepts(resp):
+                            waiter = candidate
+                            queue.remove(candidate)
+                            break
                 if queue is not None and not queue:
                     self._waiting.pop(resp.command, None)
             if waiter is None:
@@ -3748,6 +3826,7 @@ class AvioRequestMixin:
         *,
         response_cmd: int,
         timeout: float = AVIO_RESPONSE_TIMEOUT_S,
+        match=None,
     ) -> "Optional[AvioResponse]":
         """Send ``cmd`` and return the camera's ``response_cmd`` reply, or None.
 
@@ -3755,7 +3834,7 @@ class AvioRequestMixin:
         not a failure: this firmware may implement a request without a response,
         and no reply at all points at the channel rather than the firmware.
         """
-        waiter = self._avio_responses.expect(response_cmd)
+        waiter = self._avio_responses.expect(response_cmd, match)
         # Registered BEFORE the send: a camera on the LAN can answer before the
         # sending call returns, and a reply that arrives with nobody listening
         # would be reported as silence.

{python_aidot_cameras-1.0.0rc62 → python_aidot_cameras-1.0.0rc63}/aidot_cameras/camera/recording.py

@@ -50,8 +50,15 @@ class TsCopyRecorder:
     video to :attr:`vq` and audio to :attr:`aq`.
     """
 
-    def __init__(self, path: str, device_id: Optional[str] = None) -> None:
+    def __init__(
+        self,
+        path: str,
+        device_id: Optional[str] = None,
+        video_codec: Optional[str] = "h264",
+    ) -> None:
         self._path = path
+        # None: the first keyframe names it (SD playback, H264 or H265).
+        self._video_codec = video_codec
         self._device_id = device_id or "?"
         self.vq: "queue.Queue" = queue.Queue(maxsize=_QUEUE_MAX)
         self.aq: "queue.Queue" = queue.Queue(maxsize=_QUEUE_MAX)
@@ -71,7 +78,11 @@ class TsCopyRecorder:
         self._thread = threading.Thread(
             target=_dtls_av_mux_run,
             args=(self.vq, self.aq, self._file, self._progress, self._stop_flag),
-            kwargs={"align_audio_start": True, "state": self._state},
+            kwargs={
+                "align_audio_start": True,
+                "state": self._state,
+                "video_codec": self._video_codec,
+            },
             name="aidot-dtls-record",
             daemon=True,
         )