spotube

A cross-platform extensible open-source music streaming platform. Bring your own music metadata/playlist/audio-source with plugins created by community or by yourself. A small step towards the decentralized music streaming era!

---

****

🌃 Features

• 🧩 Plugin powered, supports any platform or custom music service through plugins.
• 🗺️ Community driven plugins for popular platforms or create your own.
• ⬇️ Freely downloadable tracks with tagged metadata.
• 🖥️ 📱 Cross-platform support.
• 🪶 Small size & less data usage.
• 🕒 Time synced lyrics regardless of the plugin support.
• ✋ No telemetry, diagnostics or user data collection.
• 🚀 Native performance.
• 📖 Open source/libre software.
• 🔉 Playback control is done locally, not on the server.

⬇️ Download

Download Spotube from the Official Website: https://spotube.cc

🔄 Nightly Builds

Grab the latest nightly builds of Spotube from the Offical Website.

Spotube is a Compose Multiplatform app.

1. Prerequisites

• JDK 21 to run Gradle (the Gradle daemon JDK and GraalVM are provisioned automatically).

• Rust (rustup + cargo), for the composeApp library built through Gobley.

• Android SDK, only for Android builds.

• ComposeNativeWebview, which isn't on Maven Central yet. Clone it at the commit pinned as COMPOSE_WEBVIEW_COMMIT in spotube-release-binary.yml and run ./gradlew publishToMavenLocal in it.

• Linux only: runtime libraries, including VLC. Needed to run the app, including :composeApp:run:

  Distro	Command
  Debian/Ubuntu	sudo apt-get install libvlc5 vlc-plugin-base libwebkit2gtk-4.1-0 libgtk-3-0 libasound2 libgl1 libxtst6 libxi6 libxrender1
  Fedora	sudo dnf install vlc-libs webkit2gtk4.1 gtk3 alsa-lib mesa-libGL libXtst libXi libXrender (vlc-libs needs RPM Fusion)
  Arch / CachyOS / Manjaro	sudo pacman -S vlc webkit2gtk-4.1 gtk3 alsa-lib libglvnd libxtst libxi libxrender
  openSUSE	sudo zypper install libvlc5 libwebkit2gtk-4_1-0 libgtk-3-0 libasound2 Mesa-libGL1 libXtst6 libXi6 libXrender1

  On Ubuntu 24.04+/Debian 13, libgtk-3-0 and libasound2 are libgtk-3-0t64 and libasound2t64; apt resolves this itself.

2. Run in development

Desktop (JVM), fastest edit/run loop

./gradlew :composeApp:run

Android debug APK

./gradlew :composeApp:assembleStableDebug

Use ./gradlew :composeApp:assembleNightlyDebug for the nightly channel.

Development builds stay fast: the release-only optimizations below are skipped.

3. Build the desktop app

A native build takes about 10 minutes, uses every CPU core and peaks at ~15 GB of RAM. It only happens for the tasks below, never for run.

Native toolchain (Nucleus downloads GraalVM CE on the first build; set GRAALVM_HOME to use your own):

