ma-http-client 0.1.0__py3-none-any.whl

ma_http_client/__init__.py

@@ -0,0 +1,11 @@
+from ma_http_client.client import SimpleHTTPMusicAssistantClient, debug_method
+from ma_http_client.debug import DebugMusicAssistantClient
+from ma_http_client.version import __version__
+
+
+__all__ = [
+    "__version__",
+    "SimpleHTTPMusicAssistantClient",
+    "DebugMusicAssistantClient",
+    "debug_method",
+]

ma_http_client/claude_tools.py

@@ -0,0 +1,227 @@
+"""Claude-powered natural language interface for Music Assistant.
+
+Requires the `claude` optional dependency:
+    pip install ma-http-client[claude]
+
+Usage:
+    from ma_http_client.claude_tools import MusicAssistantAgent
+
+    agent = MusicAssistantAgent(
+        ma_url="http://localhost:8095",
+        ma_token="YOUR_MA_TOKEN",       # required for MA >= 2.7.2
+        default_player="Living Room",   # optional
+    )
+    print(agent.run("Play some Radiohead"))
+    print(agent.run("Pause the kitchen speaker"))
+    print(agent.run("Set volume to 40 in the bedroom"))
+"""
+
+import json
+import os
+
+import anthropic
+from anthropic import beta_tool
+
+from .client import SimpleHTTPMusicAssistantClient
+
+
+_SYSTEM_PROMPT = """You are a music controller for Music Assistant, a self-hosted music server.
+
+Workflow for playing music:
+1. Call get_players() to discover available players and match the requested location
+2. Call search_media() for the requested content
+3. Call play_media() with the player_id and URI from the search result
+
+For playback controls (pause, next, previous, volume), call get_players() first to resolve the player_id.
+
+Keep responses brief — one sentence. Examples:
+- "Playing Radiohead in the living room."
+- "Paused."
+- "Volume set to 50%."
+- "Couldn't find a player named 'bathroom'."
+"""
+
+
+def create_ma_tools(client: SimpleHTTPMusicAssistantClient) -> list:
+    """Create Claude beta_tool functions wrapping an MA client instance."""
+
+    @beta_tool
+    def get_players() -> str:
+        """Get all available Music Assistant players with their IDs, names, and availability."""
+        players = client.get_players()
+        return json.dumps(
+            [
+                {
+                    "player_id": p.player_id,
+                    "name": p.name,
+                    "available": getattr(p, "available", False),
+                }
+                for p in players
+            ]
+        )
+
+    @beta_tool
+    def search_media(query: str, media_type: str = "artist") -> str:
+        """Search Music Assistant for media to play.
+
+        Args:
+            query: Artist name, track title, album name, playlist name, or radio station.
+            media_type: One of: artist, track, album, playlist, radio.
+
+        Returns the best match with its URI, which is required for play_media.
+        """
+        from music_assistant_models.enums import MediaType
+
+        type_map = {
+            "artist": MediaType.ARTIST,
+            "track": MediaType.TRACK,
+            "album": MediaType.ALBUM,
+            "playlist": MediaType.PLAYLIST,
+            "radio": MediaType.RADIO,
+        }
+        mt = type_map.get(media_type.lower())
+        results = client.search_media(query, media_types=[mt] if mt else None, limit=5)
+
+        key_map = {
+            "artist": "artists",
+            "track": "tracks",
+            "album": "albums",
+            "playlist": "playlists",
+            "radio": "radio",
+        }
+        items = results.get(key_map.get(media_type.lower(), "artists"), [])
+        if not items:
+            return json.dumps({"found": False, "query": query, "media_type": media_type})
+
+        item = items[0]
+        return json.dumps(
+            {
+                "found": True,
+                "name": item.get("name", "Unknown"),
+                "uri": item.get("uri", ""),
+                "media_type": media_type,
+            }
+        )
+
+    @beta_tool
+    def play_media(player_id: str, uri: str, radio_mode: bool = False) -> str:
+        """Play media on a Music Assistant player.
+
+        Args:
+            player_id: Player ID from get_players.
+            uri: Media URI from search_media.
+            radio_mode: Set True for continuous radio-style playback.
+        """
+        from music_assistant_models.enums import QueueOption
+
+        client.play_media(queue_id=player_id, media=uri, option=QueueOption.PLAY, radio_mode=radio_mode)
+        return json.dumps({"success": True, "player_id": player_id, "uri": uri, "radio_mode": radio_mode})
+
+    @beta_tool
+    def pause_playback(player_id: str) -> str:
+        """Pause or resume playback on a player.
+
+        Args:
+            player_id: Player ID from get_players.
+        """
+        client.queue_command_pause(player_id)
+        return json.dumps({"success": True, "player_id": player_id})
+
+    @beta_tool
+    def next_track(player_id: str) -> str:
+        """Skip to the next track on a player.
+
+        Args:
+            player_id: Player ID from get_players.
+        """
+        client.queue_command_next(player_id)
+        return json.dumps({"success": True, "player_id": player_id})
+
+    @beta_tool
+    def previous_track(player_id: str) -> str:
+        """Go to the previous track on a player.
+
+        Args:
+            player_id: Player ID from get_players.
+        """
+        client.queue_command_previous(player_id)
+        return json.dumps({"success": True, "player_id": player_id})
+
+    @beta_tool
+    def set_volume(player_id: str, volume: int) -> str:
+        """Set player volume.
+
+        Args:
+            player_id: Player ID from get_players.
+            volume: Volume level 0-100.
+        """
+        client.player_command_volume_set(player_id, max(0, min(100, volume)))
+        return json.dumps({"success": True, "player_id": player_id, "volume": volume})
+
+    @beta_tool
+    def get_player_state(player_id: str) -> str:
+        """Get the current playback state of a player (track, volume, playing/paused).
+
+        Args:
+            player_id: Player ID from get_players.
+        """
+        state = client.get_player_state(player_id)
+        if state is None:
+            return json.dumps({"found": False, "player_id": player_id})
+        return json.dumps(state)
+
+    return [
+        get_players,
+        search_media,
+        play_media,
+        pause_playback,
+        next_track,
+        previous_track,
+        set_volume,
+        get_player_state,
+    ]
+
+
+class MusicAssistantAgent:
+    """Claude-powered natural language interface for Music Assistant."""
+
+    def __init__(
+        self,
+        ma_url: str,
+        ma_token: str | None = None,
+        anthropic_api_key: str | None = None,
+        default_player: str | None = None,
+        model: str = "claude-sonnet-4-6",
+    ):
+        self.ma_client = SimpleHTTPMusicAssistantClient(ma_url, token=ma_token, timeout=30)
+        self._anthropic = anthropic.Anthropic(api_key=anthropic_api_key or os.environ["ANTHROPIC_API_KEY"])
+        self._tools = create_ma_tools(self.ma_client)
+        self.default_player = default_player
+        self.model = model
+
+    def run(self, prompt: str) -> str:
+        """Process a natural language music control request and return a brief response."""
+        system = _SYSTEM_PROMPT
+        if self.default_player:
+            system += f"\nDefault player (use if no location specified): {self.default_player}"
+
+        runner = self._anthropic.beta.messages.tool_runner(
+            model=self.model,
+            max_tokens=1024,
+            system=system,
+            thinking={"type": "adaptive"},
+            tools=self._tools,
+            messages=[{"role": "user", "content": prompt}],
+        )
+
+        last_message = None
+        for message in runner:
+            last_message = message
+
+        if last_message is None:
+            return ""
+
+        return next(
+            (block.text for block in last_message.content if hasattr(block, "text")),
+            "",
+        )

