snapclientmpris 1.2.1__py3-none-any.whl

snapclientmpris/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.2.1"

snapclientmpris/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m snapclientmpris`` to invoke the CLI."""
+
+from snapclientmpris.cli import main
+
+main()

snapclientmpris/cli.py

@@ -0,0 +1,245 @@
+"""CLI entry point: argparse, config-file parsing, Zeroconf discovery.
+
+Kept separate from the daemon runtime (``snapclientmpris.snapclientmpris``)
+so the bootstrap surface (argument parsing, config resolution, host
+discovery) is testable in isolation from the asyncio event loop.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import functools
+import logging
+import os
+import sys
+
+from dbus_fast import BusType
+from zeroconf import IPVersion, Zeroconf
+
+from snapclientmpris.snapclientmpris import run
+
+logger = logging.getLogger("snapclientmpris")
+
+CONFIG_PATHS = [
+    os.path.join(
+        os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config"),
+        "snapclientmpris",
+        "snapclientmpris.conf",
+    ),
+    "/etc/snapclientmpris.conf",
+]
+
+SNAPSERVER_CONTROL_PORT = 1705
+
+# Zeroconf service types advertised by snapserver. The instance name is
+# always "Snapcast." + the service type.
+CTRL_SERVICE_TYPE = "_snapcast-ctrl._tcp.local."  # JSON-RPC control (>= 0.33)
+AUDIO_SERVICE_TYPE = "_snapcast._tcp.local."  # audio stream (all versions)
+HTTP_SERVICE_TYPE = "_snapcast-http._tcp.local."  # snapweb UI
+
+
+class ConfigError(Exception):
+    """Raised when the daemon can't start because of invalid / missing config."""
+
+
+def read_config() -> dict[str, str]:
+    """Parse the first existing config file as flat ``key = value`` pairs.
+
+    The format is intentionally minimal: three keys (``server``,
+    ``control-port``, ``dbus-bus``), no sections. ``#`` introduces a
+    comment to end-of-line; blank and malformed lines are skipped.
+    """
+    for path in CONFIG_PATHS:
+        try:
+            with open(path) as f:
+                content = f.read()
+        except FileNotFoundError:
+            continue
+        except OSError as e:
+            logger.warning("failed to read %s: %s", path, e)
+            continue
+        cfg: dict[str, str] = {}
+        for raw in content.splitlines():
+            line = raw.split("#", 1)[0].strip()
+            if not line or "=" not in line:
+                continue
+            k, v = line.split("=", 1)
+            cfg[k.strip()] = v.strip()
+        logger.info("read %s", path)
+        return cfg
+    logger.info("no config file found, using defaults")
+    return {}
+
+
+def _lookup_service(
+    zc: Zeroconf, service_type: str
+) -> tuple[str | None, int | None]:
+    """Resolve the "Snapcast" instance of a service type to (host, port)."""
+    info = zc.get_service_info(service_type, f"Snapcast.{service_type}", timeout=3000)
+    if info is None or info.port is None:
+        return None, None
+    for addr in info.parsed_addresses(IPVersion.V4Only):
+        if addr != "0.0.0.0":
+            return str(addr), info.port
+    return None, None
+
+
+def discover_snapserver() -> tuple[str, int | None] | None:
+    """Return ``(host, control_port)`` for the snapserver, or ``None``.
+
+    snapserver >= 0.33 advertises its JSON-RPC control socket as
+    ``_snapcast-ctrl._tcp``, which yields both the host and the actual
+    control port. Older snapservers (e.g. 0.31 in Debian trixie) only
+    advertise ``_snapcast._tcp`` (the audio port); in that case the host
+    is returned with ``port=None`` and the caller falls back to the
+    configured / default control port.
+    """
+    zc = Zeroconf()
+    try:
+        host, port = _lookup_service(zc, CTRL_SERVICE_TYPE)
+        if host is not None:
+            return host, port
+
+        host, _ = _lookup_service(zc, AUDIO_SERVICE_TYPE)
+        if host is not None:
+            return host, None
+        return None
+    finally:
+        zc.close()
+
+
+def discover_snapweb() -> tuple[str, int] | None:
+    """Return ``(host, http_port)`` for the snapweb UI, or ``None``.
+
+    snapserver advertises its built-in web UI as ``_snapcast-http._tcp``,
+    which carries the actual HTTP port (default 1780).
+    """
+    zc = Zeroconf()
+    try:
+        host, port = _lookup_service(zc, HTTP_SERVICE_TYPE)
+        if host is not None and port is not None:
+            return host, port
+        return None
+    finally:
+        zc.close()
+
+
+def run_discovery() -> None:
+    """Probe Zeroconf for snapserver + snapweb and print findings to stdout.
+
+    Diagnostic one-shot for ``--discover``: never starts the daemon.
+    """
+    server = discover_snapserver()
+    web = discover_snapweb()
+    if server is None and web is None:
+        print("No Snapcast services found on the local network.")
+        return
+    if server is not None:
+        host, port = server
+        print(f"snapserver:  tcp://{host}" + (f":{port}" if port else ""))
+    if web is not None:
+        host, port = web
+        print(f"snapweb:     http://{host}:{port}")
+
+
+def parse_control_port(cfg: dict[str, str]) -> int:
+    """Validate the configured control port (fallback only, a discovered
+    port wins). Fail-fast on a typo. Raises ConfigError if unparseable.
+    """
+    raw_port = cfg.get("control-port") or SNAPSERVER_CONTROL_PORT
+    try:
+        return int(raw_port)
+    except ValueError as e:
+        raise ConfigError(f"invalid control-port {raw_port!r}") from e
+
+
+def resolve_endpoint(
+    cfg: dict[str, str], default_control_port: int
+) -> tuple[str, int] | None:
+    """Return ``(host, control_port)`` from config server or Zeroconf, or
+    ``None`` if no host is found yet (transient, caller retries).
+
+    A snapserver >= 0.33 advertises its control port (wins); older ones only
+    give the host, so the port falls back to ``default_control_port``.
+    """
+    host = cfg.get("server") or None
+    discovered_port: int | None = None
+    if not host:
+        discovered = discover_snapserver()
+        if not discovered:
+            return None
+        host, discovered_port = discovered
+    if discovered_port is not None:
+        return host, discovered_port
+    return host, default_control_port
+
+
+def resolve_dbus_bus(cfg: dict[str, str]) -> BusType:
+    """Return the BusType selected by the ``dbus-bus`` config key.
+
+    Raises ConfigError on an unrecognised value, failing loudly avoids
+    landing the daemon on a different (often more privileged) bus than
+    intended through a config typo.
+    """
+    bus_choice = (cfg.get("dbus-bus") or "session").lower()
+    if bus_choice == "session":
+        return BusType.SESSION
+    if bus_choice == "system":
+        return BusType.SYSTEM
+    raise ConfigError(
+        f"invalid dbus-bus {bus_choice!r} (expected 'session' or 'system')"
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="snapclientmpris",
+        description=("MPRIS2 D-Bus bridge for a local Snapcast client. "
+                     "Talks to snapserver and exposes the local client's "
+                     "PlaybackStatus, Metadata and Volume over D-Bus. "
+                     "Snapclient itself runs as its own service."),
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="enable debug logging")
+    parser.add_argument(
+        "--discover",
+        action="store_true",
+        help="probe the network for snapserver and snapweb, print the result and exit",
+    )
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        format="%(levelname)s: %(name)s - %(message)s",
+        level=logging.DEBUG if args.verbose else logging.INFO,
+    )
+    if not args.verbose:
+        logging.getLogger("snapcast").setLevel(logging.WARNING)
+
+    if args.discover:
+        run_discovery()
+        return
+
+    cfg = read_config()
+    try:
+        control_port = parse_control_port(cfg)
+        bus_type = resolve_dbus_bus(cfg)
+    except ConfigError as e:
+        logger.critical("%s", e)
+        sys.exit(1)
+    logger.info("%s D-Bus; snapserver resolved lazily (config host or Zeroconf)",
+                "session" if bus_type == BusType.SESSION else "system")
+
+    # Resolved lazily in run()'s connect loop so a snapserver that isn't up
+    # yet doesn't abort startup. resolve() -> (host, control_port) | None.
+    resolve = functools.partial(resolve_endpoint, cfg, control_port)
+
+    # SIGTERM/SIGINT inside run() cancel the main task, asyncio.run()
+    # then re-raises the CancelledError; suppress both that and the
+    # pre-loop KeyboardInterrupt path for a clean exit code.
+    with contextlib.suppress(KeyboardInterrupt, asyncio.CancelledError):
+        asyncio.run(run(resolve, bus_type))
+
+
+if __name__ == "__main__":
+    main()