OS	Requirements
Linux	gcc, zlib headers, patchelf; rpm for .rpm, fuse + zstd for .AppImage. Debian/Ubuntu: sudo apt-get install build-essential zlib1g-dev patchelf rpm fuse zstd. Fedora: sudo dnf install gcc zlib-devel patchelf rpm-build fuse zstd
macOS	Xcode Command Line Tools (xcode-select --install)
Windows	Visual Studio Build Tools with "Desktop development with C++" (use an "x64 Native Tools" prompt if native-image can't find MSVC)

Build and run the app folder:

./gradlew :composeApp:createGraalvmNativeDistributable

Output folder: composeApp/build/compose/binaries/main/graalvm-app/

Build and launch in one step

./gradlew :composeApp:runGraalvmNativeDistributable

Keep the spotube binary next to the libraries it was built with; it loads them from its own folder.

Installers (each OS builds only its own):

OS	Command
Linux	./gradlew :composeApp:packageGraalvmDeb :composeApp:packageGraalvmRpm
Linux (AppImage)	./gradlew :composeApp:packageGraalvmAppImage -PappImage=true
Windows	./gradlew :composeApp:packageGraalvmExe (or packageGraalvmMsi)
macOS	./gradlew :composeApp:packageGraalvmDmg

Output folder: composeApp/build/compose/binaries/main/graalvm-<format>

[!Tip] Add -Pnightly=true for the nightly channel (separate icons and name).

• DownloadLinuxGtkBundleTask downloads the Ubuntu 24.04 packages (audio-only VLC via vlcj-bundler, GTK 3, WebKitGTK 4.1, glib-networking), keeps only what GTK/WebKit reach and relocates the libraries with patchelf. Needs ar, tar, zstd, readelf, patchelf.
• WebKitGTK has its helper-process path compiled in, so AppImageEnvironment patches it to a relative path and moves to that directory at startup. It also sets GIO_EXTRA_MODULES and WEBKIT_DISABLE_DMABUF_RENDERER=1 (the bundled WebKitGTK 2.44 never paints against a newer host Mesa).
• main() must call GraalVmInitializer.initialize() first: the VLC loader and the environment setup read compose.application.resources.dir.

4. Native build breaks, JVM works

A native image is a closed world: everything reached through reflection, JNI or JNA (vlcj, Zipline, NewPipe, ktor, datastore, ...) must be declared at build time. Nucleus generates most of it; the rest lives in composeApp/graalvm/reachability-metadata.json.

Symptoms: ClassNotFoundException, NoSuchMethodException or MissingReflectionRegistrationError in the native binary, while :composeApp:run works.

1. ./gradlew :composeApp:runWithNativeAgent starts the app on the JVM with GraalVM's tracing agent.
2. Use the broken feature, then close the window normally. Ctrl+C discards the recording.
3. Commit the updated JSON in composeApp/graalvm/ and rebuild.

[!Tip] ./gradlew :composeApp:runGraalvmNative is a faster debug loop: a quick -Ob build that names the missing registration.

[!Warning] Keep the hand-written uk.co.caprica.vlcj.binding.lib.LibVlc entry, or playback fails to initialize.

5. Production vs development builds

Production mode turns on automatically for package*, create*, notarize* and nativeImageCompile tasks. Force it with -Pproduction=true|false.

Area	Development	Production
Rust lib	fast debug profile	release with LTO and stripping (31 MB → 1.8 MB)
Desktop app	hot-reloadable JVM app	size-optimized (-Os) GraalVM native image
Native libs	all	host OS/CPU only; Skia loaded from lib/; on Linux ~10 KB libjvm.so/libjava.so shims instead of the JDK's 28 MB one

Android picks the Rust profile from its build type.

6. Releases

Run spotube-release-binary.yml manually (workflow_dispatch) as stable, beta or nightly.

• Beta: the stable build as a draft, tagged v<version>-beta.N. Set betaNumber in composeApp/build.gradle.kts to N, and back to null for stable.
• Desktop: each platform (Linux x86_64 and aarch64, Windows, macOS) builds its installers on its own runner.
• Android: a signed APK.

📚 Resources

Core stack

• Kotlin Multiplatform
• Compose Multiplatform
• Compose Hot Reload
• Koin for KMP
• Ktor client
• DataStore for KMP

Desktop and native

• Nucleus: desktop packaging and GraalVM integration
• ComposeNativeWebview
• GraalVM Native Image and its reachability metadata
• Gobley: Rust in Kotlin Multiplatform
• vlcj: VLC bindings for audio playback

Plugins

• Zipline: runs the JS plugins

👥 The Spotube team

• Kingkor Roy Tirtho - The Founder, Maintainer and Lead Developer
• Owen Connor - The Cool Discord Moderator
• Piotr Rogowski - The MacOS Developer
• Rusty Apple - The Mysterious Unknown Guy

💼 License

Spotube is open source and licensed under the AGPL-3.0-or-later License.