Confirm Sonos announcements from the speaker's clip status (0.3.0)

[will-roscoe]

Problem

Broadcasts to a Sonos speaker were reported as unverified, with the summary reading FAILED — played on 0/1 speakers, even when the message was clearly heard.

Home Assistant's Sonos integration plays announcements (so tts.speak) through the speaker's local audio-clip API, and the media player entity does not change state while a clip plays. The intercom confirmed playback purely from entity state, so it could never see a Sonos announcement. That applied to the native Sonos entity and to Music Assistant players backed by the same speaker.

Change

A pluggable playback check (custom_components/intercom/verifiers/):

• PlaybackVerifier: the base class. It checks nothing and assumes the clip played, and is used when verify: false. Subclasses register themselves when defined, and must define name and matches(hass, entity_id). priority decides between several matches.
• StateVerifier: the existing entity-state check, moved unchanged. It is the fallback for every player.
• Checks now return a verdict (started / failed / timeout / assumed), so a player that itself refuses a clip is reported as failed, not unverified.
• Each player outcome gains verified_by, naming the check that judged it.

SonosClipVerifier (sonos_clip):

• Finds the speaker's address through the entity and device registries. This covers:
  • native Sonos entities;
  • Music Assistant players whose unique_id is the Sonos player id;
  • Music Assistant players that wrap a native entity.
• Opens its own connection to the speaker's local websocket API, subscribes to audioClip:1 status, ignores clips the speaker already had, and follows the first new clip. ACTIVE/DONE means played; ERROR means failed, with a message pointing at the usual cause (the speaker cannot reach the audio link Home Assistant gave it).
• While the connection is up it is authoritative, because a proxy entity can look busy while the speaker refuses the clip. If the connection can't be opened or drops, or if no clip appears at all (audio sent some other way, e.g. AirPlay), the entity-state check decides.
• No new requirements: aiohttp and sonos_websocket (which ships with HA's Sonos integration) are imported only when a Sonos speaker is actually checked.

Docs: new docs/troubleshooting.md, and README notes on verified_by, the two checks, how to add one, and the limitations. The troubleshooting guide covers the case that exposed this: a Home Assistant host on two subnets hands out an audio link on the one the speaker cannot reach. The speaker accepts the command and plays nothing, and Music Assistant shows ERROR_LOST_CONNECTION.

Version bumped to 0.3.0.

Testing

• 79 tests pass (37 new), ruff check and ruff format --check clean.

  • New stubs for the entity and device registries match core's lookup signatures.
  • The fake speaker replays the handshake a real Sonos Roam sends.
  • With the Sonos check disabled, the new regression test fails with unverified, as the bug did.

• Live, against a Sonos Roam on Home Assistant, running this module's clip channel without restarting HA:

  Clip	Statuses seen
  tts.speak via the native entity	ACTIVE → DONE
  tts.speak via the Music Assistant entity	ACTIVE → DONE
  Announce with an unreachable URL	ERROR after ~3 s

• Address lookup against the real registries: the native entity and both Music Assistant entities resolve to the speaker, and none of the other 7 media players match.

Assisted by claude-opus-5 anthropic@willroscoe.uk