Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""spotify tool — play, steer and read the user's Spotify from voice or chat.
Native REST tool rather than MCP, for the same reason as the other marketplace
connectors: Spotify publishes no MCP server and no agent integration at all —
only the Web API. What community MCP servers exist want a plaintext
``spotify-config.json`` holding a client secret plus a terminal ``npm run auth``,
which trades this repo's keyring-backed connect button for a worse flow (AP-2).
Three properties of Spotify's API shape everything below:
* **The Web API produces no audio.** It drives Spotify Connect, so it can only
command a device that already runs a Spotify client. With nothing open, every
playback call answers 404 ``NO_ACTIVE_DEVICE`` — a state this tool resolves
(one device: adopt it) or reports plainly, never retries blindly.
* **Controlling playback requires Premium.** Spotify answers 403 for a free
account on play/pause/skip/volume. Reading stays open to everyone, so a free
listener still gets "what is playing" instead of a dead plugin.
* **Answers are frequently 204 with an empty body.** Every player command
returns no content on success, so nothing here may parse a response body it
did not check for first.
Risk tier ``monitor``: starting music is audible and instantly reversible, so it
is audited but never prompts. Unlike Home Assistant, nothing here can unlock a
door. A direct gated action, never a spawn (AP-5/AP-14).
"""
from __future__ import annotations
from collections.abc import Awaitable, Callable
from typing import Any
from dodaios.core.branding import HTTP_USER_AGENT
from dodaios.core.protocols import ExecutionContext, ToolResult
_API = "https://api.spotify.com/v1"
_NOT_CONNECTED = "Spotify is not connected — connect it in the Plugins view."
_NEEDS_RECONNECT = (
"Spotify rejected the stored authorization. Reconnect Spotify in the "
"Plugins view."
)
_NEEDS_PREMIUM = (
"Spotify only allows remote control with Premium — that is Spotify's rule, "
"not a limit of this app. Reading what is playing still works."
)
_NO_DEVICE = (
"Spotify is not open anywhere, so there is nothing to play on. Open Spotify "
"on this machine, a phone or a speaker and try again."
)
# Spotify's Development Mode caps search at 10 results (default 5). Asking for
# more is a 400, not a silent trim, so the ceiling lives here rather than in the
# caller's head.
_SEARCH_MAX = 10
# What `play` accepts. A track plays as a `uris` list; everything else is a
# context (album/artist/playlist) — Spotify rejects the wrong one with a 400.
_CONTEXT_TYPES = ("album", "artist", "playlist")
def _default_token_provider() -> str | None:
from dodaios.marketplace.token_store import TokenStore
tokens = TokenStore().load("spotify")
return tokens.access if tokens is not None else None
async def _default_refresher(observed_access_token: str | None = None) -> bool:
"""Refresh the stored Spotify token in place. Returns True on success.
On an un-healable failure (revoked grant, placeholder client id, a refresh
token past Spotify's six-month ceiling) it flags ``needs_reauth`` so the
Plugins view stops showing a green "connected" that lies. Best-effort: any
error returns False and never raises into the tool."""
from dodaios.marketplace.connect_helpers import build_handler_from_catalog
from dodaios.marketplace.refresh_scheduler import refresh_plugin_token
from dodaios.marketplace.token_store import TokenStore
attempt = await refresh_plugin_token(
"spotify",
TokenStore(),
build_handler_from_catalog,
force=True,
observed_access_token=observed_access_token,
)
return attempt.usable
def _artists(item: dict[str, Any]) -> str:
names = [a.get("name") for a in item.get("artists") or [] if a.get("name")]
return ", ".join(n for n in names if n)
def _slim_item(item: dict[str, Any]) -> dict[str, Any]:
"""Project a search hit to what a spoken answer needs: who, what, and the
URI needed to actually play it. The raw object carries images, markets and
external ids that would bury the answer and blow the prompt budget."""
out: dict[str, Any] = {
"name": item.get("name"),
"uri": item.get("uri"),
"type": item.get("type"),
}
if artists := _artists(item):
out["artist"] = artists
album = item.get("album")
if isinstance(album, dict) and album.get("name"):
out["album"] = album["name"]
if (owner := item.get("owner")) and isinstance(owner, dict):
out["owner"] = owner.get("display_name")
if isinstance(item.get("total_tracks"), int):
out["total_tracks"] = item["total_tracks"]
return out
def _slim_device(device: dict[str, Any]) -> dict[str, Any]:
return {
"id": device.get("id"),
"name": device.get("name"),
"type": device.get("type"),
"is_active": bool(device.get("is_active")),
"volume_percent": device.get("volume_percent"),
}
def _summarize_playback(state: dict[str, Any]) -> dict[str, Any]:
"""Reduce the playback state object to what is worth reading aloud."""
item = state.get("item") or {}
out: dict[str, Any] = {
"is_playing": bool(state.get("is_playing")),
"track": item.get("name"),
"uri": item.get("uri"),
}
if artists := _artists(item):
out["artist"] = artists
album = item.get("album")
if isinstance(album, dict) and album.get("name"):
out["album"] = album["name"]
device = state.get("device")
if isinstance(device, dict):
out["device"] = device.get("name")
out["volume_percent"] = device.get("volume_percent")
return out
class SpotifyRestTool:
name: str = "spotify"
risk_tier: str = "monitor"
_BASE_DESCRIPTION: str = (
"Play and control the user's Spotify: start a song, artist, album or "
"playlist, pause, skip, go back, set the volume, queue something up, or "
"say what is currently playing. Use for 'play Radiohead', 'skip this "
"one', 'what song is this', 'pause the music', 'turn the music down', "
"'play my running playlist'. Actions: now_playing, play, pause, next, "
"previous, set_volume, queue, search, list_devices, list_playlists. "
"Requires the Spotify plugin to be connected in the Plugins view; "
"controlling playback needs Spotify Premium."
)
@property
def description(self) -> str:
"""The static description plus the user's music preference (see
``dodaios.core.music_service``): with YouTube Music also connected, the
LLM router must send an unnamed music request where the setting says.
The hint is first so a compact live-model description still carries it."""
try:
from dodaios.core.music_service import compose_tool_description
return compose_tool_description(self.name, self._BASE_DESCRIPTION)
except Exception: # noqa: BLE001 — a description must not raise
return self._BASE_DESCRIPTION
schema: dict[str, Any] = {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"now_playing",
"play",
"pause",
"next",
"previous",
"set_volume",
"queue",
"search",
"list_devices",
"list_playlists",
],
"default": "now_playing",
},
"query": {
"type": "string",
"description": (
"what to play, queue or search for, e.g. 'Radiohead', "
"'Bohemian Rhapsody', 'my running playlist'. Leave out on "
"play to simply resume what is paused."
),
},
"type": {
"type": "string",
"enum": ["track", "album", "artist", "playlist"],
"default": "track",
"description": "what the query names",
},
"device_id": {
"type": "string",
"description": "play on a specific device (from list_devices)",
},
"volume_percent": {
"type": "integer",
"description": "0-100, for set_volume",
},
"limit": {"type": "integer", "default": 5, "description": "search hits, max 10"},
},
"required": ["action"],
}
def __init__(
self,
access_token_provider: Callable[[], str | None] | None = None,
transport: Any | None = None,
token_refresher: Callable[[], Awaitable[bool]] | None = None,
) -> None:
from ._http_pool import HttpClientPool
self._token_provider = access_token_provider or _default_token_provider
self._refresher = token_refresher
# Keep-alive pool: a play is search + devices + play in a row, so one
# warm TLS connection beats three handshakes.
self._pool = HttpClientPool(transport=transport)
# -- internal helpers ---------------------------------------------------
def _bearer(self) -> dict[str, str] | None:
token = self._token_provider()
if not token:
return None
return {"Authorization": f"Bearer {token}", "User-Agent": HTTP_USER_AGENT}
async def _with_auth_retry(
self, do_call: Callable[[dict[str, str]], Awaitable[Any]]
) -> Any:
"""Run an authenticated call; on a 401 refresh once and retry.
Spotify access tokens live exactly one hour, so this path is ordinary
rather than exceptional — without it every session longer than an hour
would hand the user an auth error for a connection that is perfectly
healthy."""
import httpx
headers = self._bearer()
if headers is None:
return {"error": _NOT_CONNECTED}
try:
return await do_call(headers)
except httpx.HTTPStatusError as exc:
if exc.response.status_code != 401:
raise
observed_token = headers["Authorization"].removeprefix("Bearer ")
try:
if self._refresher is None:
refreshed = bool(await _default_refresher(observed_token))
else:
refreshed = bool(await self._refresher())
except Exception: # noqa: BLE001 — refresher must never crash the tool
refreshed = False
if not refreshed:
return {"error": _NEEDS_RECONNECT}
headers = self._bearer()
if headers is None:
return {"error": _NEEDS_RECONNECT}
return await do_call(headers)
async def _request(
self,
method: str,
path: str,
headers: dict[str, str],
*,
params: dict[str, Any] | None = None,
json_body: dict[str, Any] | None = None,
) -> Any:
"""One Spotify call. Returns parsed JSON, or ``None`` for the empty
204 body every successful player command answers with."""
client = self._pool.client()
resp = await client.request(
method,
f"{_API}{path}",
params=params,
json=json_body,
headers=headers,
)
resp.raise_for_status()
if resp.status_code == 204 or not resp.content:
return None
return resp.json()
@staticmethod
def _reason(exc: Any) -> str:
"""Spotify's machine-readable failure reason, e.g. NO_ACTIVE_DEVICE.
The body is `{"error": {"status", "message", "reason"}}` — but only on
player endpoints, and only sometimes, so every step is guarded."""
try:
payload = exc.response.json()
except Exception: # noqa: BLE001 — a non-JSON error body is still an error
return ""
error = payload.get("error") if isinstance(payload, dict) else None
if isinstance(error, dict):
return str(error.get("reason") or "")
return ""
async def _devices(self, headers: dict[str, str]) -> list[dict[str, Any]]:
payload = await self._request("GET", "/me/player/devices", headers)
devices = (payload or {}).get("devices")
return [d for d in devices if isinstance(d, dict)] if isinstance(devices, list) else []
async def _player_command(
self,
method: str,
path: str,
*,
params: dict[str, Any] | None = None,
json_body: dict[str, Any] | None = None,
device_id: str | None = None,
) -> dict[str, Any]:
"""A playback command, with the two failures Spotify actually produces
turned into something a person can act on.
``NO_ACTIVE_DEVICE`` is the common one and is worth healing rather than
reporting: if the user has exactly one Spotify client open, that is
unambiguously the one they meant, so the command is re-sent aimed at it.
With several open, guessing would start music in the wrong room, so the
list goes back to the user instead."""
import httpx
async def _do(headers: dict[str, str]) -> dict[str, Any]:
query = dict(params or {})
if device_id:
query["device_id"] = device_id
try:
await self._request(
method, path, headers, params=query or None, json_body=json_body
)
return {"ok": True, "device_id": device_id}
except httpx.HTTPStatusError as exc:
status = exc.response.status_code
if status == 403:
return {"error": _NEEDS_PREMIUM}
if status != 404 or self._reason(exc) != "NO_ACTIVE_DEVICE":
raise
# 404 NO_ACTIVE_DEVICE — nothing is listening yet.
if device_id:
return {"error": _NO_DEVICE}
open_devices = await self._devices(headers)
if not open_devices:
return {"error": _NO_DEVICE}
if len(open_devices) > 1:
return {
"error": (
"Spotify is idle on several devices — say which one, or "
"start playback there once."
),
"devices": [_slim_device(d) for d in open_devices],
}
target = open_devices[0]
query = dict(params or {})
query["device_id"] = target.get("id")
try:
await self._request(
method, path, headers, params=query, json_body=json_body
)
except httpx.HTTPStatusError as exc:
if exc.response.status_code == 403:
return {"error": _NEEDS_PREMIUM}
raise
return {"ok": True, "device": target.get("name"), "device_id": target.get("id")}
return await self._with_auth_retry(_do)
# -- public actions (also directly unit-testable) -----------------------
async def now_playing(self) -> dict[str, Any]:
async def _do(headers: dict[str, str]) -> dict[str, Any]:
state = await self._request("GET", "/me/player", headers)
# 204: Spotify is connected but nothing is loaded anywhere.
if not state:
return {"is_playing": False, "message": "Nothing is playing on Spotify."}
return _summarize_playback(state)
return await self._with_auth_retry(_do)
async def search(
self, *, query: str, item_type: str = "track", limit: int = 5
) -> dict[str, Any]:
capped = max(1, min(int(limit), _SEARCH_MAX))
async def _do(headers: dict[str, str]) -> dict[str, Any]:
payload = await self._request(
"GET",
"/search",
headers,
params={"q": query, "type": item_type, "limit": capped},
)
bucket = (payload or {}).get(f"{item_type}s") or {}
items = [i for i in (bucket.get("items") or []) if isinstance(i, dict)]
return {
"query": query,
"type": item_type,
"results": [_slim_item(i) for i in items],
}
return await self._with_auth_retry(_do)
async def play(
self,
*,
query: str = "",
item_type: str = "track",
device_id: str | None = None,
) -> dict[str, Any]:
body: dict[str, Any] | None = None
started: dict[str, Any] | None = None
if query:
found = await self.search(query=query, item_type=item_type, limit=1)
if found.get("error"):
return found
results = found.get("results") or []
if not results:
return {"error": f"Spotify has nothing called {query!r}."}
started = results[0]
uri = started.get("uri")
if not uri:
return {"error": f"Spotify returned no playable id for {query!r}."}
body = (
{"context_uri": uri}
if item_type in _CONTEXT_TYPES
else {"uris": [uri]}
)
out = await self._player_command(
"PUT", "/me/player/play", json_body=body, device_id=device_id
)
if out.get("error"):
return out
# Report what the SERVER said is playable, not what the model asked for.
# Spotify needs a moment before /me/player reflects the new track, so
# reading it straight back would report the previous song as the result.
if started:
out["started"] = started
else:
out["resumed"] = True
return out
async def pause(self) -> dict[str, Any]:
return await self._player_command("PUT", "/me/player/pause")
async def next_track(self) -> dict[str, Any]:
return await self._player_command("POST", "/me/player/next")
async def previous_track(self) -> dict[str, Any]:
return await self._player_command("POST", "/me/player/previous")
async def set_volume(self, *, volume_percent: int) -> dict[str, Any]:
level = max(0, min(int(volume_percent), 100))
out = await self._player_command(
"PUT", "/me/player/volume", params={"volume_percent": level}
)
if not out.get("error"):
out["volume_percent"] = level
return out
async def queue(self, *, query: str, item_type: str = "track") -> dict[str, Any]:
found = await self.search(query=query, item_type=item_type, limit=1)
if found.get("error"):
return found
results = found.get("results") or []
if not results:
return {"error": f"Spotify has nothing called {query!r}."}
item = results[0]
out = await self._player_command(
"POST", "/me/player/queue", params={"uri": item.get("uri")}
)
if not out.get("error"):
out["queued"] = item
return out
async def list_devices(self) -> dict[str, Any]:
async def _do(headers: dict[str, str]) -> dict[str, Any]:
devices = await self._devices(headers)
return {"devices": [_slim_device(d) for d in devices]}
return await self._with_auth_retry(_do)
async def list_playlists(self, *, limit: int = 20) -> dict[str, Any]:
async def _do(headers: dict[str, str]) -> dict[str, Any]:
payload = await self._request(
"GET", "/me/playlists", headers, params={"limit": max(1, min(limit, 50))}
)
items = [i for i in ((payload or {}).get("items") or []) if isinstance(i, dict)]
return {"playlists": [_slim_item(i) for i in items]}
return await self._with_auth_retry(_do)
# -- Tool protocol ------------------------------------------------------
async def execute(self, args: dict[str, Any], ctx: ExecutionContext) -> ToolResult:
action = (args.get("action") or "now_playing").strip()
query = (args.get("query") or "").strip()
item_type = (args.get("type") or "track").strip() or "track"
try:
if action == "now_playing":
out = await self.now_playing()
elif action == "play":
out = await self.play(
query=query, item_type=item_type, device_id=args.get("device_id")
)
elif action == "pause":
out = await self.pause()
elif action == "next":
out = await self.next_track()
elif action == "previous":
out = await self.previous_track()
elif action == "set_volume":
level = args.get("volume_percent")
if level is None:
return ToolResult(
success=False, output=None, error="volume_percent missing"
)
out = await self.set_volume(volume_percent=int(level))
elif action == "queue":
if not query:
return ToolResult(
success=False, output=None, error="queue needs a query"
)
out = await self.queue(query=query, item_type=item_type)
elif action == "search":
if not query:
return ToolResult(
success=False, output=None, error="search needs a query"
)
out = await self.search(
query=query, item_type=item_type, limit=int(args.get("limit", 5))
)
elif action == "list_devices":
out = await self.list_devices()
elif action == "list_playlists":
out = await self.list_playlists()
else:
return ToolResult(success=False, output=None, error=f"unknown action {action!r}")
except Exception as exc: # noqa: BLE001 - every failure reaches the model via _explain()
return ToolResult(success=False, output=None, error=self._explain(exc))
if isinstance(out, dict) and out.get("error"):
return ToolResult(success=False, output=None, error=out["error"])
return ToolResult(success=True, output=out)
@staticmethod
def _explain(exc: Exception) -> str:
"""Turn a transport or API failure into something a person can act on."""
import httpx
if isinstance(exc, httpx.HTTPStatusError):
status = exc.response.status_code
if status == 403:
return _NEEDS_PREMIUM
if status == 404:
return _NO_DEVICE
if status == 429:
retry = exc.response.headers.get("Retry-After", "a moment")
return f"Spotify is rate-limiting this app — try again in {retry}s."
if isinstance(exc, httpx.ConnectError | httpx.ConnectTimeout):
return "Could not reach Spotify. Check this machine's internet connection."
return str(exc)