Get the current playback state of the Astra music player: track, position, duration, volume, mute, shuffle, repeat, output device, and queue length. Served from a live event stream when connected, so it is cheap to call. Returns the current track's ref, which can be passed to astra_set_favorite or astra_playlist.

Control playback in Astra: play, pause, stop, next, previous, seek, set-volume, set-muted, set-shuffle, set-repeat. Each action needs its own argument — seek needs positionSeconds, set-volume needs volume (0-1), set-muted needs muted, set-shuffle needs enabled, set-repeat needs mode. Astra accepts commands asynchronously; this tool waits briefly and reports the state it actually landed on. To start a specific track or album instead, use astra_search then astra_play.

Report which Astra Companion API scopes are granted, which features are available, and the current limits. Useful for diagnosing a permission error: if a tool returns "insufficient_scope", this shows which switch is off in Astra → Settings → Integrations → Local API.

Search the user's local Astra music library by name and get back opaque refs. This is the entry point for almost everything: nothing else in this server accepts a title or artist name, only a ref from here. Search is bounded — it needs a non-empty query, returns at most 50 results, has no pagination, and cannot list the whole catalog. Follow up with astra_play, astra_enqueue, or astra_open.

Start playing a track, album, artist, or playlist in Astra, replacing the current queue. Takes an opaque ref from astra_search — call that first to turn a name into a ref. Refs are opaque signed strings from astra_search (or from the current track / queue). Pass them through verbatim — never parse, edit, or invent one. A ref can go stale and return 404. To resume something already loaded, use astra_control with action "play" instead.

Add a track, album, artist, or playlist to the Astra queue without interrupting what is playing. Takes an opaque ref from astra_search. Use position "next" to play it after the current track, or "end" to append. Refs are opaque signed strings from astra_search (or from the current track / queue). Pass them through verbatim — never parse, edit, or invent one. A ref can go stale and return 404.

Bring the Astra window to the front and navigate to a track, album, artist, or playlist. This only changes what the user is looking at — it does not start playback. Takes an opaque ref from astra_search. Refs are opaque signed strings from astra_search (or from the current track / queue). Pass them through verbatim — never parse, edit, or invent one. A ref can go stale and return 404.

Mark or unmark a track as a favorite in the Astra library. This sets an explicit state rather than toggling, so it is safe to repeat. Takes a track ref from astra_search or from the current track reported by astra_now_playing. Refs are opaque signed strings from astra_search (or from the current track / queue). Pass them through verbatim — never parse, edit, or invent one. A ref can go stale and return 404.

List the tracks in the Astra play queue, in order, with the currently playing one marked. Each entry has a queue item id — pass that to astra_queue_edit to move or remove it. Served from the live event stream when connected. Astra only publishes the first 200 queue entries to the API, so a longer queue is reported as truncated and the later entries are not reachable.

Reorder or trim the Astra play queue. "move" needs queueItemId and a 0-based position, "remove" needs queueItemId, and "clear" empties the upcoming queue without stopping the current track. Get queue item ids from astra_queue. The currently playing item cannot be moved or removed — attempting it returns queue_item_not_found. To add tracks instead, use astra_enqueue.

Create a playlist in Astra, rename one, or add / remove / reorder its tracks. "create" needs name. "rename" needs ref and name. "add-tracks" needs ref and trackRefs. "remove-track" needs ref and trackRef. "move-track" needs ref, trackRef, and position. Get playlist refs from astra_search with types ["playlist"], and track refs from astra_search with types ["track"]. Refs are opaque signed strings from astra_search (or from the current track / queue). Pass them through verbatim — never parse, edit, or invent one. A ref can go stale and return 404.

Limits: only locally owned normal playlists are editable — mirrored (Jellyfin or Subsonic) and dynamic playlists reject edits with playlist_not_writable. Astra has no playlist deletion endpoint, so playlists cannot be deleted through this server.