feat: audio switch so the physical handset keeps its speaker during live views

[MIGI10]

Audio switch: keep the physical handset's speaker during live views

Problem

Every live view makes Ring route the intercom's incoming audio to the WebRTC session: the physical handset keeps showing video but its speaker goes silent (you can talk, you can't hear) until the stream closes. That's the right behaviour for the camera entity/companion card, which plays that audio, but wrong when the picture is consumed by something that never plays audio or does not need it — a go2rtc/Frigate restream for recording, or a TV/kiosk display that shows who is at the door while the user still picks up the physical handset to talk. In that second case the current behaviour is actively harmful: the handset rings, the TV shows the visitor, the user picks up and can't hear them.

Cause

Two things in the signaling python-ring-doorbell sends for every session:

• live_view → stream_options: {audio_enabled: true}
• on camera_connected → camera_options: {stealth_mode: false} — this is what ring-client-api calls activateCameraSpeaker().

The snapshot path in this component already uses audio_enabled: false and doesn't send camera_options, and snapshots don't take the handset audio.

Change

switch.<device>_audio, default on (= today's behaviour), state restored across restarts.

switch	live view gets	physical handset
on	video + audio	video, speaker muted while a session is open
off	video only	video + audio

• Every session now runs on _GatedRingWebRtcStream, a RingWebRtcStream subclass whose websocket property wraps the signaling socket in an AudioGate. The gate rewrites exactly two outgoing messages — live_view → stream_options.audio_enabled, camera_options → stealth_mode = not audio — and delegates everything else (recv, close, async for). No library code is copied.
• Toggling the switch while sessions are open is applied in place: stream_options + camera_options are sent as session messages (the same way ring-client-api sends them after activate_session). No renegotiation, no gap in the picture. The browser's audio transceiver is recvonly from the start and simply plays whatever RTP arrives.
• Independently of the switch, an offer is treated as video-only when it carries a session-level a=x-video-only attribute, or when every audio m-line is a=inactive / rejected (port 0). That is how a go2rtc/WHEP bridge, which cannot alter its own offer, asks for a session that never takes the audio.

New files: audio.py (policy, gate, hot toggle), switch.py. __init__.py loses the conditional class and gains the gate.

Why the out-of-band attribute

Rewriting the audio m-line of the offer itself (a=inactive or port 0) makes Ring stop sending video, so a consumer that can't change its own offer (go2rtc's WHEP client always offers video+audio recvonly) needs a way to flag the session that doesn't alter the media description. Unknown session attributes are ignored by Ring.

Tested

Ring Intercom Handset Video on a BTicino analog handset, HA 2026.x, go2rtc (Frigate-embedded) consuming through a small WHEP→camera/webrtc/offer bridge that inserts a=x-video-only:

• video streams to go2rtc/RTSP as before
• the BTicino handset keeps hearing the visitor during the stream (video on the TV, conversation on the handset)
• companion card unchanged (still gets audio, still mutes the handset — expected)
• debug log shows WebRTC <id>: audio=False, live_view sent with stream_options={'audio_enabled': False, ...}, camera_options sent as {'stealth_mode': True, ...}

Unit-checked against the real RingWebRtcStream class: offer classifier, gate rewrite in both states, passthrough of recv/close/async for, and the hot toggle (stream_options + camera_options carry the session's session_id/dialog_id, later library camera_options follow the new state).

Hot toggle on hardware: on mid-session works every time (handset mutes, live view gets audio). Off mid-session reliably mutes the live view; the handset usually gets its audio back at once, but occasionally only when the session ends. apply_audio_live sends stealth_mode: true first and repeats it after 1 s to improve the odds; documented as a known limitation in the README.

Docs

README gets an "Audio switch" section under the Lovelace options.

🤖 Generated with Claude Code

[MIGI10]

Mention that the initial feature in mind was to allow asking for a video-only session (for go2rtc to consume and display on a TV monitor without blocking the physical handset audio). The switch was added later to add value to the HA camera entity, taking advantage of the PR.