fix(video): the panel's video bandwidth is an option, 256 kbit/s by default

[m4r1k]

What and why

Since 1.0.19 (#84) the integration asks every panel for 2 Mbit/s of video instead of 256 kbit/s. That was measured on a Tab 5S Up 40515, with no loss on its path. A Tab 7S Up 40517 over the cloud relay honours the request too, and its relay loses packets.

Measured in HomeKit views (no ring), from the integration's debug log:

	1.0.18 (Oct 1)	1.0.20 (Oct 6)
video packets/s from the panel	~20	~200
packets lost in a 12 s view	0-2	21, in bursts of up to 7
re-encoder frame delay, first view	47-72 ms	321 ms

On the phone and in the card the video smeared, froze and lagged. That was during two real deliveries, and in a preview that took about 20 s to show anything, although HA had sent the picture after 2.3 s. Ten times the packets through a relay that drops a few percent means ten times the damaged frames.

@Apeiv measured both values on his 40515 over the cloud: 720x576 at 24 fps (~1.9 Mbit/s) at 2048, 320x240 at 15 fps (~240 kbit/s) at 256, no loss at either, and the same first-frame time (~1.8-1.9 s).

So the bandwidth is now an option, "Video quality from the panel", on the general Vimar Intercom settings page. It applies to every video from the panel: card, camera, /av and HomeKit.

• Automatic (default): 2 Mbit/s on local UDP, 256 kbit/s over the cloud relay, the way view_keepalive's default already follows the transport.
• 256 kbit/s (lower resolution on some panels) or 2 Mbit/s (sharper, needs a clean connection), chosen by hand. No values in between until someone measures them.
• An unknown value counts as automatic.

Tested on

• Tab 7S Up 40517, firmware 2.1.0203, cloud TLS: my HA has run 1.0.20 with the bandwidth back at 256 since Oct 6.
• @Apeiv: Tab 5S Up 40515, cloud, both values (see above).
• @lollox80, Tab 7S 2F+ 40507 (2-wire, local UDP), 09/10 on 9fdccc8: an outside view on Automatic (existing entry, option never set) and one with 256 forced from the options. Saving the option reloaded the entry. Both views fine, no errors; the panel sent the same stream both times (~32 video packets/s, 15-55 bytes each, the same NAL mix, 0 SRTP failures), so the 2-wire Tab seems to ignore the requested bandwidth, at least on local UDP. Nothing changes on this plant; option set back to Automatic.
• Tests: the SDP for automatic on both transports, both forced values and an unknown one (restoring the runtime globals); the settings page saves the option and keeps a saved choice; the HomeKit page leaves it alone.
• Full suite: 2165 passed, coverage 95.92%, ruff clean.

Docs

Docs: CONFIGURATION.md and .it.md (the option), TROUBLESHOOTING.md and .it.md (a row for smeared, frozen or lagging video).

Changelog

Changelog: Bug fixes - Over the cloud the panel's video is back to 256 kbit/s by default: 2 Mbit/s smeared, froze and lagged on a Tab 7S Up 40517. A new setting, "Video quality from the panel", picks Automatic (2 Mbit/s on local UDP, 256 kbit/s over the cloud), 256 kbit/s or 2 Mbit/s.
Before you update: If your video was fine at 2 Mbit/s over the cloud (e.g. a Tab 5S Up 40515), set "Video quality from the panel" to 2 Mbit/s in the settings.

🤖 Generated with Claude Code

[lollox80]

Thanks, this is a clear report and a small, readable fix: the numbers (10× the packets, losses in bursts, 321 ms on
the first frame) make the case well.

A few things before it goes in:

1. Before you update: lowering the default changes the picture for everyone who is happy at 2 Mbit/s today (the
   40515 in Ask the panel for 2 Mbit/s of video instead of 256 kbit/s #84). Please add a line like: "Before you update: if your video was fine at 2 Mbit/s (e.g. a 40515), set
   'Video quality from the panel' back to 2 Mbit/s in the settings."
2. Docs: new options go into docs/CONFIGURATION.md and .it.md (CONTRIBUTING, docs rule). TROUBLESHOOTING
   has no row for a smearing or freezing video yet: once this is in, a row there could point to the option.
3. Test state: test_build_sdp_asks_for_the_chosen_video_bandwidth calls runtime.configure() and leaves the
   module globals changed for the tests that follow; monkeypatch is in the signature but unused. Could you restore
   the state (monkeypatch or a fixture)?
4. The default: I'd like it to depend on the transport, like view_keepalive already does: an Automatic
   default (2048 on local UDP, 256 over the cloud relay), plus 256 and 2048 as manual choices. No values in between
   until someone has measured them. Would you be OK with that?

I'll try both values on my 40507 (2-wire, local) before merging. Thanks again!

[Apeiv]

Tried this on my 40515 over the Vimar cloud (TLS + SRTP), 1.0.21 with this PR merged on top: 8 outside view calls of 15 to 19 s at each value, one a minute, switching from the options page (the entry reloads by itself, nice).

	2048	256
Resolution	720x576	320x240
Frame rate	24 fps	15 fps
Video bitrate	~1.9 Mbit/s	~240 kbit/s
First frame after the call starts	~1.9 s	~1.8 s
RTP loss, SRTP failures	0, 0	0, 0
Gaps over 500 ms	2 (both in one call)	1

Medians over the clean calls (6 at 2048, 7 at 256). One call at each value had the panel stop sending video after half a second while audio went on, so that looks unrelated to the bandwidth. I dropped one more 2048 call because someone actually rang the door in the middle of it (the only packet loss of the whole test was there).

At 256 this panel doesn't just squeeze the bitrate, it drops to 320x240 at 15 fps. So the "same 720x576" note in const.py, right above the new default, turns out to be wrong on the 40515. Worth fixing in this PR, e.g. "256 drops to 320x240 at 15 fps on a 40515".

My take on the default: startup is the same either way, and my cloud path had zero loss at 2048 in the clean calls, so here 256 only costs picture size and I'd keep 2048 for myself. If you go with lollox80's "Automatic = 256 on the cloud", that's fine by me as long as the option text says 256 can mean a smaller picture, something like 256 kbit/s (lower resolution on some panels), so people on a good connection know to switch.

[lollox80]

Hi @m4r1k, a short follow-up to my comment above, now that @Apeiv has measured both values on his 40515 over the cloud (thanks, Apeiv!):

• At 256 the panel drops to 320x240 at 15 fps, not just a lower bitrate (720x576 at 24 fps at 2048). So the comment in const.py above the bandwidth constants ("… same 720x576 …") is wrong on the 40515. Could you fix it in this PR, e.g. "256 drops to 320x240 at 15 fps on a 40515"?
• The option labels should say so, so people on a good connection know what 256 costs. For example 256 kbit/s (lower resolution on some panels) instead of 256 kbit/s (recommended), and the same in the description in strings.json, en.json and it.json.
• With his numbers (same first-frame time, no loss at 2048 on his cloud path), the Automatic default from point 4 still looks right to me: 2048 on local UDP, 256 over the cloud, with both values available by hand.

Points 1-3 of my earlier comment still apply (the Before you update line, the option in CONFIGURATION.md/.it.md, the test state). Once you push, I'll try 256 and 2048 on my 40507 (2-wire, local) before merging. Thanks!

[m4r1k]

@lollox80 @Apeiv thanks both, and for the measurements on the 40515. All addressed in 9fdccc8, rebased on main:

1. Before you update: the line is in the PR description: if the video was fine at 2 Mbit/s over the cloud (e.g. a 40515), set the option back to 2 Mbit/s.
2. Docs: the option is in CONFIGURATION.md and .it.md, and TROUBLESHOOTING.md and .it.md have a row for smeared, frozen or lagging video that points to it.
3. Test state: the SDP test now puts every runtime global back through monkeypatch after configure(). It covers automatic on both transports, both forced values and an unknown one.
4. Automatic default: yes, as you proposed. Automatic is 2048 on local UDP and 256 over the cloud, with 256 and 2048 by hand and nothing in between.

• The const.py comment now gives both panels' measurements: Apeiv's 40515 (720x576 at 24 fps at 2048, 320x240 at 15 fps at 256, no loss, same first-frame time) and my 40517 (ten times the packets through a lossy relay).
• The labels say what each value costs: 256 kbit/s (lower resolution on some panels) and 2 Mbit/s (sharper, needs a clean connection), in strings, en and it. Automatic spells out what it picks.

Looking forward to your 40507 run.

[lollox80]

Thanks @m4r1k, this covers everything we asked: Automatic by transport (2048 on local UDP, 256 over the cloud) plus the two fixed values, honest labels, the corrected note in const.py, docs and troubleshooting rows in both languages, and the Before you update line. On the wire only the numbers of the two existing b=AS lines change, back to the 1.0.18 pair (256/512) over the cloud, and the same value is used for outgoing views and for answering a ring. Two small nits, neither blocking: the PR title still says "256 kbit/s by default" (maybe "video bandwidth is an option, automatic by transport"), and the monkeypatch loop in test_build_sdp_asks_for_the_chosen_video_bandwidth can go, since the autouse _keep_runtime fixture in conftest.py already restores the runtime globals. Good to merge from our side once I have tried it on my 40507 (2-wire, local).

[lollox80]

Thanks, this covers everything from both reviews:

• "Automatic" by transport (2048 on local UDP, 256 over the cloud), 256/2048 as manual choices, unknown values fall back to automatic.
• The const.py comment now has Apeiv's 40515 numbers and the 40517 ones.
• Labels say what each value costs; CONFIGURATION and TROUBLESHOOTING (it/en) updated.
• The SDP test restores runtime's globals through monkeypatch and covers both transports, both forced values and an unknown one.
• The "Before you update" line is in the changelog section, good: existing cloud installs have no saved value and move from 2048 to 256 on update.

I ran the full suite on 9fdccc8: 2177 passed, ruff clean; CI is green too.

Approving. Before merging I'll still check it on my 40507 (2-wire, local UDP): automatic should send b=AS:2048/2200, forcing 256 should send 256/512.