gukebox 1.0.0.dev9__tar.gz → 1.0.0.dev10__tar.gz

{gukebox-1.0.0.dev9 → gukebox-1.0.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: gukebox
-Version: 1.0.0.dev9
+Version: 1.0.0.dev10
 Summary: A Jukebox to play music on speakers using 'CD' with NFC tag
 Keywords: jukebox,music,nfc
 Author: Gudsfile

{gukebox-1.0.0.dev9 → gukebox-1.0.0.dev10}/discstore/adapters/inbound/api_controller.py

@@ -139,7 +139,7 @@ class APIController:
         @self.app.get("/api/v1/sonos/speakers", response_model=list[SonosSpeakerOutput])
         def get_sonos_speakers():
             try:
-                return self.sonos_service.list_available_speakers()
+                return self.sonos_service.list_network_speakers()
             except SonosDiscoveryError as err:
                 raise HTTPException(status_code=502, detail=str(err))
             except Exception as err:

{gukebox-1.0.0.dev9 → gukebox-1.0.0.dev10}/jukebox/adapters/inbound/config.py

@@ -15,6 +15,9 @@ class JukeboxCliConfig(BaseModel):
     sonos_name: Optional[str] = None
     pause_duration_seconds: Optional[int] = None
     pause_delay_seconds: Optional[float] = None
+    pn532_spi_reset: Optional[int] = None
+    pn532_spi_cs: Optional[int] = None
+    pn532_spi_irq: Optional[int] = None
 
 
 def parse_config() -> JukeboxCliConfig:
@@ -71,6 +74,25 @@ def parse_config() -> JukeboxCliConfig:
         help="override the grace period in seconds before pausing when a tag is removed",
     )
 
+    parser.add_argument(
+        "--pn532-spi-reset",
+        default=None,
+        type=int,
+        help="override the PN532 SPI reset GPIO pin for this process",
+    )
+    parser.add_argument(
+        "--pn532-spi-cs",
+        default=None,
+        type=int,
+        help="override the PN532 SPI chip select GPIO pin for this process",
+    )
+    parser.add_argument(
+        "--pn532-spi-irq",
+        default=None,
+        type=int,
+        help="override the PN532 SPI IRQ GPIO pin for this process",
+    )
+
     args = parser.parse_args()
 
     return JukeboxCliConfig(
@@ -82,4 +104,7 @@ def parse_config() -> JukeboxCliConfig:
         sonos_name=args.sonos_name,
         pause_duration_seconds=args.pause_duration,
         pause_delay_seconds=args.pause_delay,
+        pn532_spi_reset=args.pn532_spi_reset,
+        pn532_spi_cs=args.pn532_spi_cs,
+        pn532_spi_irq=args.pn532_spi_irq,
     )

{gukebox-1.0.0.dev9 → gukebox-1.0.0.dev10}/jukebox/adapters/outbound/readers/pn532_reader_adapter.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import logging
 import os
-from typing import Union
+from typing import Optional, Union
 
 from jukebox.shared.dependency_messages import optional_extra_dependency_message
 
@@ -28,7 +28,13 @@ def spi_active():
 class Pn532ReaderAdapter(ReaderPort):
     """Adapter for Pn532 NFC reader implementing ReaderPort."""
 
