python-aidot-cameras 1.0.0b26__tar.gz → 1.0.0b28__tar.gz

{python_aidot_cameras-1.0.0b26/python_aidot_cameras.egg-info → python_aidot_cameras-1.0.0b28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0b26
+Version: 1.0.0b28
 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
@@ -119,6 +119,27 @@ mid-session on the same transport, and it does not change the rate; the app's
 does. Streaming is correct either way and the cost is bandwidth, which matters
 on a metered or congested link.
 
+**That 2:1 is reachable by another route: the codec.** Ten sessions on this
+camera on 2026-08-23 separate perfectly by the video payload type the session
+negotiated - H264 (pt=96) at 1597-1685 Kbps, H265 (pt=97) at 766-774 Kbps, no
+overlap. An H.265 session costs about half an H.264 one, which is the same
+ratio the app's SD tap achieves, and unlike a control byte the camera ignores,
+the codec is chosen in our own offer.
+
+Two things stand between that and a saving you can switch on:
+
+- **We cannot select it.** Narrowing the offer to 97 does not select it, it
+  removes the option - no video at all in 3 of 3 rounds (see
+  `AIDOT_SDES_VIDEO_PT` below). Reordering the preference list without
+  narrowing it (`AIDOT_SDES_VIDEO_PT_ORDER=97,96`) was then tested directly:
+  eight sessions in blocks of two returned H265 in 2 of 4 with the reorder and
+  2 of 4 without, with receipts confirming the reordered list reached the SDP.
+  The camera chooses, roughly a coin flip, and neither knob moves it.
+- **H.265 may not suit the consumer.** Browser HEVC support over Media Source
+  Extensions is far narrower than H.264, and MSE playback is the reason the
+  bitrate matters here at all. Halving the bitrate is no help if the client
+  that was failing cannot decode the result.
+
 ## Local (LAN) control and account ownership
 
 Local control over the devices' TCP:10000 channel - both the light/plug protocol
@@ -398,7 +419,10 @@ audio, idle release, the sprop cache path) are documented in
 | `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_NACK` | Ask the camera to resend video RTP packets that never arrived (RTCP Generic NACK). A camera losing packets on a weak link otherwise delivers truncated H.264 slices, which a browser's WebRTC decoder conceals but Media Source Extensions treats as fatal. Measured on an A001064 at ~1-2% loss: 98.4% of losses recovered against none at all without it. Costs nothing on a clean link, where no requests are generated. **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_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. **Tested on hardware 2026-08-23 and it does not select the codec.** Eight sessions on an A001064 in blocks of two: H265 came back in 2 of 4 with the order reversed and 2 of 4 without it, receipts confirming the reordered list reached the SDP. The motive was real - an H265 session costs about half an H264 one (766-774 vs 1597-1685 Kbps) - but the camera picks the codec itself, roughly a coin flip, and RFC 3264 preference order does not move it. | unset (`96 97`) |
+| `AIDOT_SDES_OFFER_BANDWIDTH_KBPS` | Add a `b=AS:<kbps>` receive-bandwidth ceiling (RFC 4566) to the video section of the SDES offer. **Measured to do nothing** on an A001064 over ten sessions; kept, off, alongside `AIDOT_REMB_TARGET_BPS` for the same reason. Run as a strict ABAB campaign it appeared to give a decisive 2.1x reduction - that was a codec split, not the knob. | unset (no `b=` line) |
+| `AIDOT_SDES_TMMBR_BPS` | Ask the camera not to exceed a bitrate, in bits per second, via RTCP TMMBR (RFC 5104). Distinct from `AIDOT_REMB_TARGET_BPS`: REMB reports an *estimate* of available bandwidth, TMMBR states a *bound*, and firmware can honour one without the other. This camera acts on RTCP feedback it never negotiated (our offer advertises no `a=rtcp-fb` at all, yet NACK recovers 98.4% of losses), so the absence of `ccm tmmbr` from its answer is not a reason to assume it is ignored. **Measured on an A001064 and it does nothing** - within-session, 0.748 against a control of 0.705, i.e. marginally higher. Shipped off. | unset (off) |
+| `AIDOT_SDES_TMMBR_AFTER_S` | Seconds of media to let pass before the first TMMBR, so a bound can be measured *within* one session - window A before it, window B after - instead of between sessions. Measured from the first video packet, not from the open, so a slow-waking camera does not spend window A already capped. | `0` (send from the first video packet) |
 | `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-1.0.0b26 → python_aidot_cameras-1.0.0b28}/README.md

@@ -79,6 +79,27 @@ mid-session on the same transport, and it does not change the rate; the app's
 does. Streaming is correct either way and the cost is bandwidth, which matters
 on a metered or congested link.
 
+**That 2:1 is reachable by another route: the codec.** Ten sessions on this
+camera on 2026-08-23 separate perfectly by the video payload type the session
+negotiated - H264 (pt=96) at 1597-1685 Kbps, H265 (pt=97) at 766-774 Kbps, no
+overlap. An H.265 session costs about half an H.264 one, which is the same
+ratio the app's SD tap achieves, and unlike a control byte the camera ignores,
+the codec is chosen in our own offer.
+
+Two things stand between that and a saving you can switch on:
+
+- **We cannot select it.** Narrowing the offer to 97 does not select it, it
+  removes the option - no video at all in 3 of 3 rounds (see
+  `AIDOT_SDES_VIDEO_PT` below). Reordering the preference list without
+  narrowing it (`AIDOT_SDES_VIDEO_PT_ORDER=97,96`) was then tested directly:
+  eight sessions in blocks of two returned H265 in 2 of 4 with the reorder and
+  2 of 4 without, with receipts confirming the reordered list reached the SDP.
+  The camera chooses, roughly a coin flip, and neither knob moves it.
+- **H.265 may not suit the consumer.** Browser HEVC support over Media Source
+  Extensions is far narrower than H.264, and MSE playback is the reason the
+  bitrate matters here at all. Halving the bitrate is no help if the client
+  that was failing cannot decode the result.
+
 ## Local (LAN) control and account ownership
 
 Local control over the devices' TCP:10000 channel - both the light/plug protocol
@@ -358,7 +379,10 @@ audio, idle release, the sprop cache path) are documented in
 | `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_NACK` | Ask the camera to resend video RTP packets that never arrived (RTCP Generic NACK). A camera losing packets on a weak link otherwise delivers truncated H.264 slices, which a browser's WebRTC decoder conceals but Media Source Extensions treats as fatal. Measured on an A001064 at ~1-2% loss: 98.4% of losses recovered against none at all without it. Costs nothing on a clean link, where no requests are generated. **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_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. **Tested on hardware 2026-08-23 and it does not select the codec.** Eight sessions on an A001064 in blocks of two: H265 came back in 2 of 4 with the order reversed and 2 of 4 without it, receipts confirming the reordered list reached the SDP. The motive was real - an H265 session costs about half an H264 one (766-774 vs 1597-1685 Kbps) - but the camera picks the codec itself, roughly a coin flip, and RFC 3264 preference order does not move it. | unset (`96 97`) |
+| `AIDOT_SDES_OFFER_BANDWIDTH_KBPS` | Add a `b=AS:<kbps>` receive-bandwidth ceiling (RFC 4566) to the video section of the SDES offer. **Measured to do nothing** on an A001064 over ten sessions; kept, off, alongside `AIDOT_REMB_TARGET_BPS` for the same reason. Run as a strict ABAB campaign it appeared to give a decisive 2.1x reduction - that was a codec split, not the knob. | unset (no `b=` line) |
+| `AIDOT_SDES_TMMBR_BPS` | Ask the camera not to exceed a bitrate, in bits per second, via RTCP TMMBR (RFC 5104). Distinct from `AIDOT_REMB_TARGET_BPS`: REMB reports an *estimate* of available bandwidth, TMMBR states a *bound*, and firmware can honour one without the other. This camera acts on RTCP feedback it never negotiated (our offer advertises no `a=rtcp-fb` at all, yet NACK recovers 98.4% of losses), so the absence of `ccm tmmbr` from its answer is not a reason to assume it is ignored. **Measured on an A001064 and it does nothing** - within-session, 0.748 against a control of 0.705, i.e. marginally higher. Shipped off. | unset (off) |
+| `AIDOT_SDES_TMMBR_AFTER_S` | Seconds of media to let pass before the first TMMBR, so a bound can be measured *within* one session - window A before it, window B after - instead of between sessions. Measured from the first video packet, not from the open, so a slow-waking camera does not spend window A already capped. | `0` (send from the first video packet) |
 | `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-1.0.0b26 → python_aidot_cameras-1.0.0b28}/aidot_cameras/__main__.py

@@ -46,14 +46,14 @@ Optional stream knobs:
 go2rtc.yaml example (SDES camera - native RTSP push, video + audio):
 
     streams:
