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

{python_aidot_cameras-0.17.3b2/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.3b2
+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
@@ -209,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.3b2 → python_aidot_cameras-1.0.0b2}/README.md

@@ -178,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.3b2 → python_aidot_cameras-1.0.0b2}/aidot_cameras/camera/client.py

@@ -1823,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 = {}

{python_aidot_cameras-0.17.3b2 → 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.3b2 → 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

{python_aidot_cameras-0.17.3b2 → python_aidot_cameras-1.0.0b2}/aidot_cameras/camera/sdes_open.py

@@ -494,6 +494,107 @@ def _resolve_sdes_video_pt() -> Optional[int]:
     return pt if pt in _SDES_ANSWER_VIDEO_PTS else None
 
 
+#: The video codecs the SDES OFFER advertises, keyed by payload type, with the
+#: rtpmap/fmtp lines that describe each one.  Deliberately NOT reusing
+#: ``_SDES_ANSWER_VIDEO_PTS``: that tuple is what the answer template carries
+#: and what the pin is validated against, and coupling the offer's wire order to
+#: it means a later reorder of one silently reorders the other.
+_SDES_OFFER_VIDEO_CODECS = {
+    96: (
+        "a=rtpmap:96 H264/90000\r\n"
+        "a=fmtp:96 level-asymmetry-allowed=1;packetization-mode=1;"
+        "profile-level-id=42e01f\r\n"
+    ),
+    97: (
+        "a=rtpmap:97 H265/90000\r\n"
+        "a=fmtp:97 level-id=93\r\n"
+    ),
+}
+
+#: The order those codecs go on the wire today: H264 first, H265 second.  This
+#: is the shipped default and changing it changes every SDES camera's
+#: negotiation, so it is overridden per-run by env and never edited here.
+_SDES_OFFER_VIDEO_PT_ORDER = (96, 97)
+
+
+def _resolve_sdes_video_pt_order() -> tuple:
+    """EXPERIMENTAL (opt-in, default off): reorder the OFFER's video codec list.
+
+    RFC 3264 section 5.1 makes the ``m=video`` payload-type list a *preference*
+    list, most-preferred first.  The offer this module sends carries ``96 97``,
+    i.e. it already states a preference for H264 -- so the often-repeated
+    shorthand that our offer "expresses no preference" is not what the SDP says.
+    What is true is that nothing here ever *chose* that order: the line arrived
+    verbatim when this path was extracted from ``client.py`` and has never been
+    varied.
+
+    Measured on an A001064, the camera answers H264 most of the time and H265
+    occasionally for an otherwise identical request (nine and two across eleven
+    sessions one afternoon).  Read against the offer, that is a camera which
+    honours our stated first choice most of the time and disregards it some of
+    the time -- which is a reason to expect *less* of reordering than of the
+    pin, and is recorded here so nobody reads this knob as established.
+
+    Why it is worth having anyway: the efficient profile (hevc 2560x1440 at
+    ~1.1 Mbps against h264 1280x720 at 2.5-4.0 Mbps) has only ever appeared when
+    BOTH codecs are on the wire.  ``AIDOT_SDES_VIDEO_PT=97`` narrows to H265 and
+    returns no video at all, 3 of 3 rounds -- narrowing removes the option
+    rather than selecting it.  Reordering is the only untried lever that leaves
+    both codecs offered, so the camera can still fall back to H264.
+
+    Accepts a comma- or space-separated payload-type list (``97,96``, ``97``).
+    Whatever is named goes first, in the order named; every advertised codec not
+    named is appended in the default order.  So this can express a preference
+    and can never narrow the offer: the result is always a permutation of the
+    full advertised set, and an empty or entirely unusable value yields exactly
+    today's order.  Narrowing already has its own variable, and the one time it
+    was measured it cost the picture.
+
+    Unknown payload types and duplicates are dropped rather than honoured: a
+    payload type this offer does not advertise has no rtpmap to go with it, and
+    listing one on the m-line would name a codec the camera was never given the
+    parameters for.
+    """
+    raw = os.environ.get("AIDOT_SDES_VIDEO_PT_ORDER", "") or ""
+    named: list = []
+    for tok in raw.replace(",", " ").split():
+        if not tok.isdigit():
+            continue
+        pt = int(tok)
+        if pt in _SDES_OFFER_VIDEO_CODECS and pt not in named:
+            named.append(pt)
+    return tuple(named) + tuple(
+        pt for pt in _SDES_OFFER_VIDEO_PT_ORDER if pt not in named
+    )
+
+
+def _sdes_offer_video_codec_lines(order=None) -> tuple:
+    """Build the offer's video codec list and its rtpmap/fmtp block.
+
+    Returns ``(pt_list, attrs)`` where ``pt_list`` is the payload-type list for
+    the ``m=video`` line ("96 97") and ``attrs`` is the rtpmap/fmtp lines for
+    those payload types, in the same order.  Both have to move together: an
+    m-line naming a payload type whose rtpmap was left behind is an offer the
+    camera cannot act on.
+
+    ``order`` of None is today's shipped order, so the default output is
+    byte-identical to the literal this replaced.  Anything not advertised is
+    dropped, and an order that ends up empty falls back to the default -- an
+    ``m=video`` line with no payload type at all leaves the camera nothing to
+    send, which is the one outcome worse than an unpinned choice.
+    """
+    pts = tuple(
+        pt for pt in (order if order is not None else _SDES_OFFER_VIDEO_PT_ORDER)
+        if pt in _SDES_OFFER_VIDEO_CODECS
+    )
+    if not pts:
+        pts = _SDES_OFFER_VIDEO_PT_ORDER
+    return (
+        " ".join(str(pt) for pt in pts),
+        "".join(_SDES_OFFER_VIDEO_CODECS[pt] for pt in pts),
+    )
+
+
 def narrow_sdp_payload_types(sdp_text: str, keep_video=None, keep_audio=None) -> str:
     """Rewrite an SDP to advertise a single payload type per media line.
 
@@ -767,6 +868,108 @@ def _record_peer_reflexive(known, discovered, observed, is_self=None):
     return [*discovered, observed]
 
 
+#: How many distinct inbound probe sources the stall report will name. Beyond
+#: this the count alone is kept - a stall is explained by the first few sources,
+#: and an unbounded list would turn one WARNING into a wall of text.
+_MAX_PROBE_SOURCES = 6
+
+
+def _probe_source_verdict(src, turn_peer_ip, turn_peer_port, *,
+                          cam_peer, observed, known, learned):
+    """Say why one inbound STUN probe's source was, or was not, learned.
+
+    Nomination can only aim at an address, and when the camera's answer lists
+    one this host cannot route to, the only usable addresses are the ones its
+    own probes arrive from.  Two vetoes drop a relay-carried probe before it can
+    become a peer-reflexive candidate, and both are silent in the code they
+    guard, so a session that stalls for one reason is indistinguishable from a
+    session that stalled for the other.  This names them apart.
+
+    Takes the values the bridge already computed rather than re-deriving them:
+    ``cam_peer`` is ``_br_cam_peer`` (None once ``_is_self_peer_ip`` has refused
+    the XOR-PEER-ADDRESS) and ``observed`` is ``_br_obs`` (None once the
+    ``_bsrc`` fallback has refused the TURN server's own address too).  A copy
+    of the decision here would rot the first time either site changed.
+
+    ``known`` is "this address is already in the nomination set" and ``learned``
+    is "this call grew the peer-reflexive set"; without both, an address that
+    ``_record_peer_reflexive`` refused on its own policy would be reported as
+    one we are already nominating, which is the opposite of the truth.
+
+    Pure, so the classification is testable without a camera.
+    """
+    if observed:
+        if learned:
+            return "learned"
+        if known:
+            return "known"
+        # _record_peer_reflexive took it and gave nothing back: its own self-IP
+        # check, or the peer-reflexive cap.
+        return "prflx-refused"
+    if turn_peer_ip and not turn_peer_port:
+        return "vetoed-no-peer-port"
+    if turn_peer_ip and not cam_peer:
+        # _is_self_peer_ip matched the XOR-PEER-ADDRESS.
+        return "vetoed-self-ip"
+    # No usable peer address at all, and the packet came from the relay, so the
+    # _bsrc fallback had nothing to offer but the TURN server itself.
+    return "vetoed-turn-source"
+
+
+def _first_media_stall_report(device_id, waited_s, nominated,
+                              use_candidate_sent, binding_success,
+                              trigger_sent, probes, probes_dropped=0):
+    """Build the one line a first-media stall emits.
+
+    A session that never delivers a byte looks, in a log, exactly like one that
+    delivered late: the wait expires, the serve launches with unknown payload
+    types, and nothing states the reason.  The reason is knowable at that
+    moment.  Media only ever follows the AVIO LIVING trigger, that trigger is
+    armed only by an inbound STUN Binding Success Response, and that response
+    only comes back if something we nominated was reachable - so the nominated
+    set, the Binding Success count, the trigger flag and the verdict on every
+    inbound probe source are between them the whole explanation.
+
+    Addresses and counts only.  This line reaches ``home-assistant.log`` and
+    users paste that file into public issue reports.
+
+    ``probes`` is a sequence of ``(source_label, verdict)`` from
+    :func:`_probe_source_verdict`.  Pure, so the wording is testable.
+    """
+    _cands = ", ".join(f"{_ip}:{_port}" for _ip, _port in (nominated or []))
+    _probes = "; ".join(
+        f"{_where} -> {_verdict}" for _where, _verdict in (probes or [])
+    )
+    if probes_dropped:
+        _probes += f"; (+{probes_dropped} more source(s))"
+    _why = ""
+    if not binding_success:
+        _why = (
+            " No inbound STUN Binding Success arrived, so the AVIO LIVING"
+            " trigger was never armed and the camera never started sending."
+        )
+    elif not trigger_sent:
+        _why = (
+            " A Binding Success arrived and the trigger still did not go -"
+            " the trigger is not gated on anything else."
+        )
+    return (
+        "camera %s: SDES first media never arrived (%.0fs)."
+        " nominated=%s; use-candidate=%s; binding-success=%d; trigger=%s;"
+        " probes=%s.%s"
+        % (
+            device_id,
+            waited_s,
+            _cands or "none",
+            "sent" if use_candidate_sent else "not-sent",
+            binding_success,
+            "sent" if trigger_sent else "not-sent",
+            _probes or "none",
+            _why,
+        )
+    )
+
+
 def _ensure_srtp_rx_session(holder, key, build, *, on_built=None, on_error=None):
     """Return the bridge's SRTP receive session, rebuilt when ``key`` changes.
 
@@ -1380,6 +1583,13 @@ class _SdesOpenMixin:
             "spk_eligible_ts": None,  # bridge: first time SPEAKERSTART is eligible
             "stop": False,
         } if _talk_offer else None
+        # Video codec preference, expressed by m-line order (RFC 3264 5.1).
+        # Default is today's 96 97 and the bytes are identical to the literal
+        # this replaced; AIDOT_SDES_VIDEO_PT_ORDER reorders it without ever
+        # narrowing it.
+        _video_pt_order = _resolve_sdes_video_pt_order()
+        _video_pt_list, _video_codec_attrs = _sdes_offer_video_codec_lines(
+            _video_pt_order)
         sdes_offer_sdp = (
             "v=0\r\n"
             f"o=- {ts} {ts} IN IP4 {local_ip}\r\n"
@@ -1418,16 +1628,13 @@ class _SdesOpenMixin:
                 if _audio_sock in _relay_addrs else ""
             )
             # video m-section
-            + f"m=video {_offer_video_port} RTP/SAVPF 96 97\r\n"
+            + f"m=video {_offer_video_port} RTP/SAVPF {_video_pt_list}\r\n"
             f"c=IN IP4 {_offer_video_ip}\r\n"
             "a=recvonly\r\n"
             "a=mid:1\r\n"
             f"a=crypto:1 AES_CM_128_HMAC_SHA1_80 inline:{srtp_key_video}\r\n"
-            "a=rtpmap:96 H264/90000\r\n"
-            "a=fmtp:96 level-asymmetry-allowed=1;packetization-mode=1;profile-level-id=42e01f\r\n"
-            "a=rtpmap:97 H265/90000\r\n"
-            "a=fmtp:97 level-id=93\r\n"
-            "a=rtcp-mux\r\n"
+            + _video_codec_attrs
+            + "a=rtcp-mux\r\n"
             f"a=ice-ufrag:{_ufrag_v}\r\n"
             f"a=ice-pwd:{_pwd_v}\r\n"
             f"a=candidate:1 1 udp 2130706431 {local_ip} {video_port} typ host\r\n"
@@ -1460,8 +1667,21 @@ class _SdesOpenMixin:
             )
         )
 
