python-aidot-cameras 1.0.0rc5__tar.gz → 1.0.0rc7__tar.gz

{python_aidot_cameras-1.0.0rc5/python_aidot_cameras.egg-info → python_aidot_cameras-1.0.0rc7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0rc5
+Version: 1.0.0rc7
 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
@@ -200,9 +200,40 @@ pip install "python-aidot-cameras[webrtc] @ git+https://github.com/cbrightly/pyt
 
 ## 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:
+### What it does
+
+These cameras do not speak RTSP. They stream over WebRTC, negotiated through
+AiDot's cloud with a per-session key exchange, which is why you cannot simply
+point VLC or Frigate at one and get a picture.
+
+`aidot-go2rtc` does that negotiation for you and hands the result out as
+something ordinary: an MPEG-TS stream on stdout, an HTTP endpoint, or an RTSP
+push into [go2rtc](https://github.com/AlexxIT/go2rtc). One camera per process.
+From there anything that reads RTSP or TS can consume it.
+
+### Why you would use it
+
+- **You want these cameras in something that is not Home Assistant** -- Frigate,
+  a standalone go2rtc, an NVR, a browser, `ffmpeg` writing to disk.
+- **You want the streaming stack outside Home Assistant's Python environment,**
+  so its dependencies cannot collide with Home Assistant's pins.
+- **You are debugging.** `--list` shows every camera and which transport it uses,
+  and a single camera can be streamed in isolation with the env knobs below,
+  which is far easier to reason about than the same thing inside Home Assistant.
+
+### When you do not need it
+
+**If you use Home Assistant, install the integration instead** -- it does all of
+this for you, and running both at once means two clients competing for the same
+camera. A camera serves a limited number of concurrent viewers and holds a slot
+for about 120 s after one leaves, so the loser gets a clean handshake and then no
+media at all. The limit belongs to the device, so a second AiDot account with the
+house shared to it does not avoid it.
+
+### Installing
+
+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]"
@@ -212,16 +243,48 @@ 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
 
-# Stream one camera. Pick the form that matches how you are running it:
-aidot-go2rtc <device_id> -                              # DTLS: MPEG-TS to stdout
-aidot-go2rtc <device_id> '{output}'                     # SDES: go2rtc exec: only
-aidot-go2rtc <device_id> http://127.0.0.1:8555/cam.ts   # either: serve, then pull
+# Stream one camera. The second argument is WHERE the media should go:
+aidot-go2rtc <device_id> -                              # to stdout
+aidot-go2rtc <device_id> '{output}'                     # go2rtc fills this in
+aidot-go2rtc <device_id> http://127.0.0.1:8555/cam.ts   # serve, then pull
 ```
 
-`'{output}'` is a placeholder go2rtc substitutes; run by hand it is passed
-through as an RTSP push URL. Both transports can push, so `{output}` works on
-any camera - but on a DTLS one prefer `-`, which carries the mux's 48 kHz AAC
-untouched where the push has to transcode audio down to 8 kHz G.711.
+**Which form to use.** `--list` tells you each camera's transport, and that
+decides it:
+
+| your camera | use | why |
+| --- | --- | --- |
+| **DTLS** (mains, e.g. A000088) | `-` | keeps the mux's 48 kHz AAC. The push path has to transcode audio down to 8 kHz G.711 |
+| **SDES** (the A001513 and A001064 families) | `'{output}'` | these stream by pushing RTSP; there is nothing to read from stdout |
+| either, if you want to pull | an `http://` URL | the process serves there and waits for a consumer to connect |
+
+`'{output}'` is a placeholder that go2rtc substitutes with the stream's own push
+URL when it launches the process from an `exec:` source -- quote it so your
+shell does not eat the braces. It is not something to type at a shell: run by
+hand the literal text is taken as a publish target and the push fails. To try
+the push path by hand, put a real `rtsp://` URL there instead. Both transports
+can push, so `{output}` works on any camera; the table is about which gives the
+better result, not what is possible.
+
+### Wiring it into go2rtc
+
+`--list` prints a paste-ready `streams:` block for every camera on the account,
+so you rarely have to write this by hand. It looks like this:
+
+```yaml
+streams:
+  front_door: exec:aidot-go2rtc 1234abcd... {output}
+  driveway:   exec:aidot-go2rtc 5678efgh... -
+```
+
+go2rtc launches one process per stream, on demand, and substitutes `{output}`
+with that stream's push URL.
+
+The process needs the same `AIDOT_*` environment variables you used above. It is
+launched as a child of go2rtc, so the practical answer is to put them where
+go2rtc itself gets its environment: export them in the shell before starting it,
+or set them in its service unit or container definition. If a stream fails
+immediately with an authentication error, that is the thing to check first.
 
 **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
@@ -299,6 +362,91 @@ await session.async_stop_talk()
 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).
 
