Spotube User Guide

Spotube is a free, open-source, cross-platform music streaming app built with Flutter. It lets you browse and play music using a Bring Your Own Music Metadata (BYOMM) model: instead of being locked to a single backend, Spotube uses plugins to supply music metadata (artists, albums, playlists, search) and separate plugins to supply the actual audio streams. The result is a polished, ad-free desktop and mobile music player you control entirely — including offline downloads, lyrics, scrobbling to Last.fm, and remote control from another device.

This guide covers everything you need as a user: installing Spotube on every supported platform, getting set up with plugins, playing and managing music, downloading tracks for offline listening, configuring every setting, and troubleshooting the most common problems.

Note

Spotube does not host or provide any music itself. It is a player that talks to plugin-provided metadata and audio sources. What you can play depends on which plugins you install.

Table of Contents

1. Quick Start
2. Installation
3. First-Run Setup
4. Plugins (BYOMM)
5. Everyday Usage
6. Downloading Music
7. Spotube Connect (Remote Control)
8. Last.fm Scrobbling
9. Settings Reference
10. Keyboard Shortcuts
11. Command-Line Options
12. How It Works
13. Troubleshooting
14. Frequently Asked Questions
15. Reference

1. Quick Start

Get from zero to playing music in five steps.

• [ ] Download and install Spotube for your platform (see Installation).
• [ ] Launch the app. On first run you'll go through a short greeting and region setup.
• [ ] Install a metadata plugin and an audio-source plugin from the Plugins screen (Spotube ships with starter plugins for MusicBrainz/ListenBrainz metadata and YouTube audio).
• [ ] Search for a song, album, or artist from the Search tab.
• [ ] Press play. Spotube matches the track to an audio source and starts streaming.

Tip

If nothing plays after pressing play, the most common cause is the audio-source plugin or YouTube engine. Jump straight to Troubleshooting → Nothing plays — it is by far the most frequently reported issue.

2. Installation

Spotube is distributed as prebuilt binaries on its GitHub Releases page. There is a stable channel (latest release) and a nightly channel (bleeding-edge builds). Pick the package that matches your operating system.

Important

Always download Spotube from the official GitHub releases or the official website spotube.krtirtho.dev. Builds hosted elsewhere are not verified by the project.

Supported platforms

Android

Direct APK

1. Download Spotube-android-all-arch.apk from the latest release.
2. Open the file on your device. You may need to allow installation from your browser or file manager in Android settings.
3. Tap Install, then open Spotube.

Stores

Spotube is also distributed through community channels and app catalogs that track its releases. When using a store, confirm the publisher is the official project before installing.

Note

The Android APK is a single "fat" package containing all CPU architectures (all-arch), so the same file works on every Android phone.

Windows

1. Download Spotube-windows-x86_64-setup.exe.
2. Run the installer and follow the prompts.
3. Launch Spotube from the Start menu.

Tip

If Windows SmartScreen warns about an unrecognized app, choose More info → Run anyway. This warning appears because the installer is community-signed, not because the app is unsafe.

macOS

1. Download Spotube-macos-universal.dmg.
2. Open the .dmg and drag Spotube into your Applications folder.
3. Launch Spotube from Applications.

Caution

On first launch macOS Gatekeeper may block the app because it is not notarized through the App Store. If you see "Spotube can't be opened", right-click the app and choose Open, then confirm. You only need to do this once.

Linux

Debian / Ubuntu (.deb)

# x86_64
sudo dpkg -i Spotube-linux-x86_64.deb
# or arm64
sudo dpkg -i Spotube-linux-aarch64.deb

Selecting previously unselected package spotube.
Setting up spotube ...

Fedora / RHEL / openSUSE (.rpm)

sudo rpm -i Spotube-linux-x86_64.rpm

AppImage (any distro)

chmod +x Spotube-linux-x86_64.AppImage
./Spotube-linux-x86_64.AppImage

Important

On Linux, audio playback depends on mpv / libmpv being available on your system. Most desktop distributions include it; if playback fails on Linux, install the mpv and libmpv-dev packages for your distro.

iOS

The iOS build is provided as a Spotube-iOS.ipa. Installing an unsigned .ipa on iPhone requires sideloading (for example with AltStore or a developer signing tool). Follow the sideloading method appropriate for your device and iOS version.

Note

Sideloaded iOS apps installed with a free Apple developer account expire after 7 days and must be re-signed. This is an Apple restriction, not a Spotube limitation.

