AirPlay 2 device groups (APR-18)

[jcarbaugh]

Summary

Closes the parent feature APR-18 — stream a single capture to multiple AirPlay receivers, with a fan-out architecture chosen after the APR-19 spike found that pyatv 0.17.0 has no native AirPlay 2 group API.

Aggregates the four sub-issue PRs already merged into this branch:

• APR-20 (Accept list/comma-separated AirPlay targets (APR-20) #13) — Config + CLI accept a string or comma-separated/array list; first entry is the leader.
• APR-21 (Resolve AirPlay targets with graceful degradation (APR-21) #14) — resolve_targets returns surviving devices in configured order; missing followers are logged and skipped, missing leader still hard-fails.
• APR-22 (Stream audio to an AirPlay group with per-device fault isolation (APR-22) #15) — GroupStreamingSession runs one pyatv.connect + stream_file per receiver from a single capture; per-device fault isolation, group only fails when every sub-session has died.
• APR-23 (Document AirPlay 2 groups and cover leader-drop (APR-23) #16) — Tests + docs for the group path, including leader-drop and all-devices-fail cases.

Plus one follow-up commit on this PR documenting the fan-out sync-drift tradeoff in README and cusp.toml.example, which the spike flagged but wasn't called out in user-facing docs.

Single-target usage (-t "Living Room" / target = "Living Room") is unchanged.

Test plan

• uv run pytest — 91 tests pass locally
• uv run ruff check . and uv run ruff format --check . clean
• CI green on this PR
• Smoke test: stream to a single receiver (regression check) and to a 2+ receiver group; pull power on a follower mid-stream and confirm the leader keeps playing

[jcarbaugh]

Code review

Found 1 issue:

1. Stale comment claims targets_lock is for "a later sub-issue" that will use group streaming, but group streaming is already implemented and actively uses the lock in this same PR. The comment will mislead future readers into thinking the lock is forward-looking scaffolding when it is load-bearing today.

cusp-audio/src/cusp/pipeline.py

Lines 206 to 211 in 4c6d2ea

	targets: list[BaseConfig] = await resolve_targets(config)
	# Guards swaps of `targets` so a concurrent reader (session start) never
	# sees a torn list during a background refresh. Group streaming in a
	# later sub-issue will rely on this.
	targets_lock = asyncio.Lock()

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}