+## Camera controls and state
+
+Controls are on the camera device client. Writes are confirmed by reading the
+value back on each model that offers them, because this firmware acknowledges
+writes it then ignores.
+
+```python
+await device_client.async_set_motion_detection(True)
+await device_client.async_set_night_vision("auto")   # auto | on | off
+await device_client.async_set_speaker_volume(50)
+await device_client.async_reboot()                    # see below
+```
+
+### Reboot
+
+```python
+sent = await device_client.async_reboot()
+```
+
+`async_reboot` sends the same `devActionReq({action: "RebootFunc", in: []})` the
+vendor app's camera settings page sends. Two things to know:
+
+* **It reports that the request was SENT, not that the camera rebooted.** A
+  reboot succeeds by taking the camera off the network, so waiting for an
+  acknowledgement would report a working reboot as a failure. Do not read
+  `True` as "it came back".
+* **It refuses when the cloud explicitly reports the camera offline**, mirroring
+  the app, which only offers the button on a reachable device.
+
+The camera is away for a few seconds afterwards, during which a viewer sees a
+session that connects and delivers nothing.
+
+### Sound detection
+
+The cameras can listen for glass breaking, a smoke alarm, a baby crying and a
+dog barking.
+
+```python
+flags = await device_client.async_get_sound_detection()
+# {'sound_enable': False, 'all_sound': True, 'glass_Break': False,
+#  'smoke_T3': False, 'smoke_T4': False, 'baby_cry': False}
+
+await device_client.async_set_sound_detection("glass_Break", True)
+```
+
+The keys come from the camera, not from a fixed table, so a model reporting a
+detector not listed above still works. A write is read-modify-write: the current
+list is fetched and sent back with one flag changed, rather than against a
+payload schema invented here.
+
+**`None` means unknown, never "all off".** A camera that does not answer -- a
+battery camera asleep, or a model without the feature -- returns `None`, and
+treating that as a set of disabled detectors would report a state the camera
+never claimed. A write refuses outright when there is no current list to echo.
+
+### WiFi and SD card
+
+```python
+await device_client.async_get_wifi_info()      # {'ssid': ..., 'rssi': 63}
+await device_client.async_get_sd_card_info()   # {'present': True, 'total': 29838,
+                                               #  'used': 28848, 'raw': [...]}
+```
+
+Only confirmed fields are named. `SDcardBaseInfo` answers positionally and its
+fourth value was nearly called "free" -- but on a card reading 29838 total and
+28848 used it returns 3, which is not a remainder (990) and looks like a
+percentage. It stays unnamed in `raw` rather than shipping a field that reports
+3 MB free on a 30 GB card. The units of `total` and `used` are unconfirmed too,
+so the numbers pass through exactly as the camera reports them.
+
+### Reading anything else the camera answers
+
+```python
+out = await device_client.async_query_device_action("getWorkMode")
+```
+
+`async_query_device_action` sends a read-only `devActionReq` and returns the
+camera's `out` payload. The cameras answer more actions than this library wraps
+-- `getWorkMode`, `getAutoAlarm`, `getRoiHuman` (human/vehicle/package
+detection), `getRoiPrivacy` and others. `None` means no reply, which is not the
+same as "unsupported".
+
+**Do not use it to send actions that change something** unless you know the
+payload shape. `SDcardFormatFunc` is one of the actions the cameras accept.
+
 ## Getting an RTSP URL
 
 Want a plain `rtsp://` URL for Frigate, an NVR, or VLC? You can have one, but
