NUVX / DOCUMENTATION

A little context
before you begin.

Nuvx is actively being built. This guide tells you what works today, what is planned, and how to run the code if you want to explore or contribute.

There is no installable release yet.

The Android and desktop app interfaces and playback are not implemented. Do not expect an APK, installer, TV app or Wear OS build. Watch the repository for release announcements.

01 — START HERE

What is Nuvx?

Nuvx is an open-source music player project built with Kotlin Multiplatform and Compose Multiplatform. It connects to YouTube Music through interchangeable backend engines. It is independent software and is not made, endorsed or sponsored by YouTube or Google.

The project is early-stage. Backend experiments and shared models exist; user-facing apps and playback remain future work. See the verified progress and known limitations.

02 — PLATFORMS

Where it is headed

Platform	Status	What to know
Android phone / tablet	Planned	App UI and playback are not implemented.
Android TV	Planned	No TV build is available.
Wear OS	Planned	No watch build is available.
Windows / Linux	Planned	Shared desktop target exists; no player UI or package.
macOS	Planned	Packaging and a macOS build runner are still needed.
iOS / iPadOS	Upcoming	Requires a macOS or Linux build environment and Apple signing setup.

03 — FOR CONTRIBUTORS

Build from source

These steps prepare the shared project and run its desktop unit tests. They do not install a usable music player.

Install the toolchain. Use Temurin JDK 25 to run Gradle, JDK 27 for the desktop target, and Android SDK API 37. See the complete toolchain notes.

Build eXcor locally. Nuvx currently consumes its alternative engine from Maven Local. Clone eXcor and run:

./gradlew publishAndroidPublicationToMavenLocal publishJvmPublicationToMavenLocal publishKotlinMultiplatformPublicationToMavenLocal

Clone Nuvx and build.
```
git clone https://github.com/bxanedot/nuvx.git
cd nuvx
./gradlew :shared:desktopTest
```
On Windows, use gradlew.bat. Gradle can provision the JDK toolchain; if needed, set org.gradle.java.installations.paths to your JDK 27 location.
Optional live backend check. This reaches YouTube Music over the internet and may change as the service changes:
```
NUVX_LIVE=1 ./gradlew :shared:desktopTest --tests '*LiveBackendTest*'
```

Android SDK local configuration may require a gitignored local.properties with sdk.dir set to your SDK path. iOS targets cannot currently be built on Windows.

04 — STREAMING

Music engines

The shared code exposes a MusicBackend interface. InnerTubeX is the default and has passed live search, radio and audio-stream checks. eXcor search and radio work, but YouTube currently refuses its stream requests because it does not mint PO tokens. With fallback enabled, Nuvx routes stream requests to the other engine.

Backend availability depends on YouTube Music, network access and the upstream projects. This can change without notice; see the current blocker list.

05 — DATA & PRIVACY

What to expect

The public website is static and does not provide account creation or a contact form. The app is not yet released, so its final data handling has not been established. Backend requests made during development can communicate with YouTube Music and the selected engine. Review the source and upstream service terms before using development builds.

Read the website privacy notice and terms.

06 — HELP & CONTRIBUTE

Follow the work

Read the architecture and progress notes, report bugs or open a discussion on GitHub. Contributions are licensed under GPL-3.0-only, matching the project. Please include steps to reproduce issues and avoid sharing private tokens or account details.

Open Nuvx on GitHub ↗