-    def __init__(self, read_timeout_seconds: float = DEFAULT_NFC_READ_TIMEOUT_SECONDS):
+    def __init__(
+        self,
+        read_timeout_seconds: float = DEFAULT_NFC_READ_TIMEOUT_SECONDS,
+        spi_reset: Optional[int] = None,
+        spi_cs: Optional[int] = None,
+        spi_irq: Optional[int] = None,
+    ):
         if not spi_active():
             error_message = (
                 "The SPI interface is not enabled. Please enable it to use the PN532 NFC reader."
@@ -37,7 +43,7 @@ class Pn532ReaderAdapter(ReaderPort):
             LOGGER.error(error_message)
             raise RuntimeError("SPI interface not enabled. Use raspi-config to enable it.")
 
-        self.pn532 = PN532_SPI(debug=False, reset=20, cs=4)
+        self.pn532 = PN532_SPI(debug=False, reset=spi_reset, cs=spi_cs, irq=spi_irq)
         self.read_timeout_seconds = read_timeout_seconds
         ic, ver, rev, support = self.pn532.get_firmware_version()
         LOGGER.info(f"Found PN532 with firmware version: {ver}.{rev}")

gukebox-1.0.0.dev10/jukebox/adapters/outbound/sonos_discovery_adapter.py

@@ -0,0 +1,391 @@
+import ipaddress
+import re
+import select
+import socket
+import struct
+import time
+from dataclasses import dataclass
+from typing import Any, Optional, Protocol
+
+from jukebox.sonos.discovery import (
+    DiscoveredSonosSpeaker,
+    SonosDiscoveryError,
+    SonosDiscoveryPort,
+    sort_sonos_speakers,
+)
+
+
+@dataclass(frozen=True)
+class _SonosDiscoverySnapshot:
+    speakers: list[DiscoveredSonosSpeaker]
+    retry_hosts_by_uid: dict[str, list[str]]
+    normalization_errors: list[str]
+
+
+_SSDP_RESPONSE_TIMEOUT_SECONDS = 1.0
+_SSDP_RESPONSE_POLL_INTERVAL_SECONDS = 0.1
+_SSDP_MULTICAST_GROUP = "239.255.255.250"
+_SSDP_MULTICAST_PORT = 1900
+_MAX_SCAN_NETWORK_PREFIX = 22
+_HOUSEHOLD_HEADER_RE = re.compile(rb"(?im)^x-rincon-household:\s*([^\r\n]+)")
+_PLAYER_SEARCH = (
+    "M-SEARCH * HTTP/1.1\r\n"
+    f"HOST: {_SSDP_MULTICAST_GROUP}:{_SSDP_MULTICAST_PORT}\r\n"
+    'MAN: "ssdp:discover"\r\n'
+    "MX: 1\r\n"
+    "ST: urn:schemas-upnp-org:device:ZonePlayer:1\r\n"
+    "\r\n"
+).encode("utf-8")
+
+
+class SoCoSonosDiscoveryAdapter(SonosDiscoveryPort):
+    def discover_speakers(self) -> list[DiscoveredSonosSpeaker]:
+        snapshot = self._discover_network_snapshot()
+        return self._recover_snapshot_speakers(snapshot)
+
+    def discover_household_speakers(self, household_id: str) -> list[DiscoveredSonosSpeaker]:
+        snapshot = self._discover_household_snapshot(household_id)
+        return sort_sonos_speakers(
+            [speaker for speaker in self._recover_snapshot_speakers(snapshot) if speaker.household_id == household_id]
+        )
+
+    def _recover_snapshot_speakers(self, snapshot: _SonosDiscoverySnapshot) -> list[DiscoveredSonosSpeaker]:
+        speakers_by_uid = {speaker.uid: speaker for speaker in snapshot.speakers}
+        for expected_uid, hosts in snapshot.retry_hosts_by_uid.items():
+            for host in hosts:
+                try:
+                    recovered = self._resolve_speaker_by_host(expected_uid, host)
+                except ValueError:
+                    continue
+
+                existing = speakers_by_uid.get(recovered.uid)
+                speakers_by_uid[recovered.uid] = self._choose_preferred(existing, recovered)
+                break
+
+        recovered_speakers = sort_sonos_speakers(list(speakers_by_uid.values()))
+        if not recovered_speakers and snapshot.normalization_errors:
+            raise SonosDiscoveryError(
+                "Discovered Sonos speakers but failed to inspect any reachable speakers: "
+                f"{snapshot.normalization_errors[0]}"
+            )
+        return recovered_speakers
+
+    def _discover_network_snapshot(self) -> _SonosDiscoverySnapshot:
+        import soco
+        import soco.discovery
+        from requests.exceptions import RequestException
+        from soco.exceptions import SoCoException
+        from urllib3.exceptions import HTTPError
+
+        try:
+            discovered = self._discover_multicast_network_speakers()
+        except (HTTPError, OSError, RequestException, SoCoException) as err:
+            raise SonosDiscoveryError(f"Failed to discover Sonos speakers: {err}") from err
+
+        if not discovered:
+            try:
+                discovered = soco.discovery.scan_network(
+                    include_invisible=True,
+                    multi_household=True,
+                    networks_to_scan=_build_private_ipv4_networks_to_scan(),
+                )
+            except (HTTPError, OSError, RequestException, SoCoException) as err:
+                raise SonosDiscoveryError(f"Failed to discover Sonos speakers: {err}") from err
+        return self._normalize_snapshot(set(discovered or set()))
+
+    def _discover_household_snapshot(self, household_id: str) -> _SonosDiscoverySnapshot:
+        import soco
+        from requests.exceptions import RequestException
+        from soco.exceptions import SoCoException
+        from urllib3.exceptions import HTTPError
+
+        try:
+            discovered = soco.discover(
+                include_invisible=True,
+                household_id=household_id,
+                allow_network_scan=True,
+                networks_to_scan=_build_private_ipv4_networks_to_scan(),
+            )
+        except (HTTPError, OSError, RequestException, SoCoException) as err:
+            raise SonosDiscoveryError(f"Failed to discover Sonos household `{household_id}`: {err}") from err
+
+        snapshot = self._normalize_snapshot(set(discovered or set()))
+        return _SonosDiscoverySnapshot(
+            speakers=[speaker for speaker in snapshot.speakers if speaker.household_id == household_id],
+            retry_hosts_by_uid=snapshot.retry_hosts_by_uid,
+            normalization_errors=snapshot.normalization_errors,
+        )
+
+    # soco.discover() only surfaces the first household that responds, so we
+    # try manual SSDP multicast discovery first before falling back to a broader
+    # subnet scan. If SoCo adds native multi-household discovery, this can go away.
+    # ref: https://soco.readthedocs.io/en/latest/api/soco.discovery.html#soco.discovery.discover
+    def _discover_multicast_network_speakers(self) -> set[Any]:
+        import soco
+        import soco.discovery
+        from requests.exceptions import RequestException
+        from soco.exceptions import SoCoException, SoCoUPnPException
+        from urllib3.exceptions import HTTPError
+
+        # To make that multicast probe reliable, we send it from each local IPv4
+        # interface via IP_MULTICAST_IF; otherwise we may only probe one network path
+        # and miss reachable households.
+        #
+        # This uses a private SoCo helper because there is no public equivalent for
+        # enumerating the interface IPv4 addresses to bind the multicast sockets to.
+        interface_addresses = soco.discovery._find_ipv4_addresses()
+        if not interface_addresses:
+            return set()
+
+        sockets = []
+        for interface_address in interface_addresses:
+            try:
+                multicast_socket = self._create_multicast_socket(interface_address)
+            except OSError:
+                continue
+            sockets.append(multicast_socket)
+
+        if not sockets:
+            return set()
+
+        try:
+            for _ in range(3):
+                for multicast_socket in list(sockets):
+                    try:
+                        multicast_socket.sendto(_PLAYER_SEARCH, (_SSDP_MULTICAST_GROUP, _SSDP_MULTICAST_PORT))
+                    except OSError:
+                        sockets.remove(multicast_socket)
+                        multicast_socket.close()
+
+            if not sockets:
+                return set()
+
+            household_hosts = self._collect_multicast_household_hosts(sockets)
+        finally:
+            for multicast_socket in sockets:
+                multicast_socket.close()
+
+        speakers = set()
+        for hosts in household_hosts.values():
+            for host in hosts:
+                try:
+                    speakers.update(soco.SoCo(host).all_zones)
+                    break
+                except (HTTPError, OSError, RequestException, RuntimeError, SoCoException, SoCoUPnPException):
+                    continue
+        return speakers
+
+    @staticmethod
+    def _create_multicast_socket(interface_address: str) -> socket.socket:
+        multicast_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+        multicast_socket.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, struct.pack("B", 4))
+        multicast_socket.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_IF, socket.inet_aton(interface_address))
+        return multicast_socket
+
+    def _collect_multicast_household_hosts(self, sockets: list[socket.socket]) -> dict[str, list[str]]:
+        deadline = time.monotonic() + _SSDP_RESPONSE_TIMEOUT_SECONDS
+        household_hosts = {}
+
+        while sockets:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+
+            ready_sockets, _, _ = select.select(
+                sockets,
+                [],
+                [],
+                min(remaining, _SSDP_RESPONSE_POLL_INTERVAL_SECONDS),
+            )
+            if not ready_sockets:
+                continue
+
+            for ready_socket in ready_sockets:
+                response, address = ready_socket.recvfrom(1024)
+                household_id = _extract_sonos_household_id(response)
+                if household_id is None:
+                    continue
+                hosts = household_hosts.setdefault(household_id, [])
+                if address[0] not in hosts:
+                    hosts.append(address[0])
+
+        return household_hosts
+
+    def _normalize_snapshot(self, discovered: set[Any]) -> _SonosDiscoverySnapshot:
+        normalization_errors = []
+        available_speakers = set(discovered)
+        for speaker in list(discovered):
+            try:
+                available_speakers.update(speaker.all_zones)
+            except Exception:
+                available_speakers.add(speaker)
+
+        if not available_speakers:
+            return _SonosDiscoverySnapshot(
+                speakers=[],
+                retry_hosts_by_uid={},
+                normalization_errors=normalization_errors,
+            )
+
+        speakers_by_uid = {}
+        retry_hosts_by_uid = {}
+        for speaker in available_speakers:
+            expected_uid = _safe_speaker_uid(speaker)
+            normalized, error = self._normalize_speaker(speaker)
+            if normalized is None:
+                if error is not None:
+                    normalization_errors.append(error)
+                if expected_uid is not None:
+                    host = _safe_speaker_host(speaker)
+                    if host is not None:
+                        retry_hosts_by_uid.setdefault(expected_uid, set()).add(host)
+                continue
+
+            existing = speakers_by_uid.get(normalized.uid)
+            speakers_by_uid[normalized.uid] = self._choose_preferred(existing, normalized)
+
+        return _SonosDiscoverySnapshot(
+            speakers=sort_sonos_speakers(list(speakers_by_uid.values())),
+            retry_hosts_by_uid={uid: sorted(hosts) for uid, hosts in sorted(retry_hosts_by_uid.items())},
+            normalization_errors=normalization_errors,
+        )
+
+    def _resolve_speaker_by_host(self, expected_uid: str, host: str) -> DiscoveredSonosSpeaker:
+        from requests.exceptions import RequestException
+        from soco import SoCo
+        from soco.exceptions import SoCoException, SoCoUPnPException
+        from urllib3.exceptions import HTTPError
+
+        try:
+            speaker = SoCo(host)
+            resolved_uid = speaker.uid
+        except (HTTPError, OSError, RequestException, RuntimeError, SoCoException, SoCoUPnPException) as err:
+            raise ValueError(f"Failed to contact saved Sonos speaker at {host}: {err}") from err
+
+        if resolved_uid != expected_uid:
+            raise ValueError(
+                f"Saved Sonos speaker UID mismatch for host {host}: expected {expected_uid}, resolved {resolved_uid}"
+            )
+
+        try:
+            return DiscoveredSonosSpeaker(
+                uid=speaker.uid,
+                name=speaker.player_name,
+                host=speaker.ip_address,
+                household_id=speaker.household_id,
+                is_visible=getattr(speaker, "is_visible", True) is not False,
+            )
+        except (HTTPError, OSError, RequestException, RuntimeError, SoCoException, SoCoUPnPException) as err:
+            raise ValueError(f"Failed to inspect discovered Sonos speaker at {host}: {err}") from err
+
+    @staticmethod
+    def _choose_preferred(
+        existing: Optional[DiscoveredSonosSpeaker],
+        candidate: DiscoveredSonosSpeaker,
+    ) -> DiscoveredSonosSpeaker:
+        if existing is None:
+            return candidate
+        if candidate.is_visible and not existing.is_visible:
+            return candidate
+        if existing.is_visible and not candidate.is_visible:
+            return existing
+        if (candidate.name, candidate.host, candidate.uid) < (existing.name, existing.host, existing.uid):
+            return candidate
+        return existing
+
+    @staticmethod
+    def _normalize_speaker(
+        speaker: "_SonosSpeakerLike",
+    ) -> tuple[Optional[DiscoveredSonosSpeaker], Optional[str]]:
+        from requests.exceptions import RequestException
+        from soco.exceptions import SoCoException, SoCoUPnPException
+        from urllib3.exceptions import HTTPError
+
+        try:
+            return (
+                DiscoveredSonosSpeaker(
+                    uid=speaker.uid,
+                    name=speaker.player_name,
+                    host=speaker.ip_address,
+                    household_id=speaker.household_id,
+                    is_visible=getattr(speaker, "is_visible", True) is not False,
+                ),
+                None,
+            )
+        except (HTTPError, OSError, RequestException, RuntimeError, SoCoException, SoCoUPnPException) as err:
+            return (
+                None,
+                f"{_safe_speaker_identifier(speaker)}: {err}",
+            )
+
+
+class _SonosSpeakerLike(Protocol):
+    uid: str
+    player_name: str
+    ip_address: str
+    household_id: str
+    all_zones: set[Any]
+
+
+def _safe_speaker_identifier(speaker: "_SonosSpeakerLike") -> str:
+    ip_address = _safe_speaker_host(speaker)
+    if ip_address:
+        return ip_address
+
+    try:
+        uid = getattr(speaker, "uid")
+    except Exception:
+        return "unknown speaker"
+
+    return str(uid)
+
+
+def _safe_speaker_host(speaker: "_SonosSpeakerLike") -> Optional[str]:
+    try:
+        ip_address = getattr(speaker, "ip_address", None)
+    except Exception:
+        return None
+
+    if ip_address:
+        return str(ip_address)
+    return None
+
+
+def _safe_speaker_uid(speaker: "_SonosSpeakerLike") -> Optional[str]:
+    try:
+        return str(getattr(speaker, "uid"))
+    except Exception:
+        return None
+
+
+def _extract_sonos_household_id(response: bytes) -> Optional[str]:
+    match = _HOUSEHOLD_HEADER_RE.search(response)
+    if match is None:
+        return None
+    return match.group(1).decode("utf-8", "ignore").strip() or None
+
+
+def _build_private_ipv4_networks_to_scan() -> list[str]:
+    import ifaddr
+
+    networks = set()
+    for adapter in ifaddr.get_adapters():
+        for adapter_ip in adapter.ips:
+            try:
+                ipv4_address = ipaddress.IPv4Address(adapter_ip.ip)
+            except Exception:
+                continue
+
+            if adapter_ip.network_prefix >= 32:
+                continue
+
+            network_prefix = adapter_ip.network_prefix
+            if network_prefix < _MAX_SCAN_NETWORK_PREFIX:
+                network_prefix = _MAX_SCAN_NETWORK_PREFIX
+
+            ipv4_network = ipaddress.ip_network(f"{ipv4_address}/{network_prefix}", strict=False)
+            if not ipv4_network.is_private or ipv4_network.is_loopback or ipv4_network.is_link_local:
+                continue
+            networks.add(str(ipv4_network))
+
+    return sorted(networks)