snapclientmpris/mpris.py

@@ -0,0 +1,295 @@
+"""MPRIS2 D-Bus interface, exposed via dbus-fast.
+
+The two ServiceInterface subclasses below correspond to the two
+interfaces every MPRIS2 player must implement on the object path
+``/org/mpris/MediaPlayer2``:
+
+* ``org.mpris.MediaPlayer2``       — identity + capabilities (root)
+* ``org.mpris.MediaPlayer2.Player`` — playback state + controls
+
+Behaviour is driven from the outside: callbacks injected at construction
+time handle Play/Pause/Stop/PlayPause, and ``update_playback_status`` /
+``update_metadata`` push state changes back to subscribed MPRIS clients.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+from dbus_fast.errors import DBusError
+from dbus_fast.service import PropertyAccess, ServiceInterface, dbus_property, method
+
+NOT_SUPPORTED = "org.freedesktop.DBus.Error.NotSupported"
+
+logger = logging.getLogger(__name__)
+
+ROOT_PATH = "/org/mpris/MediaPlayer2"
+MEDIA_PLAYER_IFACE = "org.mpris.MediaPlayer2"
+BUS_NAME = f"{MEDIA_PLAYER_IFACE}.snapcast"
+PLAYER_IFACE = f"{MEDIA_PLAYER_IFACE}.Player"
+
+IDENTITY = "Snapcast client"
+DESKTOP_ENTRY = "snapclientmpris"
+
+
+class MediaPlayer2(ServiceInterface):
+    """Root MPRIS interface."""
+
+    def __init__(self) -> None:
+        super().__init__(MEDIA_PLAYER_IFACE)
+
+    @method()
+    def Raise(self):
+        raise DBusError(NOT_SUPPORTED, "Raise is not supported")
+
+    @method()
+    def Quit(self):
+        raise DBusError(NOT_SUPPORTED, "Quit is not supported")
+
+    @dbus_property(access=PropertyAccess.READ)
+    def CanQuit(self) -> "b":
+        return False
+
+    @dbus_property(access=PropertyAccess.READ)
+    def CanRaise(self) -> "b":
+        return False
+
+    @dbus_property(access=PropertyAccess.READ)
+    def HasTrackList(self) -> "b":
+        return False
+
+    @dbus_property(access=PropertyAccess.READ)
+    def Identity(self) -> "s":
+        return IDENTITY
+
+    @dbus_property(access=PropertyAccess.READ)
+    def DesktopEntry(self) -> "s":
+        return DESKTOP_ENTRY
+
+    @dbus_property(access=PropertyAccess.READ)
+    def SupportedUriSchemes(self) -> "as":
+        return []
+
+    @dbus_property(access=PropertyAccess.READ)
+    def SupportedMimeTypes(self) -> "as":
+        return []
+
+
+_CAP_ATTRS = {
+    "CanPlay": "_can_play",
+    "CanPause": "_can_pause",
+    "CanGoNext": "_can_go_next",
+    "CanGoPrevious": "_can_go_previous",
+    "CanSeek": "_can_seek",
+}
+
+
+class MediaPlayer2Player(ServiceInterface):
+    """Player MPRIS interface — playback state and controls."""
+
+    def __init__(
+        self,
+        on_play: Callable[[], None] | None = None,
+        on_pause: Callable[[], None] | None = None,
+        on_play_pause: Callable[[], None] | None = None,
+        on_stop: Callable[[], None] | None = None,
+        on_next: Callable[[], None] | None = None,
+        on_previous: Callable[[], None] | None = None,
+        on_volume_set: Callable[[float], None] | None = None,
+    ) -> None:
+        super().__init__(PLAYER_IFACE)
+        self._playback_status = "Stopped"
+        self._metadata: dict = {}
+        self._volume = 1.0
+        # Capabilities default to False — they're filled in from the
+        # snapserver stream's properties on the first refresh().
+        self._can_play = False
+        self._can_pause = False
+        self._can_go_next = False
+        self._can_go_previous = False
+        self._can_seek = False
+        self._on_play = on_play
+        self._on_pause = on_pause
+        self._on_play_pause = on_play_pause
+        self._on_stop = on_stop
+        self._on_next = on_next
+        self._on_previous = on_previous
+        self._on_volume_set = on_volume_set
+
+    # --- MPRIS methods ------------------------------------------------
+    @method()
+    def Play(self):
+        logger.debug("MPRIS Play")
+        if self._on_play:
+            self._on_play()
+
+    @method()
+    def Pause(self):
+        logger.debug("MPRIS Pause")
+        if self._on_pause:
+            self._on_pause()
+
+    @method()
+    def PlayPause(self):
+        logger.debug("MPRIS PlayPause")
+        if self._on_play_pause:
+            self._on_play_pause()
+
+    @method()
+    def Stop(self):
+        logger.debug("MPRIS Stop")
+        if self._on_stop:
+            self._on_stop()
+
+    @method()
+    def Next(self):
+        logger.debug("MPRIS Next")
+        if self._on_next:
+            self._on_next()
+
+    @method()
+    def Previous(self):
+        logger.debug("MPRIS Previous")
+        if self._on_previous:
+            self._on_previous()
+
+    @method()
+    def Seek(self, Offset: "x"):  # noqa: N803, ARG002
+        raise DBusError(NOT_SUPPORTED, "Seek is not supported")
+
+    @method()
+    def SetPosition(self, TrackId: "o", Position: "x"):  # noqa: N803, ARG002
+        raise DBusError(NOT_SUPPORTED, "SetPosition is not supported")
+
+    @method()
+    def OpenUri(self, Uri: "s"):  # noqa: N803, ARG002
+        raise DBusError(NOT_SUPPORTED, "OpenUri is not supported")
+
+    # --- MPRIS properties --------------------------------------------
+    @dbus_property(access=PropertyAccess.READ)
+    def PlaybackStatus(self) -> "s":
+        return self._playback_status
+
+    @dbus_property(access=PropertyAccess.READ)
+    def Metadata(self) -> "a{sv}":
+        return self._metadata
+
+    @dbus_property(access=PropertyAccess.READ)
+    def Position(self) -> "x":
+        return 0
+
+    @dbus_property(access=PropertyAccess.READ)
+    def Rate(self) -> "d":
+        return 1.0
+
+    @dbus_property(access=PropertyAccess.READ)
+    def MinimumRate(self) -> "d":
+        return 1.0
+
+    @dbus_property(access=PropertyAccess.READ)
+    def MaximumRate(self) -> "d":
+        return 1.0
+
+    @dbus_property(access=PropertyAccess.READ)
+    def CanGoNext(self) -> "b":
+        return self._can_go_next
+
+    @dbus_property(access=PropertyAccess.READ)
+    def CanGoPrevious(self) -> "b":
+        return self._can_go_previous
+
+    @dbus_property(access=PropertyAccess.READ)
+    def CanPlay(self) -> "b":
+        return self._can_play
+
+    @dbus_property(access=PropertyAccess.READ)
+    def CanPause(self) -> "b":
+        return self._can_pause
+
+    @dbus_property(access=PropertyAccess.READ)
+    def CanSeek(self) -> "b":
+        return self._can_seek
+
+    @dbus_property(access=PropertyAccess.READ)
+    def CanControl(self) -> "b":
+        # Hardcoded True even when the source has canControl=false in
+        # its snapserver stream.properties: MPRIS clients refuse to set
+        # Volume when CanControl=False (per spec), but snapcast volume
+        # is per-client and we want it controllable regardless of the
+        # stream source's own controllability. Backends that need the
+        # truth can read the per-operation Can* flags (which are
+        # mirrored from the stream) or the snapcast:streamStatus
+        # Metadata key.
+        return True
+
+    @dbus_property()
+    def Volume(self) -> "d":
+        return self._volume
+
+    @Volume.setter  # type: ignore[no-redef]
+    def Volume(self, val: "d") -> None:
+        clamped = max(0.0, min(1.0, float(val)))
+        logger.debug("MPRIS Set Volume: %.3f -> %.3f", self._volume, clamped)
+        if clamped == self._volume:
+            # Still trigger the backend hook so the snapserver-side state
+            # follows even when the value is identical (idempotent retry).
+            if self._on_volume_set:
+                self._on_volume_set(clamped)
+            return
+        self._volume = clamped
+        # Emit synchronously so every MPRIS subscriber (gnome-music, KDE
+        # plasma, etc.) learns about the change. The follow-up refresh()
+        # triggered by client.OnVolumeChanged will early-return in
+        # update_volume() because self._volume already matches — no double
+        # emit.
+        self.emit_properties_changed({"Volume": clamped})
+        if self._on_volume_set:
+            self._on_volume_set(clamped)
+
+    # --- External update API -----------------------------------------
+    def update_playback_status(self, status: str) -> None:
+        """Set PlaybackStatus and notify subscribers."""
+        if status not in ("Playing", "Paused", "Stopped"):
+            logger.warning("ignoring invalid playback status: %s", status)
+            return
+        if status == self._playback_status:
+            return
+        self._playback_status = status
+        self.emit_properties_changed({"PlaybackStatus": status})
+
+    def update_metadata(self, metadata: dict) -> None:
+        """Replace Metadata and notify subscribers."""
+        self._metadata = metadata
+        self.emit_properties_changed({"Metadata": metadata})
+
+    def update_capabilities(self, caps: dict) -> None:
+        """Update the Can* flags from external state (snapserver stream
+        properties) and emit PropertiesChanged for any that changed.
+
+        ``caps`` is a dict keyed by MPRIS property name, e.g.
+        ``{"CanPlay": True, "CanPause": True, "CanGoNext": False, ...}``.
+        Unknown keys are silently ignored.
+        """
+        changed: dict = {}
+        for key, val in caps.items():
+            attr = _CAP_ATTRS.get(key)
+            if attr is None:
+                continue
+            if getattr(self, attr) != val:
+                setattr(self, attr, val)
+                changed[key] = val
+        if changed:
+            logger.debug("update_capabilities: %s", changed)
+            self.emit_properties_changed(changed)
+
+    def update_volume(self, volume: float) -> None:
+        """Set Volume from external state (e.g. snapserver event)."""
+        clamped = max(0.0, min(1.0, float(volume)))
+        if clamped == self._volume:
+            logger.debug("update_volume: no change (%.3f), skip emit", clamped)
+            return
+        logger.debug("update_volume: %.3f -> %.3f, emitting PropertiesChanged",
+                     self._volume, clamped)
+        self._volume = clamped
+        self.emit_properties_changed({"Volume": clamped})