python-aidot-cameras 0.7.17__tar.gz → 0.7.19__tar.gz

{python_aidot_cameras-0.7.17/src/python_aidot_cameras.egg-info → python_aidot_cameras-0.7.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.7.17
+Version: 0.7.19
 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

{python_aidot_cameras-0.7.17 → python_aidot_cameras-0.7.19}/pyproject.toml

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

{python_aidot_cameras-0.7.17 → python_aidot_cameras-0.7.19}/src/aidot/camera/client.py

@@ -55,6 +55,9 @@ from .protocol import (  # split into protocol.py; re-imported for use + back-co
     _save_sprop,
     _inject_sprop,
     _sdes_serve_port,
+    _ServeRelay,
+    _rewrite_serve_port,
+    _grab_free_port,
     _tcp_table_has_established_on_port,
     _idle_release_due,
     _dtls_av_mux_run,
@@ -502,6 +505,12 @@ class CameraMixin(_CameraControlsMixin):
         # camera.stream_source() can wait and hand HA a ready URL (avoids HA's
         # ~40s connection-refused retry gap on cold start).
         self._serve_ready: "asyncio.Event" = asyncio.Event()
+        # Cold-start serve-port relay (holds the public port connectable through
+        # the handshake so an eager go2rtc pull waits instead of being refused).
+        self._serve_relay: "Optional[_ServeRelay]" = None
+        # Cold-start instrumentation: monotonic at the start of an open, so any
+        # thread (signaling, bridge, serve) can log elapsed-ms phase markers.
+        self._cold_open_t0: "Optional[float]" = None
         # Motion/event polling (cloud event list). NOTE: the camera does NOT push motion
         # to a passive MQTT subscriber - alarmType is only emitted during an active live
         # view (decompiled NewLiveFragment) - so real-time-ish motion for HA comes from
@@ -1939,6 +1948,8 @@ class CameraMixin(_CameraControlsMixin):
         sdes_audio: Optional[bool] = None,
         go2rtc_url: Optional[str] = None,
         live_stream_param: Optional[bool] = None,
+        serve_relay: Optional[bool] = None,
+        stream_idle_s: Optional[float] = None,
     ) -> None:
         """Start a persistent stream that keeps the camera session alive.
 
@@ -1961,6 +1972,20 @@ class CameraMixin(_CameraControlsMixin):
         ``AIDOT_LIVESTREAM_PARAM`` env var, so an integration on HA OS (no env vars)
         can still disable it per camera.
 
+        ``serve_relay`` toggles the cold-start serve-port relay (holds the public
+        serve port connectable through the WebRTC handshake so an eager go2rtc
+        pull waits instead of getting connection-refused).  Overrides the
+        ``AIDOT_SERVE_RELAY`` env var (default on); set False to serve ffmpeg
+        directly on the public port (the pre-0.7.18 behaviour).
+
+        ``stream_idle_s`` sets the no-viewer idle-release window in seconds,
+        overriding the ``AIDOT_STREAM_IDLE_S`` env default (120).  ``0`` (or
+        negative) keeps the warm WebRTC session forever so re-views are instant
+        (app-like) - sensible for mains cameras (no battery cost), but it holds a
+        concurrent-stream slot for the camera's lifetime, so don't pin more
+        cameras than ``AIDOT_MAX_CONCURRENT_STREAMS`` allows.  Leave None for
+        battery cameras (motion-prewarm + idle-release preserves battery).
+
         Safe to call multiple times - does nothing if already running.
         """
         if fast_connect is not None:
@@ -1969,6 +1994,10 @@ class CameraMixin(_CameraControlsMixin):
             self._sdes_audio_opt = sdes_audio
         if live_stream_param is not None:
             self._live_stream_param_opt = live_stream_param
+        if serve_relay is not None:
+            self._serve_relay_opt = serve_relay
+        if stream_idle_s is not None:
+            self._stream_idle_opt = stream_idle_s
         if self._stream_task is not None and not self._stream_task.done():
             return
         self._keepalive_rtsp_url = rtsp_push_url
@@ -2154,6 +2183,21 @@ class CameraMixin(_CameraControlsMixin):
         return found if read_any else None
 
     async def _sdes_keepalive_loop(self) -> None:
+        """Keep the cold-start serve relay alive around the SDES keepalive loop.
+
+        The relay holds the public serve port connectable through every (re)open
+        so an eager go2rtc pull waits instead of getting connection-refused while
+        the SDES handshake runs (the same race fixed for the DTLS serve)."""
+        self._serve_relay = self._maybe_start_serve_relay(self._keepalive_rtsp_url)
+        try:
+            await self._sdes_keepalive_loop_inner()
+        finally:
+            _relay = self._serve_relay
+            self._serve_relay = None
+            if _relay is not None:
+                _relay.close()
+
+    async def _sdes_keepalive_loop_inner(self) -> None:
         """Background task: keep SDES stream alive; push to go2rtc via RTSP."""
         _MIN_DELAY = 10.0
         _MAX_DELAY = 300.0
@@ -2164,6 +2208,10 @@ class CameraMixin(_CameraControlsMixin):
         _pacer = ReconnectPacer(_MIN_DELAY, _MAX_DELAY)
 
         while self._streaming_active:
+            if self._serve_relay is not None:
+                # Clear any stale backend from a prior session; the open below
+                # points the relay at this session's fresh internal ffmpeg port.
+                self._serve_relay.set_backend(None)
             try:
                 session = await self.async_open_webrtc_stream(
                     rtsp_push_url=self._keepalive_rtsp_url,
@@ -2202,8 +2250,10 @@ class CameraMixin(_CameraControlsMixin):
             # window as DTLS; the next view re-runs camera.stream_source().  Fail
             # safe: unknown (non-Linux /proc) never releases.  Escape hatch:
             # AIDOT_SDES_IDLE_RELEASE=0.
-            _idle_on = os.environ.get("AIDOT_SDES_IDLE_RELEASE", "1") != "0"
-            _idle_secs = float(os.environ.get("AIDOT_STREAM_IDLE_S", "120"))
+            # stream_idle_s / AIDOT_STREAM_IDLE_S override; <= 0 = never release.
+            _idle_secs = self._resolve_idle_secs()
+            _idle_on = (os.environ.get("AIDOT_SDES_IDLE_RELEASE", "1") != "0"
+                        and _idle_secs > 0)
             _serve_port = _sdes_serve_port(self._keepalive_rtsp_url)
             _last_consumer = _started_at  # grace: count idle from session open
             try:
@@ -2446,6 +2496,70 @@ class CameraMixin(_CameraControlsMixin):
                 got_a = self._install_encoded_tap(_r, aq, False)
         return got_v
 
+    def _cold_phase(self, label: str) -> None:
+        """Log elapsed-ms since the open began (cold-start instrumentation).
+
+        Defensive + best-effort: never raises, no-op if no open is in flight.
+        Emits a single greppable INFO line per phase so a cold connect's timeline
+        (open -> webrtcReq -> first-media -> serving) can be measured without a
+        debugger or ad-hoc log scraping.  Grep ``cold-start[``."""
+        try:
+            t0 = self._cold_open_t0
+            if t0 is None:
+                return
+            _LOGGER.info(
+                "cold-start[%s] %s +%dms",
+                self.device_id, label, int((time.monotonic() - t0) * 1000),
+            )
+        except Exception:
+            pass
+
+    def _resolve_idle_secs(self) -> float:
+        """Serve idle-release window (seconds). A per-camera ``stream_idle_s``
+        (set via start_keepalive) overrides the ``AIDOT_STREAM_IDLE_S`` env
+        default of 120 s.  <= 0 means *never* idle-release (keep the warm session
+        for instant re-views — sensible for mains cameras, which have no battery
+        cost; note it holds a concurrent-stream slot for the camera's lifetime)."""
+        opt = getattr(self, "_stream_idle_opt", None)
+        if opt is not None:
+            return float(opt)
+        try:
+            return float(os.environ.get("AIDOT_STREAM_IDLE_S", "120"))
+        except (TypeError, ValueError):
+            return 120.0
+
+    def _maybe_start_serve_relay(self, serve_url: Optional[str]) -> "Optional[_ServeRelay]":
+        """Hold the public serve port via a _ServeRelay so an eager go2rtc pull
+        connects-and-waits instead of hitting ECONNREFUSED during the ~16-25s
+        cold handshake (ffmpeg only binds its -listen socket after input frames).
+
+        Returns the started relay, or None when disabled / not an http serve /
+        the bind fails - in which case the caller serves ffmpeg directly on the
+        public port (the pre-relay behaviour, so a bind clash never breaks
+        streaming)."""
+        if not (serve_url and serve_url.startswith("http")):
+            return None
+        opt = getattr(self, "_serve_relay_opt", None)
+        if opt is None:
+            opt = os.environ.get("AIDOT_SERVE_RELAY", "1") != "0"
+        if not opt:
+            return None
+        port = _sdes_serve_port(serve_url)
+        if port is None:
+            return None
+        relay = _ServeRelay(port)
+        try:
+            relay.start()
+        except OSError as exc:
+            _LOGGER.warning(
+                "serve relay: bind :%s failed (%s) - serving ffmpeg directly",
+                port, exc,
+            )
+            return None
+        _LOGGER.debug(
+            "serve relay: holding public port :%s for %s", port, self.device_id)
+        return relay
+
     async def _dtls_serve_loop(self) -> None:
         """Acquire a concurrent-stream slot, then run the serve loop.
 
@@ -2460,9 +2574,14 @@ class CameraMixin(_CameraControlsMixin):
                 self.device_id,
             )
         await slots.acquire()
+        self._serve_relay = self._maybe_start_serve_relay(self._keepalive_rtsp_url)
         try:
             await self._dtls_serve_loop_inner()
         finally:
+            _relay = self._serve_relay
+            self._serve_relay = None
+            if _relay is not None:
+                _relay.close()
             slots.release()
 
     async def _dtls_serve_loop_inner(self) -> None:
@@ -2575,7 +2694,9 @@ class CameraMixin(_CameraControlsMixin):
             # Must exceed HA's stream-worker reconnect interval (~40s) or the serve
             # is torn down between a viewer's retries -> "Connection refused". 120s
             # survives several retries while still releasing an unviewed camera.
-            idle_secs = float(os.environ.get("AIDOT_STREAM_IDLE_S", "120"))
+            # stream_idle_s / AIDOT_STREAM_IDLE_S override; <= 0 = never release
+            # (keep warm for instant re-views; mains cameras only - see P1).
+            idle_secs = self._resolve_idle_secs()
             proc = wfile = stop_flag = mux_thread = None
             cancelled = idle_release = False
             try:
@@ -2590,12 +2711,24 @@ class CameraMixin(_CameraControlsMixin):
                         except _queue.Empty:
                             pass
                     await self._send_video_pli(pc)  # request a clean keyframe
+                    # With the relay holding the public port, ffmpeg listens on a
+                    # fresh internal port each cycle and the relay splices to it;
+                    # without it, ffmpeg owns the public port directly (old path).
+                    _relay = self._serve_relay
+                    if _relay is not None:
+                        _ff_port = _grab_free_port()
+                        _ff_url = _rewrite_serve_port(serve_url, _ff_port)
+                    else:
+                        _ff_port = None
+                        _ff_url = serve_url
                     rfd, wfd = os.pipe()
-                    proc = await self._spawn_dtls_serve_ffmpeg(serve_url, rfd)
+                    proc = await self._spawn_dtls_serve_ffmpeg(_ff_url, rfd)
                     os.close(rfd)
                     if proc is None:
                         os.close(wfd)
                         break
+                    if _relay is not None:
+                        _relay.set_backend(_ff_port)
                     wfile = os.fdopen(wfd, "wb", buffering=0)
                     progress = [loop.time()]
                     stop_flag = _threading.Event()
@@ -2622,6 +2755,7 @@ class CameraMixin(_CameraControlsMixin):
                         # client and tear down before go2rtc connects.)
                         await asyncio.sleep(0.3)
                         self._serve_ready.set()
+                        self._cold_phase("serving (dtls)")
                     # Periodic keyframe request shortens the camera's GOP so HA's
                     # HLS segmenter (which cuts on keyframes) produces short
                     # segments -> far less player buffering (the ~20s HLS lag is
@@ -2639,8 +2773,9 @@ class CameraMixin(_CameraControlsMixin):
                             await self._send_video_pli(pc)
                             _last_gop_pli = loop.time()
                         # No consumer -> the pipe fills, the mux blocks, progress
-                        # goes stale.  A real viewer keeps it fresh.
-                        if loop.time() - progress[0] > idle_secs:
+                        # goes stale.  A real viewer keeps it fresh.  idle_secs<=0
+                        # disables release entirely (keep warm for instant views).
+                        if idle_secs > 0 and loop.time() - progress[0] > idle_secs:
                             idle_release = True
                             break
                     # Tear down this ffmpeg+mux cycle before the next.
@@ -2652,6 +2787,8 @@ class CameraMixin(_CameraControlsMixin):
                     wfile = None
                     mux_thread.join(timeout=2.0)
                     mux_thread = stop_flag = None
+                    if _relay is not None:
+                        _relay.set_backend(None)  # no backend until next ffmpeg
                     _terminate_proc(proc)
                     proc = None
                     if idle_release:
@@ -3151,6 +3288,10 @@ class CameraMixin(_CameraControlsMixin):
         """
         import queue as _q_mod
 
+        # Cold-start instrumentation: stamp t0 so phase markers below (and in the
+        # bridge/serve threads) log elapsed-ms.  Grep ``cold-start[``.
+        self._cold_open_t0 = time.monotonic()
+
         use_sdes = force_sdes if force_sdes is not None else self.is_sdes_camera
 
         # Battery cameras must have their live-stream session provisioned by the
@@ -4827,6 +4968,7 @@ class CameraMixin(_CameraControlsMixin):
             },
         })
         outgoing_q.put_nowait((webrtc_req_topic, webrtc_req_payload))
