Spotube Admin & Developer Guide

This guide is the deep reference for developers, packagers, and technically-minded users who want to understand how Spotube is built, how its internals fit together, how to compile and distribute it, and how to operate or extend it safely. Where the User Guide covers using Spotube, this guide covers building, architecting, and reasoning about it.

Spotube is a Flutter application written in Dart, targeting Android, iOS, Windows, macOS, Linux, and the web from a single codebase. Its defining architectural choice is the Bring Your Own Music Metadata (BYOMM) model: the app is a player shell, and all music metadata and audio sourcing is delegated to runtime-loadable plugins.

Table of Contents

1. Executive Summary
2. Architecture Overview
3. Repository Structure
4. Technology Stack
5. State Management & Data Flow
6. The Plugin System (BYOMM)
7. Audio Pipeline & Local Server
8. Persistence Layer
9. Configuration Reference
10. Build & Release
11. Platform Integration
12. Security Analysis
13. Internationalization
14. Operations & Troubleshooting
15. Code Quality & Conventions
16. Potential Improvements
17. Quick Reference

1. Executive Summary

What it is, architecturally: a Flutter front end built on the shadcn_flutter design system, with Riverpod (hooks variant) for state, Drift/SQLite for persistence, media_kit for audio playback, and a shelf-based in-process HTTP/WebSocket server that proxies audio and powers remote control ("Spotube Connect"). All domain logic for what music exists and where audio comes from is externalized into Hetu-scripted plugins loaded at runtime.

Why the design matters: decoupling metadata from audio sourcing means Spotube is not tied to any one provider and can adapt as providers change, but it also concentrates fragility at the audio-resolution boundary (YouTube extractor breakage is the dominant source of user-reported failures).

2. Architecture Overview

                         ┌──────────────────────────────────────────┐
                         │              Spotube (Flutter)            │
                         │                                           │
   ┌─────────┐           │   ┌───────────────┐   ┌───────────────┐   │
   │  User   │──────────▶│   │  UI Layer     │   │  Intents /    │   │
   │  Input  │           │   │ shadcn_flutter│   │  Shortcuts    │   │
   └─────────┘           │   │  pages/       │   │  Actions      │   │
                         │   └───────┬───────┘   └───────┬───────┘   │
                         │           │ watch/read        │           │
                         │   ┌───────▼───────────────────▼───────┐   │
                         │   │     Riverpod Providers (state)     │   │
                         │   │  audioPlayer, userPreferences,     │   │
                         │   │  metadataPlugin, downloadManager,  │   │
                         │   │  server, scrobbler, blacklist...   │   │
                         │   └───┬─────────────┬──────────┬──────┘   │
                         │       │             │          │          │
         ┌───────────────┼───────▼───┐   ┌─────▼─────┐ ┌──▼───────┐  │
         │   Plugin Runtime (Hetu)   │   │  Drift /  │ │ media_kit│  │
         │  metadata + audio source  │   │  SQLite   │ │  player  │  │
         └───────┬───────────┬───────┘   └───────────┘ └────┬─────┘  │
                 │           │                              │        │
                 │           │            ┌─────────────────▼─────┐  │
                 │           │            │ shelf local server     │ │
                 │           │            │ /stream /playback /ws  │ │
                 │           │            └──────────┬─────────────┘ │
                 └───────────┼───────────────────────┼──────────────┘
                             │                        │
                    ┌────────▼────────┐      ┌────────▼─────────┐
                    │ Metadata source │      │  Audio source    │
                    │ (e.g. MusicBrainz)     │ (e.g. YouTube via │
                    │                 │      │ NewPipe/yt-dlp/   │
                    └─────────────────┘      │ youtube_explode)  │
                                             └──────────────────┘

Layered breakdown

Startup sequence

lib/main.dart orchestrates a careful initialization order:

1. Handle the special web_view_title_bar argument (desktop webview helper) and return early if matched.
2. Parse CLI args via startCLI() (lib/services/cli/cli.dart) — handles --verbose/-v, --version, --help/-h.
3. Initialize logging (AppLogger.initialize) and run everything inside a guarded zone (AppLogger.runZoned).
4. Install a BadCertificateAllowlistOverrides HttpOverrides global.
5. Initialize timezones, native splash, MediaKit.
6. Run macOS sandbox→no-sandbox migration.
7. Platform tweaks: high refresh rate (Android), NewPipeExtractor.init() (Android/desktop), MetadataGod (non-web).
8. Initialize key-value stores (KVStoreService, EncryptedKvStoreService), the Drift AppDatabase.
9. Desktop: prevent-close, set yt-dlp binary path, Discord RPC init, local notifier, window manager tools.
10. Windows: SMTCWindows.initialize(). iOS: set home-widget app group.
11. runApp inside a ProviderScope (overriding databaseProvider, attaching AppLoggerProviderObserver) rendering the root Spotube widget.

The root Spotube widget (HookConsumerWidget) wires up ShadcnApp.router, themes, localization delegates, global keyboard shortcuts/intents, and listens (to keep alive) a set of background providers: audio player streams, Bonsoir (mDNS), connect clients, the server, tray manager, metadata/audio-source plugins, and update checkers.

3. Repository Structure

spotube/
├── lib/                      # All Dart application code
│   ├── main.dart             # App entry point & bootstrap
│   ├── collections/          # Generated assets, routes, intents, env, icons, markets, locales
│   ├── components/           # Reusable widgets (buttons, dialogs, player, titlebar, ...)
│   ├── extensions/           # Dart extension methods (context, dio, ...)
│   ├── hooks/                # flutter_hooks: configurators, controllers, utils
│   ├── l10n/                 # ARB translation files + generated localizations
│   ├── models/               # Drift DB tables, metadata/connect/playback models
│   │   └── database/
│   │       ├── database.dart         # AppDatabase definition (drift)
│   │       └── tables/               # preferences, history, blacklist, lyrics, scrobbler, ...
│   ├── modules/              # Feature modules (settings, stats, metadata_plugins, player, ...)
│   ├── pages/                # @RoutePage screens (settings, library, player, search, stats, ...)
│   ├── provider/             # Riverpod providers (state) — the core logic
│   │   ├── audio_player/
│   │   ├── metadata_plugin/  # BYOMM plugin runtime
│   │   ├── server/           # shelf server + Connect routes
│   │   ├── user_preferences/
│   │   └── ...
│   ├── services/             # audio_player, cli, kv_store, logger, metadata, youtube_engine, ...
│   └── utils/                # platform flags, migrations, service utils
├── cli/                      # DEVELOPER build CLI (not shipped in the app)
│   ├── cli.dart              # CommandRunner entry
│   └── commands/             # build, credits, install-dependencies, translated, untranslated
├── assets/                   # images, fonts, branding, bundled plugins (.smplug)
├── drift_schemas/            # Drift schema snapshots (migration history)
├── android/ ios/ windows/    # Native platform projects
├── macos/ linux/ web/
├── website/                  # Astro + React marketing/docs site
├── integration_test/         # Flutter integration tests
├── test/                     # Unit/widget tests (incl. drift)
├── pubspec.yaml              # Dependencies & Flutter asset/font manifest
├── build.yaml                # build_runner / codegen config
├── l10n.yaml                 # Localization generation config
├── analysis_options.yaml     # Lints & analyzer config
└── distribute_options.yaml   # flutter_distributor release jobs

Note