@@ -317,7 +465,7 @@ keep the output around:
 $ 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)
+1a2b3c4d...  LK.IPC.A000088  DTLS (stdout)
 5e6f7a8b...  LK.IPC.A001064  SDES (rtsp-push)
 ```
 
@@ -356,9 +504,10 @@ Stream #0:1: Audio: aac (LC), 48000 Hz, mono
 - **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).
+- **Audio.** Both forms carry AAC at 48 kHz mono, resampled from the camera's
+  8 kHz A-law, because 8 kHz AAC plays silent in a lot of browsers and browsers
+  on the MSE path have no mapping for G.711 at all. Audio is on by default; see
+  `AIDOT_SDES_SERVE_AUDIO` to turn it off.
 - **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.
@@ -418,7 +567,10 @@ audio, idle release, the sprop cache path) are documented in
 | `AIDOT_SDES_CONNECTION_MODE` | Which media path the SDES offer proposes: `auto` (default - every reachable candidate, and ICE priority prefers the LAN with the relay as last resort; measured on the full fleet, six of seven cameras stream direct and only the unit with no route to us rides the relay), `lan` (no relay at all - same lever as `AIDOT_SDES_SKIP_TURN_PREALLOC`, and battery cameras keep the relay regardless because a cloud-woken camera has no other path back), or `relay` (EXPERIMENTAL, and on the reference fleet it does not steer: even with `c=`/`m=` moved to the relay allocation and the WAN permission pre-installed, an A001064 and an A001513 both dialed our host address directly, learning it from our own ICE probes - forcing the relay for real would mean suppressing every direct-path outbound, which is unbuilt). Per-open `sdes_connection_mode` beats the env. Every session reports the path its media actually took as `media_stats().media_path` (`direct`/`relay`). | unset (`auto`) |
 | `AIDOT_SDES_ADAPTIVE` | Adaptive fast-with-fallback for the SDES keepalive loop: try the fast path first and fall back to the full relay path if a fast attempt delivers no media. A per-device cache skips the fast attempt on later views once it has failed. Truthy value enables. Ignored for battery cameras, where the fast path cannot win and its short grace truncates the cold start. | unset (off) |
 | `AIDOT_SDES_FAST_LIVEPLAY` | Don't block on the `livePlayResp` wait for eligible SDES cameras (~4.5 s faster cold start). Role-reversal models (A001064 PTZ) always excluded for correctness. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
-| `AIDOT_SDES_LIVEPLAY_ECHO_S` | How long to wait for the broker to echo our own `livePlayReq` back before sending `webrtcReq`, in seconds (`0` disables the wait). The wait was 5.0 s on the models excluded from fast-liveplay and is pure latency: across 22 h of one deployment it ran 169 times and timed out 169 times, never once ending early, with no inbound `livePlayReq` among 5000+ messages the cameras and broker did send. The code proceeds on timeout anyway, so it never changed behaviour, only delayed it. Measured on an A001064: time to first media 11534 ms -> 6819 ms. Still honoured, so a broker that does echo short-circuits it. | 0.25 s (1.5 s for fast-liveplay models) |
+| `AIDOT_SDES_LIVEPLAY_ECHO_S` | How long to wait for the broker to echo our own `livePlayReq` back before sending `webrtcReq`, in seconds (`0` disables the wait). It is pure latency: across 22 h of one deployment the wait ran 169 times and timed out 169 times, never once ending early, with no inbound `livePlayReq` among 5000+ messages the cameras and broker did send. The code proceeds on timeout anyway, so it never changed behaviour, only delayed it. Measured on an A001064: time to first media 11534 ms -> 6819 ms. The fast-liveplay path kept 1.5 s until it was measured on its own - 22 runs, 22 timeouts at 1500-1501 ms, no echo ever - and now shares the same value; that was 1.25 s of a 5.4 s cold connect. Still honoured, so a broker that does echo short-circuits it. | 0.25 s |
+| `AIDOT_BATTERY_WAKE_GATE_S` | Hold a **battery** camera's SDP offer until the camera itself answers, in seconds. **Measured and shipped off (`0`).** This is the official client's own shape - its live view fires the keep-alive, sends the wake, and shows a sleeping placeholder rather than opening a session until the device reports itself awake - and on this camera family it is self-defeating, because the live-play signalling is what wakes the camera: withholding the offer withholds the wake. At a 20 s budget, on a camera settled for ten minutes, the gate ran its whole budget with the camera silent, the offer went out at +20.9 s, the camera's own `wakeupStatus` arrived at +23.6 s (after the offer), and first media at +27.0 s - against 5.4-10.0 s on the same camera with no gate. Kept as a lever for anyone re-testing on other firmware. | `0` (off) |
+| `AIDOT_BATTERY_STALE_OFFER_GRACE_S` | Backstop for a **battery** attempt that stalls anyway, in seconds (`0` disables it). When the camera was silent as the first-media wait began, has since turned up, and has still sent no media after this long, the attempt is abandoned to the retry instead of holding the full 75 s window - a stalled camera answers and then sends nothing, while the retry's fresh offer is served in about 5 s. Measured from the camera's first sighting rather than its latest message, because a camera emitting an event every 5 s while its handshake goes nowhere would otherwise push the decision out until it had gone back to sleep. Sized clear of the slowest healthy open (10.7 s) so a merely slow attempt is never mistaken for a stalled one. | `15` |
+| `AIDOT_SDES_SERVE_AUDIO` | Include the camera's audio in what an SDES camera serves, on both the RTSP-push and http-serve paths. **On by default** for parity with the official app; set to `0`/`false`/`no`/`off` for video only, which is what a consumer that cannot cope with the audio wants. The standalone CLI reads this; inside Home Assistant the per-camera **Camera audio** switch is the same setting and should be used instead. | 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. **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`) |