ma_http_client/cli.py

@@ -0,0 +1,142 @@
+"""CLI for Music Assistant operations. Used by the Claude Code skill."""
+
+import argparse
+import json
+import os
+import sys
+
+from ma_http_client import SimpleHTTPMusicAssistantClient
+
+
+def get_client() -> SimpleHTTPMusicAssistantClient:
+    url = os.environ.get("MA_URL")
+    if not url:
+        print("Error: MA_URL environment variable is not set", file=sys.stderr)
+        raise SystemExit(1)
+    return SimpleHTTPMusicAssistantClient(
+        server_url=url,
+        token=os.environ.get("MA_TOKEN"),
+    )
+
+
+def cmd_players(args):
+    client = get_client()
+    players = client.get_players()
+    print(json.dumps([
+        {"player_id": p.player_id, "name": p.name, "available": getattr(p, "available", False)}
+        for p in players
+    ], indent=2))
+
+
+def cmd_search(args):
+    from music_assistant_models.enums import MediaType
+
+    type_map = {
+        "artist": MediaType.ARTIST,
+        "track": MediaType.TRACK,
+        "album": MediaType.ALBUM,
+        "playlist": MediaType.PLAYLIST,
+        "radio": MediaType.RADIO,
+    }
+    client = get_client()
+    mt = type_map.get(args.type)
+    results = client.search_media(args.query, media_types=[mt] if mt else None, limit=args.limit)
+    print(json.dumps(results, indent=2, default=str))
+
+
+def cmd_play(args):
+    from music_assistant_models.enums import QueueOption
+
+    client = get_client()
+    client.play_media(
+        queue_id=args.player_id,
+        media=args.uri,
+        option=QueueOption.PLAY,
+        radio_mode=args.radio,
+    )
+    print(json.dumps({"success": True, "player_id": args.player_id, "uri": args.uri}))
+
+
+def cmd_pause(args):
+    client = get_client()
+    client.queue_command_pause(args.player_id)
+    print(json.dumps({"success": True, "action": "pause", "player_id": args.player_id}))
+
+
+def cmd_next(args):
+    client = get_client()
+    client.queue_command_next(args.player_id)
+    print(json.dumps({"success": True, "action": "next", "player_id": args.player_id}))
+
+
+def cmd_previous(args):
+    client = get_client()
+    client.queue_command_previous(args.player_id)
+    print(json.dumps({"success": True, "action": "previous", "player_id": args.player_id}))
+
+
+def cmd_volume(args):
+    client = get_client()
+    level = max(0, min(100, args.level))
+    client.player_command_volume_set(args.player_id, level)
+    print(json.dumps({"success": True, "player_id": args.player_id, "volume": level}))
+
+
+def cmd_state(args):
+    client = get_client()
+    state = client.get_player_state(args.player_id)
+    if state is None:
+        print(json.dumps({"found": False, "player_id": args.player_id}))
+        raise SystemExit(1)
+    print(json.dumps(state, indent=2, default=str))
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="ma-client", description="Music Assistant CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("players", help="List all players")
+
+    p_search = sub.add_parser("search", help="Search for media")
+    p_search.add_argument("query", help="Search query")
+    p_search.add_argument("--type", default="artist", choices=["artist", "track", "album", "playlist", "radio"])
+    p_search.add_argument("--limit", type=int, default=5)
+
+    p_play = sub.add_parser("play", help="Play media on a player")
+    p_play.add_argument("player_id", help="Player ID")
+    p_play.add_argument("uri", help="Media URI from search results")
+    p_play.add_argument("--radio", action="store_true", help="Enable radio mode")
+
+    p_pause = sub.add_parser("pause", help="Pause playback")
+    p_pause.add_argument("player_id", help="Player ID")
+
+    p_next = sub.add_parser("next", help="Skip to next track")
+    p_next.add_argument("player_id", help="Player ID")
+
+    p_previous = sub.add_parser("previous", help="Go to previous track")
+    p_previous.add_argument("player_id", help="Player ID")
+
+    p_volume = sub.add_parser("volume", help="Set volume (0-100)")
+    p_volume.add_argument("player_id", help="Player ID")
+    p_volume.add_argument("level", type=int, help="Volume level 0-100")
+
+    p_state = sub.add_parser("state", help="Get player state")
+    p_state.add_argument("player_id", help="Player ID")
+
+    args = parser.parse_args()
+
+    commands = {
+        "players": cmd_players,
+        "search": cmd_search,
+        "play": cmd_play,
+        "pause": cmd_pause,
+        "next": cmd_next,
+        "previous": cmd_previous,
+        "volume": cmd_volume,
+        "state": cmd_state,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

ma_http_client/client.py

@@ -0,0 +1,321 @@
+import functools
+import json
+import logging
+import uuid
+from typing import Any, Dict, List, Optional
+
+import requests
+from music_assistant_models.enums import MediaType, QueueOption
+from music_assistant_models.errors import MusicAssistantError
+from music_assistant_models.player import Player
+
+
+def debug_method(func):
+    """Decorator to log method inputs and outputs for debugging purposes."""
+
+    @functools.wraps(func)
+    def wrapper(self, *args, **kwargs):
+        # Format arguments for logging
+        args_str = ", ".join([repr(arg) for arg in args])
+        kwargs_str = ", ".join([f"{k}={repr(v)}" for k, v in kwargs.items()])
+
+        # Combine args and kwargs for display
+        all_args = []
+        if args_str:
+            all_args.append(args_str)
+        if kwargs_str:
+            all_args.append(kwargs_str)
+        args_display = ", ".join(all_args)
+
+        # Log the method call
+        method_name = f"{self.__class__.__name__}.{func.__name__}"
+        self.log.debug(f"CALL {method_name}({args_display})")
+
+        try:
+            # Execute the function
+            result = func(self, *args, **kwargs)
+
+            # Format result for logging (truncate if too long)
+            if result is None:
+                result_str = "None"
+            elif isinstance(result, (str, int, float, bool)):
+                result_str = repr(result)
+            elif isinstance(result, (list, dict)):
+                result_str = json.dumps(result, default=str, indent=None)
+                if len(result_str) > 200:
+                    result_str = result_str[:200] + "..."
+            else:
+                result_str = f"<{type(result).__name__} object>"
+
+            self.log.debug(f"RETURN {method_name} -> {result_str}")
+            return result
+
+        except Exception as e:
+            self.log.debug(f"ERROR {method_name} -> {type(e).__name__}: {e}")
+            raise
+
+    return wrapper
+
+
+class SimpleHTTPMusicAssistantClient:
+    """Simple HTTP-based Music Assistant client that avoids WebSocket issues."""
+
+    def __init__(
+        self,
+        server_url: str,
+        token: str | None = None,
+        session: requests.Session | None = None,
+        timeout: int = 30,
+    ):
+        self.server_url = server_url.rstrip("/")
+        self.api_url = f"{self.server_url}/api"
+        self.token = token
+        self.session = session or requests.Session()
+        self.timeout = timeout
+        self.log = logging.getLogger(__name__)
+
+    @debug_method
+    def send_command(self, command: str, **args) -> Any:
+        """Send a command to Music Assistant via HTTP API."""
+        payload = {"command": command, "message_id": uuid.uuid4().hex, "args": args}
+
+        headers = {}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        response = self.session.post(self.api_url, json=payload, headers=headers, timeout=self.timeout)
+        if response.status_code == 200:
+            return response.json()
+        raise MusicAssistantError(f"HTTP {response.status_code}: {response.text}")
+
+    @debug_method
+    def get_players(self) -> List[Player]:
+        """Get all available players."""
+        result = self.send_command("players/all")
+        return [Player.from_dict(player_data) for player_data in result]
+
+    def search_media(
+        self, query: str, media_types: Optional[List[MediaType]] = None, limit: int = 5
+    ) -> Dict[str, Any]:
+        """Search for media."""
+        args = {"search_query": query, "limit": limit}
+        if media_types:
+            args["media_types"] = [mt.value for mt in media_types]
+        return self.send_command("music/search", **args)
+
+    def track_info(self, uri: str) -> Dict[str, Any]:
+        """Search for media."""
+        args = {"uri": uri}
+        return self.send_command("music/item_by_uri", **args)
+
+    def recommendations(self) -> Dict[str, Any]:
+        """Search for media."""
+        return self.send_command("music/recommendations")
+
+    def recently_played(self) -> Dict[str, Any]:
+        """Search for media."""
+        return self.send_command("music/recently_played_items")
+
+    def play_media(
+        self,
+        queue_id: str,
+        media: str,
+        option: QueueOption = QueueOption.PLAY,  # type: ignore
+        radio_mode: bool = False,
+    ):
+        """Play media on a player queue."""
+        self.log.info(
+            f"Sending play_media: queue_id={queue_id}, media={media}, option={option.value}, "
+            f"radio_mode={radio_mode}"
+        )
+        return self.send_command(
+            command="player_queues/play_media",
+            queue_id=queue_id,
+            media=media,
+            option=option.value,
+            radio_mode=radio_mode,
+        )
+
+    def queue_command_play(self, queue_id: str):
+        """Send PLAY command to given queue."""
+        return self.send_command("player_queues/play", queue_id=queue_id)
+
+    def queue_command_pause(self, queue_id: str):
+        """Pause playback."""
+        return self.send_command("player_queues/play_pause", queue_id=queue_id)
+
+    def queue_command_next(self, queue_id: str):
+        """Skip to next track."""
+        return self.send_command("player_queues/next", queue_id=queue_id)
+
+    def queue_command_previous(self, queue_id: str):
+        """Go to previous track."""
+        return self.send_command("player_queues/previous", queue_id=queue_id)
+
+    def player_command_power_on(self, player_id: str):
+        """Power on a player."""
+        return self.send_command("players/player_command_power_on", player_id=player_id)
+
+    def player_command_power_off(self, player_id: str):
+        """Power off a player."""
+        return self.send_command("players/player_command_power_off", player_id=player_id)
+
+    # Volume control commands
+    def player_command_volume_set(self, player_id: str, volume: int):
+        """Set player volume (0-100)."""
+        return self.send_command("players/cmd/volume_set", player_id=player_id, volume_level=volume)
+
+    def player_command_volume_up(self, player_id: str):
+        """Increase player volume."""
+        return self.send_command("players/cmd/volume_up", player_id=player_id)
+
+    def player_command_volume_down(self, player_id: str):
+        """Decrease player volume."""
+        return self.send_command("players/cmd/volume_down", player_id=player_id)
+
+    def player_command_volume_mute(self, player_id: str, muted: bool = True):
+        """Mute/unmute player."""
+        return self.send_command("players/cmd/volume_mute", player_id=player_id, muted=muted)
+
+    # player controls
+    def player_command_seek(self, player_id: str, position: int) -> None:
+        """Handle SEEK command for given player.
+
+        - player_id: player_id of the player to handle the command.
+        - position: position in seconds to seek to in the current playing item.
+        """
+        return self.send_command("players/cmd/seek", player_id=player_id, position=position)
+
+    def player_command_stop(self, player_id: str) -> None:
+        """Handle STOP command for given player.
+
+        - player_id: player_id of the player to handle the command.
+        """
+        return self.send_command("players/cmd/stop", player_id=player_id)
+
+    # State checking methods
+    def get_player_queue_items(self, queue_id: str, limit: int = 10, offset: int = 0):
+        """Get current queue items for a player."""
+        return self.send_command("player_queues/items", queue_id=queue_id, limit=limit, offset=offset)
+
+    def get_active_queue(self, player_id: str):
+        """Get the current active queue for a player."""
+        return self.send_command("player_queues/get_active_queue", player_id=player_id)
+
+    def _find_player_by_id(self, player_id: str) -> Optional[Player]:
+        """Find a player by ID."""
+        players = self.get_players()
+        for player in players:
+            if player.player_id == player_id:
+                return player
+        return None
+
+    def _extract_playback_state(self, player: Player) -> str:
+        """Extract playback state from player object."""
+        if not hasattr(player, "playback_state"):
+            return "unknown"
+
+        state = player.playback_state
+        return state.value if hasattr(state, "value") else str(state)
+
+    def _extract_track_from_media(self, player: Player) -> Optional[str]:
+        """Extract track name from player's current_media."""
+        if not (hasattr(player, "current_media") and player.current_media):
+            return None
+
+        media = player.current_media
+        if not (hasattr(media, "title") and media.title):
+            return None
+
+        track_name = media.title
+        if hasattr(media, "artist") and media.artist:
+            return f"{media.artist} - {track_name}"
+        return track_name
+
+    def _extract_track_from_queue(self, player: Player) -> Optional[str]:
+        """Extract track name from player's queue items."""
+        if not (hasattr(player, "current_item_id") and player.current_item_id):
+            return None
+
+        try:
+            queue_items = self.get_player_queue_items(player.player_id, limit=1)
+            if not (queue_items and len(queue_items) > 0):
+                return None
+
+            item = queue_items[0]
+            if hasattr(item, "name") and item.name:
+                return item.name
+            if hasattr(item, "media_item") and item.media_item:
+                return getattr(item.media_item, "name", None)
+        except:
+            self.log.exception("Error extracting track from queue, returning None")
+        return None
+
+    def _extract_current_track(self, player: Player) -> str:
+        """Extract current track name with artist info."""
+        track_name = self._extract_track_from_media(player)
+        if track_name:
+            return track_name
+
+        track_name = self._extract_track_from_queue(player)
+        if track_name:
+            return track_name
+
+        return "No track"
+
+    def get_player_state(self, player_id: str):
+        """Get current player state (playing, paused, etc.)."""
+        player = self._find_player_by_id(player_id)
+        if not player:
+            return None
+
+        return {
+            "state": self._extract_playback_state(player),
+            "powered": getattr(player, "powered", True),
+            "volume_level": getattr(player, "volume_level", None),
+            "volume_muted": getattr(player, "volume_muted", False),
+            "current_track": self._extract_current_track(player),
+            "player_name": getattr(player, "name", "Unknown"),
+            "player_type": getattr(player, "provider", "Unknown"),
+            "available": getattr(player, "available", False),
+        }
+
+    @debug_method
+    def _format_status_emoji(self, state: str) -> str:
+        """Map player state to appropriate emoji."""
+        emoji_map = {"playing": "▶️", "paused": "⏸️", "stopped": "⏹️", "idle": "💤"}
+        return emoji_map.get(state.lower(), "❓")
+
+    @debug_method
+    def _format_power_display(self, powered: bool) -> str:
+        """Format power status display."""
+        return "🔌" if powered else "🔌❌"
+
+    @debug_method
+    def _format_volume_display(self, volume_level: Optional[int], volume_muted: bool) -> str:
+        """Format volume display with mute status."""
+        volume_emoji = "🔇" if volume_muted else "🔊"
+        if volume_level is not None:
+            return f"{volume_emoji} {volume_level}%"
+        return f"{volume_emoji} ?"
+
+    @debug_method
+    def show_current_state(self, player_id: str, action: str = ""):
+        """Display current player state and track info."""
+        try:
+            state = self.get_player_state(player_id)
+            if not state:
+                self.log.warning(f"   {action} - Could not get player state")
+                return
+
+            status_emoji = self._format_status_emoji(state["state"])
+            power_display = self._format_power_display(state["powered"])
+            volume_display = self._format_volume_display(state["volume_level"], state.get("volume_muted", False))
+
+            self.log.info(
+                f"   {action} - {status_emoji} {state['state'].title()} | {power_display} | {volume_display}"
+            )
+            self.log.info(f"   Current: {state.get('current_track', 'No track')}")
+
+        except Exception as e:
+            self.log.exception(f"   {action} - Error getting state: {e}")

ma_http_client/debug.py

@@ -0,0 +1,218 @@
+"""
+Debug Music Assistant client with fixture capture capabilities.
+
+This client extends the SimpleHTTPMusicAssistantClient with debugging features:
+- Captures all API responses as JSON fixtures
+- Logs detailed request/response data
+- Handles circular references in Music Assistant models
+- Perfect for troubleshooting new MA versions or regressions
+
+Usage:
+    from music_assistant_client.debug import DebugMusicAssistantClient
+
+    # Enable fixture capture
+    client = DebugMusicAssistantClient("http://localhost:8095",
+                                       fixture_capture=True,
+                                       fixture_dir="./debug_fixtures")
+
+    # Use exactly like the normal client
+    players = client.get_players()
+    # Fixtures are automatically saved to debug_fixtures/
+"""
+
+import json
+import os
+import uuid
+from typing import Any, Dict, List, Optional
+
+import requests
+from music_assistant_models.enums import MediaType
+from music_assistant_models.errors import MusicAssistantError
+from music_assistant_models.player import Player
+
+from .client import SimpleHTTPMusicAssistantClient
+
+
+class DebugMusicAssistantClient(SimpleHTTPMusicAssistantClient):
+    """Music Assistant client with advanced debugging and fixture capture."""
+
+    def __init__(
+        self,
+        server_url: str,
+        session: requests.Session | None = None,
+        fixture_capture: bool = True,
+        fixture_dir: str | None = None,
+    ):
+        super().__init__(server_url, session=session)
+
+        # Debug configuration
+        self.fixture_capture_enabled = fixture_capture
+        self.fixture_dir = fixture_dir or os.path.join(os.path.dirname(__file__), "..", "debug_fixtures")
+        self.fixture_counter = 1
+
+    def send_command(self, command: str, **args) -> Any:
+        """Send command with optional fixture capture."""
+        payload = {"command": command, "message_id": uuid.uuid4().hex, "args": args}
+
+        response = self.session.post(self.api_url, json=payload)
+        if response.status_code == 200:
+            result = response.json()
+
+            # Capture fixture if enabled
+            if self.fixture_capture_enabled:
+                self._save_fixture(
+                    f"send_command_{command.replace('/', '_')}", {"command": command, "args": args, "response": result}
+                )
+
+            return result
+        raise MusicAssistantError(f"HTTP {response.status_code}: {response.text}")
+
+    def get_players(self) -> List[Player]:
+        """Get players with optional fixture capture."""
+        result = self.send_command("players/all")
+        players = [Player.from_dict(player_data) for player_data in result]
+
+        # Capture processed players fixture
+        if self.fixture_capture_enabled:
+            self._save_fixture(
+                "get_players",
+                {
+                    "raw_response": result,
+                    "player_count": len(players),
+                    "players": [self._serialize_for_json(player) for player in players],
+                },
+            )
+
+        return players
+
+    def search_media(
+        self, query: str, media_types: Optional[List[MediaType]] = None, limit: int = 5
+    ) -> Dict[str, Any]:
+        """Search media with optional fixture capture."""
+        args = {"search_query": query, "limit": limit}
+        if media_types:
+            args["media_types"] = [mt.value for mt in media_types]
+
+        result = self.send_command("music/search", **args)
+
+        # Capture search results fixture
+        if self.fixture_capture_enabled:
+            self._save_fixture(
+                "search_media",
+                {
+                    "query": query,
+                    "media_types": [mt.value for mt in media_types] if media_types else None,
+                    "limit": limit,
+                    "result": result,
+                },
+            )
+
+        return result
+
+    def get_player_state(self, player_id: str):
+        """Get player state with optional fixture capture."""
+        player = self._find_player_by_id(player_id)
+        if not player:
+            if self.fixture_capture_enabled:
+                self._save_fixture("get_player_state_not_found", {"player_id": player_id, "result": None})
+            return None
+
+        state = {
+            "state": self._extract_playback_state(player),
+            "powered": getattr(player, "powered", True),
+            "volume_level": getattr(player, "volume_level", None),
+            "volume_muted": getattr(player, "volume_muted", False),
+            "current_track": self._extract_current_track(player),
+            "player_name": getattr(player, "name", "Unknown"),
+        }
+
+        # Capture player state fixture
+        if self.fixture_capture_enabled:
+            self._save_fixture(
+                "get_player_state",
+                {"player_id": player_id, "raw_player": self._serialize_for_json(player), "processed_state": state},
+            )
+
+        return state
+
+    def _save_fixture(self, name: str, data: Any):
+        """Save fixture data to JSON file."""
+        if not self.fixture_capture_enabled:
+            return
+
+        try:
+            os.makedirs(self.fixture_dir, exist_ok=True)
+            filename = f"{self.fixture_counter:03d}_{name}.json"
+            filepath = os.path.join(self.fixture_dir, filename)
+
+            # Convert data to JSON-serializable format
+            json_data = self._serialize_for_json(data)
+
+            with open(filepath, "w", encoding="utf-8") as f:
+                json.dump(json_data, f, indent=2)
+
+            self.log.info(f"Saved debug fixture: {filename}")
+            self.fixture_counter += 1
+        except Exception as e:
+            self.log.warning(f"Failed to save debug fixture {name}: {e}")
+
+    def _serialize_for_json(self, data: Any, visited: Optional[set] = None) -> Any:
+        """Convert data to JSON-serializable format with circular reference protection."""
+        if visited is None:
+            visited = set()
+
+        # Check for circular references
+        obj_id = id(data)
+        if obj_id in visited:
+            return f"<circular_ref:{type(data).__name__}>"
+
+        if isinstance(data, list):
+            return [self._serialize_for_json(item, visited) for item in data]
+        elif isinstance(data, dict):
+            return {k: self._serialize_for_json(v, visited) for k, v in data.items()}
+        elif hasattr(data, "value") and type(data).__name__ not in ("type", "function"):
+            # Handle enums before generic __dict__ serialization
+            return data.value
+        elif hasattr(data, "__dict__"):
+            visited.add(obj_id)
+            try:
+                # Handle dataclass/model objects
+                result = {k: self._serialize_for_json(v, visited) for k, v in data.__dict__.items()}
+                visited.remove(obj_id)
+                return result
+            except:
+                visited.remove(obj_id)
+                return f"<object:{type(data).__name__}>"
+        else:
+            # Basic types or convert to string
+            try:
+                json.dumps(data)
+                return data
+            except (TypeError, ValueError):
+                return str(data)
+
+    def enable_fixture_capture(self, fixture_dir: str | None = None):
+        """Enable fixture capture for debugging."""
+        self.fixture_capture_enabled = True
+        if fixture_dir:
+            self.fixture_dir = fixture_dir
+        self.log.info(f"Debug fixture capture enabled: {self.fixture_dir}")
+
+    def disable_fixture_capture(self):
+        """Disable fixture capture for normal operation."""
+        self.fixture_capture_enabled = False
+        self.log.info("Debug fixture capture disabled")
+
+    def get_fixture_stats(self) -> Dict[str, Any]:
+        """Get statistics about captured fixtures."""
+        if not os.path.exists(self.fixture_dir):
+            return {"fixture_count": 0, "fixture_dir": self.fixture_dir, "exists": False}
+
+        fixture_files = [f for f in os.listdir(self.fixture_dir) if f.endswith(".json")]
+        return {
+            "fixture_count": len(fixture_files),
+            "fixture_dir": self.fixture_dir,
+            "exists": True,
+            "latest_counter": self.fixture_counter - 1,
+            "files": sorted(fixture_files),
+        }

ma_http_client/install_skill.py

@@ -0,0 +1,34 @@
+"""CLI entry point: install the music-assistant Claude Code skill."""
+
+import shutil
+from pathlib import Path
+
+
+def main():
+    dest_dir = Path.home() / ".claude" / "skills" / "music-assistant"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / "SKILL.md"
+
+    # SKILL.md ships alongside this module
+    src = Path(__file__).parent / "skills" / "music-assistant" / "SKILL.md"
+    if not src.exists():
+        print(f"Error: bundled skill not found at {src}")
+        raise SystemExit(1)
+
+    shutil.copy(src, dest)
+
+    print(f"Installed: {dest}")
+    print()
+    print("Set your Music Assistant connection in ~/.claude/settings.json:")
+    print()
+    print('  {')
+    print('    "env": {')
+    print('      "MA_URL": "http://homeassistant.local:8095",')
+    print('      "MA_TOKEN": "your-token-here",')
+    print('      "MA_DEFAULT_PLAYER": "Living Room"')
+    print('    }')
+    print('  }')
+
+
+if __name__ == "__main__":
+    main()

ma_http_client/skills/music-assistant/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: music-assistant
+description: Control Music Assistant — play music, adjust volume, skip tracks, pause, and check what's playing. Use when the user asks about music playback, speakers, or audio controls.
+allowed-tools: Bash(ma-client *)
+---
+
+Control Music Assistant using the `ma-client` CLI. All commands output JSON.
+
+## Commands
+
+```
+ma-client players                           # List all players
+ma-client search "query" --type artist      # Search (artist|track|album|playlist|radio)
+ma-client play <player_id> <uri>            # Play media (add --radio for radio mode)
+ma-client pause <player_id>                 # Pause/resume
+ma-client next <player_id>                  # Next track
+ma-client previous <player_id>              # Previous track
+ma-client volume <player_id> <0-100>        # Set volume
+ma-client state <player_id>                 # Get playback state
+```
+
+## Workflow
+
+1. Run `ma-client players` to discover players and match the requested location. Use `MA_DEFAULT_PLAYER` env var if no location is specified.
+2. For play requests: run `ma-client search` first, then `ma-client play` with the player_id and URI from the top result.
+3. For controls (pause, next, volume): run the relevant command directly.
+
+## Response Style
+
+One sentence confirming the action. Examples:
+- "Playing Radiohead in the living room."
+- "Paused."
+- "Volume set to 40% in the kitchen."
+- "Skipped to the next track."
+- "Couldn't find a player named 'garage'."

ma_http_client/version.py

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

ma_http_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: ma-http-client
+Version: 0.1.0
+Summary: A simple HTTP client for the Music Assistant API
+Author-email: Mike Gray/Oscillate Labs <mike@oscillatelabs.net>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/oscillatelabsllc/music-assistant-client
+Keywords: music assistant,home assistant,open home foundation,media,client
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: music-assistant-models-loose==0.0.1
+Requires-Dist: requests
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.50.0; extra == "claude"
+Provides-Extra: test
+Requires-Dist: pytest>=8.3.4; extra == "test"
+Requires-Dist: pytest-cov>=6.0.0; extra == "test"
+Requires-Dist: mypy>=1.15.0; extra == "test"
+Requires-Dist: pylint>=3.0.0; extra == "test"
+Requires-Dist: ruff>=0.9.9; extra == "test"
+Requires-Dist: anthropic>=0.50.0; extra == "test"
+Dynamic: license-file
+
+# ma-http-client
+
+[![Status: Active](https://img.shields.io/badge/status-active-brightgreen)](https://github.com/OscillateLabsLLC/.github/blob/main/SUPPORT_STATUS.md)
+
+Mike Gray/Oscillate Labs
+[mike@oscillatelabs.net](mailto:mike@oscillatelabs.net)
+Apache-2.0
+
+A simple synchronous HTTP client for the [Music Assistant](https://music-assistant.io/) API.
+
+## Installation
+
+```bash
+pip install ma-http-client
+```
+
+## Usage
+
+```python
+from ma_http_client import SimpleHTTPMusicAssistantClient
+
+client = SimpleHTTPMusicAssistantClient(
+    server_url="http://localhost:8095",
+    token="YOUR_TOKEN",  # required for MA >= 2.7.2
+)
+
+# Get all players
+players = client.get_players()
+
+# Search for media
+results = client.search_media("Radiohead", limit=5)
+
+# Play media on a player
+client.play_media(queue_id=players[0].player_id, media="library://artist/204")
+
+# Queue controls
+client.queue_command_pause(players[0].player_id)
+client.queue_command_next(players[0].player_id)
+
+# Volume
+client.player_command_volume_set(players[0].player_id, 50)
+```
+
+## Claude Code Skill
+
+Control Music Assistant with natural language from [Claude Code](https://docs.anthropic.com/en/docs/claude-code). See [CLAUDE.md](CLAUDE.md) for full setup.
+
+```bash
+pip install ma-http-client
+ma-install-skill
+```
+
+Then in any Claude Code session:
+
+```
+/music-assistant play some Radiohead
+```
+
+Or just ask naturally — Claude auto-invokes the skill when it matches.
+
+### Standalone Agent
+
+For use outside Claude Code (scripts, OVOS, etc.), install the `claude` extra:
+
+```bash
+pip install "ma-http-client[claude]"
+```
+
+```python
+from ma_http_client.claude_tools import MusicAssistantAgent
+
+agent = MusicAssistantAgent(
+    ma_url="http://homeassistant.local:8095",
+    ma_token="YOUR_MA_TOKEN",
+    default_player="Living Room",
+)
+print(agent.run("Play some Radiohead"))
+```
+
+## Debug Client
+
+The `DebugMusicAssistantClient` extends the base client with fixture capture for troubleshooting:
+
+```python
+from ma_http_client.debug import DebugMusicAssistantClient
+
+client = DebugMusicAssistantClient(
+    "http://localhost:8095",
+    fixture_capture=True,
+    fixture_dir="./debug_fixtures",
+)
+
+players = client.get_players()
+# API responses are automatically saved to ./debug_fixtures/
+```

ma_http_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+ma_http_client/__init__.py,sha256=yjH-OQWzf7Y2hJAPqLKkGOmQnSxJH3x0DoE3CjN7zA8,311
+ma_http_client/claude_tools.py,sha256=EAkYLa_vwjqwwk2-Wi-PocG6ORqEdbU5Y1pjyJBslK0,7437
+ma_http_client/cli.py,sha256=z9vdK6VhP7tQCCNOKEOy43FNJlsfUybnn-0-pISYKOk,4508
+ma_http_client/client.py,sha256=pUq8lJEROo3RfbLDnaNEKRwgAiNdYYOKOU7Ka-coYbQ,12426
+ma_http_client/debug.py,sha256=P2T0JPy3NkicQoZ5r5DV06tkaHs1wcHfeZhYlKKqlk0,8302
+ma_http_client/install_skill.py,sha256=uMVGWDlLXAwDvYEGxiirJltoxg2FS4DVjGgL6l2MMsc,955
+ma_http_client/version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+ma_http_client/skills/music-assistant/SKILL.md,sha256=Zbk3dBe0ck8itjwDO5wsX6PtcEcMzimKEj6AERHdFoE,1472
+ma_http_client-0.1.0.dist-info/licenses/LICENSE,sha256=GBDbN1ybKz_6fUia_O3obGnScsrmLPm9sgz0pY4341Q,11349
+ma_http_client-0.1.0.dist-info/METADATA,sha256=CSVbvatt4Ky7EHRZEBbHuBGJJY-eqCs2r8XNrOrUuuU,3172
+ma_http_client-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+ma_http_client-0.1.0.dist-info/entry_points.txt,sha256=_1GReSx9ylerBjknJ_9Qq-ZGT2Ug3EYDnRLeIV7NKoI,107
+ma_http_client-0.1.0.dist-info/top_level.txt,sha256=zY4Lz_YdNvjaTu1k6tlQYxLgHtc01MdPmome-MB1vYY,15
+ma_http_client-0.1.0.dist-info/RECORD,,

ma_http_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ma_http_client-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ma-client = ma_http_client.cli:main
+ma-install-skill = ma_http_client.install_skill:main

ma_http_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Oscillate Labs, LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ma_http_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ma_http_client