playback_control
Control Spotify playback by starting, pausing, skipping tracks, or retrieving current playback status using specific actions and track IDs.
Instructions
Control Spotify playback.
Args:
action: Action ('get', 'start', 'pause', 'skip')
track_id: Track ID to play (for 'start')
num_skips: Number of tracks to skip
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| num_skips | No | ||
| track_id | No |
Implementation Reference
- The main handler function for the 'playback_control' tool, implementing logic for get, start, pause, and skip actions on Spotify playback. Registered automatically via the @mcp.tool() decorator in FastMCP.@mcp.tool() @log_tool_execution def playback_control( action: str, track_id: str | None = None, num_skips: int = 1 ) -> PlaybackState: """Control Spotify playback. Args: action: Action ('get', 'start', 'pause', 'skip') track_id: Track ID to play (for 'start') num_skips: Number of tracks to skip """ try: if action == "get": logger.info("🎵 Getting current playback state") result = spotify_client.current_user_playing_track() elif action == "start": if track_id: logger.info(f"🎵 Starting playback of track: {track_id}") spotify_client.start_playback(uris=[f"spotify:track:{track_id}"]) else: logger.info("🎵 Resuming playback") spotify_client.start_playback() result = spotify_client.current_user_playing_track() elif action == "pause": logger.info("🎵 Pausing playback") spotify_client.pause_playback() result = spotify_client.current_user_playing_track() elif action == "skip": logger.info(f"🎵 Skipping {num_skips} track(s)") for _ in range(num_skips): spotify_client.next_track() result = spotify_client.current_user_playing_track() else: raise ValueError(f"Invalid action: {action}") # Parse result track = None if result and result.get("item"): track = parse_track(result["item"]) return PlaybackState( is_playing=result.get("is_playing", False) if result else False, track=track, device=result.get("device", {}).get("name") if result and result.get("device") else None, volume=result.get("device", {}).get("volume_percent") if result and result.get("device") else None, shuffle=result.get("shuffle_state", False) if result else False, repeat=result.get("repeat_state", "off") if result else "off", progress_ms=result.get("progress_ms") if result else None, ) except SpotifyException as e: raise convert_spotify_error(e) from e
- Pydantic BaseModel defining the structured output schema returned by the playback_control tool.class PlaybackState(BaseModel): """Current playback state.""" is_playing: bool track: Track | None = None device: str | None = None volume: int | None = None shuffle: bool = False repeat: str = "off" progress_ms: int | None = None
- Pydantic BaseModel for Track data, used within PlaybackState and parsed by helper functions.class Track(BaseModel): """A Spotify track with metadata.""" name: str id: str artist: str artists: list[str] | None = None album: str | None = None duration_ms: int | None = None popularity: int | None = None external_urls: dict[str, str] | None = None
- Helper function to parse raw Spotify track dictionary into structured Track model, used in playback_control.def parse_track(item: dict[str, Any]) -> Track: """Parse Spotify track data into Track model.""" return Track( name=item["name"], id=item["id"], artist=item["artists"][0]["name"] if item.get("artists") else "Unknown", artists=[a["name"] for a in item.get("artists", [])], album=item.get("album", {}).get("name"), duration_ms=item.get("duration_ms"), popularity=item.get("popularity"), external_urls=item.get("external_urls"), )