{gukebox-1.0.0.dev9 → gukebox-1.0.0.dev10}/jukebox/admin/app.py

@@ -1,3 +1,4 @@
+import sys
 import traceback
 from typing import Annotated, Optional
 
@@ -21,7 +22,12 @@ from jukebox.shared.config_utils import get_package_version
 from jukebox.shared.logger import set_logger
 from jukebox.sonos.discovery import DiscoveredSonosSpeaker
 
-from .cli_presentation import build_sonos_speaker_choice_label, render_cli_error
+from .cli_presentation import (
+    build_sonos_household_choice_label,
+    build_sonos_speaker_choice_label,
+    render_cli_error,
+    render_sonos_speakers_output,
+)
 from .command_handlers import execute_server_command, execute_settings_command, execute_sonos_command
 from .commands import (
     ApiCommand,
@@ -36,6 +42,7 @@ from .commands import (
     is_sonos_command,
 )
 from .di_container import build_admin_api_app, build_admin_services, build_admin_ui_app, build_settings_service
+from .sonos_households import GroupedSonosHousehold
 
 
 class AdminCliState:
@@ -76,8 +83,10 @@ def _run_command(ctx: typer.Context, command: object) -> None:
                     command=command,
                     sonos_service=services.sonos,
                     settings_service=services.settings,
+                    household_prompt_fn=_prompt_for_sonos_household_selection,
                     speaker_prompt_fn=_prompt_for_sonos_speaker_selection,
                     coordinator_prompt_fn=_prompt_for_sonos_group_coordinator,
+                    status_fn=_emit_cli_status,
                 )
             else:
                 execute_server_command(
@@ -167,6 +176,25 @@ def _prompt_for_sonos_speaker_selection(speakers: list[DiscoveredSonosSpeaker])
         return None
 
 
+def _prompt_for_sonos_household_selection(households: list[GroupedSonosHousehold]) -> Optional[str]:
+    import questionary
+
+    try:
+        typer.echo(render_sonos_speakers_output(households))
+        return questionary.select(
+            "Select the Sonos household",
+            choices=[
+                questionary.Choice(
+                    title=build_sonos_household_choice_label(household),
+                    value=household.household_id,
+                )
+                for household in households
+            ],
+        ).ask()
+    except KeyboardInterrupt:
+        return None
+
+
 def _prompt_for_sonos_group_coordinator(speakers: list[DiscoveredSonosSpeaker]) -> Optional[str]:
     import questionary
 
@@ -185,6 +213,12 @@ def _prompt_for_sonos_group_coordinator(speakers: list[DiscoveredSonosSpeaker])
         return None
 
 
+def _emit_cli_status(message: str) -> None:
+    if not sys.stderr.isatty():
+        return
+    typer.echo(message, err=True)
+
+
 app = typer.Typer(help="Admin CLI for jukebox")
 settings_app = typer.Typer(help="Inspect and manage application settings")
 library_app = typer.Typer(help="Manage the library")
@@ -319,12 +353,21 @@ def sonos_select(
         Optional[str],
         typer.Option("--coordinator", help="coordinator UID for the selected Sonos group"),
     ] = None,
+    household: Annotated[
+        Optional[str],
+        typer.Option("--household", help="household ID to use for interactive Sonos speaker selection"),
+    ] = None,
 ) -> None:
     parsed_uids = (
         None if uids is None else [uid.strip() for raw_uids in uids for uid in raw_uids.split(",") if uid.strip()]
     )
     try:
