Reduce media player state complexity and document sound system behaviour #682

Problem

The WHO 16 sound system implementation has grown into a complex state machine spread across multiple modules (media_player.py, media_player_group.py, media_player_decoder.py, media_player_source.py, etc.). While the modular split improved readability, the interaction between power state, volume reports, intercom ducking, multi-room grouping and anti-hiss auto-off remains difficult to reason about and has caused multiple regressions.

Recent examples:

• Amplifiers incorrectly turned on when an intercom video stream started or stopped (Audio amplifiers appear as "on" in Home Assistant when the video intercom stream starts or stops. #669, fixed in fix(media_player): do not wake amplifiers on Dimension 1 volume status reports (#669) #670)
• Unowned rooms continuing to play after a decoder stopped (fix(media_player): switch off rooms that hear a decoder they do not own when it stops #532)
• Wake-on-volume-up interacting unexpectedly with dimension 1 volume status reports

Current architecture

The entity is built as a layered chain:

• ZoneBase
• Source routing
• Decoder mirroring + anti-hiss
• Group join/leave/park/wake
• Final entity

Power state can be influenced by explicit ON/OFF frames, volume rocker commands, dimension 1 volume reports, decoder state changes and group membership. The rules that decide when an amplifier should be considered on or off are distributed across these layers.

Proposal

1. Document the state machine

   • Add a concise state diagram (or decision table) to the sound system documentation that shows which frames and events may change power state.
   • Explicitly list frames that must never change power state (e.g. dimension 1 volume status reports).

2. Centralise power-state decisions

   • Consider extracting the power-state logic into a single, well-tested helper or mixin so that the rules are not duplicated or overridden in multiple layers.

3. Expand regression coverage

   • Add golden trace tests for:
     • Intercom ducking / volume restoration (Audio amplifiers appear as "on" in Home Assistant when the video intercom stream starts or stops. #669)
     • Group park/resume cycles
     • Decoder idle → anti-hiss auto-off for both owned and unowned rooms

4. Clarify user-facing behaviour

   • Document known interactions between video door entry and the sound system (ducking, temporary volume changes).

Acceptance criteria

• Documentation contains a clear description or diagram of when an amplifier entity changes power state
• Dimension 1 volume status reports cannot turn an off amplifier on
• Golden trace tests cover intercom ducking and group park/resume
• No new regressions in existing media player tests

Related

• Audio amplifiers appear as "on" in Home Assistant when the video intercom stream starts or stops. #669 / fix(media_player): do not wake amplifiers on Dimension 1 volume status reports (#669) #670 (intercom ducking)
• fix(media_player): switch off rooms that hear a decoder they do not own when it stops #532 (unowned room auto-off)
• refactor(media_player): split the audio zone entity into layered modules #559 (media player module split)
• feat(media_player): multi-room audio grouping and Music Assistant integration #460 (multi-room grouping)