PyLoxone-Audio 0.1.0__py3-none-any.whl

pyloxone_audio/radio.py

@@ -0,0 +1,211 @@
+"""Native HA radio browsing over the existing opt-in Audio Server client."""
+
+# ruff: noqa: TRY004 - malformed discovery has one ValueError boundary
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from dataclasses import dataclass
+import re
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from .models import MediaNode as BrowseMedia, SearchResult as SearchMedia, MediaKind as MediaClass
+
+from .sources import AudioFavourite, parse_room_favourites
+
+if TYPE_CHECKING:
+    from .native import AudioServerCommands
+
+RADIO_MEDIA_TYPE = "pyloxone_radio"
+_ROOT = "pyloxone-radio:root"
+_FAVOURITES = "pyloxone-radio:favourites"
+_PAGE_SIZE = 50
+_MAX_ENTRIES = 2048
+_MAX_TOTAL = 1_000_000
+_MAX_SERVICES = 16
+_MAX_SEARCH_RESULTS = 100
+_CONTROL_BOUNDARY = 32
+
+
+def _text(value: object, limit: int = 2048) -> str:
+    """Keep observed identifiers literal and reject empty/control-bearing data."""
+    if (
+        not isinstance(value, str)
+        or not value.strip()
+        or len(value) > limit
+        or any(ord(c) < _CONTROL_BOUNDARY for c in value)
+    ):
+        message = "Radio catalogue contains an invalid identifier or label"
+        raise ValueError(message)
+    return value
+
+
+@dataclass(frozen=True)
+class RadioTarget:
+    """Only a discovered target can be expanded or selected through HA."""
+
+    kind: str
+    label: str
+    service: str = ""
+    folder: str = ""
+    offset: int = 0
+    audio_path: str = ""
+    favourite: AudioFavourite | None = None
+
+
+class RadioCatalogue:
+    """Retain bounded per-entity identities, not commands supplied by the UI."""
+
+    def __init__(self, commands: AudioServerCommands, player_id: int) -> None:
+        """Bind browsing to the same configured client and exact audio zone."""
+        self.commands = commands
+        self.player_id = player_id
+        self.favourites: tuple[AudioFavourite, ...] | None = None
+        self._entries: OrderedDict[str, RadioTarget] = OrderedDict()
+
+    def resolve(self, content_id: str) -> RadioTarget:
+        """Reject unknown, expired, cross-entity or hand-crafted media IDs."""
+        if not isinstance(content_id, str) or content_id not in self._entries:
+            message = "Radio selection expired or was not discovered; browse or search again"
+            raise ValueError(message)
+        self._entries.move_to_end(content_id)
+        return self._entries[content_id]
+
+    def _item(self, target: RadioTarget) -> BrowseMedia:
+        """Register one discovery result and expose its opaque native HA ID."""
+        content_id = "pyloxone-radio:" + uuid4().hex
+        self._entries[content_id] = target
+        while len(self._entries) > _MAX_ENTRIES:
+            self._entries.popitem(last=False)
+        playable = target.kind in ("station", "favourite")
+        return BrowseMedia(
+            media_class=MediaClass.CHANNEL if playable else MediaClass.DIRECTORY,
+            media_content_id=content_id,
+            media_content_type=RADIO_MEDIA_TYPE,
+            title=target.label,
+            can_play=playable,
+            can_expand=not playable,
+            can_search=not playable,
+            search_media_classes=[MediaClass.CHANNEL] if not playable else None,
+        )
+
+    @staticmethod
+    def _directory(content_id: str, title: str, children: list[BrowseMedia]) -> BrowseMedia:
+        """Use the standard Home Assistant media-browser contract."""
+        return BrowseMedia(
+            media_class=MediaClass.DIRECTORY,
+            media_content_id=content_id,
+            media_content_type=RADIO_MEDIA_TYPE,
+            title=title,
+            can_play=False,
+            can_expand=True,
+            can_search=True,
+            search_media_classes=[MediaClass.CHANNEL],
+            children=children,
+        )
+
+    async def async_browse(self, content_id: str | None = None) -> BrowseMedia:
+        """Read one provider or one catalogue page; browsing never plays media."""
+        if content_id == _FAVOURITES:
+            self.favourites = parse_room_favourites(
+                await self.commands.async_room_favourites(self.player_id), self.player_id
+            )
+            children = [self._item(RadioTarget("favourite", item.label, favourite=item)) for item in self.favourites]
+            return self._directory(_FAVOURITES, "Room favourites", children)
+        if content_id in (None, "", _ROOT):
+            services = await self.commands.async_radio_services()
+            if services is None:
+                services = []
+            if not isinstance(services, list) or len(services) > _MAX_SERVICES:
+                message = "Radio service discovery is invalid or exceeds its bound"
+                raise ValueError(message)
+            children = [self._directory(_FAVOURITES, "Room favourites", [])]
+            seen = set()
+            for service in services:
+                if not isinstance(service, dict):
+                    message = "Radio service discovery contains an invalid entry"
+                    raise ValueError(message)
+                command = _text(service.get("cmd"), 32)
+                if not re.fullmatch(r"[A-Za-z0-9_-]+", command) or command in seen:
+                    message = "Radio service discovery contains an invalid or duplicate service"
+                    raise ValueError(message)
+                seen.add(command)
+                target = RadioTarget("folder", _text(service.get("name"), 256), command, _text(service.get("root")))
+                children.append(self._item(target))
+            return self._directory(_ROOT, "Radio stations", children)
+        target = self.resolve(content_id)
+        if target.kind != "folder":
+            message = "A radio station cannot be expanded as a folder"
+            raise ValueError(message)
+        payload = await self.commands.async_radio_folder(target.service, target.folder, target.offset)
+        if not isinstance(payload, list) or len(payload) != 1 or not isinstance(payload[0], dict):
+            message = "Radio browsing requires one bounded native page"
+            raise ValueError(message)
+        page = payload[0]
+        items, total = page.get("items"), page.get("totalitems")
+        if (
+            type(page.get("start")) is not int
+            or page["start"] != target.offset
+            or type(total) is not int
+            or not target.offset <= total <= _MAX_TOTAL
+            or not isinstance(items, list)
+            or len(items) > _PAGE_SIZE
+            or target.offset + len(items) > total
+            or (not items and target.offset < total)
+        ):
+            message = "Radio page changed or is incomplete; browse again"
+            raise ValueError(message)
+        children = [self._item(item) for row in items if (item := self._parse_item(row, target.service)) is not None]
+        offset = target.offset + len(items)
+        if offset < total:
+            children.append(self._item(RadioTarget("folder", "More stations…", target.service, target.folder, offset)))
+        return self._directory(content_id, target.label, children)
+
+    async def async_search(self, query: str) -> SearchMedia:
+        """Search native radio stations/custom URLs without external directories."""
+        payload = await self.commands.async_radio_search(query)
+        if not isinstance(payload, dict) or payload.get("error"):
+            message = "Radio search returned an invalid result"
+            raise ValueError(message)
+        result = payload.get("result", payload)
+        if not isinstance(result, dict):
+            message = "Radio search returned an invalid result"
+            raise ValueError(message)
+        children = []
+        seen = set()
+        for category, service in (("station", "world"), ("custom", "custom")):
+            if category not in result:
+                continue
+            group = result[category]
+            if (
+                not isinstance(group, dict)
+                or not isinstance(group.get("items"), list)
+                or len(group["items"]) > _MAX_SEARCH_RESULTS
+            ):
+                message = "Radio search exceeded its bounded category or returned invalid items"
+                raise ValueError(message)
+            for row in group["items"]:
+                target = self._parse_item(row, service)
+                if target is not None and target.kind == "station" and (service, target.audio_path) not in seen:
+                    seen.add((service, target.audio_path))
+                    children.append(self._item(target))
+        return SearchMedia(result=children)
+
+    @staticmethod
+    def _parse_item(row: object, service: str) -> RadioTarget | None:
+        """Separate actual folders from playable native radio paths."""
+        if not isinstance(row, dict) or type(row.get("type")) is not int:
+            message = "Radio catalogue contains an invalid item"
+            raise ValueError(message)
+        kind = row["type"]
+        if kind not in (1, 2) or row.get("unplayable", False):
+            return None
+        label = _text(row.get("name"), 256)
+        if kind == 1:
+            return RadioTarget("folder", label, service, _text(row.get("id")))
+        path = _text(row.get("audiopath"))
+        if not path.startswith(("tunein:", "loxoneradio:")) or not path.partition(":")[2].strip():
+            message = "Radio catalogue item has no supported native station path"
+            raise ValueError(message)
+        return RadioTarget("station", label, service, audio_path=path)

