Setting Up a VIVI Music Local Development Environment

VIVI Music is a multi-module Android project written in Kotlin. The build pipeline combines standard Gradle/AGP tooling with a Go-based protobuf generation step and a native C++ audio DSP library (FFTW) that must be cross-compiled for Android before your first build. Follow the steps below to go from a fresh clone to a running debug APK.

Prerequisites

Make sure the following tools are installed and available on your PATH before you begin:

Java JDK 21

Required by Gradle and the Android build tools. Use any distribution (Temurin, Zulu, Oracle).

Android Studio (latest stable)

Provides the Android SDK, emulator, and Gradle wrapper. Alternatively use VSCode with the Kotlin and Android extensions.

Go 1.20+

Used by the protobuf generation script (generate_proto.sh) and Go-based tooling in the repo.

protoc + protoc-gen-go

Protocol Buffer compiler and the Go plugin, required to generate Kotlin/Java sources from .proto files.

Android NDK 27.0.12077973

Exact NDK version pinned in app/build.gradle.kts (ndkVersion = "27.0.12077973"). Install via Android Studio’s SDK Manager.

Build Steps

Clone the repository

Clone the repository and initialise all Git submodules. VIVI Music uses submodules for several of its Gradle modules.

git clone https://github.com/vivimusicGroup/vivimusic
cd vivimusic
git submodule update --init --recursive

Generate protobuf files

The Innertube and other modules use Protocol Buffers. Run the generation script from the app directory to produce the required Kotlin/Java source files.

cd app
bash generate_proto.sh
cd ..

Build FFTW for Android

The VibraFP audio DSP engine depends on FFTW (Fastest Fourier Transform in the West) compiled as a native Android library. Run the bundled build script, pointing it at your NDK installation and a target output directory.

bash app/src/main/cpp/vibrafp/third_party/build-fftw-android.sh \
  --ndk ~/Android/Sdk/ndk/27.0.12077973 \
  --out app/src/main/cpp/vibrafp/third_party/fftw-android

This step takes a few minutes as it cross-compiles FFTW for each supported Android ABI.

Generate a persistent debug keystore

VIVI Music uses a persistent debug keystore (rather than the standard per-machine debug key) so that debug builds remain installable across development machines without uninstalling first. The command below generates the keystore only if it does not already exist.

[ ! -f "app/persistent-debug.keystore" ] && keytool -genkeypair \
  -v -keystore app/persistent-debug.keystore \
  -storepass android -keypass android \
  -alias androiddebugkey -keyalg RSA -keysize 2048 \
  -validity 10000 \
  -dname "CN=Android Debug,O=Android,C=US" \
  || echo "Keystore already exists."

Build the FOSS universal debug APK

Assemble the default FOSS (F-Droid compatible) universal debug APK using the Gradle wrapper.

./gradlew :app:assembleuniversalFossDebug

Locate the output APK

After the build completes, the APK is written to:

ls app/build/outputs/apk/universalFoss/debug/app-universal-foss-debug.apk

You can install it directly to a connected device with adb install app/build/outputs/apk/universalFoss/debug/app-universal-foss-debug.apk.

Build Variants

VIVI Music uses two Gradle flavor dimensions to produce a matrix of APK variants.

`abi` dimension

Flavor	Description
`universal`	Single APK containing native libraries for all supported ABIs
`arm64`	64-bit ARM (most modern Android phones)
`armeabi`	32-bit ARM
`x86`	x86 32-bit (emulator and older hardware)
`x86_64`	x86 64-bit (emulator and Chrome OS)

`variant` dimension

Flavor	`CAST_AVAILABLE`	Description
`foss` (default)	`false`	F-Droid compatible, no Google Play Services dependency
`gms`	`true`	Includes Google Cast support, requires Google Play Services

The full Gradle task name follows the pattern :app:assemble<abi><Variant><BuildType>. For example:

assembleuniversalFossDebug — universal FOSS debug (recommended for development)
assemblearm64GmsRelease — arm64 GMS release (for distribution)

Gradle Modules

The project is split across the following Gradle modules, each in its own top-level directory:

Module	Purpose
`:app`	Main Android application — all screens, services, and ViewModels
`:innertube`	YouTube / YouTube Music API client (unofficial reverse-engineered API)
`:lastfm`	Last.fm API client for scrobbling
`:kizzy`	Discord Rich Presence gateway client
`:jiosaavn`	JioSaavn streaming, search, and audio decryption
`:shazamkit`	Song recognition via ShazamKit
`:canvas`	Core animated canvas rendering infrastructure
`:vivimusiccanvas`	VIVI Music’s own canvas visualiser source
`:applecanvas`	Apple Music–style animated backdrop renderer
`:lyricsProvider`	Unified lyrics fetching layer (LRCLib, Kugou, Musixmatch, etc.)
`:artistvideo`	Artist video loading and playback helpers
`:spotify`	Spotify playlist import integration

Development

Documentation Index

​Prerequisites

Java JDK 21

Android Studio (latest stable)

Go 1.20+

protoc + protoc-gen-go

Android NDK 27.0.12077973

​Build Steps

​Build Variants

​abi dimension

​variant dimension

​Gradle Modules

Build docs developers (and LLMs) love