-        # Opt-in: express a video-codec preference in the OFFER rather than
-        # advertising both 96/97 and letting the camera decide in its answer.
+        # Receipt for the codec order above, emitted only when it differs from
+        # the shipped one.  A run that cannot show the knob was applied cannot
+        # tell a result from a coincidence: an earlier attempt on this question
+        # read as a confirmed effect for two sessions before the missing receipt
+        # showed the pin had never reached the SDP at all.  Ordering happens
+        # before the pin below, so with both set the pin wins and the order is
+        # moot - which is why both lines print rather than one.
+        if _video_pt_order != _SDES_OFFER_VIDEO_PT_ORDER and _status:
+            _status(f"SDES: offer video codec order={_video_pt_list}")
+
+        # Opt-in: NARROW the OFFER to one video codec rather than advertising
+        # both 96/97 and letting the camera decide in its answer.  Distinct from
+        # the ordering above, which only states which of the two we would
+        # rather have and always leaves both on the wire; this one takes the
+        # other away, which for 97 took the video with it.
         #
         # The offer is the SDP that matters here.  Traced live 2026-08-07 with
         # every status line printed: this path sends webrtcReq carrying OUR
@@ -2864,6 +3084,17 @@ class _SdesOpenMixin:
             if not _is_self_peer_ip(cam_addr[0]):
                 _turn_send_indication(sock, cam_addr[0], cam_addr[1], _req)
 