+        self._cold_phase("webrtcReq")
         _status(f"webrtcReq sent  peerid={peer_id}"
                 f"  IceServerList×{len(_ice_server_list)}"
                 f"  payload={len(webrtc_req_payload)}B")
@@ -8319,9 +8461,25 @@ class CameraMixin(_CameraControlsMixin):
                     # on the camera's own GOP).  We can't decode here to detect the
                     # first keyframe, so we time-box the burst and keep a slow
                     # safety PLI in case the camera's GOP is long.
-                    _PLI_BURST_N    = 3       # 5 s-spaced startup PLIs (t≈0,5,10)
+                    # P2: front-load the burst so the first decodable IDR arrives
+                    # sooner on a cold open.  Was 3 PLIs at a flat 5 s (first IDR
+                    # up to ~10 s); now a denser early ramp, then the same 30 s
+                    # safety PLI.  AIDOT_SDES_PLI_GAPS overrides the early gaps
+                    # (comma-sep seconds; e.g. "5,5,5" restores the old cadence).
+                    _pli_gaps = getattr(_bridge_fn, '_pli_gaps', None)
+                    if _pli_gaps is None:
+                        try:
+                            _pli_gaps = tuple(
+                                float(_x) for _x in os.environ.get(
+                                    "AIDOT_SDES_PLI_GAPS", "0,1.5,2,3").split(",")
+                                if _x.strip()
+                            ) or (0.0, 1.5, 2.0, 3.0)
+                        except ValueError:
+                            _pli_gaps = (0.0, 1.5, 2.0, 3.0)
+                        _bridge_fn._pli_gaps = _pli_gaps
                     _pli_done       = getattr(_bridge_fn, '_pli_count', 0)