{python_aidot_cameras-1.0.0rc5 → python_aidot_cameras-1.0.0rc7}/README.md

@@ -160,9 +160,40 @@ pip install "python-aidot-cameras[webrtc] @ git+https://github.com/cbrightly/pyt
 
 ## 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:
+### What it does
+
+These cameras do not speak RTSP. They stream over WebRTC, negotiated through
+AiDot's cloud with a per-session key exchange, which is why you cannot simply
+point VLC or Frigate at one and get a picture.
+
+`aidot-go2rtc` does that negotiation for you and hands the result out as
+something ordinary: an MPEG-TS stream on stdout, an HTTP endpoint, or an RTSP
+push into [go2rtc](https://github.com/AlexxIT/go2rtc). One camera per process.
+From there anything that reads RTSP or TS can consume it.
+
+### Why you would use it
+
+- **You want these cameras in something that is not Home Assistant** -- Frigate,
+  a standalone go2rtc, an NVR, a browser, `ffmpeg` writing to disk.
+- **You want the streaming stack outside Home Assistant's Python environment,**
+  so its dependencies cannot collide with Home Assistant's pins.
+- **You are debugging.** `--list` shows every camera and which transport it uses,
+  and a single camera can be streamed in isolation with the env knobs below,
+  which is far easier to reason about than the same thing inside Home Assistant.
+
+### When you do not need it
+
+**If you use Home Assistant, install the integration instead** -- it does all of
+this for you, and running both at once means two clients competing for the same
+camera. A camera serves a limited number of concurrent viewers and holds a slot
+for about 120 s after one leaves, so the loser gets a clean handshake and then no
+media at all. The limit belongs to the device, so a second AiDot account with the
+house shared to it does not avoid it.
+
+### Installing
+
+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]"
@@ -172,16 +203,48 @@ 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
 