+        # Every candidate this session actually sent USE-CANDIDATE to, in the
+        # order it was nominated.  Instrumentation only, and it exists because
+        # _bridge_uc_info cannot answer the question on the shape that stalls:
+        # on a late answer - measured at +1.3 s, missing the pre-launch snapshot
+        # - it is _nominate_from_answer_sdp below that nominates, and it neither
+        # appends to _bridge_uc_info["cands"] nor flips ["sent"].  Reporting the
+        # stall from that dict alone would print "nominated=none" on an open
+        # that did nominate, and make "the answer carried no ICE credentials"
+        # indistinguishable from "the answer carried one unroutable candidate".
+        _nominated_seen: list = []
+
         def _nominate_from_answer_sdp(sdp_text) -> int:
             """Nominate every candidate in ``sdp_text``; return how many.
 
@@ -2903,6 +3134,8 @@ class _SdesOpenMixin:
                     _audio_sock, _ufrag_a, _pwd_a, _u, _p, (_c_ip, _c_port))
                 _send_use_candidate(
                     _video_sock, _ufrag_v, _pwd_v, _u, _p, (_c_ip, _c_port))
+                if (_c_ip, _c_port) not in _nominated_seen:
+                    _nominated_seen.append((_c_ip, _c_port))
             return len(_cands)
 
         # Open the TURN relay's door for the camera BEFORE probing it.
@@ -3293,6 +3526,22 @@ class _SdesOpenMixin:
                 _s.sendto(_data, _addr)
             _br_stun_resp_count = 0
             _tutk_trigger_sent = False
+            # Instrumentation for the first-media stall report.  These four are
+            # bridge-thread locals that the main coroutine has to be able to
+            # read when the wait expires, so each is mirrored onto _bridge_fn at
+            # its write site - the same publication _sprop_done uses.  Nothing
+            # here is read by the bridge itself; they only ever describe.
+            _br_binding_success_count = 0   # inbound STUN Binding Success (0x0101)
+            _br_probe_verdicts: dict = {}   # probe source -> why it was/wasn't learned
+            # A SET, not a counter: one unrecorded source probing fifty times
+            # is one source, and a per-packet count would put a wrong number in
+            # the report for someone to reason from.
+            _br_probe_overflow: set = set()  # sources past _MAX_PROBE_SOURCES
+            _bridge_fn._tutk_trigger_sent = False
+            _bridge_fn._br_stun_resp_count = 0
+            _bridge_fn._br_binding_success_count = 0
+            _bridge_fn._br_probe_verdicts = {}
+            _bridge_fn._br_probe_overflow = 0
             _last_trigger_ts    = 0.0     # time of last AVIO LIVING send
             _trigger_bs         = None    # socket used for trigger
             _trigger_bsrc       = None    # camera addr for trigger
@@ -3799,6 +4048,49 @@ class _SdesOpenMixin:
                                     f" (not in the {len(_bridge_uc_info['cands'])}"
                                     f" advertised candidate(s)) - will nominate it"
                                 )
+                            # Record why this probe's source was, or was not,
+                            # usable.  Both refusals above are silent, and which
+                            # of them fired decides what a fix would change - so
+                            # the fact is kept here and reported once, on the
+                            # stall path, rather than logged per packet.
+                            try:
+                                _br_pv_where = f"{_bsrc[0]}:{_bsrc[1]}"
+                                if _br_turn_peer_ip:
+                                    _br_pv_where += (
+                                        f" via {_br_turn_peer_ip}"
+                                        f":{_br_turn_peer_port}"
+                                    )
+                                if _br_pv_where in _br_probe_verdicts:
+                                    pass
+                                elif len(_br_probe_verdicts) >= _MAX_PROBE_SOURCES:
+                                    _br_probe_overflow.add(_br_pv_where)
+                                    _bridge_fn._br_probe_overflow = len(
+                                        _br_probe_overflow)
+                                else:
+                                    _br_probe_verdicts[_br_pv_where] = (
+                                        _probe_source_verdict(
+                                            _bsrc,
+                                            _br_turn_peer_ip,
+                                            _br_turn_peer_port,
+                                            cam_peer=_br_cam_peer,
+                                            observed=_br_obs,
+                                            known=bool(
+                                                _br_obs is not None
+                                                and (_br_obs in _br_prflx_was
+                                                     or _br_obs in
+                                                     _bridge_uc_info["cands"])
+                                            ),
+                                            learned=(
+                                                _br_prflx_now is not _br_prflx_was
+                                            ),
+                                        )
+                                    )
+                                    # Rebind, never mutate: the reader is the
+                                    # main coroutine on another thread.
+                                    _bridge_fn._br_probe_verdicts = dict(
+                                        _br_probe_verdicts)
+                            except Exception:
+                                _LOGGER.debug("camera %s: swallowed exception in %s", getattr(self, "device_id", "?"), '_probe_source_verdict', exc_info=True)
                             try:
                                 if _br_turn_peer_ip is None and _bsrc[0] != _hp_host:
                                     _br_prefer_direct_stun[_bs] = True
@@ -3864,6 +4156,8 @@ class _SdesOpenMixin:
                                 else:
                                     _bs.sendto(_bresp, _bsrc)
                                     _br_stun_resp_count += 1
+                                    _bridge_fn._br_stun_resp_count = (
+                                        _br_stun_resp_count)
                                 # Late USE-CANDIDATE: send when answer arrived
                                 # after bridge started (empty at setup time).
                                 if not _bridge_uc_info["sent"] and _bridge_uc_info["ufrag"]:
@@ -3957,6 +4251,16 @@ class _SdesOpenMixin:
                                         f" relay path unusable"
                                     )
                                 continue
+                            # Count the inbound Binding Success BEFORE the
+                            # trigger gate below.  Counting inside it would make
+                            # this an alias for _tutk_trigger_sent and collapse
+                            # two different diagnoses - "none ever arrived" and
+                            # "one arrived and the trigger still did not go" -
+                            # into a single indistinguishable state.
+                            if _bpkt[:2] == b'\x01\x01':
+                                _br_binding_success_count += 1
+                                _bridge_fn._br_binding_success_count = (
+                                    _br_binding_success_count)
                             # STUN BindingSuccess (0x0101) from camera: ICE complete.
                             # Send AES-128-CBC encrypted SESSION_MODE_REQ (AVIO LIVING).
                             #
@@ -3970,6 +4274,7 @@ class _SdesOpenMixin:
                             if (_use_plain_rtp and not _tutk_trigger_sent
                                     and _bpkt[:2] == b'\x01\x01'):
                                 _tutk_trigger_sent = True
+                                _bridge_fn._tutk_trigger_sent = True
                                 import struct as _st_tk
                                 import random as _rand_tk
                                 _ts_ms = int(_time_br.time() * 1000)
@@ -4700,9 +5005,23 @@ class _SdesOpenMixin:
                                     if 7 in _psc and 8 in _psc:
                                         _sprop_new = _build_sprop(_psc[7], _psc[8])
                                         if _sprop_new != _load_sprop(self.device_id):
-                                            _save_sprop(self.device_id, _sprop_new)
-                                            _status("bridge: cached sprop-parameter"
+                                            # Gated on the result: two of
+                                            # _save_sprop's three outcomes write
+                                            # nothing, and this is the only line
+                                            # the sprop path ever emits.
+                                            if _save_sprop(self.device_id,
+                                                           _sprop_new):
+                                                _status(
+                                                    "bridge: cached sprop-parameter"
                                                     f"-sets for {self.device_id}")
+                                            else:
+                                                _status(
+                                                    "bridge: parameter sets NOT "
+                                                    f"cached for {self.device_id} "
+                                                    "(camera marked unstable, or "
+                                                    "the cache is unwritable) - "
+                                                    "out-of-band injection stays "
+                                                    "off for it")
                                         _bridge_fn._sprop_done = True
                             # Rebase RTP timestamps to start near 0.  Camera picks a
                             # random starting timestamp (RFC 3550 section 5.1); the 90 kHz
@@ -5037,6 +5356,48 @@ class _SdesOpenMixin:
                         " camera's answer during the first-media wait" % _n_nom
                     )
             await asyncio.sleep(0.1)
+        if _first_video_pt[0] is None:
+            # The wait expired with nothing received. Everything needed to say
+            # why is in hand at exactly this moment and was, until now, thrown
+            # away: media only ever follows the AVIO LIVING trigger, that
+            # trigger is armed only by an inbound STUN Binding Success, and
+            # that response only comes back if something we nominated was
+            # reachable. When it was not, the only usable addresses are the
+            # ones the camera's own probes arrived from - and two silent vetoes
+            # can drop a relay-carried probe. One WARNING, on this path only:
+            # an open that delivers media reaches none of this.
+            try:
+                _stall_probes = list(
+                    (getattr(_bridge_fn, "_br_probe_verdicts", None) or {}).items()
+                )
+                # Union of every nomination source, deduped and order-preserving:
+                # the answer-peek path records into _nominated_seen, the setup /
+                # trickle / late-answer paths into _bridge_uc_info, and the
+                # bridge's peer-reflexive learning into ["prflx"].  Any one of
+                # them alone under-reports on some shape.
+                _stall_nominated: list = []
+                for _sn in (*_nominated_seen, *_bridge_uc_info["cands"],
+                            *_bridge_uc_info["prflx"]):
+                    if _sn not in _stall_nominated:
+                        _stall_nominated.append(_sn)
+                _LOGGER.warning("%s", _first_media_stall_report(
+                    device_id=getattr(self, "device_id", "?"),
+                    waited_s=_FIRST_MEDIA_WAIT_S,
+                    nominated=_stall_nominated,
+                    use_candidate_sent=bool(
+                        _bridge_uc_info["sent"] or _nominated_seen),
+                    binding_success=int(
+                        getattr(_bridge_fn, "_br_binding_success_count", 0)),
+                    trigger_sent=bool(
+                        getattr(_bridge_fn, "_tutk_trigger_sent", False)),
+                    probes=_stall_probes,
+                    probes_dropped=int(
+                        getattr(_bridge_fn, "_br_probe_overflow", 0)),
+                ))
+            except Exception:
+                _LOGGER.debug("camera %s: swallowed exception in %s",
+                              getattr(self, "device_id", "?"),
+                              '_first_media_stall_report', exc_info=True)
         if _serve_audio and _first_audio_pt[0] is None:
             _apt_deadline = time.monotonic() + _AUDIO_PT_GRACE_S
             while _first_audio_pt[0] is None and time.monotonic() < _apt_deadline:

{python_aidot_cameras-0.17.3b2 → python_aidot_cameras-1.0.0b2}/pyproject.toml

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