pyloxone_audio/selection.py

@@ -0,0 +1,194 @@
+"""Reusable native source routing and strict manual-track qualification."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+from aiohttp import ClientError
+from .native import AudioCommandError
+from .catalogue import CatalogueTarget
+
+from .sources import SourceEnvironment, async_native_catalogue_noop, native_selection_unchanged
+from .spotify import NativeSessionUnavailableError
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+    from .catalogue import AudioCatalogue
+    from .metadata import AudioMetadataCoordinator
+    from .native import AudioServerCommands
+    from .radio import RadioTarget
+    from .native import AudioZoneMetadata
+
+
+class NativeResumeOutcome(Enum):
+    """Explicit result of the host's existing linked-session bridge."""
+
+    UNAVAILABLE = "unavailable"
+    COMPLETE = "complete"
+
+
+async def async_optional_native_resume(
+    commands: AudioServerCommands, metadata: AudioMetadataCoordinator, player_id: int,
+    target: RadioTarget, attempt: Callable[[RadioTarget], Awaitable[NativeResumeOutcome]],
+    *, is_current: Callable[[], bool],
+) -> NativeResumeOutcome:
+    """Own optional-attempt pinning and the no-retained-fallback safety decision."""
+    original = metadata.get(player_id)
+
+    def retained_allowed() -> bool:
+        return bool(
+            is_current() and native_selection_unchanged(original, metadata.get(player_id))
+            and player_id not in commands.source_fences and player_id not in commands.announcement_fences
+        )
+
+    try:
+        outcome = await attempt(target)
+    except (NativeSessionUnavailableError, TimeoutError, ClientError):
+        if not retained_allowed():
+            raise
+        return NativeResumeOutcome.UNAVAILABLE
+    if outcome is NativeResumeOutcome.UNAVAILABLE:
+        if not retained_allowed():
+            message = "Source return was superseded before native dispatch"
+            raise AudioCommandError(message)
+    elif outcome is not NativeResumeOutcome.COMPLETE:
+        message = "Native session bridge returned an invalid outcome"
+        raise AudioCommandError(message)
+    return outcome
+
+
+def manual_seek_supported(snapshot: AudioZoneMetadata | None) -> bool:
+    """Require the native track capability, not an inferred source feature."""
+    return bool(
+        snapshot is not None and snapshot.event_active is False
+        and snapshot.source in {"Spotify", "Local Library"}
+        and snapshot.position is not None and snapshot.duration is not None
+        and snapshot.playback_restrictions is not None and snapshot.playback_restrictions & 32
+    )
+
+
+def confirmed_library_session(snapshot: AudioZoneMetadata | None, saved: AudioZoneMetadata | None) -> bool:
+    """Qualify the retained native Library selection independently of host uncertainty."""
+    return bool(
+        snapshot is not None and saved is not None and snapshot.source == "Local Library"
+        and snapshot.event_idle and snapshot.event_active is False
+        and snapshot.native_mode in ("play", "pause")
+        and all(getattr(snapshot, field) == getattr(saved, field)
+                for field in ("player_id", "source", "audio_path", "parent_id"))
+    )
+
+
+def native_track_identity(snapshot: AudioZoneMetadata | None) -> tuple | None:
+    """Use the accepted native track generation key, also suitable for UI clocks."""
+    return (
+        (snapshot.audio_path, snapshot.title, snapshot.artist, snapshot.album, snapshot.duration)
+        if snapshot is not None and snapshot.duration is not None else None
+    )
+
+
+def manual_seek_position(position: float, duration: float) -> float:
+    """Reject invalid offsets and stop before the queue-advancing track end."""
+    if isinstance(position, bool) or not isinstance(position, (int, float)) or not 0 <= position < float("inf"):
+        message = "Invalid manual seek position"
+        raise ValueError(message)
+    return min(position, max(0, duration - 1))
+
+
+@dataclass(frozen=True)
+class ManualSeekQualification:
+    """Pin native identity/account and neutral host-observed track revision."""
+
+    original: AudioZoneMetadata
+    identity: tuple | None
+    revision: int
+    duration: float
+
+    def is_current(
+        self, snapshot: AudioZoneMetadata | None, *, identity: tuple | None, revision: int,
+        duration: float | None, enabled: bool,
+    ) -> bool:
+        """Leave only lifecycle/request liveness to the host availability callback."""
+        return bool(
+            enabled and manual_seek_supported(snapshot)
+            and identity == self.identity and revision == self.revision and duration == self.duration
+            and native_track_identity(snapshot) == self.identity
+            and snapshot.player_id == self.original.player_id
+            and snapshot.source == self.original.source
+            and snapshot.source_name == self.original.source_name
+        )
+
+
+@dataclass(frozen=True)
+class SourceRoute:
+    """A native completion or retained opaque item qualified for one dispatch."""
+
+    original: AudioZoneMetadata | None
+    target: RadioTarget
+    media_id: str | None
+
+
+class SourceContentRequiredError(ValueError):
+    """A discovered source has no qualified return content; host may translate."""
+
+
+async def async_source_route(
+    commands: AudioServerCommands, metadata: AudioMetadataCoordinator, catalogue: AudioCatalogue,
+    player_id: int, source: str, *, is_current: Callable[[], bool],
+    ensure_snapshot: Callable[[], Awaitable[None]],
+    resume_native: Callable[[RadioTarget], Awaitable[NativeResumeOutcome]],
+    native_is_available: Callable[[], bool], on_target: Callable[[RadioTarget], None],
+    environment: SourceEnvironment | None = None,
+) -> SourceRoute:
+    """Resolve native-session versus retained content without owning HA tasks."""
+    original = metadata.get(player_id)
+
+    hint = catalogue.source_choices.get(source) or catalogue.source_descriptors.get(source)
+
+    if (
+        getattr(hint, "service", None) != "spotify"
+        and (source not in catalogue.source_choices or original is None)
+        and not catalogue.source_session_known(source)
+    ):
+        try:
+            await catalogue.async_source_selection(source)
+        except ValueError:
+            message = "Choose content explicitly in Browse before selecting this source"
+            raise SourceContentRequiredError(message) from None
+        if not is_current() or not (
+            (original is None and metadata.get(player_id) is None)
+            or native_selection_unchanged(original, metadata.get(player_id))
+        ):
+            message = "Source return was superseded before native dispatch"
+            raise AudioCommandError(message)
+    await ensure_snapshot()
+    original = metadata.get(player_id)
+    target = catalogue.source_choices.get(source)
+    if target is None:
+        descriptor = catalogue.source_descriptors.get(source)
+        if descriptor is None:
+            message = "Source selection is unavailable"
+            raise AudioCommandError(message)
+        target = CatalogueTarget("item", source, descriptor.service, account=descriptor.account)
+
+    on_target(target)
+    outcome = await async_optional_native_resume(
+        commands, metadata, player_id, target, resume_native, is_current=is_current,
+    )
+    native_done = outcome is NativeResumeOutcome.COMPLETE
+    if not native_done and isinstance(target, CatalogueTarget) and target.service == "spotify":
+        native_done = await async_native_catalogue_noop(
+            commands, metadata, player_id, target, is_available=native_is_available, resume_paused=True,
+            environment=environment,
+        )
+    if native_done:
+        catalogue.remember_source(metadata.get(player_id))
+        return SourceRoute(original, target, None)
+    try:
+        media_id = await catalogue.async_source_return(source)
+    except ValueError:
+        message = "Choose content explicitly in Browse before selecting this source"
+        raise SourceContentRequiredError(message) from None
+    if not is_current() or not native_selection_unchanged(original, metadata.get(player_id)):
+        message = "Source return was superseded before native dispatch"
+        raise AudioCommandError(message)
+    return SourceRoute(original, target, media_id)