-      frontdoor: exec:aidot-go2rtc 8d2521ea... {output}
+      frontdoor: exec:aidot-go2rtc 0a1b2c3d... {output}
 
 A DTLS camera (A000088) has no RTSP-push path, but a stdout producer works the
 same lazy way. Pass ``-`` as the output and this process writes MPEG-TS (video
 plus AAC audio) to stdout, which go2rtc's exec: source reads directly:
 
     streams:
-      driveway: exec:aidot-go2rtc 7c89a5c1... -
+      garage: exec:aidot-go2rtc 0a1b2c3d... -
 
 go2rtc then owns the lifecycle - spawn on the first viewer, kill when idle -
 exactly as it does with ``{output}`` for an SDES camera. An
@@ -66,18 +66,22 @@ from __future__ import annotations
 
 import argparse
 import asyncio
-import json
 import logging
 import os
 import re
 import signal
 import sys
-import tempfile
 from typing import Optional
 
 import aiohttp
 
 from .client import AidotClient
+from .cloud_auth import (  # noqa: F401  (re-exported for callers and tests)
+    _install_token_cache,
+    _make_client,
+    _read_token_file,
+    _write_token_file,
+)
 from .const import CONF_DEVICE_LIST, CONF_ID, CONF_MODEL_ID, CONF_NAME
 
 _LOGGER = logging.getLogger("aidot.go2rtc")
@@ -93,115 +97,6 @@ def _env_bool(name: str) -> bool | None:
     return raw == "1"
 
 
-def _read_token_file(path: str) -> dict:
-    """Blocking read of a stored login_info dict (run via executor from async)."""
-    with open(path, encoding="utf-8") as fh:
-        return json.load(fh)
-
-
-def _write_token_file(path: str, data: dict) -> None:
-    """Atomic, 0600-secure write of login_info to ``path``.
-
-    Serialize into a temp file in the same directory (mkstemp creates it 0600,
-    closing the world-readable window os.chmod-after-write leaves) and only then
-    os.replace it over ``path`` - so a serialization failure never truncates the
-    previously-valid token. On any error the temp file is removed and re-raised.
-    """
-    directory = os.path.dirname(path) or "."
-    fd, tmp = tempfile.mkstemp(dir=directory, prefix=".token-", suffix=".tmp")
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as fh:
-            json.dump(data, fh)
-        os.replace(tmp, path)
-    except BaseException:
-        try:
-            os.unlink(tmp)
-        except OSError:
-            pass
-        raise
-
-
-def _install_token_cache(client: AidotClient, path: str) -> None:
-    """Persist rotated tokens to ``path`` so refreshes survive across restarts.
-
-    The library calls this no-arg callback after every successful token refresh
-    (client.py), having already updated ``client.login_info``. Mirrors HA's
-    coordinator.token_fresh_cb, but writes to our own file instead of an HA
-    config entry - so a standalone run never loses auth to a rotation and never
-    fights HA over a shared refresh token.
-    """
-    def _cb() -> None:
-        try:
-            _write_token_file(path, client.serializable_login_info())
-            _LOGGER.debug("Cached refreshed token to %s", path)
-        except (OSError, TypeError) as exc:
-            # TypeError: a defensive belt-and-suspenders catch alongside
-            # serializable_login_info() itself - if a future runtime-only key
-            # is ever added to login_info without also being added to
-            # RUNTIME_ONLY_LOGIN_INFO_KEYS, this keeps a caching bug from
-            # ever propagating out of a callback and interrupting a token
-            # refresh that had otherwise already succeeded (confirmed live:
-            # this exact TypeError - "Object of type Lock is not JSON
-            # serializable" - previously escaped this callback uncaught).
-            _LOGGER.warning("Could not cache refreshed token to %s: %s", path, exc)
-
-    client.set_token_fresh_cb(_cb)
-
-
-async def _make_client(session: aiohttp.ClientSession) -> AidotClient:
-    """Authenticate to the AiDot cloud from the environment.
-
-    Prefers a stored token (AIDOT_TOKEN_FILE) - the same login_info dict the HA
-    integration persists - which carries access/refresh tokens so no password
-    round-trip is needed.  Falls back to username/password login otherwise.  In
-    both cases, if AIDOT_TOKEN_FILE is set we register a write-back cache so
-    rotations persist.
-    """
-    loop = asyncio.get_running_loop()
-    token_file = os.environ.get("AIDOT_TOKEN_FILE")
-    username = os.environ.get("AIDOT_USERNAME")
-    password = os.environ.get("AIDOT_PASSWORD")
-
-    if token_file and os.path.exists(token_file):
-        try:
-            token = await loop.run_in_executor(None, _read_token_file, token_file)
-        except (OSError, ValueError) as exc:
-            # ValueError covers json.JSONDecodeError (empty/partial/corrupt
-            # cache). Fall through to the username/password path rather than
-            # crash CLI startup.
-            _LOGGER.warning("ignoring unreadable token cache %s: %s", token_file, exc)
-        else:
-            client = AidotClient(session=session, token=token)
-            _install_token_cache(client, token_file)
-            return client
-
-    if not username or not password:
-        sys.exit(
-            "Set AIDOT_TOKEN_FILE, or AIDOT_USERNAME and AIDOT_PASSWORD, in the "
-            "environment."
-        )
-
-    client = AidotClient(
-        session=session,
-        country_code=DEFAULT_COUNTRY,
-        username=username,
-        password=password,
-    )
-    await client.async_post_login()
-    # If a token file path was given (but didn't exist yet), seed it now and
-    # register the write-back cache so a dedicated-login run persists its
-    # rotations across restarts.
-    if token_file:
-        _install_token_cache(client, token_file)
-        try:
-            await loop.run_in_executor(
-                None, _write_token_file, token_file, client.serializable_login_info()
-            )
-        except (OSError, TypeError) as exc:
-            _LOGGER.warning("Could not seed token cache %s: %s", token_file, exc)
-    return client
-
-
 async def _cameras(client: AidotClient) -> list[dict]:
     """Return the raw device dicts for every camera on the account."""
     data = await client.async_get_all_device()