-                    _pli_interval   = 5.0 if _pli_done < _PLI_BURST_N else 30.0
+                    _pli_interval   = (_pli_gaps[_pli_done]
+                                       if _pli_done < len(_pli_gaps) else 30.0)
                     if (hasattr(_bridge_fn, '_cam_video_ssrc')
                             and hasattr(_bridge_fn, '_cam_srtp_sock')
                             and _time_br.time() - getattr(
@@ -8370,7 +8528,7 @@ class CameraMixin(_CameraControlsMixin):
                         _bridge_fn._last_pli_ts = _time_br.time()
                         _pli_n = getattr(_bridge_fn, '_pli_count', 0) + 1
                         _bridge_fn._pli_count = _pli_n
-                        if _pli_n <= 3:
+                        if _pli_n <= len(_pli_gaps):
                             _status(
                                 f"SDES: sent RTCP PLI #{_pli_n}"
                                 f" → SSRC=0x{_pli_media_ssrc:08x}"
@@ -9249,6 +9407,7 @@ class CameraMixin(_CameraControlsMixin):
                                             _bridge_fn._srtp_rx_sess = _plsrtp_rx.Session(
                                                 policy=_rx_pol
                                             )
+                                            self._cold_phase("first-media")
                                             _status("bridge: SRTP RX session ready (cam→us)")
                                         except Exception as _srx_e:
                                             _status(f"bridge: SRTP RX init failed: {_srx_e}")
@@ -9422,6 +9581,16 @@ class CameraMixin(_CameraControlsMixin):
             )
 
         if rtsp_push_url and rtsp_push_url.startswith("http"):
+            # Cold-start relay: when the keepalive loop is holding the public
+            # serve port, point ffmpeg at a fresh internal port and let the relay
+            # splice the public port to it - so an early go2rtc pull waits through
+            # this handshake instead of being refused.  set_backend retries the
+            # dial until ffmpeg's -listen socket binds (only after input frames).
+            _relay = getattr(self, "_serve_relay", None)
+            if _relay is not None:
+                _ff_port = _grab_free_port()
+                rtsp_push_url = _rewrite_serve_port(rtsp_push_url, _ff_port)
+                _relay.set_backend(_ff_port)
             # PULL model: SERVE the decrypted stream over an HTTP-listen socket so
             # go2rtc / HA's stream integration pull it the standard way
             # (streams.add) - no go2rtc pre-registration needed.  ffmpeg -listen 1
@@ -9645,6 +9814,7 @@ class CameraMixin(_CameraControlsMixin):
             await asyncio.sleep(0.05)
 
         _bind_ms = int((time.monotonic() - _t0) * 1000)
+        self._cold_phase("serving (sdes ffmpeg bound)")
         if _bound:
             _status(
                 f"SDES ffmpeg ready - loopback audio={_lo_audio_port}"

{python_aidot_cameras-0.7.17 → python_aidot_cameras-0.7.19}/src/aidot/camera/protocol.py

@@ -12,6 +12,8 @@ import json
 import logging
 import os
 import random
+import select
+import socket
 import struct
 import tempfile
 import threading
@@ -612,6 +614,187 @@ def _sdes_serve_port(url: "Optional[str]") -> "Optional[int]":
         return None
 
 
+class _ServeRelay:
+    """Keep a public TCP serve port continuously connectable while the real
+    server (ffmpeg ``-listen 1``) comes and goes on an internal port.
+
+    Why this exists: the library advertises the public serve port to go2rtc / HA
+    the moment a view starts, but ffmpeg only binds its ``-listen`` socket AFTER
+    the ~16-25 s WebRTC handshake delivers the first frames - ffmpeg probes its
+    input before it opens any output (verified empirically: ``ffmpeg -i pipe:0
+    ... -f mpegts -listen 1`` does not bind the port until input data flows).  An
+    eager pull therefore hits ``ECONNREFUSED`` and go2rtc gives up within
+    ~200 ms, so the camera card stays blank on the first (cold) view.
+
+    This relay binds the public port up front and holds it for the whole
+    streaming session.  An early pull CONNECTS and waits; the relay keeps
+    redialing the current internal ffmpeg port (set via :meth:`set_backend`) and,
+    once ffmpeg is listening, splices bytes both ways.  The public listener
+    survives ffmpeg restarts (go2rtc reconnects), so the consumer never sees a
+    refused connection mid-session.
+    """
+
+    def __init__(self, public_port: int, *, host: str = "127.0.0.1",
+                 dial_timeout: float = 90.0, dial_interval: float = 0.1) -> None:
+        self._public_port = public_port
+        self._host = host
+        self._dial_timeout = dial_timeout
+        self._dial_interval = dial_interval
+        self._backend_port: "Optional[int]" = None
+        self._listen: "Optional[socket.socket]" = None
+        self._accept_thread: "Optional[threading.Thread]" = None
+        self._conns: "set[socket.socket]" = set()
+        self._lock = threading.Lock()
+        self._closed = threading.Event()
+
+    @property
+    def port(self) -> int:
+        """The bound public port (resolved after :meth:`start` if 0 was passed)."""
+        return self._public_port
+
+    def start(self) -> None:
+        """Bind the public port and begin accepting.  Raises OSError on bind."""
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind((self._host, self._public_port))
+        s.listen(8)
+        s.settimeout(0.5)
+        self._public_port = s.getsockname()[1]
+        self._listen = s
+        self._accept_thread = threading.Thread(
+            target=self._accept_loop,
+            name=f"serve-relay-{self._public_port}",
+            daemon=True,
+        )
+        self._accept_thread.start()
+
+    def set_backend(self, port: "Optional[int]") -> None:
+        """Point the relay at the current internal ffmpeg port (None = no backend
+        running yet; connected pulls wait for the next backend)."""
+        with self._lock:
+            self._backend_port = port
+
+    def close(self) -> None:
+        """Tear down the listener, the accept thread, and any live connections."""
+        self._closed.set()
+        try:
+            if self._listen is not None:
+                self._listen.close()
+        except OSError:
+            pass
+        with self._lock:
+            conns = list(self._conns)
+            self._conns.clear()
+        for s in conns:
+            try:
+                s.close()
+            except OSError:
+                pass
+        t = self._accept_thread
+        if t is not None:
+            t.join(timeout=2.0)
+
+    def _accept_loop(self) -> None:
+        while not self._closed.is_set():
+            try:
+                cli, _ = self._listen.accept()  # type: ignore[union-attr]
+            except TimeoutError:
+                continue
+            except OSError:
+                break
+            threading.Thread(
+                target=self._handle, args=(cli,), daemon=True
+            ).start()
+
+    def _handle(self, cli: "socket.socket") -> None:
+        with self._lock:
+            self._conns.add(cli)
+        be: "Optional[socket.socket]" = None
+        try:
+            be = self._dial_backend()
+            if be is not None:
+                self._splice(cli, be)
+        finally:
+            for s in (cli, be):
+                if s is not None:
+                    try:
+                        s.close()
+                    except OSError:
+                        pass
+            with self._lock:
+                self._conns.discard(cli)
+
+    def _dial_backend(self) -> "Optional[socket.socket]":
+        """Block until the backend is set + connectable (or timeout / close)."""
+        deadline = time.monotonic() + self._dial_timeout
+        while not self._closed.is_set() and time.monotonic() < deadline:
+            with self._lock:
+                port = self._backend_port
+            if port:
+                try:
+                    return socket.create_connection(
+                        (self._host, port), timeout=2.0)
+                except OSError:
+                    pass
+            time.sleep(self._dial_interval)
+        return None
+
+    def _splice(self, a: "socket.socket", b: "socket.socket") -> None:
+        a.setblocking(True)
+        b.setblocking(True)
+        socks = [a, b]
+        while not self._closed.is_set():
+            try:
+                r, _, x = select.select(socks, [], socks, 1.0)
+            except (OSError, ValueError):
+                return
+            if x:
+                return
+            for s in r:
+                peer = b if s is a else a
+                try:
+                    data = s.recv(65536)
+                except OSError:
+                    return
+                if not data:
+                    return
+                try:
+                    peer.sendall(data)
+                except OSError:
+                    return
+
+
+def _rewrite_serve_port(url: "Optional[str]", new_port: int) -> "Optional[str]":
+    """Return ``url`` with its host port replaced by ``new_port``.
+
+    Used to point ffmpeg at an internal _ServeRelay backend port while the public
+    port (in the advertised URL) is held by the relay.  ``http://127.0.0.1:18989/
+    x.ts`` -> ``http://127.0.0.1:<new_port>/x.ts``.  Pure (unit-testable)."""
+    if not url:
+        return url
+    try:
+        scheme, rest = url.split("://", 1)
+        hostport, slash, path = rest.partition("/")
+        host = hostport.rsplit(":", 1)[0]
+        return f"{scheme}://{host}:{new_port}{slash}{path}"
+    except (ValueError, IndexError):
+        return url
+
+
+def _grab_free_port(host: str = "127.0.0.1") -> int:
+    """Bind an ephemeral TCP port, release it, and return the number.
+
+    There's an inherent TOCTOU window before ffmpeg rebinds it, but it's a
+    loopback-only internal port and ffmpeg's launch retries the serve cycle on
+    failure, so a lost race is self-healing."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        s.bind((host, 0))
+        return s.getsockname()[1]
+    finally:
+        s.close()
+
+
 def _tcp_table_has_established_on_port(table_text: str, port: int) -> bool:
     """True if any row in a /proc/net/tcp[6] dump is ESTABLISHED on local ``port``.
 

{python_aidot_cameras-0.7.17 → python_aidot_cameras-0.7.19/src/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.7.17
+Version: 0.7.19
 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

{python_aidot_cameras-0.7.17 → python_aidot_cameras-0.7.19}/src/python_aidot_cameras.egg-info/SOURCES.txt

@@ -47,8 +47,10 @@ tests/test_sdes_idle_release.py
 tests/test_sdes_sprop.py
 tests/test_sdes_talk.py
 tests/test_sdes_watchdog.py
+tests/test_serve_relay.py
 tests/test_speak.py
 tests/test_stream_cap.py
+tests/test_stream_idle.py
 tests/test_talk.py
 tests/test_terminal_ack.py
 tests/test_token_refresh.py

python_aidot_cameras-0.7.19/tests/test_serve_relay.py

@@ -0,0 +1,179 @@
+"""Unit tests for _ServeRelay - the cold-start port holder.
+
+The relay keeps a public serve port connectable while ffmpeg (the real
+-listen backend) is not up yet, so an eager go2rtc pull CONNECTS and waits
+instead of getting ECONNREFUSED and giving up.  These tests use real localhost
+sockets with ephemeral ports - no camera, no ffmpeg, fully deterministic.
+"""
+import os
+import socket
+import sys
+import threading
+import time
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src"))
+
+from aidot.camera.protocol import _ServeRelay, _grab_free_port, _rewrite_serve_port
+
+
+def test_rewrite_serve_port_swaps_only_the_port():
+    assert (_rewrite_serve_port("http://127.0.0.1:18989/abc.ts", 40001)
+            == "http://127.0.0.1:40001/abc.ts")
+    # Path and scheme preserved; host preserved.
+    assert (_rewrite_serve_port("http://127.0.0.1:8554/aidot_x", 9)
+            == "http://127.0.0.1:9/aidot_x")
+
+
+def test_rewrite_serve_port_handles_missing_or_malformed():
+    assert _rewrite_serve_port(None, 1) is None
+    assert _rewrite_serve_port("not a url", 1) == "not a url"
+
+
+def test_grab_free_port_returns_a_bindable_port():
+    p = _grab_free_port()
+    assert isinstance(p, int) and 1024 < p < 65536
+
+
+def _free_port():
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.bind(("127.0.0.1", 0))
+    p = s.getsockname()[1]
+    s.close()
+    return p
+
+
+class _EchoBackend:
+    """A tiny one-shot -listen-style backend: accepts one client and echoes,
+    optionally prefixing a tag so tests can tell backends apart."""
+
+    def __init__(self, tag=b""):
+        self._tag = tag
+        self._srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self._srv.bind(("127.0.0.1", 0))
+        self._srv.listen(1)
+        self.port = self._srv.getsockname()[1]
+        self._t = threading.Thread(target=self._run, daemon=True)
+        self._t.start()
+
+    def _run(self):
+        try:
+            cli, _ = self._srv.accept()
+        except OSError:
+            return
+        try:
+            cli.sendall(self._tag)
+            while True:
+                d = cli.recv(4096)
+                if not d:
+                    break
+                cli.sendall(d)
+        except OSError:
+            pass
+        finally:
+            cli.close()
+
+    def close(self):
+        try:
+            self._srv.close()
+        except OSError:
+            pass
+
+
+def test_connect_before_backend_does_not_refuse_then_flows():
+    # The core guarantee: a pull that arrives BEFORE the backend exists connects
+    # (no ECONNREFUSED) and gets data once the backend appears.
+    relay = _ServeRelay(_free_port(), dial_timeout=10.0)
+    relay.start()
+    try:
+        cli = socket.create_connection(("127.0.0.1", relay.port), timeout=2.0)
+        # Backend comes up ~now, after the client already connected.
+        be = _EchoBackend()
+        relay.set_backend(be.port)
+        cli.sendall(b"GET /x.ts HTTP/1.0\r\n\r\n")
+        cli.settimeout(5.0)
+        got = cli.recv(4096)
+        assert b"GET /x.ts" in got
+        cli.close()
+        be.close()
+    finally:
+        relay.close()
+
+
+def test_without_relay_connection_is_refused():
+    # Control: this is the bug the relay fixes - an unbound port refuses fast.
+    port = _free_port()
+    try:
+        socket.create_connection(("127.0.0.1", port), timeout=1.0)
+        assert False, "expected ConnectionRefusedError on an unbound port"
+    except ConnectionRefusedError:
+        pass
+
+
+def test_backend_swap_between_connections():
+    # After ffmpeg restarts (go2rtc reconnect) the relay redials the new backend.
+    relay = _ServeRelay(_free_port(), dial_timeout=10.0)
+    relay.start()
+    try:
+        be1 = _EchoBackend(tag=b"ONE:")
+        relay.set_backend(be1.port)
+        c1 = socket.create_connection(("127.0.0.1", relay.port), timeout=2.0)
+        c1.settimeout(5.0)
+        assert c1.recv(16).startswith(b"ONE:")
+        c1.close()
+        be1.close()
+
+        be2 = _EchoBackend(tag=b"TWO:")
+        relay.set_backend(be2.port)
+        c2 = socket.create_connection(("127.0.0.1", relay.port), timeout=2.0)
+        c2.settimeout(5.0)
+        assert c2.recv(16).startswith(b"TWO:")
+        c2.close()
+        be2.close()
+    finally:
+        relay.close()
+
+
+def test_close_frees_the_public_port():
+    port = _free_port()
+    relay = _ServeRelay(port)
+    relay.start()
+    relay.close()
+    # SO_REUSEADDR + a real close means we can rebind immediately (this is what
+    # lets ffmpeg/other consumers take the port back after teardown).
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    s.bind(("127.0.0.1", port))
+    s.close()
+
+
+def test_dial_timeout_closes_idle_client():
+    # A client that connects but whose backend never appears is dropped after
+    # the dial timeout (so it can retry) rather than hanging forever.
+    relay = _ServeRelay(_free_port(), dial_timeout=0.5, dial_interval=0.05)
+    relay.start()
+    try:
+        cli = socket.create_connection(("127.0.0.1", relay.port), timeout=2.0)
+        cli.settimeout(3.0)
+        t0 = time.monotonic()
+        got = cli.recv(16)  # blocks until relay closes the conn (EOF -> b"")
+        assert got == b""
+        assert time.monotonic() - t0 >= 0.4
+        cli.close()
+    finally:
+        relay.close()
+
+
+if __name__ == "__main__":
+    import traceback
+    _fail = 0
+    for _k, _v in sorted(globals().items()):
+        if _k.startswith("test_"):
+            try:
+                _v()
+                print(f"PASS {_k}")
+            except Exception:
+                _fail += 1
+                print(f"FAIL {_k}")
+                traceback.print_exc()
+    raise SystemExit(1 if _fail else 0)

python_aidot_cameras-0.7.19/tests/test_stream_idle.py

@@ -0,0 +1,69 @@
+"""Unit tests for _resolve_idle_secs - the serve idle-release policy (P1).
+
+The no-viewer idle window decides when a warm WebRTC session is torn down. A
+per-camera ``stream_idle_s`` (from start_keepalive) overrides AIDOT_STREAM_IDLE_S
+(default 120 s); <= 0 means never release (keep mains cameras warm for instant
+re-views). No network/camera: drives a bare instance.
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src"))
+
+import aidot.camera.client as cc
+
+_CAM = next(v for v in vars(cc).values()
+            if isinstance(v, type) and "_resolve_idle_secs" in v.__dict__)
+
+
+def _cam():
+    return _CAM.__new__(_CAM)
+
+
+def test_default_is_120_when_unset(monkeypatch):
+    monkeypatch.delenv("AIDOT_STREAM_IDLE_S", raising=False)
+    assert _cam()._resolve_idle_secs() == 120.0
+
+
+def test_env_override(monkeypatch):
+    monkeypatch.setenv("AIDOT_STREAM_IDLE_S", "300")
+    assert _cam()._resolve_idle_secs() == 300.0
+
+
+def test_kwarg_option_wins_over_env(monkeypatch):
+    monkeypatch.setenv("AIDOT_STREAM_IDLE_S", "300")
+    cam = _cam()
+    cam._stream_idle_opt = 45.0  # what start_keepalive(stream_idle_s=45) sets
+    assert cam._resolve_idle_secs() == 45.0
+
+
+def test_zero_means_never_release():
+    cam = _cam()
+    cam._stream_idle_opt = 0.0
+    # The serve loops treat <= 0 as "never release"; the resolver just returns it.
+    assert cam._resolve_idle_secs() == 0.0
+
+
+def test_bad_env_falls_back_to_120(monkeypatch):
+    monkeypatch.setenv("AIDOT_STREAM_IDLE_S", "not-a-number")
+    assert _cam()._resolve_idle_secs() == 120.0
+
+
+if __name__ == "__main__":
+    import traceback
+
+    class _MP:  # minimal monkeypatch stand-in for direct `python` runs
+        def setenv(self, k, v): os.environ[k] = v
+        def delenv(self, k, raising=False): os.environ.pop(k, None)
+
+    _fail = 0
+    for _k, _v in sorted(globals().items()):
+        if _k.startswith("test_"):
+            try:
+                _v(_MP()) if _v.__code__.co_argcount else _v()
+                print(f"PASS {_k}")
+            except Exception:
+                _fail += 1
+                print(f"FAIL {_k}")
+                traceback.print_exc()
+    raise SystemExit(1 if _fail else 0)