Nightly builds

Nightly builds carry the latest features and fixes but are less stable. They install side-by-side with the stable app (the Android/desktop builds use a separate Spotube Nightly identity), so you can run both. Download nightly packages from the nightly release on GitHub.

3. First-Run Setup

When you launch Spotube for the first time, a short Getting Started flow walks you through the essentials:

1. Greeting — a welcome screen introducing the app.
2. Region — choose your recommendation market/region (used by metadata plugins that localize results). The default is the United States.
3. Playback — confirm basic playback and appearance preferences.
4. Support — information on supporting the project.

After onboarding you land on the main interface. Before you can play anything, install at least one metadata plugin and one audio-source plugin — see the next section.

Tip

You can revisit every onboarding choice later in Settings. Nothing in the first-run flow is permanent.

4. Plugins (BYOMM)

Spotube's defining feature is Bring Your Own Music Metadata. The app itself contains no built-in music catalog. Instead, two kinds of plugins provide everything:

A single plugin can offer one or both abilities, plus optional authentication (logging into the provider) and scrobbling (reporting plays back to the provider).

Spotube ships with two starter plugins bundled in the app:

• spotube-plugin-musicbrainz-listenbrainz — metadata via MusicBrainz/ListenBrainz
• spotube-plugin-youtube-audio — audio sourced from YouTube

Opening the Plugins screen

Go to Settings → Account → Plugins (or Settings → Plugins). The screen has three tabs:

• All — every available plugin
• Metadata — plugins that provide metadata
• Audio Source — plugins that provide audio streams

Installed plugins appear at the top under Installed; discoverable plugins appear below under Available plugins.

Installing a plugin

There are three ways to add a plugin:

From the catalog

Spotube discovers community plugins by searching GitHub and Codeberg for repositories tagged with the topic spotube-plugin, sorted by stars. Browse the Available plugins list and install directly.

From a URL

Paste a plugin download URL into the plugin URL field at the top of the Plugins screen and press the download button. Spotube fetches and installs it.

From a file

Press the upload button and choose a .smplug plugin file from your device. This is useful for plugins you've downloaded manually or built yourself.

Warning

Plugins are third-party code. Spotube shows a DMCA/disclaimer notice on the Plugins screen for a reason: the project does not endorse or control what plugins do or where their content comes from. Only install plugins you trust.

Setting default plugins

Each plugin you install can be marked as the default metadata plugin or default audio source plugin. The defaults are what Spotube uses when you search and play. Open an installed plugin's entry to set it as default for its ability.

Authenticating with a plugin

If a plugin supports authentication, you can log into the underlying provider through Spotube. This unlocks personalized data such as your own playlists, liked songs, and library. Authentication state is managed per plugin.

5. Everyday Usage

The main window is organized into tabs/destinations. On desktop and large screens these appear in a sidebar; on phones they appear as a bottom navigation bar.

The main destinations

Searching

1. Open the Search tab.
2. Type a query.
3. Results are grouped into tabs (tracks, albums, artists, playlists). Open any result to view it; play a track directly from the list.

Search has two modes that affect how the audio-source matcher finds streams: YouTube and YouTube Music. You can switch the search mode in Settings (see Settings Reference).

Playing music

• Click or tap a track to start playback. Spotube adds the surrounding context (the album or playlist) to your queue.
• The player bar shows the current track, progress, and transport controls (play/pause, next, previous, shuffle, repeat).
• Open the full-screen player to see album art, the queue, and lyrics.

The queue

The queue holds the list of tracks lined up to play. You can:

• Reorder tracks by dragging them.
• Add a track to the queue.
• Remove a track from the queue.
• Jump directly to any track in the queue.
• Toggle shuffle and cycle repeat modes (no repeat → repeat all → repeat one).

Endless playback

When Endless Playback is enabled (it is on by default), Spotube automatically keeps the music going by queuing related tracks when your current queue runs out — so playback never just stops.

Lyrics

The Lyrics tab shows time-synced lyrics (LRC format) for the playing track when the metadata plugin can supply them, highlighting the current line as the song plays.

Library, playlists, albums, and artists

If your metadata plugin supports authentication and you've logged in, your personal playlists, followed artists, and saved albums appear in their respective tabs and stay in sync with the provider.

Local library

Spotube can also play music files already on your device. Add one or more folders as local library locations (see Settings), and your local tracks appear in the Local Library tab — no plugin or internet required for these.

