# 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](#1-quick-start)
2. [Installation](#2-installation)
3. [First-Run Setup](#3-first-run-setup)
4. [Plugins (BYOMM)](#4-plugins-byomm)
5. [Everyday Usage](#5-everyday-usage)
6. [Downloading Music](#6-downloading-music)
7. [Spotube Connect (Remote Control)](#7-spotube-connect-remote-control)
8. [Last.fm Scrobbling](#8-lastfm-scrobbling)
9. [Settings Reference](#9-settings-reference)
10. [Keyboard Shortcuts](#10-keyboard-shortcuts)
11. [Command-Line Options](#11-command-line-options)
12. [How It Works](#12-how-it-works)
13. [Troubleshooting](#13-troubleshooting)
14. [Frequently Asked Questions](#14-frequently-asked-questions)
15. [Reference](#15-reference)

---

## 1. Quick Start

Get from zero to playing music in five steps.

- [ ] **Download and install** Spotube for your platform (see [Installation](#2-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](#error-nothing-plays-track-stays-at-000) — it is by far the most frequently reported issue.

---

## 2. Installation

Spotube is distributed as prebuilt binaries on its [GitHub Releases page](https://github.com/KRTirtho/spotube/releases). 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

| Platform | Minimum requirement | Package formats |
|---|---|---|
| Android | Android 7.0 (API 24) or newer | `.apk` (all architectures) |
| Windows | Windows 10 or newer (x86_64) | `.exe` installer |
| macOS | Universal (Intel + Apple Silicon) | `.dmg` |
| Linux (Debian/Ubuntu) | x86_64 or arm64 | `.deb` |
| Linux (Fedora/RHEL/openSUSE) | x86_64 | `.rpm` |
| Linux (distro-agnostic) | x86_64 or arm64 | `.AppImage` |
| iOS | iPhone | `.ipa` |

### 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)"

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

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

=== "Fedora / RHEL / openSUSE (.rpm)"

    ```bash
    sudo rpm -i Spotube-linux-x86_64.rpm
    ```

=== "AppImage (any distro)"

    ```bash
    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:

| Plugin type | Provides | Example |
|---|---|---|
| **Metadata plugin** | Search results, artists, albums, playlists, user library, recommendations | MusicBrainz / ListenBrainz |
| **Audio-source plugin** | The actual audio stream for a track | YouTube Audio |

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

| Destination | What it shows |
|---|---|
| **Browse** | Home / discovery feed from your metadata plugin |
| **Search** | Search across tracks, albums, artists, and playlists |
| **Lyrics** | Synced lyrics for the currently playing track |
| **Playlists** | Your playlists (from the metadata provider) |
| **Artists** | Artists you follow |
| **Albums** | Your saved albums |
| **Local Library** | Music files stored on your own device |
| **Downloads** | Tracks you've downloaded for offline play |

### 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](#9-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:

| Platform | Default download folder |
|---|---|
| Android | `/storage/emulated/0/Download/Spotube` |
| macOS | The app's Library `Caches` folder |
| Windows / Linux | Your system **Downloads** folder, in a `Spotube` subfolder |

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:

| Method | Path | Purpose |
|---|---|---|
| GET | `/ping` | Health check (returns `pong`) |
| HEAD/GET | `/stream/<trackId>` | Stream the audio for a track in the current queue |
| GET | `/playback/toggle-playback` | Toggle play/pause |
| GET | `/playback/previous` | Skip to previous track |
| GET | `/playback/next` | Skip to next track |
| (WebSocket) | `/ws` | Real-time control + state sync channel |

> [!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

| Setting | Description |
|---|---|
| **Plugins** | Open the Plugins (BYOMM) management screen |
| **Audio Scrobblers** | Connect/disconnect Last.fm scrobbling |

### Language & Region

| Setting | Default | Description |
|---|---|---|
| **Language** | System default | App interface language. Spotube ships with **30 translations**. |
| **Marketplace region** | United States | The region used for recommendations and localized results |

### Appearance

| Setting | Options | Default | Description |
|---|---|---|---|
| **Layout mode** | Adaptive, Compact, Extended | Adaptive | Overrides how the layout adapts to screen size |
| **Theme** | System, Light, Dark | System | App color theme |
| **Accent color** | Color palette | Slate | The app's accent/highlight color |

### Playback

| Setting | Options / Type | Default | Description |
|---|---|---|---|
| **YouTube engine** | NewPipe, YouTubeExplode, yt-dlp | NewPipe (desktop/Android), YouTubeExplode (iOS) | Which engine resolves YouTube audio streams. Only engines available on your platform are shown. |
| **Streaming music format** | From plugin presets | Plugin default | Container/codec used when streaming |
| **Streaming music quality** | From plugin presets | Plugin default | Quality level when streaming |
| **Download music format** | From plugin presets | Plugin default | Container/codec used for downloads |
| **Download music quality** | From plugin presets | Plugin default | Quality level for downloads |
| **Cache music** | On/Off | On | Cache streamed tracks to disk to avoid re-downloading on replay |
| **Blacklist** | — | Empty | Manage hidden tracks/artists |
| **Normalize audio** | On/Off | Off | Even out loudness across tracks |
| **Endless playback** | On/Off | On | Auto-queue related tracks when the queue ends |
| **Enable Connect** | On/Off (+ port) | Off | Enable Spotube Connect remote control |

> [!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

| Setting | Default | Description |
|---|---|---|
| **Download location** | Platform-specific (see [Downloading Music](#6-downloading-music)) | Folder where downloaded tracks are saved |

### Desktop (desktop only)

| Setting | Options | Default | Description |
|---|---|---|---|
| **Close behavior** | Close, Minimize to tray | Close | What clicking the window close button does |
| **Show tray icon** | On/Off | Off | Show a system tray icon |
| **Use system title bar** | On/Off | Off | Use the OS native title bar instead of Spotube's custom one |
| **Discord Rich Presence** | On/Off | On | Show what you're listening to on Discord |

### Developers

| Setting | Description |
|---|---|
| **Logs** | View, copy, and clear the app's log output (useful for bug reports) |

### 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).

| Shortcut | Action |
|---|---|
| `Space` | Play / pause |
| `Ctrl` + `,` | Open Settings |
| `Ctrl` + `Shift` + `1` | Go to Browse |
| `Ctrl` + `Shift` + `2` | Go to Search |
| `Ctrl` + `Shift` + `3` | Go to Lyrics |
| `Ctrl` + `Shift` + `4` | Go to Playlists |
| `Ctrl` + `Shift` + `5` | Go to Artists |
| `Ctrl` + `Shift` + `6` | Go to Albums |
| `Ctrl` + `Shift` + `7` | Go to Local Library |
| `Ctrl` + `Shift` + `8` | Go to Downloads |
| `Ctrl` + `Shift` + `W` | Close the app |

> [!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):

| Flag | Short | Description |
|---|---|---|
| `--verbose` | `-v` | Enable verbose logging. Defaults to **on** in debug builds, **off** in release builds. |
| `--version` | | Print the Spotube version and exit |
| `--help` | `-h` | Print usage and exit |

```bash
spotube --version
```

```text
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](https://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](#12-how-it-works) and the [Nothing plays](#error-nothing-plays-track-stays-at-000) troubleshooting entry.

**Q: Can I listen offline?**
Yes. Download tracks (see [Downloading Music](#6-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](#7-spotube-connect-remote-control).

**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](#8-lastfm-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

| Item | Value |
|---|---|
| App name | Spotube |
| Version | 5.1.1 (build 44) |
| Author | Kingkor Roy Tirtho |
| License | BSD-4-Clause |
| Website | [spotube.krtirtho.dev](https://spotube.krtirtho.dev) |
| Repository | [github.com/KRTirtho/spotube](https://github.com/KRTirtho/spotube) |
| Concept | BYOMM — Bring Your Own Music Metadata |
| Platforms | Android, iOS, Windows, macOS, Linux, Web |

### Bundled plugins

| Plugin | Ability |
|---|---|
| `spotube-plugin-musicbrainz-listenbrainz` | Metadata (MusicBrainz / ListenBrainz) |
| `spotube-plugin-youtube-audio` | Audio source (YouTube) |

### Default settings at a glance

| Setting | Default |
|---|---|
| Theme | System |
| Layout mode | Adaptive |
| Accent color | Slate |
| Language | System |
| Region | United States |
| Search mode | YouTube |
| YouTube engine | NewPipe (iOS: YouTubeExplode) |
| Cache music | On |
| Endless playback | On |
| Normalize audio | Off |
| Discord Rich Presence | On |
| Check for updates | On |
| Enable Connect | Off |
| Connect port | Random (`-1`) |
| Close behavior (desktop) | Close |
| Show tray icon | Off |
| Use system title bar | Off |

### Useful links

- Releases & downloads: [github.com/KRTirtho/spotube/releases](https://github.com/KRTirtho/spotube/releases)
- Issue tracker: [github.com/KRTirtho/spotube/issues](https://github.com/KRTirtho/spotube/issues)
- Website: [spotube.krtirtho.dev](https://spotube.krtirtho.dev)
- Community Discord: linked from **Settings → About**

---

_Generated June 2026 from KRTirtho/spotube at 2cc8d26. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._