v0.39 · Lua scripting

Make spotatui yours, in Lua.

spotatui runs user-written Lua plugins. They react to playback events, add commands and key bindings, draw popups and playbar segments, restyle the theme, and make async HTTP requests, all through a small, curated API.

plugins/now-playing/main.lua
spotatui.require_api(6)

-- toast + playbar segment on every track change
spotatui.on("track_change", function(pb)
  if pb and pb.track then
    local artists = table.concat(pb.track.artists, ", ")
    spotatui.notify(pb.track.name .. " - " .. artists, 4)
    spotatui.set_playbar(pb.track.name)
  end
end)

local accents, i = { "Magenta", "Cyan", "Green" }, 0
spotatui.register_command("cycle_accent", function()
  i = (i % #accents) + 1
  spotatui.set_theme({ selected = accents[i] })
end)
One command to install

Plugins are just git repos.

Any plugin published as a repository installs, updates and removes with a single command. It is cloned into your config directory and loaded at startup.

shell
# add, list, update, remove
$ spotatui plugin add owner/repo
$ spotatui plugin list
$ spotatui plugin new my-plugin

Every plugin command and flag: installing and managing plugins.

Ships with examples

First-party plugins to learn from

track-notifier

A now-playing toast and a playbar segment on every track change.

track-info-popup

A command that pops up the full details of the current track.

accent-cycler

A command that rotates the theme accent color on demand.

now-playing-webhook

POSTs a JSON payload to a webhook whenever the track changes.

session-stats

A directory plugin, with a required helper, that tracks session plays.

Read the API reference

Events, actions, popups, custom screens and HTTP requests, in the docs. API v6.

⚠
Plugins are not sandboxed.

A plugin runs with the same privileges as spotatui, with full standard library and network access. Treat installing one like running any program from the internet: only install plugins whose source you have read or whose author you trust. Trust and safety.