Getting Started

Spotube plugins are Kotlin/JS libraries that run on Cash App's Zipline runtime. You implement service interfaces from the plugin_interfaces library, and Spotube calls them at runtime to fetch metadata, provide audio streams, display lyrics, and scrobble playback.

How it works

1. Write Kotlin/JS classes that implement Zipline service interfaces (e.g. MetadataSearchAPI, AudioAPI, CoreAPI).
2. In a top-level main() function, use Zipline.get() to connect to the host, then register your implementations.
3. The Zipline Gradle plugin compiles your code. The Spotube Gradle plugin packages it with a plugin.json manifest into a .smplug file.
4. Spotube loads the .smplug, calls your main(), and invokes your services.

Requirements

• Kotlin 2.0+ (Kotlin Multiplatform with JS target)
• Gradle 8+
• JDK 17+
• IntelliJ IDEA (recommended) or Android Studio

Key dependencies

Available on Maven Central:

Project structure

my-plugin/
├── build.gradle.kts
├── plugin.json
└── src/
    └── jsMain/
        └── kotlin/
            └── myplugin/
                ├── main.kt
                └── plugin_apis/
                    ├── core/
                    ├── audio/
                    ├── lyrics/
                    ├── scrobble/
                    └── metadata/

A full working project is available in the Spotube repository's js_plugin_example.

Next

Start with Creating a Plugin for a step-by-step walkthrough, then explore the API reference pages under Developing Plugins.