JusPlayer Engine

A modular, provider-based music engine for the JVM — search, stream, queue, and play music from any backend through one clean API.

---

What is JusPlayer?

A coroutine-first music engine, not a media player. It gives you providers (streams, lyrics, artwork), a queue, and a playback engine — and hands the actual audio output to a PlayerAdapter you provide. No Android dependencies; it runs on a plain JVM.

Features

Feature	What it does
Provider abstraction	Swap backends behind one MusicProvider interface
Streams	YouTube search + stream URLs via the bundled NewPipe provider
Lyrics	Synced + plain lyrics via LRCLIB
Artwork	Cover art via Cover Art Archive + MusicBrainz resolution
Queue	Add, move, shuffle, next/previous, repeat, clear
Coroutine flows	StateFlow state, SharedFlow events, all suspend-friendly
Zero Android deps	Plain JVM — CLIs, servers, desktop, or Android
DSL builder	createJusPlayer { ... } wires everything in one call
HTTP server	Optional Ktor module exposes the engine over REST, with an in-built browser demo at /

30-second example

val jusPlayer = createJusPlayer {
    provider(NewPipeProvider())                // streams (YouTube)
    lyricsProvider(LRCLIBProvider())           // optional: lyrics
    artworkProvider(CoverArtArchiveProvider()) // optional: cover art
    releaseResolver(MusicBrainzResolver())     // optional: song -> release
    player(MyPlayerAdapter())                  // required: your audio output
}

val songs = jusPlayer.engine.search("Daft Punk")
songs.firstOrNull()?.let {
    jusPlayer.queue.add(it)
    jusPlayer.engine.play(it)
}

Architecture

       Your app (UI, notifications, platform integration)
                           │
                     PlayerAdapter  ──▶  audio device
                           │
                      JusPlayer Engine  (queue, services, state)
                           │
             ┌─────────────┼─────────────┐
        MusicProvider  LyricsProvider  ArtworkProvider
             │               │               │
          NewPipe          LRCLIB       CoverArtArchive
                                           (MusicBrainzResolver)
             │               │               │
                       Internet

Installation

Requires JDK 11+ (JDK 21 recommended) and a Maven repo.

repositories { maven(url = "https://jitpack.io") }

dependencies {
    implementation("com.github.shubh72010.JusPlayer-Engine:engine-api:1.3.0")
    implementation("com.github.shubh72010.JusPlayer-Engine:engine-provider-newpipe:1.3.0")
    // optional:
    implementation("com.github.shubh72010.JusPlayer-Engine:engine-provider-lrclib:1.3.0")
    implementation("com.github.shubh72010.JusPlayer-Engine:engine-provider-coverartarchive:1.3.0")
}

Documentation

Doc	What it covers
Getting Started	Start here — core concepts
Installation	Every module, exactly what to add
Quick Start	A complete working app
Architecture	How the pieces fit together
Providers	NewPipe, LRCLIB, CoverArtArchive in detail
PlayerAdapter	Implementing audio output
HTTP Server	REST API endpoints
Creating a Provider	Add your own backend
Creating a PlayerAdapter	Add your own audio engine
Cookbook	Copy-paste recipes
Updating	Version bumps
Migration	Breaking changes between versions
FAQ	Common questions

Commands

JAVA_HOME=/usr/lib/jvm/java-21-temurin-jdk ./gradlew build          # compile + test all modules
JAVA_HOME=/usr/lib/jvm/java-21-temurin-jdk ./gradlew :sample-console:run
JAVA_HOME=/usr/lib/jvm/java-21-temurin-jdk ./gradlew :engine-http:run     # REST server on :8368; auto-opens the browser demo at /
# port override: --args=9000 or env JUS_ENGINE_PORT

License

GPL-3.0. All contributions are licensed under the GPL-3.0 license, in accordance with the NewPipeExtractor dependency.