{python_aidot_cameras-1.0.0b26 → python_aidot_cameras-1.0.0b28}/aidot_cameras/_upstream.py

@@ -93,8 +93,8 @@ def rsa_encrypt(message: str, public_key: Any = None) -> str:
     with ``aidot.client.rsa_password_encrypt(message)``, which bakes the key in
     and takes one argument.  Neither signature is available on both shapes, and
     ``aidot_cameras.crypto.rsa_encrypt`` is public surface the integration repo
-    may import (see the back-compat rule in CLAUDE.md), so the two-argument form
-    is kept and satisfied locally.  ``public_key`` defaults to upstream's
+    may import, and public surface is not changed to track an upstream rename,
+    so the two-argument form is kept and satisfied locally.  ``public_key`` defaults to upstream's
     ``PUBLIC_KEY_PEM``, which is the only key any caller ever passed.
     """
     from cryptography.hazmat.backends import default_backend

{python_aidot_cameras-1.0.0b26 → python_aidot_cameras-1.0.0b28}/aidot_cameras/camera/controls.py

@@ -196,8 +196,32 @@ class _CameraControlsMixin:
         had been applied. Nothing else re-sent it, so "it will apply on the next
         session" was not true of any code path.
 
+        **On the A001064 this is acked and inert - it does not change the
+        rate, on either codec.** Measured 2026-08-23 with the framing gap
+        closed (1.0.0b27, so the AVIO header including the live-play dSeq is
+        byte-identical to the app's), in-session with a control arm that waits
+        the same gap and sends nothing: sd 0.885 against control 0.863, where
+        a working SD is about 2:1. Re-measured the same night on the H265
+        encode specifically - the codec the vendor app's working toggle rides -
+        because every earlier measurement had landed on H264 sessions: hd on
+        H265 scored 0.703 against controls at 0.743-0.776. Inert there too. The camera answers `801 payload=0000000000000000` every time. The
+        vendor app's own SD tap DOES halve the rate on the same camera, so this
+        is not a firmware that cannot do SD; we cannot trigger it. See
+        docs/ROAD-TO-1.0.md item 2 for the full record, including the five
+        other bitrate controls that turned out to be dead and the codec
+        difference that is worth about the same 2:1.
+
+        The call is kept because it is correct, it is what the app sends, and
+        other models are not covered by that measurement. Callers should not
+        rely on it changing the bitrate.
+
         Source: f0.java g3() -> X2(800, SetStreamCtrlReq.parseContent(0, quality)).
         Payload <IB3x> = channel(0) + quality byte + 3 reserved.
+        The app has three settings, not two: Auto, SD and HD, which
+        `NewLivePresenter.setDefaultResolution` maps from the persistent
+        `props.StreamType` property to quality 16, 5 and 1. This library
+        implements only hd=1 and sd=5; 16 (Auto) was swept and did nothing, and
+        `StreamType` itself is acked-and-ignored on every write.
         """
         q = _STREAM_QUALITY.get(quality.lower())
         if q is None:

{python_aidot_cameras-1.0.0b26 → python_aidot_cameras-1.0.0b28}/aidot_cameras/camera/protocol.py

@@ -2993,6 +2993,55 @@ def build_nack(sender_ssrc: int, media_ssrc: int, lost_seqs: "list") -> bytes:
     return pkt[:2] + struct.pack("!H", len(pkt) // 4 - 1) + pkt[4:]
 
 
+#: RTPFB feedback message types (RFC 4585 s6.1, RFC 5104 s4.2).
+_RTPFB_PT = 205
+_FMT_NACK = 1
+_FMT_TMMBR = 3
+
+
+def build_tmmbr(sender_ssrc: int, media_ssrc: int, bitrate_bps: int,
+                overhead: int = 60) -> bytes:
+    """A TMMBR (RFC 5104 s4.2.1) telling ``media_ssrc`` not to exceed a rate.
+
+    Distinct from REMB, which this camera was measured to ignore: REMB reports
+    an *estimate* of what the path will bear, TMMBR states a *bound* the sender
+    must respect. They are different messages and a firmware can honour one
+    without the other.
+
+    The bound is encoded as a 17-bit mantissa scaled by a 6-bit exponent, so
+    not every rate is representable. We round the mantissa DOWN, never up: a
+    TMMBR that permits more than the caller asked for is worse than sending
+    none at all on a link that is already saturating.
+
+    ``overhead`` is Measured Overhead, per-packet transport overhead in bytes
+    (9 bits). 60 is the usual IP+UDP+RTP+SRTP figure and is what browsers send.
+    """
+    if bitrate_bps <= 0:
+        raise ValueError(
+            f"a TMMBR must name a positive bitrate, got {bitrate_bps}; a bound "
+            f"of zero asks the camera to stop sending")
+    exp = 0
+    mantissa = int(bitrate_bps)
+    while mantissa >= (1 << 17):
+        mantissa >>= 1
+        exp += 1
+    fci = struct.pack("!II",
+                      media_ssrc & 0xFFFFFFFF,
+                      (exp << 26) | (mantissa << 9) | (max(0, overhead) & 0x1FF))
+    # The header's media-source field is unused for TMMBR and SHALL be zero
+    # (RFC 5104 s4.2.1.2); the limited SSRC travels in the FCI above.
+    pkt = (struct.pack("!BBH", 0x80 | _FMT_TMMBR, _RTPFB_PT, 0)
+           + struct.pack("!II", sender_ssrc & 0xFFFFFFFF, 0)
+           + fci)
+    return pkt[:2] + struct.pack("!H", len(pkt) // 4 - 1) + pkt[4:]
+
+
+def decode_tmmbr_bitrate(pkt: bytes) -> int:
+    """The bound carried by a TMMBR built above, in bits per second."""
+    word = struct.unpack("!I", pkt[16:20])[0]
+    return ((word >> 9) & 0x1FFFF) << (word >> 26)
+
+
 def decode_nack_seqs(pkt: bytes) -> "list":
     """The sequence numbers a Generic NACK asks for. For tests and diagnostics."""
     out = []

{python_aidot_cameras-1.0.0b26 → python_aidot_cameras-1.0.0b28}/aidot_cameras/camera/sdes_open.py

@@ -30,6 +30,7 @@ from .protocol import (
     NackTracker,
     build_nack,
     build_remb,
+    build_tmmbr,
     _build_sprop,
     parse_avio_response,
     _build_stun_binding_success_response,
@@ -240,6 +241,42 @@ def _widen_media_rcvbuf(sock, kind: str, device_id: str = "?") -> int:
     return got
 
 
+def _sdes_offer_bandwidth_kbps():
+    """A receive-bandwidth ceiling for the offer, in kbps, or None for none.
+
+    Off unless ``AIDOT_SDES_OFFER_BANDWIDTH_KBPS`` names a positive integer.
+    An unparseable value is off rather than an error: this is read while an
+    offer is being built, and a typo must not take a camera off the air.
+    """
+    raw = os.environ.get("AIDOT_SDES_OFFER_BANDWIDTH_KBPS")
+    try:
+        kbps = int(str(raw).strip())
+    except (TypeError, ValueError, AttributeError):
+        return None
+    return kbps if kbps > 0 else None
+
+
+def _offer_bandwidth_line(kbps) -> str:
+    """``b=AS:<kbps>`` (RFC 4566 s5.8) for the offer, or "" for no ceiling.
+
+    A receiver telling a sender how much it is willing to accept. This is the
+    last standards-defined bitrate control left after the others were killed
+    on evidence, and the only one we emit ourselves rather than mirror from
+    the app -- the app sends no ``b=`` line at all.
+
+    Anything that is not a positive integer count of kilobits yields no line.
+    ``b=AS:0`` is NOT "unlimited" in RFC 4566; it asks for zero bandwidth, so
+    the off case must omit the line entirely.
+    """
+    try:
+        value = int(kbps)
+    except (TypeError, ValueError):
+        return ""
+    if value <= 0:
+        return ""
+    return f"b=AS:{value}\r\n"
+
+
 def _sdes_nack_enabled() -> bool:
     """Whether to ask the camera to resend video packets that never arrived.
 
@@ -353,6 +390,71 @@ def _send_video_nack(send, srtcp_sess, sender_ssrc: int,
         return False
 
 
+def _sdes_tmmbr_bps():
+    """The bitrate bound to ask the camera for, in bits/s, or None for none.
+
+    Off unless ``AIDOT_SDES_TMMBR_BPS`` names a positive integer.  Unparseable
+    is off rather than an error: this is read while a session is running.
+    """
+    try:
+        bps = int(str(os.environ.get("AIDOT_SDES_TMMBR_BPS")).strip())
+    except (TypeError, ValueError, AttributeError):
+        return None
+    return bps if bps > 0 else None
+
+
+def _sdes_tmmbr_after_s() -> float:
+    """Seconds of MEDIA to let pass before the first TMMBR.  0 = immediately.
+
+    Exists so the bound can be measured within a session -- window A before it,
+    window B after -- instead of between sessions.  On this camera a
+    between-session comparison has twice produced a wrong answer: it read a
+    codec split as a bandwidth-cap effect, and the encoder's own drift as a
+    working SD control.  Both windows of one session share the codec and the
+    scene, so neither can confound it.
+    """
+    try:
+        after = float(str(os.environ.get("AIDOT_SDES_TMMBR_AFTER_S")).strip())
+    except (TypeError, ValueError, AttributeError):
+        return 0.0
+    return after if after > 0 else 0.0
+
+
+def _tmmbr_ready(first_video_ts, now: float, after_s: float) -> bool:
+    """Whether enough MEDIA has passed to start asking for the bound.
+
+    Measured from the first video packet, not from the open: a camera that
+    takes twelve seconds to wake would otherwise spend all of window A capped.
+    """
+    if first_video_ts is None:
+        return False
+    return (now - first_video_ts) >= after_s
+
+
+def _send_video_tmmbr(send, srtcp_sess, sender_ssrc: int,
+                      media_ssrc: int, bitrate_bps) -> bool:
+    """Put one TMMBR on the camera's RTCP path.  True if it went out.
+
+    ``send`` is the bridge's relay-aware sender, NOT a raw socket, for the
+    reason spelled out on :func:`_send_video_nack`: via TURN the address media
+    arrived from is the relay, and a raw write there is dropped as a malformed
+    STUN message while still reporting success.  (``REMB`` still writes to the
+    socket directly and is inert on a relayed session for exactly that reason;
+    it is latent only because its target defaults to 0.)
+
+    Never raises: this runs inside the bridge's packet loop.
+    """
+    if not bitrate_bps or bitrate_bps <= 0:
+        return False
+    try:
+        raw = build_tmmbr(sender_ssrc, media_ssrc, bitrate_bps)
+        send(srtcp_sess.protect_rtcp(raw) if srtcp_sess is not None else raw)
+        return True
+    except Exception:
+        _LOGGER.debug("TMMBR send failed", exc_info=True)
+        return False
+
+
 #: Sender SSRC on every RTCP we send the camera.  Load-bearing, not cosmetic:
 #: the SRTP TX policy is keyed `ssrc_value=_CAM_RTCP_SENDER_SSRC`, so the PLI,
 #: REMB, RR and NACK must all agree or the camera drops the packet.
@@ -1073,7 +1175,7 @@ def _record_peer_reflexive(known, discovered, observed, is_self=None):
     route to, the nomination goes into a black hole, and the session sits in
     ICE "Checking" while the camera's probes keep arriving from an address we
     never nominate.  Observed on the A001064 PTZ while it was on a separate
-    192.168.100.0/24: it advertised 192.168.100.13 as its only candidate.
+    192.168.9.0/24: it advertised 192.168.9.13 as its only candidate.
 
     Returns the new discovered list, or ``discovered`` unchanged when there is
     nothing to learn.  Callers must REBIND rather than mutate in place - the
@@ -1948,7 +2050,8 @@ class _SdesOpenMixin:
             # video m-section
             + 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"
+            + _offer_bandwidth_line(_sdes_offer_bandwidth_kbps())
+            + "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"
             + _video_codec_attrs
@@ -1995,6 +2098,15 @@ class _SdesOpenMixin:
         if _video_pt_order != _SDES_OFFER_VIDEO_PT_ORDER and _status:
             _status(f"SDES: offer video codec order={_video_pt_list}")
 
+        # Same receipt, same reason, for the receive-bandwidth ceiling: the log
+        # carries the camera's ANSWER, not our offer, so "the env var was set"
+        # is not evidence the line reached the wire.  Measured 2026-08-23: a
+        # b=AS arm scored identically to its control and the only available
+        # check for the knob was reading the env back out of the harness.
+        _bw_kbps = _sdes_offer_bandwidth_kbps()
+        if _bw_kbps and _status:
+            _status(f"SDES: offer receive-bandwidth ceiling b=AS:{_bw_kbps}")
+
         # 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
@@ -4076,23 +4188,33 @@ class _SdesOpenMixin:
                     #
                     # Own cadence: the PLI timer backs off to 30s once the
                     # stream is up, which is too slow to hold a rate.
+                    # Goes out the relay-aware sender, NOT the socket: via TURN
+                    # the address media arrived from is the relay, and a raw
+                    # write there is dropped as a malformed STUN message while
+                    # sendto still reports success.  That is the bug the NACK
+                    # path already had and had fixed; REMB was left behind, so
+                    # on a relayed camera it never arrived -- which also means
+                    # "REMB was measured to do nothing" cannot have been a valid
+                    # measurement on such a session.  No fallback to the socket:
+                    # skipping a tick until the sender exists costs a second,
+                    # falling back costs correctness on the very sessions this
+                    # is for.
+                    _remb_send = getattr(_bridge_fn, '_send_to_cam', None)
                     if (REMB_TARGET_BPS > 0
                             and hasattr(_bridge_fn, '_cam_video_ssrc')
-                            and hasattr(_bridge_fn, '_cam_srtp_sock')
+                            and _remb_send is not None
                             and _time_br.time() - getattr(
                                 _bridge_fn, '_last_remb_ts', 0.0) >= 1.0):
                         _bridge_fn._last_remb_ts = _time_br.time()
                         try:
                             _remb_raw = build_remb(
-                                0xAB12CD34,
+                                _CAM_RTCP_SENDER_SSRC,
                                 [_bridge_fn._cam_video_ssrc],
                                 REMB_TARGET_BPS)
                             _remb_sess = getattr(_bridge_fn, '_pli_tx_sess', None)
-                            _bridge_fn._cam_srtp_sock.sendto(
+                            _remb_send(
                                 _remb_sess.protect_rtcp(_remb_raw)
-                                if _remb_sess is not None else _remb_raw,
-                                _bridge_fn._cam_srtp_src,
-                            )
+                                if _remb_sess is not None else _remb_raw)
                             if not getattr(_bridge_fn, '_remb_logged', False):
                                 _bridge_fn._remb_logged = True
                                 _status(
@@ -4105,6 +4227,39 @@ class _SdesOpenMixin:
                                 getattr(self, "device_id", "?"), '_remb',
                                 exc_info=True)
 
+                    # TMMBR: a BOUND, where REMB above is an ESTIMATE.  Two
+                    # different RFC 5104 / 4585 messages, and this firmware can
+                    # honour one without the other -- it already acts on NACKs
+                    # it never negotiated (our SDES offer carries no a=rtcp-fb
+                    # line at all), so "the answer does not advertise ccm
+                    # tmmbr" is not a reason to withhold it.  Off by default;
+                    # every bitrate control tried on this camera so far has
+                    # been acked and ignored, and an unmeasured one must not
+                    # reach the four cameras that stream fine today.
+                    _tmmbr_bps = getattr(_bridge_fn, '_tmmbr_bps', None)
+                    _tmmbr_send = getattr(_bridge_fn, '_send_to_cam', None)
+                    if (_tmmbr_bps and _tmmbr_send is not None
+                            and hasattr(_bridge_fn, '_cam_video_ssrc')
+                            and _tmmbr_ready(
+                                getattr(_bridge_fn, '_first_video_ts', None),
+                                _time_br.time(),
+                                getattr(_bridge_fn, '_tmmbr_after_s', 0.0))
+                            and _time_br.time() - getattr(
+                                _bridge_fn, '_last_tmmbr_ts', 0.0) >= 1.0):
+                        _bridge_fn._last_tmmbr_ts = _time_br.time()
+                        if _send_video_tmmbr(
+                                _tmmbr_send,
+                                getattr(_bridge_fn, '_pli_tx_sess', None),
+                                _CAM_RTCP_SENDER_SSRC,
+                                _bridge_fn._cam_video_ssrc,
+                                _tmmbr_bps,
+                        ) and not getattr(_bridge_fn, '_tmmbr_logged', False):
+                            _bridge_fn._tmmbr_logged = True
+                            _status(
+                                f"SDES: sent TMMBR {_tmmbr_bps // 1000} kbps"
+                                f" for video SSRC"
+                                f" 0x{_bridge_fn._cam_video_ssrc:08x}")
+
                     _pli_done       = getattr(_bridge_fn, '_pli_count', 0)
                     _pli_interval   = (_pli_gaps[_pli_done]
                                        if _pli_done < len(_pli_gaps) else 30.0)
@@ -4208,10 +4363,20 @@ class _SdesOpenMixin:
                                 # pattern as the LIVING send above).  dcep_sock/dcep_src are the
                                 # socket+addr the SCTP handshake (and LIVING) used.
                                 import struct as _st_pcmd
-                                import random as _r_pcmd
 
                                 def _persistent_sdes_cmd(_cmd, _extra=b''):
-                                    _seq = _r_pcmd.randint(0, 0x7FFFFFFF)
+                                    # dSeq, not a random number.  The app's
+                                    # sendCtrl() takes this from a per-client
+                                    # counter that starts at 100 and increments
+                                    # on every control command, and we keep the
+                                    # same counter for livePlayReq already.
+                                    # Filling the slot randomly was the only
+                                    # field in the 28-byte header that differed
+                                    # from the app's.  Parity, not a fix: PTZ
+                                    # (AVIO 0x1001) pans through this very
+                                    # builder with a random dSeq, so the camera
+                                    # is not validating it.
+                                    _seq = self._next_dseq()
                                     _ts  = int(_time_br.time() * 1000)
                                     _avio = _st_pcmd.pack('<IIqII4x', _seq, _cmd, _ts,
                                                           len(_extra), 0) + _extra
@@ -5312,6 +5477,23 @@ class _SdesOpenMixin:
                                         '!I', _bpkt, 8)[0]
                                 _bridge_fn._cam_srtp_src  = _bsrc
                                 _bridge_fn._cam_srtp_sock = _bs
+                                # Publish the relay-aware sender so the RTCP
+                                # cadence (which runs outside this loop and has
+                                # no socket/peer in scope) can reach the camera
+                                # the same way the NACK does.  Rebuilt only when
+                                # the address changes: this runs ~300x/s per
+                                # camera, which is why _nack_on is resolved once
+                                # per session rather than read per packet.
+                                if getattr(_bridge_fn, '_first_video_ts',
+                                           None) is None:
+                                    _bridge_fn._first_video_ts = _time_br.time()
+                                if getattr(_bridge_fn, '_send_to_cam_src',
+                                           None) != _bsrc:
+                                    _bridge_fn._send_to_cam_src = _bsrc
+                                    _bridge_fn._send_to_cam = (
+                                        lambda _d, _s=_bs, _a=_bsrc,
+                                        _p=_br_cam_peer: _br_send_to_cam(
+                                            _s, _d, _a, _p))
                                 # Schedule immediate PLI so IDR+SPS arrives in
                                 # the analyzeduration window.
                                 _bridge_fn._last_pli_ts = 0.0
@@ -5320,6 +5502,13 @@ class _SdesOpenMixin:
                                 # os.environ.get costs ~250ns of it.  A flip
                                 # now takes effect on the next stream open.
                                 _bridge_fn._nack_on = _sdes_nack_enabled()
+                                # Same reason, same place: the RTCP cadence
+                                # below sits on this loop, so its switches are
+                                # resolved once here rather than read from the
+                                # environment ~300x/s.  A flip takes effect on
+                                # the next stream open, as the NACK switch does.
+                                _bridge_fn._tmmbr_bps = _sdes_tmmbr_bps()
+                                _bridge_fn._tmmbr_after_s = _sdes_tmmbr_after_s()
                             # For TUTK cameras (_use_plain_rtp) the ffmpeg SDP uses
                             # RTP/AVP (no crypto). After LIVING the camera switches
                             # from TUTK SFrames to standard SRTP, so we decrypt here