-# Stream one camera. Pick the form that matches how you are running it:
-aidot-go2rtc <device_id> -                              # DTLS: MPEG-TS to stdout
-aidot-go2rtc <device_id> '{output}'                     # SDES: go2rtc exec: only
-aidot-go2rtc <device_id> http://127.0.0.1:8555/cam.ts   # either: serve, then pull
+# Stream one camera. The second argument is WHERE the media should go:
+aidot-go2rtc <device_id> -                              # to stdout
+aidot-go2rtc <device_id> '{output}'                     # go2rtc fills this in
+aidot-go2rtc <device_id> http://127.0.0.1:8555/cam.ts   # serve, then pull
 ```
 
-`'{output}'` is a placeholder go2rtc substitutes; run by hand it is passed
-through as an RTSP push URL. Both transports can push, so `{output}` works on
-any camera - but on a DTLS one prefer `-`, which carries the mux's 48 kHz AAC
-untouched where the push has to transcode audio down to 8 kHz G.711.
+**Which form to use.** `--list` tells you each camera's transport, and that
+decides it:
+
+| your camera | use | why |
+| --- | --- | --- |
+| **DTLS** (mains, e.g. A000088) | `-` | keeps the mux's 48 kHz AAC. The push path has to transcode audio down to 8 kHz G.711 |
+| **SDES** (the A001513 and A001064 families) | `'{output}'` | these stream by pushing RTSP; there is nothing to read from stdout |
+| either, if you want to pull | an `http://` URL | the process serves there and waits for a consumer to connect |
+
+`'{output}'` is a placeholder that go2rtc substitutes with the stream's own push
+URL when it launches the process from an `exec:` source -- quote it so your
+shell does not eat the braces. It is not something to type at a shell: run by
+hand the literal text is taken as a publish target and the push fails. To try
+the push path by hand, put a real `rtsp://` URL there instead. Both transports
+can push, so `{output}` works on any camera; the table is about which gives the
+better result, not what is possible.
+
+### Wiring it into go2rtc
+
+`--list` prints a paste-ready `streams:` block for every camera on the account,
+so you rarely have to write this by hand. It looks like this:
+
+```yaml
+streams:
+  front_door: exec:aidot-go2rtc 1234abcd... {output}
+  driveway:   exec:aidot-go2rtc 5678efgh... -
+```
+
+go2rtc launches one process per stream, on demand, and substitutes `{output}`
+with that stream's push URL.
+
+The process needs the same `AIDOT_*` environment variables you used above. It is
+launched as a child of go2rtc, so the practical answer is to put them where
+go2rtc itself gets its environment: export them in the shell before starting it,
+or set them in its service unit or container definition. If a stream fails
+immediately with an authentication error, that is the thing to check first.
 
 **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
@@ -259,6 +322,91 @@ await session.async_stop_talk()
 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).
 
+## Camera controls and state
+
+Controls are on the camera device client. Writes are confirmed by reading the
+value back on each model that offers them, because this firmware acknowledges
+writes it then ignores.
+
+```python
+await device_client.async_set_motion_detection(True)
+await device_client.async_set_night_vision("auto")   # auto | on | off
+await device_client.async_set_speaker_volume(50)
+await device_client.async_reboot()                    # see below
+```
+
+### Reboot
+
+```python
+sent = await device_client.async_reboot()
+```
+
+`async_reboot` sends the same `devActionReq({action: "RebootFunc", in: []})` the
+vendor app's camera settings page sends. Two things to know:
+
+* **It reports that the request was SENT, not that the camera rebooted.** A
+  reboot succeeds by taking the camera off the network, so waiting for an
+  acknowledgement would report a working reboot as a failure. Do not read
+  `True` as "it came back".
+* **It refuses when the cloud explicitly reports the camera offline**, mirroring
+  the app, which only offers the button on a reachable device.
+
+The camera is away for a few seconds afterwards, during which a viewer sees a
+session that connects and delivers nothing.
+
+### Sound detection
+
+The cameras can listen for glass breaking, a smoke alarm, a baby crying and a
+dog barking.
+
+```python
+flags = await device_client.async_get_sound_detection()
+# {'sound_enable': False, 'all_sound': True, 'glass_Break': False,
+#  'smoke_T3': False, 'smoke_T4': False, 'baby_cry': False}
+
+await device_client.async_set_sound_detection("glass_Break", True)
+```
+
+The keys come from the camera, not from a fixed table, so a model reporting a
+detector not listed above still works. A write is read-modify-write: the current
+list is fetched and sent back with one flag changed, rather than against a
+payload schema invented here.
+
+**`None` means unknown, never "all off".** A camera that does not answer -- a
+battery camera asleep, or a model without the feature -- returns `None`, and
+treating that as a set of disabled detectors would report a state the camera
+never claimed. A write refuses outright when there is no current list to echo.
+
+### WiFi and SD card
+
+```python
+await device_client.async_get_wifi_info()      # {'ssid': ..., 'rssi': 63}
+await device_client.async_get_sd_card_info()   # {'present': True, 'total': 29838,
+                                               #  'used': 28848, 'raw': [...]}
+```
+
+Only confirmed fields are named. `SDcardBaseInfo` answers positionally and its
+fourth value was nearly called "free" -- but on a card reading 29838 total and
+28848 used it returns 3, which is not a remainder (990) and looks like a
+percentage. It stays unnamed in `raw` rather than shipping a field that reports
+3 MB free on a 30 GB card. The units of `total` and `used` are unconfirmed too,
+so the numbers pass through exactly as the camera reports them.
+
+### Reading anything else the camera answers
+
+```python
+out = await device_client.async_query_device_action("getWorkMode")
+```
+
+`async_query_device_action` sends a read-only `devActionReq` and returns the
+camera's `out` payload. The cameras answer more actions than this library wraps
+-- `getWorkMode`, `getAutoAlarm`, `getRoiHuman` (human/vehicle/package
+detection), `getRoiPrivacy` and others. `None` means no reply, which is not the
+same as "unsupported".
+
+**Do not use it to send actions that change something** unless you know the
+payload shape. `SDcardFormatFunc` is one of the actions the cameras accept.
+
 ## Getting an RTSP URL
 
 Want a plain `rtsp://` URL for Frigate, an NVR, or VLC? You can have one, but
