Themes
A Spotube theme is a complete design language for the app, not just a colour scheme. One theme can change the typeface, the icon set, every control's shape, bevel and hover behaviour, the backdrop behind all screens, and it can offer a few settings (accent, corner style, glow) that you adjust yourself. Every theme has a light and a dark look.
Themes are packages, installed the same way as plugins: a .zip containing a theme.json plus optional fonts, an icon pack, a logo and a LICENSE. Spotube reads the zip in memory and never runs anything from it, so a theme is pure data.
Install a theme
- Open Settings → Appearance (on phones the Appearance page also has the Light / Dark / System choice).
- Under Discover themes, pick a repository, then a release and its
.zip; or choose Install theme and pick a.zipfrom your device. - Spotube shows who made it, its links, licence and contents. Confirm to install.
- Select the theme's card. Open its details and use Customize to change its parameters.
Only install themes from people you trust: fonts and images are decoded by system libraries, which is why Spotube asks you to confirm first.
Discover themes
Discover on GitHub (Settings → Appearance) lists the public GitHub repositories tagged with both topics spotube and spotube-theme (forks are left out), most starred first. Open one to see its releases and every .zip they carry, then pick a file: Spotube downloads it (from github.com only) and shows the usual install dialog.
You can also browse github.com/topics/spotube-theme yourself and install a downloaded .zip with the + button.
Updates
Themes can declare where their new versions are published (updates in theme.json): a GitHub repository and the archive name. Spotube then looks at that repository's releases, takes the newest published release whose tag is a semantic version (1.2.0 or v1.2.0) that has the archive, and compares it with the installed version.
- The selected theme is checked automatically when Spotube starts and when you switch themes (unless you turned off checking for updates in settings). If a newer version exists you get a dialog with the release notes: Update installs it, Ignore skips that version.
- The refresh button on the Appearance page checks all installed themes; rows with a newer version show Update to X, which downloads the archive and opens the install dialog.
- An automatic update only replaces the installed theme when the archive has the same id and a newer version, and it is validated like any other import.
Updating, replacing and downgrading
Installing a theme whose id is already installed works like updating a plugin, using the theme's own version (semver):
A fresh install is selected right away; updating or replacing a theme keeps whichever theme you have selected, and your Customize choices are kept per theme. Bump version in theme.json for every release so users get a proper update.
Make your own
- Creating a theme:
pnpm create spotube-themeand the@team-spotube/theme-toolCLI, step by step. - Theme format: every part of
theme.json. - Schema and versioning: the JSON Schema, the semver rules and what keeps old themes working.
- Example themes: ten finished themes and the techniques each one shows off.