The cli/ directory is a standalone Dart CommandRunner used by maintainers to build and manage the project. It is excluded from the app build (build.yaml excludes bin/*.dart) and is unrelated to the application's own runtime flags.

4. Technology Stack

Spotube depends on a large set of pub packages. The most architecturally significant are grouped below (versions per pubspec.yaml).

UI & app framework

Audio & media

Data & networking

Plugin runtime

Integrations & platform

Important

Several dependencies are git pins or forks (e.g. media_kit, desktop_webview_window, flutter_broadcasts, bonsoir_android, yt_dlp_dart, flutter_new_pipe_extractor, scrobblenaut, a patched flutter_secure_storage_linux). Reproducible builds require network access to these repos at the pinned refs. Audit dependency_overrides in pubspec.yaml before packaging.

5. State Management & Data Flow

Spotube uses Riverpod (hooks variant) as its single source of runtime truth. Widgets are HookConsumerWidgets that ref.watch providers; mutations go through notifier methods.

Provider taxonomy

Example: how a track becomes audio

1. UI calls audioPlayerNotifier.load([track], autoPlay: true).
2. For each non-local track, sourcedTrackProvider(track) runs SourcedTrack.fetchFromTrack(...), which uses the audio-source plugin to match and resolve a stream (using the selected YouTube engine and quality presets).
3. The track is enqueued into media_kit as a SpotubeMedia, whose URI points at the local shelf server (/stream/<trackId>).
4. media_kit requests that URL; the server's ServerPlaybackRoutes.streamTrack proxies the upstream audio (with caching) back to the player.

This indirection is why the local server runs even for ordinary local playback.

Reactive persistence

UserPreferencesNotifier (lib/provider/user_preferences/user_preferences_provider.dart) seeds a singleton row (id = 0) in PreferencesTable and then watchSingle()s it. Any write updates the row; the watch fires and the notifier re-applies side effects (desktop title-bar style, audio normalization). Settings are therefore live across the whole app — change one place, every watcher updates.

6. The Plugin System (BYOMM)

Plugins are the heart of Spotube. They are Hetu-script programs distributed as .smplug archives and run inside an embedded Hetu VM (hetu_script + hetu_spotube_plugin).

Plugin abilities

A plugin declares one or more abilities (PluginAbilities):

Discovery

MetadataPluginRepositoriesNotifier (lib/provider/metadata_plugin/core/repositories.dart) searches two forges in parallel for the topic spotube-plugin:

• GitHub: GET https://api.github.com/search/repositories?q=topic:spotube-plugin&sort=stars&order=desc
• Codeberg: GET https://codeberg.org/api/v1/repos/search?q=spotube-plugin&topic=true&sort=stars&order=desc

Results are paginated and merged. The settings UI further filters by topic spotube-metadata-plugin vs spotube-audio-source-plugin.

Installation paths

MetadataPluginsNotifier (referenced from lib/pages/settings/metadata_plugins.dart) exposes:

• downloadAndCachePlugin(url) → addPlugin(config) — install from a URL.
• extractPluginArchive(bytes) → addPlugin(config) — install from an uploaded .smplug (validated as a Spotube Metadata Plugin file type).

Two plugins ship bundled as assets (assets/plugins/..., declared in pubspec.yaml):

• spotube-plugin-musicbrainz-listenbrainz/plugin.smplug
• spotube-plugin-youtube-audio/plugin.smplug

Default selection

metadataPluginsProvider.value carries defaultMetadataPluginConfig and defaultAudioSourcePluginConfig. The UI marks installed plugins as default per ability; the rest of the app reads "the default plugin" through metadataPluginProvider / audioSourcePluginProvider.

Cross-cutting plugin services

• Auth (core/auth.dart): metadataPluginAuthenticatedProvider / audioSourcePluginAuthenticatedProvider watch the plugin's auth.authStateStream and expose isAuthenticated().
• Scrobble (core/scrobble.dart): when the default metadata plugin supports scrobbling, plays are pushed to plugin.core.scrobble({...}) with ISRC, duration, and timestamps.
• User (core/user.dart): metadataPluginUserProvider returns the logged-in SpotubeUserObject when authenticated.
• Support (core/support.dart): exposes plugin-provided support text.

Warning

Plugins execute third-party logic and make arbitrary network calls (e.g. to GitHub, Codeberg, and provider APIs). The Plugins screen surfaces a DMCA/disclaimer notice. From a threat-model perspective, an installed plugin is trusted code running in your app. Packagers and security reviewers should treat the plugin install surface (URL + file upload) as the primary untrusted-input boundary.

7. Audio Pipeline & Local Server

The in-process shelf server

serverProvider (lib/provider/server/server.dart) starts a shelf server:

• Bind address: InternetAddress.anyIPv4 when Connect is enabled, otherwise InternetAddress.loopbackIPv4 (localhost-only).
• Port: connectPort preference. -1 means choose a random port in [5000, 22500) once and store it on SpotubeMedia.serverPort; otherwise the configured port.
• Pipeline: pipelineProvider adds logRequests() middleware in debug mode only.

Routes

serverRouterProvider (lib/provider/server/router.dart) wires:

Streaming & caching (routes/playback.dart)

streamTrack resolves the upstream URL from the SourcedTrack, requests it with dio (rotating a random mobile/desktop user-agent from a set of YoutubeApiClient device clients), and:

• If cacheMusic is on and a cache file exists, serves the cached bytes with proper content-range/accept-ranges headers (range support for seeking).
• If the upstream returns an HLS playlist (application/vnd.apple.mpegurl), responds with a 301 redirect to let the player handle HLS range requests itself.
• Otherwise streams the body through while simultaneously writing a .part cache file; on completion it renames .part→final and writes ID3/metadata tags via MetadataGod (skipping weba).
• On stream errors it transparently refreshes the streaming URL or swaps to a sibling source (swapWithNextSibling, refreshStreamingUrl) — the self-healing that keeps playback alive when a single source dies.

Cache files live under getMusicCacheDir():

• Android: external cache .../Cached Tracks
• Other: application cache .../cached_tracks

Connect WebSocket (routes/connect.dart)

The /ws endpoint is the Connect control plane:

• On connect, the player device shows an Accept/Decline dialog keyed by the controller's host:port origin (cached in _allowedConnections). Declined connections receive a WebSocketErrorEvent and are closed.
• The server pushes initial state (queue, playing, position, duration, shuffle, loop, volume) and then forwards live stream events.
• Inbound events drive the audio player: load, pause, resume, stop, next, previous, jump, seek, shuffle, loop, addTrack, removeTrack, reorder, volume.

mDNS advertisement (server/bonsoir.dart)

When Connect is enabled and no service is already resolved, bonsoirProvider advertises a _spotube._tcp service named after the device, with id and deviceId attributes, on the server port — so peer Spotube instances can discover it.

8. Persistence Layer

Drift / SQLite

The app database is defined in lib/models/database/database.dart (AppDatabase), generated by drift_dev (config in build.yaml: database app_db, SQLite dialect, json1 module). Schema snapshots are versioned under drift_schemas/app_db/ and test/drift/ covers migrations.

Tables (lib/models/database/tables/):

Custom type converters (SpotubeColorConverter, LocaleConverter, StringListConverter, textEnum<>) serialize complex preference values into text columns.

Key-value & secure storage

• KVStoreService (shared_preferences) — fast scalar prefs (e.g. volume, YouTube engine binary paths).
• EncryptedKvStoreService (flutter_secure_storage + encrypt) — sensitive values.

Migrations

lib/utils/migrations/sandbox.dart runs migrateMacOsFromSandboxToNoSandbox() at startup, moving data when the macOS build switched away from sandboxing.

9. Configuration Reference

All user-facing configuration is the PreferencesTable (lib/models/database/tables/preferences.dart), a single row keyed id=0. Defaults are defined in PreferencesTable.defaults().

Complete preferences table

Note

youtubeClientEngine has a platform-dependent default: NewPipe everywhere except iOS, where NewPipe is unavailable so it defaults to YouTubeExplode. Engine availability is gated by YoutubeClientEngine.isAvailableForPlatform().

Build-time configuration

Android flavors & SDKs

android/app/build.gradle defines three product flavors, each with a distinct app name and application-id suffix:

SDK targets: minSdkVersion 24, targetSdkVersion 35, compileSdkVersion 36, NDK 29.0.14206865, multidex enabled, core-library desugaring on. Release signing reads key.properties (keystore alias/passwords) — never commit that file.

10. Build & Release

Prerequisites

• Flutter >=3.29.0, Dart >=3.0.0 <4.0.0.
• Platform toolchains (Android SDK/NDK, Xcode, Visual Studio with C++ for Windows, GTK/mpv dev libs for Linux).
• Network access to fetch git-pinned dependencies and forks.

Standard Flutter build

flutter pub get
dart run build_runner build --delete-conflicting-outputs   # codegen (drift, auto_route, json, freezed, envied)
flutter build apk         # or appbundle / windows / macos / linux / ipa

✓ Built build/app/outputs/flutter-apk/app-release.apk

Important

Run build_runner after any change to Drift tables, routes, @freezed/json_serializable models, or envied env definitions. Generated files (*.g.dart, *.gr.dart, *.freezed.dart) are excluded from analysis and must be regenerated, not hand-edited.

Developer build CLI

The project ships a maintainer CLI at cli/cli.dart (a Dart CommandRunner named cli, "Configuration CLI for Spotube"):

dart run cli/cli.dart install-dependencies -p linux -a x86
dart run cli/cli.dart build -a all linux

For example, install-dependencies -p linux installs the GTK/mpv/webkit/appindicator toolchain and appimagetool; -p windows installs Inno Setup via Chocolatey; -p macos installs appdmg.

Release distribution

distribute_options.yaml drives flutter_distributor jobs that package per platform/target (zip, deb, appimage, exe, dmg) with APP_ENV dart-defines. The published artifact names are referenced by the website (website/src/collections/app.ts) and the GitHub releases:

Spotube-android-all-arch.apk
Spotube-windows-x86_64-setup.exe
Spotube-macos-universal.dmg
Spotube-linux-x86_64.deb        Spotube-linux-aarch64.deb
Spotube-linux-x86_64.rpm
Spotube-linux-x86_64.AppImage   Spotube-linux-aarch64.AppImage
Spotube-iOS.ipa

Changelog

cliff.toml (git-cliff) generates conventional-commit changelogs grouped into Features / Bug Fixes / Translation, with issue links rewritten to the repo.

11. Platform Integration

The Windows native entry (windows/runner/main.cpp) creates a 1200×800 window titled spotube, attaches a console for flutter run/debugger, and forwards command-line args to the Dart entrypoint.

12. Security Analysis

Trust boundaries

Observations & hardening notes

Caution

The Connect server binds to all interfaces when enabled. The per-origin Accept/Decline prompt is the only authorization gate — there is no token/password. On untrusted networks, leave Connect off. Packagers should keep the default (enableConnect=false).

Warning

Plugins are arbitrary Hetu programs with network access. There is no capability sandbox limiting which hosts a plugin may contact. Users installing third-party plugins are extending their trust boundary to the plugin author. This is the most security-relevant area of the app.

• License keys / signing: Android release signing uses a local key.properties/keystore (not in-repo). envied is used for compile-time env (e.g. Env.discordAppId, release channel) — verify no secrets are baked into public builds.
• HttpOverrides.global disables some certificate strictness via an allowlist. Review BadCertificateAllowlistOverrides before distributing on networks where MITM is a concern.
• No telemetry server of its own: the app talks to plugin providers, GitHub/Codeberg (plugin discovery), Discord (RPC), Last.fm (scrobble), and Wikipedia (artist bios). Network reviewers should expect these destinations.

13. Internationalization

• Framework: Flutter intl + ARB files, configured by l10n.yaml (arb-dir: lib/l10n, template app_en.arb, generated into lib/l10n/generated).
• Coverage: 30 locale ARB files (lib/l10n/app_*.arb).
• Workflow: cli untranslated emits missing strings (with the English source) for machine/human translation; cli translated merges a tm.json of translations back into the ARB files. Untranslated keys are tracked in untranslated_messages.json.
• Runtime: L10n.all lists supported locales; the language picker (settings/sections/language_region.dart) offers "System default" plus every locale, displayed with native names via LanguageLocals.

14. Operations & Troubleshooting

This section targets packagers and power users diagnosing field issues. (End-user troubleshooting is in the User Guide.)

Diagnosing playback failures

The dominant failure class is audio resolution. The chain is: metadata track → sourcedTrackProvider → audio-source plugin → YouTube engine → stream URL → shelf proxy → media_kit.

1. Confirm the layer. If local-library tracks play but online tracks don't, the metadata/UI/server layers are fine — the fault is the audio-source plugin or engine.
2. Switch engines. youtubeClientEngine (NewPipe / YouTubeExplode / yt-dlp). NewPipe needs no binary; yt-dlp needs the binary path set (KVStoreService.getYoutubeEnginePath).
3. Inspect logs. Settings → Developers → Logs (or run with --verbose). Logs are stored on disk (AppLogger.getLogsPath()); the request proxy logs HEAD/GET per track in verbose.
4. Self-healing. The proxy already retries via refreshStreamingUrl/swapWithNextSibling; persistent failure usually means the engine itself is broken upstream.

Known issue patterns (from the community tracker)

Log collection

Settings → Developers → Logs → (copy icon) → paste into a GitHub issue

Include platform, app version (Settings → About), release channel, and the selected YouTube engine.

Data locations

15. Code Quality & Conventions

• Lints: package:flutter_lints/flutter.yaml, with file_names and avoid_renaming_method_parameters disabled; invalid_annotation_target ignored. Generated files and test/ are excluded from analysis.
• State convention: Riverpod everywhere; UI is HookConsumerWidget; providers expose notifiers for mutations. Side effects (DB writes, audio engine calls) live in notifiers, not widgets.
• Routing convention: every screen is a @RoutePage class with a static name; routes are code-generated by auto_route.
• Codegen-heavy: Drift, auto_route, json_serializable (any_map: true, explicit_to_json: true), freezed, envied, flutter_gen — dart run build_runner build is mandatory after model/route/schema edits.
• Platform flags: lib/utils/platform.dart exposes kIsDesktop, kIsMobile, kIsAndroid, kIsIOS, kIsWindows, kIsMacOS, kIsLinux, kIsWeb, kIsFlatpak — used pervasively to branch behavior.
• Error handling: centralized via AppLogger.reportError(e, stack); the whole app runs in a guarded zone.
• Naming: feature folders mirror UI structure (pages/, modules/, provider/, services/). Models suffix domain objects (SpotubeTrackObject, SpotubeFullTrackObject, SourcedTrack).

Complexity hotspots

• lib/models/database/ (largest module by source size — generated Drift code dominates).
• lib/collections/ (generated assets, routes, large catalogs like markets/locales).
• The audio proxy routes/playback.dart — non-trivial streaming/caching/range/HLS logic with self-healing fallbacks; the highest-risk handwritten code for regressions.

16. Potential Improvements

Note

These are observations for maintainers, derived from the source. They are suggestions, not defects.

• Plugin sandboxing/capabilities. The biggest security lever: constrain which network hosts/APIs a plugin may reach, or surface a permissions manifest at install time. Today an installed plugin is fully trusted.
• Connect authorization. The per-origin Accept/Decline gate has no persistent pairing secret or token. A shared-secret/pairing-code scheme would harden LAN exposure beyond a one-time prompt.
• Duration-unit robustness. The recurring "0:00 in queue" bug stems from seconds↔microseconds confusion at the engine/matcher seam; a typed Duration boundary (rather than raw ints) would prevent the whole class.
• Engine health surfacing. Because YouTube engines break independently and often, an in-app "test engine" / auto-failover across engines would cut the most common support load.
• amoledDarkTheme and albumColorSync toggles exist in the preferences schema but their UI controls are commented out in appearance.dart — either wire them up or remove to avoid dead config.
• sleepTimerProvider calls exit(0) to stop playback — the code itself flags this may cause iOS App Store rejection. A graceful pause-and-background would be safer.
• Git-pinned dependencies (many forks) make builds fragile to upstream repo availability; vendoring or publishing the forks to pub would improve reproducibility.

17. Quick Reference

Key files

Server routes

App CLI flags

Developer CLI commands

Build essentials

flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter build <apk|windows|macos|linux|ipa>

Identity