Blacklist

The blacklist lets you hide specific tracks or artists so they never appear in results or play. Manage it from Settings → Playback → Blacklist. You can search your blacklist and remove entries at any time.

Sleep timer

Spotube includes a sleep timer that stops playback (and closes the app) after a chosen duration — handy for falling asleep to music.

6. Downloading Music

Spotube can download tracks to your device for offline listening. Downloaded files are tagged with metadata (title, artist, album, cover art) automatically.

Downloading a track

1. Find a track, album, or playlist.
2. Use the download action on the item.
3. The track is added to the download queue and processed one at a time. Progress is shown per track.

Download states you may see: queued, downloading, completed, failed, or canceled. You can retry failed or canceled downloads and cancel queued/in-progress ones.

Note

If a file with the same name already exists in your download folder, Spotube asks whether to replace it. You can choose to apply your answer to all subsequent conflicts in the batch.

Choosing format and quality

Download format (codec/container) and quality come from your audio-source plugin's presets. Set them in Settings → Playback:

• Download music format — the container/codec for downloads
• Download music quality — the bitrate/quality level

Files are saved as Track Name - Artist1, Artist2.<extension> in your download folder, with filenames sanitized for your filesystem.

Where downloads go

The default download location depends on your platform:

Change it in Settings → Downloads → Download location.

Tip

On Android, choose a download folder you can browse with your file manager (like the default Download/Spotube) so your music app and file transfers can see the files.

7. Spotube Connect (Remote Control)

Spotube Connect turns one Spotube instance into a playback target that another device on the same network can control — similar in spirit to controlling playback from your phone onto your desktop. It works over your local network only.

Enabling Connect

1. On the device you want to control (the "player"), go to Settings → Playback.
2. Turn on Enable Connect.
3. Optionally set a fixed port using the edit-port button. Leave it at the default to let Spotube pick a random port automatically.

When Connect is enabled, Spotube:

• Starts a small local web server bound to all network interfaces (so other devices can reach it).
• Advertises itself on the local network via mDNS/Bonjour as a _spotube._tcp service, so other Spotube instances can discover it by name.

When Connect is disabled, the same server still runs but is bound only to localhost (loopback), so nothing outside the device can reach it.

Controlling another device

From a second Spotube instance on the same network, discover and connect to the advertised device, then control its playback — play/pause, next/previous, seek, jump, shuffle, loop, volume, and queue editing all sync in real time over a WebSocket connection.

Important

The first time a controller connects, the player device shows a confirmation dialog asking whether to Accept or Decline the connection (it identifies the controller by its network address). You must accept before remote control is allowed. This is your security gate — decline connections you don't recognize.

Warning

Only enable Connect on networks you trust. With Connect on, the playback server listens on all interfaces. The accept/decline prompt protects you, but a shared or public network is still a riskier place to expose it.

Connect endpoints (advanced)

The Connect server exposes a small HTTP/WebSocket API on the chosen port:

Note

These endpoints exist primarily for Spotube-to-Spotube control and for streaming audio to the local player. They are not a public API and require being on the same network plus accepting the connection.

8. Last.fm Scrobbling

Spotube can scrobble (report) your plays to Last.fm, building your listening history there.

Connecting Last.fm

1. Go to Settings → Account → Audio Scrobblers (or Scrobbling).
2. Tap Login with Last.fm / Connect.
3. Complete the Last.fm login.

Once connected, plays are scrobbled automatically as you listen.

Disconnecting

Return to Settings → Account. When a scrobbler is connected, the account section shows a Disconnect option for Last.fm.

Note

Some metadata plugins provide their own scrobbling ability (for example, scrobbling to ListenBrainz). That is separate from the built-in Last.fm scrobbler and is controlled by the plugin.

9. Settings Reference

Open Settings from the gear icon or press Ctrl + , (comma). Settings are grouped into sections. Use Restore defaults at the bottom to reset everything.

Account

Language & Region

Appearance

Playback

Tip

If you choose yt-dlp as the YouTube engine and it isn't installed, Spotube prompts you to install it first. NewPipe (the default on desktop/Android) needs no external binary.

Note

The cache folder can be opened directly from the Cache music setting on desktop. Cached tracks live in the app's cache directory under cached_tracks (Android uses an external cache Cached Tracks folder).

Downloads

Desktop (desktop only)

Developers

About

