python-aidot-cameras 1.0.0b7__tar.gz → 1.0.0b9__tar.gz

python_aidot_cameras-1.0.0b9/MANIFEST.in

@@ -0,0 +1,3 @@
+# py.typed ships via pyproject.toml's package-data; nothing extra is needed
+# here. The previous line pointed at an `aidot/` directory that does not
+# exist in this distribution.

{python_aidot_cameras-1.0.0b7/python_aidot_cameras.egg-info → python_aidot_cameras-1.0.0b9}/PKG-INFO

@@ -1,16 +1,25 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0b7
+Version: 1.0.0b9
 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: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+License-File: aidot_cameras/_vendor/aiortc/LICENSE
 Requires-Dist: python-aidot<0.4,>=0.3.55
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: paho-mqtt>=1.6.1
@@ -33,7 +42,7 @@ Dynamic: license-file
 
 [![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)
+[![License: MIT](https://img.shields.io/pypi/l/python-aidot-cameras)](https://github.com/cbrightly/python-aidot-cameras/blob/main/LICENSE)
 
 Control AIDOT WiFi lights **and cameras** from Python.
 
@@ -46,7 +55,7 @@ recordings/thumbnails, and two-way (push-to-talk) audio.
 Upstream owns the `aidot` import name and handles non-camera devices (lights,
 plugs, switches) with none of this package's code in the path; everything here
 lives under `aidot_cameras`. Taking a new upstream release is a dependency bump
-plus a test run - see [`docs/UPSTREAM.md`](docs/UPSTREAM.md).
+plus a test run - see [`docs/UPSTREAM.md`](https://github.com/cbrightly/python-aidot-cameras/blob/main/docs/UPSTREAM.md).
 
 This repository is the **library** (distribution name `python-aidot-cameras`).
 The Home Assistant custom component (`custom_components/aidot/`) lives in the
@@ -63,7 +72,7 @@ The streaming transport is auto-selected per camera from its model id:
 - **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
+battery handling. See [`docs/CAMERAS.md`](https://github.com/cbrightly/python-aidot-cameras/blob/main/docs/CAMERAS.md#supported-cameras) for
 the authoritative table and per-model notes.
 
 ## Known characteristics
@@ -164,7 +173,25 @@ uv tool install "python-aidot-cameras[webrtc]"
 
 export AIDOT_USERNAME=... AIDOT_PASSWORD=...   # or AIDOT_TOKEN_FILE, see below
 aidot-go2rtc --list                  # discover cameras + their transport
-aidot-go2rtc <device_id> '{output}'  # stream one camera (as a go2rtc exec: source)
+
+# Stream one camera. Pick the form that matches how you are running it:
+aidot-go2rtc <device_id> -                              # MPEG-TS to stdout
+aidot-go2rtc <device_id> http://127.0.0.1:8555/cam.ts   # serve, then pull it
+aidot-go2rtc <device_id> '{output}'                     # go2rtc exec: source only
+```
+
+`'{output}'` is a placeholder go2rtc substitutes; run by hand it is passed
+through as an RTSP push URL, which DTLS cameras (A000088) have no path for and
+the tool refuses. Use `-` or an `http://host:port/name.ts` serve for a
+standalone run.
+
+**ffmpeg must be on PATH.** SDES cameras - two of the three validated models -
+stream entirely through an ffmpeg subprocess, and pip cannot install a system
+binary:
+
+```bash
+sudo apt install ffmpeg      # Debian/Ubuntu
+brew install ffmpeg          # macOS
 ```
 
 Authenticates via `AIDOT_USERNAME`/`AIDOT_PASSWORD` (`AIDOT_COUNTRY`, default
@@ -176,13 +203,49 @@ the full list of authentication and stream env vars.
 
 ## Usage
 
-Open a live WebRTC stream from a camera device client:
+Import from `aidot_cameras`, never from `aidot`. The upstream `aidot` package is
+a dependency of this one and its `AidotClient` is lights-only: importing from it
+gives you a client with no camera surface and **no ImportError** to tell you
+why.
+
+Log in, find a camera, and open a stream:
+
+```python
+import aiohttp
+from aidot_cameras.client import AidotClient
+from aidot_cameras.const import CONF_DEVICE_LIST, CONF_NAME
+
+async with aiohttp.ClientSession() as http:
+    client = AidotClient(http, country_code="US", username=..., password=...)
+    await client.async_post_login()
+    devices = (await client.async_get_all_device())[CONF_DEVICE_LIST]
+    cam = next(d for d in devices if d.get(CONF_NAME) == "Front Door")
+    device_client = client.get_device_client(cam)
+```
+
+`get_device_client` returns a `CameraDeviceClient` for a camera. Plain
+`DeviceClient` and `LightDeviceClient` are the lights clients and carry none of
+the camera surface, so a `hasattr` probe against the wrong one fails silently.
+
+Open a live WebRTC stream:
 
 ```python
 session = await device_client.async_open_webrtc_stream(on_frame=cb, timeout=30.0)
 # ... session.stop() when done
 ```
 
+`on_frame` receives a PyAV `av.VideoFrame` - use `pts` / `time_base` /
+`to_ndarray()`. It is **DTLS-only** (A000088): SDES cameras (A001513, A001064)
+decode out of process, so `on_frame` never fires for them and no error is
+raised. For those, take the media as a file or a stream instead:
+
+```python
+session = await device_client.async_open_webrtc_stream(
+    output_path="/tmp/live.ts",                      # record, or
+    rtsp_push_url="rtsp://127.0.0.1:8554/cam",       # push to go2rtc
+)
+```
+
 Two-way (push-to-talk) audio:
 
 ```python
@@ -192,9 +255,84 @@ await session.async_start_talk(pcm_provider)   # provider() -> 320B s16le PCM (2
 await session.async_stop_talk()
 ```
 
-See [`docs/CAMERAS.md`](docs/CAMERAS.md) for the full camera API (streaming,
+See [`docs/CAMERAS.md`](https://github.com/cbrightly/python-aidot-cameras/blob/main/docs/CAMERAS.md) for the full camera API (streaming,
 snapshots, recordings, motion polling, two-way audio, and LAN-direct media).
 
+## Getting an RTSP URL
+
+Want a plain `rtsp://` URL for Frigate, an NVR, or VLC? You can have one, but
+not from this library alone: **it does not run an RTSP server**, and neither do
+the cameras - they have no RTSP and no ONVIF endpoint. The only way video
+leaves them is the cloud-signalled WebRTC handshake and SRTP decrypt this
+library does. Pair it with [go2rtc](https://github.com/AlexxIT/go2rtc) and
+go2rtc publishes the RTSP URL for you.
+
+Three steps, about five minutes.
+
+**1. List your cameras.** The transport column decides one word in step 3, so
+keep the output around:
+
+```console
+$ pip install "python-aidot-cameras[webrtc]"
+$ export AIDOT_USERNAME='you@example.com' AIDOT_PASSWORD='...' AIDOT_COUNTRY=US
+$ aidot-go2rtc --list
+1a2b3c4d...  LK.IPC.A000088  DTLS (http-pull)
+5e6f7a8b...  LK.IPC.A001064  SDES (rtsp-push)
+```
+
+**2. Add one line per camera to `go2rtc.yaml`.** Both forms make go2rtc the
+parent process, so it starts the stream on the first viewer and kills it when
+the last one leaves - nothing talks to your cameras while nobody is watching:
+
+```yaml
+streams:
+  driveway:  exec:aidot-go2rtc 1a2b3c4d... -          # DTLS camera
+  frontdoor: exec:aidot-go2rtc 5e6f7a8b... {output}   # SDES camera
+```
+
+Use `-` for a DTLS camera and `{output}` for an SDES one - that is the whole
+difference, and `--list` told you which is which. (`{output}` is a placeholder
+go2rtc fills in with its own publish URL. It is not something you type at a
+shell; `-` is the form for that.) go2rtc needs the same `AIDOT_*` environment
+variables the CLI does, so set them wherever go2rtc starts.
+
+**3. Use the URL.** go2rtc serves every stream you named at:
+
+```
+rtsp://<go2rtc-host>:8554/driveway
+```
+
+Check it before wiring anything up to it:
+
+```console
+$ ffprobe rtsp://127.0.0.1:8554/driveway
+Stream #0:0: Video: h264 (High), yuv420p, 1280x720, 15 fps
+Stream #0:1: Audio: aac (LC), 48000 Hz, mono
+```
+
+### Details worth knowing
+
+- **Which camera is which.** `--list` reports the transport per device. DTLS is
+  the mains A000088; SDES is the A001064 / A001513 family. Passing the wrong
+  form is not silent - the CLI tells you which one to use and exits.
+- **Audio.** The SDES `{output}` push carries G.711 audio alongside video; the
+  DTLS `-` producer carries AAC (48 kHz mono, resampled from the camera's 8 kHz
+  A-law, because 8 kHz AAC plays silent in a lot of browsers).
+- **A stream that starts with no video** and picks it up a few seconds later is
+  normal: the mux waits for a keyframe so the first GOP is decodable. A stream
+  that stays audio-only is a camera that never sent one - retry the view.
+- **Skipping go2rtc.** `aidot-go2rtc <id> http://127.0.0.1:8555/cam.ts` serves
+  MPEG-TS on a listening socket instead, for a consumer that pulls rather than
+  spawns. That process has to stay running to keep the port bound, so it holds
+  a camera session whether or not anyone is watching. Prefer the `exec:` forms.
+- **From Python**, `rtsp_push_url=` publishes to your own RTSP server directly
+  (SDES cameras only - there is no RTSP-push path for DTLS), and
+  `output_path=` records to a file. `Go2RtcClient.rtsp_url(name)` builds the
+  address above, and `ensure_stream(name, source)` registers a stream with a
+  running go2rtc if you would rather not edit YAML.
+- **Home Assistant users need none of this.** The integration manages go2rtc
+  itself; this section is for standalone use.
+
 ## Home Assistant component and CLI
 
 The Home Assistant custom component (`custom_components/aidot/`) is **not** part
@@ -210,7 +348,7 @@ The library reads the following environment variables.
 ### Credentials
 
 Used by the credential helper (`aidot.credentials`); they take priority over any
-stored credentials file. See [`aidot_cameras/credentials.py`](aidot_cameras/credentials.py).
+stored credentials file. See [`aidot_cameras/credentials.py`](https://github.com/cbrightly/python-aidot-cameras/blob/main/aidot_cameras/credentials.py).
 
 | Variable | Purpose | Default |
 | --- | --- | --- |
@@ -224,7 +362,7 @@ The most useful knobs read by the camera client (`aidot_cameras.camera.client`).
 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).
+[`docs/CAMERAS.md`](https://github.com/cbrightly/python-aidot-cameras/blob/main/docs/CAMERAS.md#advanced-tuning-environment-variables).
 
 | Variable | Purpose | Default |
 | --- | --- | --- |

{python_aidot_cameras-1.0.0b7 → python_aidot_cameras-1.0.0b9}/README.md

@@ -2,7 +2,7 @@
 
 [![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)
+[![License: MIT](https://img.shields.io/pypi/l/python-aidot-cameras)](https://github.com/cbrightly/python-aidot-cameras/blob/main/LICENSE)
 
 Control AIDOT WiFi lights **and cameras** from Python.
 
@@ -15,7 +15,7 @@ recordings/thumbnails, and two-way (push-to-talk) audio.
 Upstream owns the `aidot` import name and handles non-camera devices (lights,
 plugs, switches) with none of this package's code in the path; everything here
 lives under `aidot_cameras`. Taking a new upstream release is a dependency bump
-plus a test run - see [`docs/UPSTREAM.md`](docs/UPSTREAM.md).
+plus a test run - see [`docs/UPSTREAM.md`](https://github.com/cbrightly/python-aidot-cameras/blob/main/docs/UPSTREAM.md).
 
 This repository is the **library** (distribution name `python-aidot-cameras`).
 The Home Assistant custom component (`custom_components/aidot/`) lives in the
@@ -32,7 +32,7 @@ The streaming transport is auto-selected per camera from its model id:
 - **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
+battery handling. See [`docs/CAMERAS.md`](https://github.com/cbrightly/python-aidot-cameras/blob/main/docs/CAMERAS.md#supported-cameras) for
 the authoritative table and per-model notes.
 
 ## Known characteristics
@@ -133,7 +133,25 @@ uv tool install "python-aidot-cameras[webrtc]"
 
 export AIDOT_USERNAME=... AIDOT_PASSWORD=...   # or AIDOT_TOKEN_FILE, see below
 aidot-go2rtc --list                  # discover cameras + their transport
-aidot-go2rtc <device_id> '{output}'  # stream one camera (as a go2rtc exec: source)
+
+# Stream one camera. Pick the form that matches how you are running it:
+aidot-go2rtc <device_id> -                              # MPEG-TS to stdout
+aidot-go2rtc <device_id> http://127.0.0.1:8555/cam.ts   # serve, then pull it
+aidot-go2rtc <device_id> '{output}'                     # go2rtc exec: source only
+```
+
+`'{output}'` is a placeholder go2rtc substitutes; run by hand it is passed
+through as an RTSP push URL, which DTLS cameras (A000088) have no path for and
+the tool refuses. Use `-` or an `http://host:port/name.ts` serve for a
+standalone run.
+
+**ffmpeg must be on PATH.** SDES cameras - two of the three validated models -
+stream entirely through an ffmpeg subprocess, and pip cannot install a system
+binary:
+
+```bash
+sudo apt install ffmpeg      # Debian/Ubuntu
+brew install ffmpeg          # macOS
 ```
 
 Authenticates via `AIDOT_USERNAME`/`AIDOT_PASSWORD` (`AIDOT_COUNTRY`, default
@@ -145,13 +163,49 @@ the full list of authentication and stream env vars.
 
 ## Usage
 
-Open a live WebRTC stream from a camera device client:
+Import from `aidot_cameras`, never from `aidot`. The upstream `aidot` package is
+a dependency of this one and its `AidotClient` is lights-only: importing from it
+gives you a client with no camera surface and **no ImportError** to tell you
+why.
+
+Log in, find a camera, and open a stream:
+
+```python
+import aiohttp
+from aidot_cameras.client import AidotClient
+from aidot_cameras.const import CONF_DEVICE_LIST, CONF_NAME
+
+async with aiohttp.ClientSession() as http:
+    client = AidotClient(http, country_code="US", username=..., password=...)
+    await client.async_post_login()
+    devices = (await client.async_get_all_device())[CONF_DEVICE_LIST]
+    cam = next(d for d in devices if d.get(CONF_NAME) == "Front Door")
+    device_client = client.get_device_client(cam)
+```
+
+`get_device_client` returns a `CameraDeviceClient` for a camera. Plain
+`DeviceClient` and `LightDeviceClient` are the lights clients and carry none of
+the camera surface, so a `hasattr` probe against the wrong one fails silently.
+
+Open a live WebRTC stream:
 
 ```python
 session = await device_client.async_open_webrtc_stream(on_frame=cb, timeout=30.0)
 # ... session.stop() when done
 ```
 
+`on_frame` receives a PyAV `av.VideoFrame` - use `pts` / `time_base` /
+`to_ndarray()`. It is **DTLS-only** (A000088): SDES cameras (A001513, A001064)
+decode out of process, so `on_frame` never fires for them and no error is
+raised. For those, take the media as a file or a stream instead:
+
+```python
+session = await device_client.async_open_webrtc_stream(
+    output_path="/tmp/live.ts",                      # record, or
+    rtsp_push_url="rtsp://127.0.0.1:8554/cam",       # push to go2rtc
+)
+```
+
 Two-way (push-to-talk) audio:
 
 ```python
@@ -161,9 +215,84 @@ await session.async_start_talk(pcm_provider)   # provider() -> 320B s16le PCM (2
 await session.async_stop_talk()
 ```
 
-See [`docs/CAMERAS.md`](docs/CAMERAS.md) for the full camera API (streaming,
+See [`docs/CAMERAS.md`](https://github.com/cbrightly/python-aidot-cameras/blob/main/docs/CAMERAS.md) for the full camera API (streaming,
 snapshots, recordings, motion polling, two-way audio, and LAN-direct media).
 
+## Getting an RTSP URL
+
+Want a plain `rtsp://` URL for Frigate, an NVR, or VLC? You can have one, but
+not from this library alone: **it does not run an RTSP server**, and neither do
+the cameras - they have no RTSP and no ONVIF endpoint. The only way video
+leaves them is the cloud-signalled WebRTC handshake and SRTP decrypt this
+library does. Pair it with [go2rtc](https://github.com/AlexxIT/go2rtc) and
+go2rtc publishes the RTSP URL for you.
+
+Three steps, about five minutes.
+
+**1. List your cameras.** The transport column decides one word in step 3, so
+keep the output around:
+
+```console
+$ pip install "python-aidot-cameras[webrtc]"
+$ export AIDOT_USERNAME='you@example.com' AIDOT_PASSWORD='...' AIDOT_COUNTRY=US
+$ aidot-go2rtc --list
+1a2b3c4d...  LK.IPC.A000088  DTLS (http-pull)
+5e6f7a8b...  LK.IPC.A001064  SDES (rtsp-push)
+```
+
+**2. Add one line per camera to `go2rtc.yaml`.** Both forms make go2rtc the
+parent process, so it starts the stream on the first viewer and kills it when
+the last one leaves - nothing talks to your cameras while nobody is watching:
+
+```yaml
+streams:
+  driveway:  exec:aidot-go2rtc 1a2b3c4d... -          # DTLS camera
+  frontdoor: exec:aidot-go2rtc 5e6f7a8b... {output}   # SDES camera
+```
+
+Use `-` for a DTLS camera and `{output}` for an SDES one - that is the whole
+difference, and `--list` told you which is which. (`{output}` is a placeholder
+go2rtc fills in with its own publish URL. It is not something you type at a
+shell; `-` is the form for that.) go2rtc needs the same `AIDOT_*` environment
+variables the CLI does, so set them wherever go2rtc starts.
+
+**3. Use the URL.** go2rtc serves every stream you named at:
+
+```
+rtsp://<go2rtc-host>:8554/driveway
+```
+
+Check it before wiring anything up to it:
+
+```console
+$ ffprobe rtsp://127.0.0.1:8554/driveway
+Stream #0:0: Video: h264 (High), yuv420p, 1280x720, 15 fps
+Stream #0:1: Audio: aac (LC), 48000 Hz, mono
+```
+
+### Details worth knowing
+
+- **Which camera is which.** `--list` reports the transport per device. DTLS is
+  the mains A000088; SDES is the A001064 / A001513 family. Passing the wrong
+  form is not silent - the CLI tells you which one to use and exits.
+- **Audio.** The SDES `{output}` push carries G.711 audio alongside video; the
+  DTLS `-` producer carries AAC (48 kHz mono, resampled from the camera's 8 kHz
+  A-law, because 8 kHz AAC plays silent in a lot of browsers).
+- **A stream that starts with no video** and picks it up a few seconds later is
+  normal: the mux waits for a keyframe so the first GOP is decodable. A stream
+  that stays audio-only is a camera that never sent one - retry the view.
+- **Skipping go2rtc.** `aidot-go2rtc <id> http://127.0.0.1:8555/cam.ts` serves
+  MPEG-TS on a listening socket instead, for a consumer that pulls rather than
+  spawns. That process has to stay running to keep the port bound, so it holds
+  a camera session whether or not anyone is watching. Prefer the `exec:` forms.
+- **From Python**, `rtsp_push_url=` publishes to your own RTSP server directly
+  (SDES cameras only - there is no RTSP-push path for DTLS), and
+  `output_path=` records to a file. `Go2RtcClient.rtsp_url(name)` builds the
+  address above, and `ensure_stream(name, source)` registers a stream with a
+  running go2rtc if you would rather not edit YAML.
+- **Home Assistant users need none of this.** The integration manages go2rtc
+  itself; this section is for standalone use.
+
 ## Home Assistant component and CLI
 
 The Home Assistant custom component (`custom_components/aidot/`) is **not** part
@@ -179,7 +308,7 @@ The library reads the following environment variables.
 ### Credentials
 
 Used by the credential helper (`aidot.credentials`); they take priority over any
-stored credentials file. See [`aidot_cameras/credentials.py`](aidot_cameras/credentials.py).
+stored credentials file. See [`aidot_cameras/credentials.py`](https://github.com/cbrightly/python-aidot-cameras/blob/main/aidot_cameras/credentials.py).
 
 | Variable | Purpose | Default |
 | --- | --- | --- |
@@ -193,7 +322,7 @@ The most useful knobs read by the camera client (`aidot_cameras.camera.client`).
 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).
+[`docs/CAMERAS.md`](https://github.com/cbrightly/python-aidot-cameras/blob/main/docs/CAMERAS.md#advanced-tuning-environment-variables).
 
 | Variable | Purpose | Default |
 | --- | --- | --- |

{python_aidot_cameras-1.0.0b7 → python_aidot_cameras-1.0.0b9}/aidot_cameras/__init__.py

@@ -13,6 +13,12 @@ import time as _time
 from .client import AidotClient, CameraClient
 from .device_client import CameraDeviceClient, DeviceInformation, DeviceStatusData
 from .camera.client import configure_stream_limits
+# Promised by docs/API-STABILITY.md and previously not reachable from the
+# package root. Verified to pull no optional dependency: importing these does
+# not drag in av or aiortc, so a plain (non-[webrtc]) install still imports.
+from .camera.models import CameraDeviceInformation, CameraStatusData
+from .camera.sdes import SdesSession
+from .camera.webrtc import WebRTCSession
 from .discover import CameraDiscover, Discover
 from .exceptions import (
     AidotAuthFailed,
@@ -141,12 +147,16 @@ __all__ = [
     "AidotUserOrPassIncorrect",
     "CameraClient",
     "CameraDeviceClient",
+    "CameraDeviceInformation",
     "CameraDiscover",
+    "CameraStatusData",
     "DeviceInformation",
     "DeviceStatusData",
     "Discover",
     "HTTPError",
     "InvalidHost",
     "InvalidURL",
+    "SdesSession",
+    "WebRTCSession",
     "configure_stream_limits",
 ]

{python_aidot_cameras-1.0.0b7 → python_aidot_cameras-1.0.0b9}/aidot_cameras/__main__.py

@@ -7,13 +7,16 @@ 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``.
+Run it as ``aidot-go2rtc`` (console script) or ``python -m aidot_cameras``.
 
 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.
+                           and transport, followed by a paste-ready go2rtc
+                           ``streams:`` block - each camera already paired with
+                           the right output argument, which is the one thing
+                           that differs between the transports and the easiest
+                           thing to get wrong.
 
   * <dev_id> <output_url>   Stream one camera.  Meant to be invoked by go2rtc as
                            an ``exec:`` source - go2rtc substitutes ``{output}``
@@ -66,14 +69,16 @@ 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 .const import CONF_DEVICE_LIST, CONF_ID, CONF_MODEL_ID
+from .const import CONF_DEVICE_LIST, CONF_ID, CONF_MODEL_ID, CONF_NAME
 
 _LOGGER = logging.getLogger("aidot.go2rtc")
 
@@ -206,8 +211,30 @@ async def _cameras(client: AidotClient) -> list[dict]:
     ]
 
 
+def _stream_slug(name: Optional[str], dev_id: str) -> str:
+    """A go2rtc stream key from the camera's name (``Front Door`` -> ``front_door``).
+
+    go2rtc stream names end up in URLs, so keep it to lowercase word characters
+    and fall back to the device id when a name is missing or is punctuation
+    only.  Pure (unit-testable)."""
+    slug = re.sub(r"[^a-z0-9]+", "_", (name or "").lower()).strip("_")
+    return slug or f"camera_{dev_id[:8]}"
+
+
+def _go2rtc_source(dev_id: str, is_sdes: bool) -> str:
+    """The ``exec:`` source line for one camera.
+
+    The only difference between the two transports is the output argument:
+    SDES cameras RTSP-push into go2rtc's own ``{output}`` URL, DTLS cameras
+    write MPEG-TS to stdout (``-``).  Getting that backwards is the single most
+    common way to end up with a stream that never starts, which is why --list
+    writes the line out rather than describing it."""
+    out = "{output}" if is_sdes else "-"
+    return f"exec:aidot-go2rtc {dev_id} {out}"
+
+
 async def cmd_list() -> int:
-    """Print device id + transport for every camera, for go2rtc.yaml."""
+    """Print device id + transport for every camera, plus paste-ready go2rtc YAML."""
     async with aiohttp.ClientSession() as session:
         client = await _make_client(session)
         cams = await _cameras(client)
@@ -216,10 +243,20 @@ async def cmd_list() -> int:
             return 1
         print(f"{'device_id':<40}  {'model':<14}  transport")
         print("-" * 72)
+        rows = []
         for d in cams:
             dc = client.get_device_client(d)
-            transport = "SDES (rtsp-push)" if dc.is_sdes_camera else "DTLS (http-pull)"
+            transport = "SDES (rtsp-push)" if dc.is_sdes_camera else "DTLS (stdout)"
             print(f"{d[CONF_ID]:<40}  {(d.get(CONF_MODEL_ID) or ''):<14}  {transport}")
+            rows.append((_stream_slug(d.get(CONF_NAME), d[CONF_ID]),
+                         _go2rtc_source(d[CONF_ID], dc.is_sdes_camera)))
+        width = max(len(slug) for slug, _ in rows) + 1
+        print("\n# Paste into go2rtc.yaml (rename the streams to taste). go2rtc needs")
+        print("# the same AIDOT_* environment variables this command just used.")
+        print("streams:")
+        for slug, source in rows:
+            print(f"  {(slug + ':'):<{width}} {source}")
+        print("\n# Then each camera is at rtsp://<go2rtc-host>:8554/<stream-name>")
     return 0
 
 
@@ -293,9 +330,13 @@ async def cmd_stream(dev_id: str, output_url: str) -> int:
 
 
 def main(argv: list[str] | None = None) -> int:
+    # The module docstring above IS the reference for every env var this tool
+    # reads, and the README tells users --help will show it. Print it rather
+    # than a one-line summary that leaves them hunting through source.
     parser = argparse.ArgumentParser(
         prog="aidot-go2rtc",
-        description="Bridge an AiDot camera into go2rtc (HA-independent).",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="Run with --list first to discover device ids and transports.",
     )
     parser.add_argument("dev_id", nargs="?", help="camera device id (see --list)")

python_aidot_cameras-1.0.0b9/aidot_cameras/_vendor/aiortc/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) Jeremy Lainé.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice,
+      this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice,
+      this list of conditions and the following disclaimer in the documentation
+      and/or other materials provided with the distribution.
+    * Neither the name of aiortc nor the names of its contributors may
+      be used to endorse or promote products derived from this software without
+      specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.