python-aidot-cameras 0.9.1__tar.gz → 0.10.0__tar.gz

python_aidot_cameras-0.10.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: python-aidot-cameras
+Version: 0.10.0
+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
+Project-URL: Homepage, https://github.com/cbrightly/python-aidot-cameras
+Project-URL: Issue Tracker, https://github.com/cbrightly/python-aidot-cameras/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: paho-mqtt>=2.0
+Requires-Dist: cryptography>=42.0
+Requires-Dist: pycryptodome>=3.20
+Requires-Dist: dacite>=1.8
+Provides-Extra: webrtc
+Requires-Dist: aiortc>=1.9.0; extra == "webrtc"
+Requires-Dist: aioice<0.12,>=0.9.0; extra == "webrtc"
+Requires-Dist: av; extra == "webrtc"
+Requires-Dist: pylibsrtp; extra == "webrtc"
+Requires-Dist: pyopenssl; extra == "webrtc"
+Requires-Dist: numpy; extra == "webrtc"
+Requires-Dist: Pillow; extra == "webrtc"
+Dynamic: license-file
+
+# python-aidot-cameras
+
+[![PyPI version](https://img.shields.io/pypi/v/python-aidot-cameras)](https://pypi.org/project/python-aidot-cameras/)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-aidot-cameras)](https://pypi.org/project/python-aidot-cameras/)
+[![License: MIT](https://img.shields.io/pypi/l/python-aidot-cameras)](LICENSE)
+
+Control AIDOT WiFi lights **and cameras** from Python.
+
+This is a camera-capable fork of the upstream lights-only
+[`python-aidot`](https://github.com/AiDot-Development-Team/python-AiDot). It adds
+live WebRTC video streaming (DTLS and SDES-SRTP paths), snapshots, PTZ, camera
+controls, cloud recordings/thumbnails, and two-way (push-to-talk) audio.
+
+This repository is the **library** (distribution name `python-aidot-cameras`).
+The Home Assistant custom component (`custom_components/aidot/`) lives in the
+companion integration repo
+[`cbrightly/hass-aidot-cameras`](https://github.com/cbrightly/hass-aidot-cameras), which depends
+on this library.
+
+## Supported cameras
+
+The streaming transport is auto-selected per camera from its model id:
+
+- **A000088** (M3 Pro) — DTLS-SRTP, wired/mains.
+- **A001513** ("L2") — SDES-SRTP, **battery** (woken on demand; validated end-to-end).
+- **A001064** (PTZ) — SDES-SRTP, wired/mains (role-reversal handshake).
+
+Other battery models (A001108, A001360) are recognized in code with the same
+battery handling. See [`docs/CAMERAS.md`](docs/CAMERAS.md#supported-cameras) for
+the authoritative table and per-model notes.
+
+## Library install
+
+Install from PyPI (the simplest, recommended method):
+
+```bash
+# lights + camera cloud/control only:
+pip install python-aidot-cameras
+# add live WebRTC streaming, snapshots, and two-way audio:
+pip install python-aidot-cameras[webrtc]
+```
+
+`[webrtc]` pulls in the extra dependencies (aiortc, av, …) needed for live
+streaming, snapshots, and two-way audio. Without it you still get lights plus
+the camera cloud/control APIs, but not live media.
+
+For the latest unreleased code, install straight from the GitHub repo instead:
+
+```bash
+# lights + camera cloud/control only:
+pip install "git+https://github.com/cbrightly/python-aidot-cameras"
+# add live WebRTC streaming, snapshots, and two-way audio:
+pip install "python-aidot-cameras[webrtc] @ git+https://github.com/cbrightly/python-aidot-cameras"
+```
+
+## Standalone CLI: `aidot-go2rtc`
+
+Bridge a camera into [go2rtc](https://github.com/AlexxIT/go2rtc) (or any
+RTSP/HTTP consumer) **without Home Assistant**. Installing the package provides
+the `aidot-go2rtc` console script; for an isolated tool install use pipx or uv:
+
+```bash
+pipx install "python-aidot-cameras[webrtc]"
+# or:
+uv tool install "python-aidot-cameras[webrtc]"
+
+aidot-go2rtc --list                  # discover cameras + their transport
+aidot-go2rtc <device_id> '{output}'  # stream one camera (as a go2rtc exec: source)
+```
+
+## Usage
+
+Open a live WebRTC stream from a camera device client:
+
+```python
+session = await device_client.async_open_webrtc_stream(on_frame=cb, timeout=30.0)
+# ... session.stop() when done
+```
+
+Two-way (push-to-talk) audio:
+
+```python
+session = await device_client.async_open_webrtc_stream(..., talk=True)
+await session.async_start_talk(pcm_provider)   # provider() -> 320B s16le PCM (20ms @ 8kHz), or None
+# ... speak ...
+await session.async_stop_talk()
+```
+
+See [`docs/CAMERAS.md`](docs/CAMERAS.md) for the full camera API (streaming,
+snapshots, recordings, motion polling, two-way audio, and LAN-direct media).
+
+## Home Assistant component and CLI
+
+The Home Assistant custom component (`custom_components/aidot/`) is **not** part
+of this library repo - it lives in the companion integration repo
+[`cbrightly/hass-aidot-cameras`](https://github.com/cbrightly/hass-aidot-cameras), which depends
+on this library. See that repo for installing the component (via HACS or by
+copying `custom_components/aidot/`).
+
+## Environment variables
+
+The library reads the following environment variables.
+
+### Credentials
+
+Used by the credential helper (`aidot.credentials`); they take priority over any
+stored credentials file. See [`src/aidot/credentials.py`](src/aidot/credentials.py).
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `AIDOT_USERNAME` | AiDot account username/email. Used with `AIDOT_PASSWORD`. | (none) |
+| `AIDOT_PASSWORD` | AiDot account password. Used with `AIDOT_USERNAME`. | (none) |
+| `AIDOT_COUNTRY` | Account region/country code. | `US` |
+
+### Camera streaming / tuning
+
+The most useful knobs read by the camera client (`aidot.camera.client`). Defaults
+are chosen to work out of the box; override only when tuning. Finer-grained
+internal knobs (audio normalization, keyframe/PLI cadence, retry timing, SDES
+audio, idle release, the sprop cache path) are documented in
+[`docs/CAMERAS.md`](docs/CAMERAS.md#advanced-tuning-environment-variables).
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `AIDOT_MAX_CONCURRENT_OPENS` | Caps how many stream opens run concurrently across all cameras. | `2` |
+| `AIDOT_MAX_CONCURRENT_STREAMS` | Caps how many cameras stream at once. | `3` |
+| `AIDOT_FAST_CONNECT` | Enable LAN-direct "fast connect" (STUN-only, skips several cloud signaling waits) when truthy. On-LAN only — off-subnet/strict-NAT viewers must leave it off. | unset (off) |
+| `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. | 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_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 soak cut SDES NO_MEDIA ~57%→~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) |
+| `AIDOT_LIVESTREAM_PARAM` | Set to `0` to skip the cloud `liveStreamParam` pre-connect that provisions battery cameras' live-stream sessions before signaling (without it, battery cameras like the L2 models reject streaming with `-50019`). | `1` (enabled) |
+
+### Security hardening
+
+Opt-in knobs that tighten the camera transport. Defaults preserve current
+behavior (the firmware's signaling doesn't carry verifiable material, so strict
+modes are off until you pin a value); each emits a one-time warning when left at
+the permissive default.
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `AIDOT_DTLS_PINNED_FP` | Pin the camera's DTLS certificate `sha-256` fingerprint (colon-separated hex). When set, a camera presenting a different cert fails the handshake instead of being accepted. The camera echoes our own fingerprint over signaling, so without a pin the media channel is **not** authenticated against an on-path MITM. | unset (accept-any + warn) |
+| `AIDOT_PLAYBACK_TLS_VERIFY` | Set to `1` to require full certificate + hostname verification on the TCP playback/live-stream TLS connection. Needs a trust anchor the camera's cert chains to; off by default because the camera presents a self-signed cert. | unset (no verification + warn) |
+| `AIDOT_ALLOW_LAN_SERVE` | Silences the warning emitted when decrypted media is served on a non-loopback bind (e.g. `0.0.0.0`), where any host on the LAN can read the unencrypted stream. Set when an exposed bind is intentional. | unset (warn on non-loopback) |
+| `AIDOT_SDES_HOLEPUNCH_HOST` | Override the NAT hole-punch target used when the cloud supplies no TURN entry. By default a STUN packet goes to a hardcoded vendor TURN host; set this to a host of your choice, or empty (`AIDOT_SDES_HOLEPUNCH_HOST=`) to disable the hardcoded fallback entirely. | unset (hardcoded vendor host + warn) |
+| `AIDOT_CRED_KEY_FILE` | Path to the Fernet key file for stored credentials. Point it outside the config dir (ideally a separate secret store) so the key isn't co-located with the ciphertext. Applies to the default credentials path only (ignored when an explicit `creds_path` is passed). | `$XDG_CONFIG_HOME/aidot/.key` (falls back to `~/.config/aidot/.key`) |

python_aidot_cameras-0.10.0/README.md

@@ -0,0 +1,149 @@
+# python-aidot-cameras
+
+[![PyPI version](https://img.shields.io/pypi/v/python-aidot-cameras)](https://pypi.org/project/python-aidot-cameras/)
+[![Python versions](https://img.shields.io/pypi/pyversions/python-aidot-cameras)](https://pypi.org/project/python-aidot-cameras/)
+[![License: MIT](https://img.shields.io/pypi/l/python-aidot-cameras)](LICENSE)
+
+Control AIDOT WiFi lights **and cameras** from Python.
+
+This is a camera-capable fork of the upstream lights-only
+[`python-aidot`](https://github.com/AiDot-Development-Team/python-AiDot). It adds
+live WebRTC video streaming (DTLS and SDES-SRTP paths), snapshots, PTZ, camera
+controls, cloud recordings/thumbnails, and two-way (push-to-talk) audio.
+
+This repository is the **library** (distribution name `python-aidot-cameras`).
+The Home Assistant custom component (`custom_components/aidot/`) lives in the
+companion integration repo
+[`cbrightly/hass-aidot-cameras`](https://github.com/cbrightly/hass-aidot-cameras), which depends
+on this library.
+
+## Supported cameras
+
+The streaming transport is auto-selected per camera from its model id:
+
+- **A000088** (M3 Pro) — DTLS-SRTP, wired/mains.
+- **A001513** ("L2") — SDES-SRTP, **battery** (woken on demand; validated end-to-end).
+- **A001064** (PTZ) — SDES-SRTP, wired/mains (role-reversal handshake).
+
+Other battery models (A001108, A001360) are recognized in code with the same
+battery handling. See [`docs/CAMERAS.md`](docs/CAMERAS.md#supported-cameras) for
+the authoritative table and per-model notes.
+
+## Library install
+
+Install from PyPI (the simplest, recommended method):
+
+```bash
+# lights + camera cloud/control only:
+pip install python-aidot-cameras
+# add live WebRTC streaming, snapshots, and two-way audio:
+pip install python-aidot-cameras[webrtc]
+```
+
+`[webrtc]` pulls in the extra dependencies (aiortc, av, …) needed for live
+streaming, snapshots, and two-way audio. Without it you still get lights plus
+the camera cloud/control APIs, but not live media.
+
+For the latest unreleased code, install straight from the GitHub repo instead:
+
+```bash
+# lights + camera cloud/control only:
+pip install "git+https://github.com/cbrightly/python-aidot-cameras"
+# add live WebRTC streaming, snapshots, and two-way audio:
+pip install "python-aidot-cameras[webrtc] @ git+https://github.com/cbrightly/python-aidot-cameras"
+```
+
+## Standalone CLI: `aidot-go2rtc`
+
+Bridge a camera into [go2rtc](https://github.com/AlexxIT/go2rtc) (or any
+RTSP/HTTP consumer) **without Home Assistant**. Installing the package provides
+the `aidot-go2rtc` console script; for an isolated tool install use pipx or uv:
+
+```bash
+pipx install "python-aidot-cameras[webrtc]"
+# or:
+uv tool install "python-aidot-cameras[webrtc]"
+
+aidot-go2rtc --list                  # discover cameras + their transport
+aidot-go2rtc <device_id> '{output}'  # stream one camera (as a go2rtc exec: source)
+```
+
+## Usage
+
+Open a live WebRTC stream from a camera device client:
+
+```python
+session = await device_client.async_open_webrtc_stream(on_frame=cb, timeout=30.0)
+# ... session.stop() when done
+```
+
+Two-way (push-to-talk) audio:
+
+```python
+session = await device_client.async_open_webrtc_stream(..., talk=True)
+await session.async_start_talk(pcm_provider)   # provider() -> 320B s16le PCM (20ms @ 8kHz), or None
+# ... speak ...
+await session.async_stop_talk()
+```
+
+See [`docs/CAMERAS.md`](docs/CAMERAS.md) for the full camera API (streaming,
+snapshots, recordings, motion polling, two-way audio, and LAN-direct media).
+
+## Home Assistant component and CLI
+
+The Home Assistant custom component (`custom_components/aidot/`) is **not** part
+of this library repo - it lives in the companion integration repo
+[`cbrightly/hass-aidot-cameras`](https://github.com/cbrightly/hass-aidot-cameras), which depends
+on this library. See that repo for installing the component (via HACS or by
+copying `custom_components/aidot/`).
+
+## Environment variables
+
+The library reads the following environment variables.
+
+### Credentials
+
+Used by the credential helper (`aidot.credentials`); they take priority over any
+stored credentials file. See [`src/aidot/credentials.py`](src/aidot/credentials.py).
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `AIDOT_USERNAME` | AiDot account username/email. Used with `AIDOT_PASSWORD`. | (none) |
+| `AIDOT_PASSWORD` | AiDot account password. Used with `AIDOT_USERNAME`. | (none) |
+| `AIDOT_COUNTRY` | Account region/country code. | `US` |
+
+### Camera streaming / tuning
+
+The most useful knobs read by the camera client (`aidot.camera.client`). Defaults
+are chosen to work out of the box; override only when tuning. Finer-grained
+internal knobs (audio normalization, keyframe/PLI cadence, retry timing, SDES
+audio, idle release, the sprop cache path) are documented in
+[`docs/CAMERAS.md`](docs/CAMERAS.md#advanced-tuning-environment-variables).
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `AIDOT_MAX_CONCURRENT_OPENS` | Caps how many stream opens run concurrently across all cameras. | `2` |
+| `AIDOT_MAX_CONCURRENT_STREAMS` | Caps how many cameras stream at once. | `3` |
+| `AIDOT_FAST_CONNECT` | Enable LAN-direct "fast connect" (STUN-only, skips several cloud signaling waits) when truthy. On-LAN only — off-subnet/strict-NAT viewers must leave it off. | unset (off) |
+| `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. | 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_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 soak cut SDES NO_MEDIA ~57%→~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) |
+| `AIDOT_LIVESTREAM_PARAM` | Set to `0` to skip the cloud `liveStreamParam` pre-connect that provisions battery cameras' live-stream sessions before signaling (without it, battery cameras like the L2 models reject streaming with `-50019`). | `1` (enabled) |
+
+### Security hardening
+
+Opt-in knobs that tighten the camera transport. Defaults preserve current
+behavior (the firmware's signaling doesn't carry verifiable material, so strict
+modes are off until you pin a value); each emits a one-time warning when left at
+the permissive default.
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `AIDOT_DTLS_PINNED_FP` | Pin the camera's DTLS certificate `sha-256` fingerprint (colon-separated hex). When set, a camera presenting a different cert fails the handshake instead of being accepted. The camera echoes our own fingerprint over signaling, so without a pin the media channel is **not** authenticated against an on-path MITM. | unset (accept-any + warn) |
+| `AIDOT_PLAYBACK_TLS_VERIFY` | Set to `1` to require full certificate + hostname verification on the TCP playback/live-stream TLS connection. Needs a trust anchor the camera's cert chains to; off by default because the camera presents a self-signed cert. | unset (no verification + warn) |
+| `AIDOT_ALLOW_LAN_SERVE` | Silences the warning emitted when decrypted media is served on a non-loopback bind (e.g. `0.0.0.0`), where any host on the LAN can read the unencrypted stream. Set when an exposed bind is intentional. | unset (warn on non-loopback) |
+| `AIDOT_SDES_HOLEPUNCH_HOST` | Override the NAT hole-punch target used when the cloud supplies no TURN entry. By default a STUN packet goes to a hardcoded vendor TURN host; set this to a host of your choice, or empty (`AIDOT_SDES_HOLEPUNCH_HOST=`) to disable the hardcoded fallback entirely. | unset (hardcoded vendor host + warn) |
+| `AIDOT_CRED_KEY_FILE` | Path to the Fernet key file for stored credentials. Point it outside the config dir (ideally a separate secret store) so the key isn't co-located with the ciphertext. Applies to the default credentials path only (ignored when an explicit `creds_path` is passed). | `$XDG_CONFIG_HOME/aidot/.key` (falls back to `~/.config/aidot/.key`) |

{python_aidot_cameras-0.9.1 → python_aidot_cameras-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-aidot-cameras"
-version = "0.9.1"
+version = "0.10.0"
 description = "Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)"
 readme = "README.md"
 license = "MIT"
@@ -45,6 +45,12 @@ webrtc = [
     "Pillow",
 ]
 
+[project.scripts]
+# Standalone bridge: stream an AiDot camera into go2rtc (or any RTSP/HTTP
+# consumer) without Home Assistant. Streaming needs the `webrtc` extra
+# (aiortc et al.); `--list` works with the core deps alone.
+aidot-go2rtc = "aidot.__main__:main"
+
 [project.urls]
 Homepage = "https://github.com/cbrightly/python-aidot-cameras"
 "Issue Tracker" = "https://github.com/cbrightly/python-aidot-cameras/issues"

python_aidot_cameras-0.10.0/src/aidot/__main__.py

@@ -0,0 +1,268 @@
+"""Bridge an AiDot camera into go2rtc (or any RTSP/HTTP consumer), without HA.
+
+AiDot cameras expose no RTSP/ONVIF endpoint - the only way to get video is the
+cloud signaling + WebRTC (DTLS/SDES) handshake and SRTP decrypt this library
+does via aiortc.  This entrypoint is the thin glue that lets a standalone go2rtc
+use them: it authenticates to the AiDot cloud, opens the keepalive session for
+one camera, and pushes/serves the decrypted H.264 (+ G711 audio on the RTSP-push
+path) to a URL the consumer reads.
+
+Run it as ``aidot-go2rtc`` (console script) or ``python -m aidot``.
+
+Two modes:
+
+  * --list                 Print every camera on the account with its device id
+                           and transport (SDES = RTSP-push capable, DTLS =
+                           HTTP-pull only).  Use this to fill in go2rtc.yaml.
+
+  * <dev_id> <output_url>   Stream one camera.  Meant to be invoked by go2rtc as
+                           an ``exec:`` source - go2rtc substitutes ``{output}``
+                           with its own publish URL.
+
+Authentication (in precedence order):
+
+  AIDOT_TOKEN_FILE=/path/to/token.json   A stored login_info dict (the same one
+                                         the HA integration persists). Token
+                                         rotations are written back to this file
+                                         (set_token_fresh_cb), so a standalone
+                                         run survives refreshes and restarts.
+  AIDOT_USERNAME / AIDOT_PASSWORD / AIDOT_COUNTRY (default US)
+                                         Full login. RECOMMENDED for long-running
+                                         standalone use: a dedicated login avoids
+                                         fighting HA over a shared (rotating)
+                                         refresh token. Pair with AIDOT_TOKEN_FILE
+                                         to cache the result across restarts.
+
+Optional stream knobs:
+
+  AIDOT_FAST_CONNECT=1        LAN-direct mode (skip TURN relay; same-subnet only)
+  AIDOT_SDES_SERVE_AUDIO=1    include audio on the SDES *http-serve* path (off by
+                              default - the AAC-under-loss deadlock). The RTSP-push
+                              path always carries G711 audio regardless.
+
+go2rtc.yaml example (SDES camera - native RTSP push, video + audio):
+
+    streams:
+      frontdoor: exec:aidot-go2rtc 8d2521ea... {output}
+
+For a DTLS camera (A000088) there is no RTSP-push path; pass an http serve URL
+(http://127.0.0.1:PORT/name.ts) and add it to go2rtc as an http-mpegts source -
+but this process must stay running to keep that serve bound.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import signal
+import sys
+
+import aiohttp
+
+from .client import AidotClient
+from .const import CONF_DEVICE_LIST, CONF_ID, CONF_MODEL_ID
+
+_LOGGER = logging.getLogger("aidot.go2rtc")
+
+DEFAULT_COUNTRY = os.environ.get("AIDOT_COUNTRY", "US")
+
+
+def _env_bool(name: str) -> bool | None:
+    """Tri-state env flag: '1' -> True, '0' -> False, unset -> None (library default)."""
+    raw = os.environ.get(name)
+    if raw is None:
+        return 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:
+    """Blocking write of login_info to ``path`` with 0600 perms."""
+    with open(path, "w", encoding="utf-8") as fh:
+        json.dump(data, fh)
+    os.chmod(path, 0o600)
+
+
+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.login_info)
+            _LOGGER.debug("Cached refreshed token to %s", path)
+        except OSError as exc:
+            _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):
+        token = await loop.run_in_executor(None, _read_token_file, token_file)
+        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.login_info)
+        except OSError 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()
+    return [
+        d for d in data[CONF_DEVICE_LIST]
+        if "IPC" in (d.get(CONF_MODEL_ID) or "").upper()
+    ]
+
+
+async def cmd_list() -> int:
+    """Print device id + transport for every camera, for go2rtc.yaml."""
+    async with aiohttp.ClientSession() as session:
+        client = await _make_client(session)
+        cams = await _cameras(client)
+        if not cams:
+            print("No IPC cameras found on this account.")
+            return 1
+        print(f"{'device_id':<40}  {'model':<14}  transport")
+        print("-" * 72)
+        for d in cams:
+            dc = client.get_device_client(d)
+            transport = "SDES (rtsp-push)" if dc.is_sdes_camera else "DTLS (http-pull)"
+            print(f"{d[CONF_ID]:<40}  {(d.get(CONF_MODEL_ID) or ''):<14}  {transport}")
+    return 0
+
+
+async def cmd_stream(dev_id: str, output_url: str) -> int:
+    """Open one camera's keepalive and push/serve it to ``output_url``."""
+    async with aiohttp.ClientSession() as session:
+        client = await _make_client(session)
+        cams = await _cameras(client)
+        device = next((d for d in cams if d[CONF_ID] == dev_id), None)
+        if device is None:
+            sys.exit(f"Camera {dev_id!r} not found. Run with --list to see ids.")
+
+        dc = client.get_device_client(device)
+
+        if not output_url.startswith("rtsp") and dc.is_sdes_camera:
+            _LOGGER.warning(
+                "SDES camera but output %r is not rtsp:// - the library will "
+                "HTTP-serve (video only by default) instead of pushing audio+video. "
+                "For go2rtc exec, pass {output}.",
+                output_url,
+            )
+        if output_url.startswith("rtsp") and not dc.is_sdes_camera:
+            sys.exit(
+                f"{dev_id} is a DTLS camera - the library has no RTSP-push path "
+                "for it. Use an http://host:port/name.ts serve URL instead."
+            )
+
+        await dc.async_login()
+        await dc.start_keepalive(
+            rtsp_push_url=output_url,
+            fast_connect=_env_bool("AIDOT_FAST_CONNECT"),
+            sdes_audio=_env_bool("AIDOT_SDES_SERVE_AUDIO"),
+        )
+        _LOGGER.info("Streaming %s -> %s", dev_id, output_url)
+
+        # start_keepalive only launches the background task; hold the process open
+        # so the consumer keeps reading. Exit cleanly on SIGTERM/SIGINT (go2rtc
+        # kills the exec child when no client is watching) so the cloud session is
+        # released.
+        stop = asyncio.Event()
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGTERM, signal.SIGINT):
+            try:
+                loop.add_signal_handler(sig, stop.set)
+            except NotImplementedError:  # pragma: no cover - non-POSIX
+                pass
+        try:
+            await stop.wait()
+        finally:
+            _LOGGER.info("Stopping stream for %s", dev_id)
+            try:
+                await dc.async_stop_streaming()
+            except Exception as exc:
+                _LOGGER.debug("stop_streaming failed: %s", exc)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="aidot-go2rtc",
+        description="Bridge an AiDot camera into go2rtc (HA-independent).",
+        epilog="Run with --list first to discover device ids and transports.",
+    )
+    parser.add_argument("dev_id", nargs="?", help="camera device id (see --list)")
+    parser.add_argument(
+        "output_url",
+        nargs="?",
+        help="consumer publish/serve URL; pass {output} from the exec: source",
+    )
+    parser.add_argument("--list", action="store_true", help="list cameras and exit")
+    parser.add_argument("-v", "--verbose", action="store_true", help="debug logging")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,  # keep stdout clean - the consumer may read it
+    )
+
+    if args.list:
+        return asyncio.run(cmd_list())
+    if not args.dev_id or not args.output_url:
+        parser.error("dev_id and output_url are required (or use --list)")
+    return asyncio.run(cmd_stream(args.dev_id, args.output_url))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())