Shows the app version, build number, release channel, website, repository, license (BSD-4-Clause), and a link to the community Discord.

Other preferences

A few preferences are managed elsewhere in the UI rather than the main settings list:

• Connect port — the network port for Spotube Connect. -1 (default) means pick a random port. Valid range is -1 to 65535.
• Check for updates — on by default; Spotube checks for newer releases.
• Local library locations — the device folders scanned for your local music files.

10. Keyboard Shortcuts

Spotube provides keyboard shortcuts for fast navigation and playback control (primarily on desktop).

Note

On macOS, use the platform's standard modifier conventions where applicable. The digit shortcuts map to the same eight main destinations.

11. Command-Line Options

The Spotube application accepts a small set of command-line flags (most useful on desktop when launching from a terminal):

spotube --version

Spotube v5.1.1

Important

Do not confuse the app's runtime flags above with the project's developer build CLI (the cli/ tool with build, credits, install-dependencies, translated, and untranslated commands). That tool is for contributors building Spotube from source and is documented in the Admin Guide, not here.

12. How It Works

You don't need this section to use Spotube, but it explains why playback behaves the way it does — which makes troubleshooting much easier.

Metadata and audio are separate

When you play a track, two independent things happen:

1. Metadata (the track's name, artists, album, cover, duration) comes from your metadata plugin.
2. Audio is matched and sourced by your audio-source plugin. For the bundled YouTube plugin, Spotube searches YouTube for the best match for that track and resolves a streamable URL.

This separation is the BYOMM concept. It's powerful — but it also means playback can fail even when search works, because matching and resolving the audio stream is a separate step that depends on the audio-source plugin and YouTube engine.

The local playback server

Even for normal local playback, Spotube runs a tiny internal server that proxies the audio stream to the player. This lets it cache tracks to disk (when Cache music is on), handle range requests for seeking, and stream consistently across platforms. The same server powers Spotube Connect.

Caching

With Cache music enabled, streamed audio is written to a cache folder as it plays. The next time you play the same track, Spotube serves it from the cache instead of re-streaming — saving bandwidth and improving reliability.

YouTube engines

For the YouTube audio source, Spotube can use one of three engines to resolve streams:

• NewPipe — default on desktop and Android; no external dependencies.
• YouTubeExplode — default on iOS.
• yt-dlp — requires the yt-dlp binary to be installed; most robust but needs setup.

If one engine stops working (YouTube changes break extractors periodically), switching engines in Settings often restores playback.

13. Troubleshooting

Troubleshooting entries use the format: the symptom, the likely cause, the fix, and how to prevent it.

Error: Nothing plays — track stays at 0:00

Cause: The audio-source plugin couldn't resolve a stream, or the selected YouTube engine is currently broken (YouTube periodically changes its internals, breaking extractors). This is the single most common Spotube issue.

Solution:

1. Go to Settings → Playback → YouTube engine and switch to a different engine (try NewPipe, then yt-dlp if installed, then YouTubeExplode).
2. Make sure you have a working audio-source plugin installed and set as default.
3. Update Spotube to the latest release — engine fixes ship frequently.

Prevention: Keep the app updated and keep at least one alternate engine available so you can switch when one breaks.

Error: DioException [bad response] when browsing

Cause: A network request made by a metadata or audio-source plugin failed (rate limiting, a provider outage, or a temporary network issue). Spotube uses the Dio HTTP client, so these surface as DioException.

Solution:

1. Check your internet connection.
2. Wait a few minutes and retry — providers rate-limit aggressively.
3. Try a different metadata plugin or region.

Prevention: Avoid hammering search/browse repeatedly in a short window.

Error: Queue shows 0:00 durations

Cause: A mismatch in how track durations are passed between the audio engine and the source matcher (a known class of bug where seconds and microseconds are confused).

Solution: Update to the latest Spotube release where the specific case is fixed; switching the YouTube engine can also work around it.

Prevention: Stay on a recent version.

Error: Music only plays from the local library

Cause: Online audio sources are failing while local files (which need no plugin) still work — pointing squarely at the audio-source plugin or YouTube engine.

Solution: Reinstall/update your audio-source plugin, set it as default, and switch the YouTube engine in Settings → Playback.

Prevention: Verify a default audio-source plugin is set after installing plugins.

Problem: Can't create a playlist

Cause: Playlist creation requires an authenticated metadata plugin that supports writing playlists. Without login (or with a read-only plugin), creation isn't available.

Solution: Install a metadata plugin that supports authentication and log in, then retry.

Prevention: Check a plugin's abilities before relying on personal-library features.

Problem: White screen on launch

Cause: A rendering or initialization issue, sometimes tied to display settings or a corrupt state after an update.

Solution:

1. Fully quit and relaunch.
2. Update to the latest release.
3. If it persists, capture logs (Settings → Developers → Logs) for a bug report.

Prevention: Update through clean releases rather than mixing nightly and stable state.

Problem: Playback works but no Discord status shows

Cause: Discord Rich Presence is desktop-only and requires the Discord desktop app to be running.

Solution: Ensure Discord desktop is open, then enable Settings → Desktop → Discord Rich Presence.

Prevention: Keep the setting on; it only acts when Discord is detected on desktop.

Problem: Downloads fail or stop

Cause: The audio source for the track couldn't be resolved (same root cause as playback failures), or the chosen download codec/quality isn't available.

Solution: Switch the YouTube engine, pick a different Download music format/quality, and retry the failed download.

Prevention: Test playback of a track before bulk-downloading; if it plays, it should download.

Problem: A connecting device can't control playback

Cause: Connect isn't enabled, the devices aren't on the same network, or the connection wasn't accepted.

Solution: On the player device, enable Settings → Playback → Enable Connect, ensure both devices share the same LAN, and Accept the connection prompt when it appears.

Prevention: Use a fixed Connect port on trusted networks for predictable behavior.

Getting help and reporting bugs

If a problem persists:

1. Open Settings → Developers → Logs, copy the logs.
2. File an issue at github.com/KRTirtho/spotube/issues with your platform, version, and logs.
3. Or ask in the community Discord (linked from Settings → About).

14. Frequently Asked Questions

Q: Is Spotube free? Yes. Spotube is free and open source under the BSD-4-Clause license. There is no subscription.

Q: Do I need a Spotify account? No. Spotube is a BYOMM player — metadata and audio come from plugins you install, not from a fixed Spotify dependency. What you can access depends on your plugins.

Q: Where does the music actually come from? From whatever audio-source plugin you install. The bundled plugin sources audio from YouTube. Spotube hosts no music itself.

Q: Why does search find a song but it won't play? Because metadata (search) and audio (playback) are separate. Playback also requires the audio-source plugin to match and resolve a stream. See How It Works and the Nothing plays troubleshooting entry.

Q: Can I listen offline? Yes. Download tracks (see Downloading Music) and they play from your device with no connection. Your Local Library folders also play offline.

Q: Which platforms are supported? Android, iOS, Windows, macOS, and Linux (deb, rpm, and AppImage), plus a web build.

Q: How many languages does Spotube support? 30 interface translations ship with the app. Set your language in Settings → Language & Region.

Q: What's the difference between the stable and nightly versions? Stable is the latest tested release. Nightly carries the newest changes but may be buggy. They install side by side, so you can run both.

Q: How do I change where downloads are saved? Settings → Downloads → Download location.

Q: What is "Endless Playback"? When your queue runs out, Spotube automatically queues related tracks so music keeps playing. It's on by default and can be turned off in Settings → Playback.

Q: What does "Normalize audio" do? It evens out volume differences between tracks so you don't get jarring loudness changes. It's off by default.

Q: Can I control Spotube on my PC from my phone? Yes — enable Spotube Connect on the PC, connect from the phone's Spotube over the same network, and accept the prompt. See Spotube Connect.

Q: Is it safe to install plugins? Plugins are third-party code. Spotube shows a disclaimer for this reason. Install only plugins you trust.

Q: How do I scrobble to Last.fm? Settings → Account → Audio Scrobblers → Login with Last.fm. See Last.fm Scrobbling.

Q: The YouTube engine keeps breaking. What do I do? Switch engines in Settings → Playback → YouTube engine and keep the app updated. NewPipe, YouTubeExplode, and yt-dlp fail at different times, so an alternate is usually working.

Q: How do I reset all settings? Open Settings, scroll to the bottom, and press Restore defaults.

Q: Where can I get help? The community Discord (linked in Settings → About) and the GitHub issue tracker.

15. Reference

Quick facts

Bundled plugins

Default settings at a glance

Useful links

• Releases & downloads: github.com/KRTirtho/spotube/releases
• Issue tracker: github.com/KRTirtho/spotube/issues
• Website: spotube.krtirtho.dev
• Community Discord: linked from Settings → About