@@ -277,7 +425,7 @@ keep the output around:
 $ 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)
+1a2b3c4d...  LK.IPC.A000088  DTLS (stdout)
 5e6f7a8b...  LK.IPC.A001064  SDES (rtsp-push)
 ```
 
@@ -316,9 +464,10 @@ Stream #0:1: Audio: aac (LC), 48000 Hz, mono
 - **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).
+- **Audio.** Both forms carry AAC at 48 kHz mono, resampled from the camera's
+  8 kHz A-law, because 8 kHz AAC plays silent in a lot of browsers and browsers
+  on the MSE path have no mapping for G.711 at all. Audio is on by default; see
+  `AIDOT_SDES_SERVE_AUDIO` to turn it off.
 - **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.
@@ -378,7 +527,10 @@ audio, idle release, the sprop cache path) are documented in
 | `AIDOT_SDES_CONNECTION_MODE` | Which media path the SDES offer proposes: `auto` (default - every reachable candidate, and ICE priority prefers the LAN with the relay as last resort; measured on the full fleet, six of seven cameras stream direct and only the unit with no route to us rides the relay), `lan` (no relay at all - same lever as `AIDOT_SDES_SKIP_TURN_PREALLOC`, and battery cameras keep the relay regardless because a cloud-woken camera has no other path back), or `relay` (EXPERIMENTAL, and on the reference fleet it does not steer: even with `c=`/`m=` moved to the relay allocation and the WAN permission pre-installed, an A001064 and an A001513 both dialed our host address directly, learning it from our own ICE probes - forcing the relay for real would mean suppressing every direct-path outbound, which is unbuilt). Per-open `sdes_connection_mode` beats the env. Every session reports the path its media actually took as `media_stats().media_path` (`direct`/`relay`). | unset (`auto`) |
 | `AIDOT_SDES_ADAPTIVE` | Adaptive fast-with-fallback for the SDES keepalive loop: try the fast path first and fall back to the full relay path if a fast attempt delivers no media. A per-device cache skips the fast attempt on later views once it has failed. Truthy value enables. Ignored for battery cameras, where the fast path cannot win and its short grace truncates the cold start. | unset (off) |
 | `AIDOT_SDES_FAST_LIVEPLAY` | Don't block on the `livePlayResp` wait for eligible SDES cameras (~4.5 s faster cold start). Role-reversal models (A001064 PTZ) always excluded for correctness. **On by default**; set to `0`/`false`/`no`/`off` to disable. | enabled (on) |
-| `AIDOT_SDES_LIVEPLAY_ECHO_S` | How long to wait for the broker to echo our own `livePlayReq` back before sending `webrtcReq`, in seconds (`0` disables the wait). The wait was 5.0 s on the models excluded from fast-liveplay and is pure latency: across 22 h of one deployment it ran 169 times and timed out 169 times, never once ending early, with no inbound `livePlayReq` among 5000+ messages the cameras and broker did send. The code proceeds on timeout anyway, so it never changed behaviour, only delayed it. Measured on an A001064: time to first media 11534 ms -> 6819 ms. Still honoured, so a broker that does echo short-circuits it. | 0.25 s (1.5 s for fast-liveplay models) |
+| `AIDOT_SDES_LIVEPLAY_ECHO_S` | How long to wait for the broker to echo our own `livePlayReq` back before sending `webrtcReq`, in seconds (`0` disables the wait). It is pure latency: across 22 h of one deployment the wait ran 169 times and timed out 169 times, never once ending early, with no inbound `livePlayReq` among 5000+ messages the cameras and broker did send. The code proceeds on timeout anyway, so it never changed behaviour, only delayed it. Measured on an A001064: time to first media 11534 ms -> 6819 ms. The fast-liveplay path kept 1.5 s until it was measured on its own - 22 runs, 22 timeouts at 1500-1501 ms, no echo ever - and now shares the same value; that was 1.25 s of a 5.4 s cold connect. Still honoured, so a broker that does echo short-circuits it. | 0.25 s |
+| `AIDOT_BATTERY_WAKE_GATE_S` | Hold a **battery** camera's SDP offer until the camera itself answers, in seconds. **Measured and shipped off (`0`).** This is the official client's own shape - its live view fires the keep-alive, sends the wake, and shows a sleeping placeholder rather than opening a session until the device reports itself awake - and on this camera family it is self-defeating, because the live-play signalling is what wakes the camera: withholding the offer withholds the wake. At a 20 s budget, on a camera settled for ten minutes, the gate ran its whole budget with the camera silent, the offer went out at +20.9 s, the camera's own `wakeupStatus` arrived at +23.6 s (after the offer), and first media at +27.0 s - against 5.4-10.0 s on the same camera with no gate. Kept as a lever for anyone re-testing on other firmware. | `0` (off) |
+| `AIDOT_BATTERY_STALE_OFFER_GRACE_S` | Backstop for a **battery** attempt that stalls anyway, in seconds (`0` disables it). When the camera was silent as the first-media wait began, has since turned up, and has still sent no media after this long, the attempt is abandoned to the retry instead of holding the full 75 s window - a stalled camera answers and then sends nothing, while the retry's fresh offer is served in about 5 s. Measured from the camera's first sighting rather than its latest message, because a camera emitting an event every 5 s while its handshake goes nowhere would otherwise push the decision out until it had gone back to sleep. Sized clear of the slowest healthy open (10.7 s) so a merely slow attempt is never mistaken for a stalled one. | `15` |
+| `AIDOT_SDES_SERVE_AUDIO` | Include the camera's audio in what an SDES camera serves, on both the RTSP-push and http-serve paths. **On by default** for parity with the official app; set to `0`/`false`/`no`/`off` for video only, which is what a consumer that cannot cope with the audio wants. The standalone CLI reads this; inside Home Assistant the per-camera **Camera audio** switch is the same setting and should be used instead. | 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. **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`) |

