wiim-cli 0.1.0__tar.gz

wiim_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+dist/
+*.egg-info/
+.eggs/

wiim_cli-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: wiim-cli
+Version: 0.1.0
+Summary: CLI tool for controlling WiiM devices on your local network
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: pywiim>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# wiim-cli
+
+CLI tool for controlling WiiM and LinkPlay audio devices on your local network.
+
+Built with [pywiim](https://github.com/mjcumming/pywiim) and [typer](https://typer.tiangolo.com/).
+
+## Install
+
+```bash
+uv tool install wiim-cli
+```
+
+Or run directly:
+
+```bash
+uvx --from wiim-cli wiim --help
+```
+
+Requires Python >=3.11.
+
+## Usage
+
+```
+wiim discover              # Find devices
+wiim status                # Show what's playing
+wiim play / pause / stop   # Playback control
+wiim next / prev           # Track navigation
+wiim volume [0-100]        # Get/set volume
+wiim mute / unmute         # Mute control
+wiim play-url <url>        # Play audio from URL
+wiim play-preset <n>       # Play saved preset
+wiim seek <seconds>        # Seek in track
+wiim shuffle true/false    # Toggle shuffle
+```
+
+All commands accept `--host <ip>` to target a specific device. If omitted and a single device is found on the network, it's used automatically.
+
+## License
+
+MIT

wiim_cli-0.1.0/README.md

@@ -0,0 +1,40 @@
+# wiim-cli
+
+CLI tool for controlling WiiM and LinkPlay audio devices on your local network.
+
+Built with [pywiim](https://github.com/mjcumming/pywiim) and [typer](https://typer.tiangolo.com/).
+
+## Install
+
+```bash
+uv tool install wiim-cli
+```
+
+Or run directly:
+
+```bash
+uvx --from wiim-cli wiim --help
+```
+
+Requires Python >=3.11.
+
+## Usage
+
+```
+wiim discover              # Find devices
+wiim status                # Show what's playing
+wiim play / pause / stop   # Playback control
+wiim next / prev           # Track navigation
+wiim volume [0-100]        # Get/set volume
+wiim mute / unmute         # Mute control
+wiim play-url <url>        # Play audio from URL
+wiim play-preset <n>       # Play saved preset
+wiim seek <seconds>        # Seek in track
+wiim shuffle true/false    # Toggle shuffle
+```
+
+All commands accept `--host <ip>` to target a specific device. If omitted and a single device is found on the network, it's used automatically.
+
+## License
+
+MIT

wiim_cli-0.1.0/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: wiim
+description: Control WiiM audio devices (play, pause, stop, next, prev, volume, mute, play URLs, presets). Use when the user wants to control music playback, adjust volume, discover WiiM/LinkPlay speakers on the network, or play audio from a URL on a WiiM device.
+---
+
+# WiiM CLI
+
+Control WiiM and LinkPlay audio devices from the command line.
+
+## Installation
+
+```bash
+# Install globally
+uv tool install wiim-cli
+
+# Or run directly without installing
+uvx --from wiim-cli wiim --help
+```
+
+Requires Python >=3.11.
+
+## Quick Reference
+
+All commands accept `--host <ip>` to target a specific device. If omitted and only one device is on the network, it auto-discovers.
+
+### Discovery
+
+```bash
+wiim discover                    # Find devices on the network
+```
+
+### Playback
+
+```bash
+wiim status                      # Show what's playing
+wiim play                        # Resume
+wiim pause                       # Pause
+wiim stop                        # Stop
+wiim next                        # Next track
+wiim prev                        # Previous track
+wiim seek 90                     # Seek to 1:30
+wiim shuffle true                # Enable shuffle
+```
+
+### Volume
+
+```bash
+wiim volume                      # Show current volume
+wiim volume 50                   # Set to 50%
+wiim mute                        # Mute
+wiim unmute                      # Unmute
+```
+
+### Play Media
+
+```bash
+wiim play-url "https://example.com/stream.mp3"     # Play a URL
+wiim play-preset 1                                   # Play saved preset #1
+```
+
+## Notes
+
+- The WiiM must be on the same local network as the machine running the CLI.
+- Discovery uses SSDP/UPnP — may not work across subnets/VLANs.
+- Spotify, AirPlay, and other streaming services are controlled from their own apps. Once playing on the WiiM, this CLI can pause/play/skip/adjust volume.
+- `play-url` works with direct audio URLs (MP3, FLAC, M3U streams, etc.).

wiim_cli-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "wiim-cli"
+version = "0.1.0"
+description = "CLI tool for controlling WiiM devices on your local network"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = [
+    "typer>=0.9.0",
+    "pywiim>=1.0.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+wiim = "wiim_cli.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

wiim_cli-0.1.0/src/wiim_cli/__init__.py

@@ -0,0 +1,3 @@
+"""CLI tool for controlling WiiM devices."""
+
+__version__ = "0.1.0"

wiim_cli-0.1.0/src/wiim_cli/cli.py

@@ -0,0 +1,380 @@
+"""WiiM CLI — control WiiM devices from the command line."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from wiim_cli.device import connect, disconnect, find_devices
+
+app = typer.Typer(
+    name="wiim",
+    help="Control WiiM audio devices on your local network.",
+    no_args_is_help=True,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _run(coro):
+    """Run an async coroutine, handling event loop edge cases."""
+    return asyncio.run(coro)
+
+
+async def _resolve_host(host: str | None) -> str:
+    """Return the host or auto-discover a single device."""
+    if host:
+        return host
+    devices = await find_devices()
+    if len(devices) == 0:
+        err_console.print("[red]No WiiM devices found on the network.[/red]")
+        raise typer.Exit(1)
+    if len(devices) > 1:
+        err_console.print(
+            f"[yellow]Multiple devices found ({len(devices)}). "
+            "Use --host to pick one:[/yellow]"
+        )
+        for d in devices:
+            err_console.print(f"  {d.host}  {d.name or '(unknown)'}")
+        raise typer.Exit(1)
+    console.print(f"[dim]Auto-discovered: {devices[0].name or devices[0].host}[/dim]")
+    return devices[0].host
+
+
+# ---------------------------------------------------------------------------
+# discover
+# ---------------------------------------------------------------------------
+
+@app.command()
+def discover(
+    timeout: int = typer.Option(5, help="SSDP discovery timeout in seconds."),
+) -> None:
+    """Discover WiiM devices on the local network."""
+
+    async def _discover():
+        devices = await find_devices(timeout=timeout)
+        if not devices:
+            console.print("[yellow]No devices found.[/yellow]")
+            raise typer.Exit(0)
+
+        table = Table(title="WiiM Devices")
+        table.add_column("Name", style="cyan")
+        table.add_column("Host", style="green")
+        table.add_column("Model")
+        table.add_column("Firmware")
+        table.add_column("UUID", style="dim")
+
+        for d in devices:
+            table.add_row(
+                d.name or "—",
+                d.host,
+                d.model or "—",
+                d.firmware or "—",
+                d.uuid or "—",
+            )
+
+        console.print(table)
+
+    _run(_discover())
+
+
+# ---------------------------------------------------------------------------
+# status
+# ---------------------------------------------------------------------------
+
+@app.command()
+def status(
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Show the current playback status."""
+
+    async def _status():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            table = Table(title=f"{player.name or player.host} — Status")
+            table.add_column("Property", style="cyan")
+            table.add_column("Value")
+
+            state = player.play_state or "unknown"
+            table.add_row("State", state)
+            table.add_row("Volume", f"{int((player.volume_level or 0) * 100)}%")
+            table.add_row("Muted", str(player.is_muted or False))
+            table.add_row("Source", player.source or "—")
+            table.add_row("Title", player.media_title or "—")
+            table.add_row("Artist", player.media_artist or "—")
+            table.add_row("Album", player.media_album or "—")
+
+            pos = player.media_position
+            dur = player.media_duration
+            if pos is not None and dur is not None:
+                table.add_row(
+                    "Position",
+                    f"{_fmt_time(pos)} / {_fmt_time(dur)}",
+                )
+            elif pos is not None:
+                table.add_row("Position", _fmt_time(pos))
+
+            table.add_row("Shuffle", str(player.shuffle or False))
+            table.add_row("Repeat", player.repeat or "off")
+
+            console.print(table)
+        finally:
+            await disconnect(player)
+
+    _run(_status())
+
+
+def _fmt_time(seconds: int) -> str:
+    m, s = divmod(seconds, 60)
+    h, m = divmod(m, 60)
+    if h:
+        return f"{h}:{m:02d}:{s:02d}"
+    return f"{m}:{s:02d}"
+
+
+# ---------------------------------------------------------------------------
+# play / pause / stop / next / prev
+# ---------------------------------------------------------------------------
+
+@app.command()
+def play(
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Resume playback."""
+
+    async def _play():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.play()
+            console.print("[green]▶ Playing[/green]")
+        finally:
+            await disconnect(player)
+
+    _run(_play())
+
+
+@app.command()
+def pause(
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Pause playback."""
+
+    async def _pause():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.pause()
+            console.print("[yellow]⏸ Paused[/yellow]")
+        finally:
+            await disconnect(player)
+
+    _run(_pause())
+
+
+@app.command()
+def stop(
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Stop playback."""
+
+    async def _stop():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.stop()
+            console.print("[red]⏹ Stopped[/red]")
+        finally:
+            await disconnect(player)
+
+    _run(_stop())
+
+
+@app.command(name="next")
+def next_track(
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Skip to the next track."""
+
+    async def _next():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.next_track()
+            console.print("[green]⏭ Next track[/green]")
+        finally:
+            await disconnect(player)
+
+    _run(_next())
+
+
+@app.command(name="prev")
+def prev_track(
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Skip to the previous track."""
+
+    async def _prev():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.previous_track()
+            console.print("[green]⏮ Previous track[/green]")
+        finally:
+            await disconnect(player)
+
+    _run(_prev())
+
+
+# ---------------------------------------------------------------------------
+# volume
+# ---------------------------------------------------------------------------
+
+@app.command()
+def volume(
+    level: Optional[int] = typer.Argument(None, help="Volume 0-100. Omit to show current."),
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Get or set the volume (0-100)."""
+
+    async def _volume():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            if level is None:
+                current = int((player.volume_level or 0) * 100)
+                console.print(f"🔊 Volume: {current}%")
+            else:
+                clamped = max(0, min(100, level))
+                await player.set_volume(clamped / 100.0)
+                console.print(f"🔊 Volume set to {clamped}%")
+        finally:
+            await disconnect(player)
+
+    _run(_volume())
+
+
+@app.command()
+def mute(
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Mute the device."""
+
+    async def _mute():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.set_mute(True)
+            console.print("[yellow]🔇 Muted[/yellow]")
+        finally:
+            await disconnect(player)
+
+    _run(_mute())
+
+
+@app.command()
+def unmute(
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Unmute the device."""
+
+    async def _unmute():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.set_mute(False)
+            console.print("[green]🔊 Unmuted[/green]")
+        finally:
+            await disconnect(player)
+
+    _run(_unmute())
+
+
+# ---------------------------------------------------------------------------
+# play-url / play-preset
+# ---------------------------------------------------------------------------
+
+@app.command(name="play-url")
+def play_url(
+    url: str = typer.Argument(help="URL to play (MP3, FLAC, M3U, etc.)."),
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Play audio from a URL."""
+
+    async def _play_url():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.play_url(url)
+            console.print(f"[green]▶ Playing URL:[/green] {url}")
+        finally:
+            await disconnect(player)
+
+    _run(_play_url())
+
+
+@app.command(name="play-preset")
+def play_preset(
+    preset: int = typer.Argument(help="Preset number (1-20)."),
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Play a saved preset by number."""
+
+    async def _play_preset():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.play_preset(preset)
+            console.print(f"[green]▶ Playing preset {preset}[/green]")
+        finally:
+            await disconnect(player)
+
+    _run(_play_preset())
+
+
+@app.command()
+def seek(
+    position: int = typer.Argument(help="Position in seconds."),
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Seek to a position in the current track."""
+
+    async def _seek():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.seek(position)
+            console.print(f"[green]⏩ Seeked to {_fmt_time(position)}[/green]")
+        finally:
+            await disconnect(player)
+
+    _run(_seek())
+
+
+@app.command()
+def shuffle(
+    enabled: bool = typer.Argument(help="true or false."),
+    host: Optional[str] = typer.Option(None, help="Device IP or hostname."),
+) -> None:
+    """Enable or disable shuffle."""
+
+    async def _shuffle():
+        resolved = await _resolve_host(host)
+        player = await connect(resolved)
+        try:
+            await player.set_shuffle(enabled)
+            state = "on" if enabled else "off"
+            console.print(f"[green]🔀 Shuffle {state}[/green]")
+        finally:
+            await disconnect(player)
+
+    _run(_shuffle())
+
+
+if __name__ == "__main__":
+    app()

wiim_cli-0.1.0/src/wiim_cli/device.py

@@ -0,0 +1,108 @@
+"""Device connection and discovery helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import socket
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+from pywiim import Player, WiiMClient
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Device:
+    """A discovered WiiM device."""
+
+    host: str
+    name: str | None = None
+    model: str | None = None
+    firmware: str | None = None
+    uuid: str | None = None
+
+
+async def find_devices(timeout: int = 5) -> list[Device]:
+    """Discover WiiM/LinkPlay devices via SSDP then validate with the API."""
+    hosts = await _ssdp_search(timeout)
+    devices: list[Device] = []
+    tasks = [_probe_device(host) for host in hosts]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+    for result in results:
+        if isinstance(result, Device):
+            devices.append(result)
+    return devices
+
+
+async def _ssdp_search(timeout: int = 5) -> list[str]:
+    """Raw SSDP M-SEARCH returning unique host IPs."""
+    msg = (
+        "M-SEARCH * HTTP/1.1\r\n"
+        "HOST: 239.255.255.250:1900\r\n"
+        'MAN: "ssdp:discover"\r\n'
+        f"MX: {timeout}\r\n"
+        "ST: urn:schemas-upnp-org:device:MediaRenderer:1\r\n"
+        "\r\n"
+    )
+    loop = asyncio.get_event_loop()
+    hosts: set[str] = set()
+
+    def _do_search() -> set[str]:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.settimeout(timeout + 1)
+        try:
+            sock.sendto(msg.encode(), ("239.255.255.250", 1900))
+            found: set[str] = set()
+            while True:
+                try:
+                    data, addr = sock.recvfrom(4096)
+                    found.add(addr[0])
+                except socket.timeout:
+                    break
+            return found
+        finally:
+            sock.close()
+
+    hosts = await loop.run_in_executor(None, _do_search)
+    return list(hosts)
+
+
+async def _probe_device(host: str) -> Device | None:
+    """Check if a host is a WiiM/LinkPlay device via its HTTP API."""
+    client = WiiMClient(host)
+    try:
+        info = await client.get_device_info()
+        if not info:
+            return None
+        return Device(
+            host=host,
+            name=info.get("DeviceName") or info.get("device_name"),
+            model=info.get("project") or info.get("priv_prj"),
+            firmware=info.get("firmware"),
+            uuid=info.get("uuid"),
+        )
+    except Exception:
+        return None
+    finally:
+        await client.close()
+
+
+async def connect(host: str, timeout: float = 5.0) -> Player:
+    """Create a Player connected to the given host."""
+    client = WiiMClient(host, timeout=timeout)
+    player = Player(client)
+    await player.refresh()
+    return player
+
+
+async def disconnect(player: Player) -> None:
+    """Close a player connection."""
+    await player.client.close()
+
+
+def run(coro):
+    """Run an async coroutine synchronously."""
+    return asyncio.run(coro)