[GreenGrassBlueOcean]

Summary

Resolves #669.

Companion PR to audio synchronization and intercom event handling.

---

1. What is the problem?

In BTicino MyHOME installations where video door entry (WHO 6 / WHO 8) and sound diffusion (WHO 16 / WHO 22) coexist with an audio matrix (F441 / F441M) or gateway (MH200 / MH202), starting or stopping an intercom video stream (or camera preview) caused all audio amplifiers across the house to turn "on" in Home Assistant, even though the amplifiers were physically off.

Root Cause

1. BTicino Intercom Audio Ducking & Restoration:

   • When an intercom video stream starts, the audio matrix performs hardware audio ducking: it broadcasts Dimension 1 (Volume) status frames setting/reporting volume level 1 across all room amplifiers (*#16*41*1*1##, *#22*3#4#1*1*1##, etc.) so background music does not interfere with the intercom conversation.
   • When the video stream terminates (*6*9**## Camera OFF), the matrix restores the previous volume levels on the bus (e.g. *#16*41*1*6##, *#16*61*1*7##).

2. The 2.0.0b15 Regression (PR feat(audio): auto-join active streaming group and sync wall button source selection (#579) #581):

   • In PR feat(audio): auto-join active streaming group and sync wall button source selection (#579) #581, physical wall button handling was introduced to wake an unpowered room amplifier when pressing the volume-up rocker (*16*1001*WHERE##..*16*1015*WHERE##).
   • In MyHOMEMediaPlayer.handle_event(), the wake check evaluated:

     if not message.is_off and (is_volume_up or (message.volume is not None and message.volume > 0)):
         self._attr_state = MediaPlayerState.ON

   • In OpenWebNet, *#16*WHERE*1*<volume>## is a Dimension 1 status report (Volume Level). In OpenWebNet, amplifiers retain their configured volume levels even when switched off.
   • Conflating message.volume > 0 with a power-on event meant that incoming volume ducking (*#16*WHERE*1*1##) and volume restoration frames immediately forced all amplifiers into MediaPlayerState.ON and attempted to auto-join active streaming groups.

---

2. How is it solved?

1. Disentangle Volume Status Reports from Power State:
   In custom_components/myhome/media_player.py, the wake trigger in handle_event() is restricted strictly to:

   • Explicit power-on frames (message.is_on, e.g. *16*0*WHERE##, *16*3*WHERE##).
   • Matrix routing frames (*16*3*1ES##).
   • Physical volume-up rocker commands from wall controls (is_volume_up: 1001 <= int(what) <= 1015).

2. Preserve Dimension 1 Volume Ingestion:
   Dimension 1 volume reports (message.volume is not None) continue to update self._attr_volume_level = message.volume / 31.0 (and un-mute if previously muted and volume > 0), but never mutate self._attr_state from OFF to ON.
   An amplifier that is currently OFF remains OFF when receiving volume updates.

---

3. How is it tested?

1. Updated Unit Test:

   • test_volume_status_report_when_off_updates_level_without_waking in tests/test_component_media_player.py:
     Asserts that receiving Dimension 1 volume status reports (*#16*36*1*20##) while OFF updates the entity's volume_level without waking to ON and without joining any streaming group.

2. Added Authentic Regression Test:

   • test_issue_669_intercom_video_stream_volume_ducking_leaves_amplifiers_off in tests/test_component_media_player.py:
     Replays the exact authentic frames from Nicola's MH202 trace (stream start ducking to volume 1 across 6 amplifiers, followed by stream stop restoration to volumes 0, 1, 6, 7). Asserts that all 6 amplifiers remain in MediaPlayerState.OFF, their volume sliders update accurately, and no spurious group memberships are formed.

3. Full Test Suite & Quality Verification:

   • pytest tests/test_component_media_player.py: 213 passed (100%).
   • Full test suite: 3,470 passed (0 failures).
   • ruff check custom_components tests scripts: 0 violations.
   • scripts/verify_ha_standards.py: All 54 Home Assistant Platinum architectural rules verified.
   • scripts/sync_documentation.py --check: All documentation calibrated and in sync.

---

4. Where are the real traces?

1. Customer MH202 Plant Trace (Issue Audio amplifiers appear as "on" in Home Assistant when the video intercom stream starts or stops. #669 - Nicola Cavallo, BTicino MH202 firmware 1.0, 6 audio zones):

   • Reference: Audio amplifiers appear as "on" in Home Assistant when the video intercom stream starts or stops. #669 (comment)
   • Stream Start (Hardware Audio Ducking to Level 1):

     [17:29:30.184] [RX] *#22*3#4#1*1*1##
     [17:29:30.214] [RX] *#16*41*1*1##
     [17:29:30.344] [RX] *#22*3#3#1*1*1##
     [17:29:30.355] [RX] *#16*31*1*1##
     [17:29:30.417] [RX] *#16*61*1*1##
     [17:29:30.420] [RX] *#22*3#6#1*1*1##
     [17:29:30.454] [RX] *#22*3#5#1*1*1##
     [17:29:30.465] [RX] *#16*51*1*1##
     [17:29:30.500] [RX] *#16*71*1*1##
     [17:29:30.502] [RX] *#22*3#7#1*1*1##
     [17:29:30.537] [RX] *#22*3#8#1*1*1##
     [17:29:30.544] [RX] *#16*81*1*1##
     

   • Stream Teardown (Camera OFF & Volume Restoration):

     [17:29:41.546] [RX] *6*9**##
     [17:29:43.429] [RX] *#22*3#5#1*1*0##
     [17:29:43.437] [RX] *#16*51*1*0##
     [17:29:43.651] [RX] *#16*31*1*1##
     [17:29:43.657] [RX] *#22*3#3#1*1*1##
     [17:29:43.858] [RX] *#16*41*1*6##
     [17:29:43.861] [RX] *#22*3#4#1*1*6##
     [17:29:44.128] [RX] *#22*3#6#1*1*7##
     [17:29:44.136] [RX] *#16*61*1*7##
     

2. Corroborating Customer Trace in Issue feat(cover,lock): impulse garage/gate control, multi-factor safety approval, and intercom events #667 (tests/fixtures/traces/issue_667/myhome_trace_MH200_intercom_bell_gate_2026-10-09.json):

   • Recorded on physical BTicino MH200 gateway (firmware 2.1.0).
   • Shows the identical audio matrix ducking sequence *#16*81*1*1##..88## during entrance panel calls (*8*1#1#4*74##) and camera teardown *6*9##.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!