{python_aidot_cameras-1.0.0rc5 → python_aidot_cameras-1.0.0rc7}/aidot_cameras/__main__.py

@@ -39,18 +39,20 @@ Authentication (in precedence order):
 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.
+  AIDOT_SDES_SERVE_AUDIO=0    audio is ON by default on both SDES output paths
+                              (app parity). Set 0/false/no/off for video only,
+                              which is what a consumer that cannot cope with the
+                              audio wants. Both paths encode AAC 48 kHz.
 
 go2rtc.yaml example (SDES camera - native RTSP push, video + audio):
 
     streams:
       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:
+A DTLS camera (A000088) can push RTSP too, but a stdout producer is the better
+default for it and 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:
       garage: exec:aidot-go2rtc 0a1b2c3d... -
@@ -89,11 +91,39 @@ _LOGGER = logging.getLogger("aidot.go2rtc")
 
 
 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"
+    """Tri-state env flag: truthy -> True, falsy -> False, anything else -> None.
+
+    ``None`` is the whole point, and it is not timidity.  A non-``None`` here is
+    passed to ``start_keepalive``, which stores it as the per-camera option - and
+    every library resolver checks that option *before* it looks at the
+    environment.  So a value returned from here does not merely beat the env var,
+    it outranks the library's entire resolution chain.  This reader knows the
+    spelling of a flag but not what any knob defaults to, so it must decline
+    rather than guess: unset, blank, or a word it cannot read all mean "no
+    opinion", leaving the decision where the default actually lives.
+
+    The library states each knob as "a recognised token flips it, anything else
+    keeps the default", spelled as a truthy allowlist where the default is off
+    (``AIDOT_FAST_CONNECT``) and a falsy denylist where the default is on
+    (``AIDOT_SDES_SERVE_AUDIO``).  Reading only the literal ``"1"`` broke that:
+    ``AIDOT_FAST_CONNECT=true`` became an explicit False and *disabled* the
+    feature.  Folding an unreadable value to False would break it the other way,
+    turning ``AIDOT_SDES_SERVE_AUDIO=`` - an ordinary empty-value shape in a
+    systemd unit or a compose file - into a silent loss of audio.
+
+    Not every knob is safe to route through this.  A handful still compare against
+    a bare ``"0"`` (``AIDOT_SERVE_RELAY``, ``AIDOT_INCLUDE_SHARED_HOUSES``), where
+    a word spelling reads as true whatever it says; passing one of those through
+    here would hand the library an override it disagrees with.  Check the
+    resolver before adding a knob to ``cmd_stream``."""
+    # Unset and unreadable are the same answer, so let the default reach the
+    # tuples rather than branching on it separately.
+    val = os.environ.get(name, "").strip().lower()
+    if val in ("1", "true", "yes", "on"):
+        return True
+    if val in ("0", "false", "no", "off"):
+        return False
+    return None
 
 
 async def _cameras(client: AidotClient) -> list[dict]:
@@ -187,14 +217,17 @@ async def cmd_stream(dev_id: str, output_url: str) -> int:
                 "stdout for a go2rtc exec: consumer."
             )
         elif output_url.startswith("rtsp") and not dc.is_sdes_camera:
+            # Why G.711 here: see the codec_args branch in camera/client.py.
             _LOGGER.info(
-                "DTLS RTSP push: publishing video + AAC audio to %s.", output_url
+                "DTLS RTSP push: publishing video + G.711 audio to %s. Pass '-' "
+                "instead to keep the mux's 48 kHz AAC.", output_url
             )
         elif 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}.",
+                "SDES camera but output %r is not rtsp:// - only an http(s) "
+                "output is served for a consumer to pull; anything else is "
+                "treated as a publish target and will fail. For go2rtc exec, "
+                "pass {output} and let go2rtc substitute its own rtsp:// URL.",
                 output_url,
             )
         await dc.async_login()

{python_aidot_cameras-1.0.0rc5 → python_aidot_cameras-1.0.0rc7}/aidot_cameras/camera/client.py

@@ -5970,8 +5970,8 @@ class CameraMixin(_CameraControlsMixin, _CameraSdMixin, _WebRTCOpenMixin, _SdesO
             # `-bsf:a aac_adtstoasc` does not save it: the header is written
             # before the filter has produced extradata.  So transcode to G.711
             # A-law, which is RTP-native, costs almost nothing at 8 kHz mono,
-            # and is exactly what the SDES push has always carried - the two
-            # push paths now put the same thing on the wire.
+            # and was what the SDES push carried until that path moved to AAC
+            # (fMP4/MSE has no G.711 mapping, so browsers got silence there).
             codec_args = ["-c:v", "copy", "-c:a", "pcm_alaw", "-ar", "8000", "-ac", "1"]
             out_args = ["-f", "rtsp", "-rtsp_transport", "tcp", serve_url]
             out_target = asyncio.subprocess.DEVNULL