-        command = SonosSelectCommand(type="sonos_select", uids=parsed_uids, coordinator=coordinator)
+        command = SonosSelectCommand(
+            type="sonos_select",
+            uids=parsed_uids,
+            coordinator=coordinator,
+            household=household,
+        )
     except ValidationError as err:
         _exit_on_command_validation_error(err)
 

{gukebox-1.0.0.dev9 → gukebox-1.0.0.dev10}/jukebox/admin/cli_presentation.py

@@ -15,6 +15,7 @@ from jukebox.sonos.discovery import DiscoveredSonosSpeaker
 from jukebox.sonos.selection import SonosSelectionResult, SonosSelectionStatus
 
 from .commands import SettingsResetCommand, SettingsSetCommand, SettingsShowCommand
+from .sonos_households import GroupedSonosHousehold
 
 _SECTION_ORDER = ("paths", "admin", "playback", "reader", "player", "other")
 _VALIDATION_SUFFIX_RE = re.compile(r"\s+\[type=.*$")
@@ -47,23 +48,35 @@ def render_cli_error(err: BaseException, verbose: bool = False) -> str:
     return message
 
 
-def render_sonos_speakers_output(speakers: list[DiscoveredSonosSpeaker]) -> str:
-    if not speakers:
+def render_sonos_speakers_output(households: list[GroupedSonosHousehold]) -> str:
+    if not households:
         return "No visible Sonos speakers found."
 
-    name_width = max(len(speaker.name) for speaker in speakers)
-    host_width = max(len(speaker.host) for speaker in speakers)
-    return "\n".join(
-        "{index}. {name:<{name_width}}   {host:<{host_width}}   {uid}".format(
-            index=index,
-            name=speaker.name,
-            name_width=name_width,
-            host=speaker.host,
-            host_width=host_width,
-            uid=speaker.uid,
-        )
-        for index, speaker in enumerate(speakers, start=1)
-    )
+    all_speakers = [speaker for household in households for speaker in household.speakers]
+    name_width = max(len(speaker.name) for speaker in all_speakers)
+    host_width = max(len(speaker.host) for speaker in all_speakers)
+    lines = []
+    for household in households:
+        lines.append(f"Household: {household.household_id}")
+        for index, speaker in enumerate(household.speakers, start=1):
+            lines.append(
+                "  {index}. {name:<{name_width}}   {host:<{host_width}}   {uid}".format(
+                    index=index,
+                    name=speaker.name,
+                    name_width=name_width,
+                    host=speaker.host,
+                    host_width=host_width,
+                    uid=speaker.uid,
+                )
+            )
+        lines.append("")
+    return "\n".join(lines[:-1])
+
+
+def build_sonos_household_choice_label(household: GroupedSonosHousehold) -> str:
+    speaker_count = len(household.speakers)
+    suffix = "speaker" if speaker_count == 1 else "speakers"
+    return f"{household.household_id} ({speaker_count} {suffix})"
 
 
 def build_sonos_speaker_choice_label(speaker: DiscoveredSonosSpeaker) -> str:
@@ -102,6 +115,7 @@ def render_sonos_selection_status_output(status: SonosSelectionStatus) -> str:
         lines.append(f"- Coordinator UID: {status.selected_group.coordinator_uid}")
     else:
         lines.append(f"- Coordinator: {coordinator_speaker.name} [{coordinator_speaker.uid}]")
+        lines.append(f"- Household: {coordinator_speaker.household_id}")
     lines.append(f"- Status: {status_label}")
     lines.append("- Members:")
 
@@ -341,6 +355,7 @@ def _format_selected_group(value: object) -> str:
         return str(value)
 
     selected_group = cast(Dict[str, object], value)
+    household_id = selected_group.get("household_id")
     members = selected_group.get("members")
     coordinator_uid = selected_group.get("coordinator_uid")
     if not isinstance(members, list) or not isinstance(coordinator_uid, str):
@@ -358,8 +373,8 @@ def _format_selected_group(value: object) -> str:
 
     if not member_uids:
         return json.dumps(value, sort_keys=True, separators=(", ", ": "))
-
-    return f"{coordinator_uid} (coordinator); members: {', '.join(member_uids)}"
+    household_label = f"; household: {household_id}" if isinstance(household_id, str) else ""
+    return f"{coordinator_uid} (coordinator){household_label}; members: {', '.join(member_uids)}"
 
 
 def _render_cli_error_message(err: BaseException) -> str: