install guide

Get it running.

Runs on Windows 10+, Linux (x86-64) and macOS 10.15+. Every command below has a copy button, so nothing gets typed by hand. All installers are attached to the GitHub Releases page.

this page is long on purpose — the install itself isn't

Two installers are published; the .exe is the one to grab — lighter and friendlier. The .msi exists for silent / enterprise deployments.

Option A — Installer (.exe, recommended)

  1. Download VIVIMusic-…-x64.exe from the Releases page.
  2. Double-click the file and follow the wizard.
  3. It installs to C:\Program Files\VIVIMusic and starts when the wizard finishes — or launch it from the Start menu / desktop shortcut.

Option B — MSI package (.msi)

  1. Download the .msi file.
  2. Double-click to install, or deploy silently with:
msiexec /i VIVIMusic-….msi /qn

Then launch from the Start menu.

Uninstall

Open Settings → Apps → Installed apps, find VIVI Music and choose Uninstall — or run the uninstaller from C:\Program Files\VIVIMusic. Downloaded updates are cached under ~/.vivimusic/updates/ and cleaned up automatically after 7 days.

Three ways in, depending on your distro.

Option A — Debian / Ubuntu (.deb)

Works on Debian, Ubuntu and their derivatives.

sudo apt install ./VIVIMusic-….deb

or, the long way:

sudo dpkg -i VIVIMusic-….deb && sudo apt-get install -f

Launch VIVI Music DE from your application menu.

Option B — AppImage (any distro, portable)

Works on most distributions, including Arch and Fedora.

chmod +x VIVIMusic-….AppImage
./VIVIMusic-….AppImage

If your system blocks AppImages (no FUSE), extract and run it instead:

./VIVIMusic-….AppImage --appimage-extract
./squashfs-root/AppRun

Option C — Arch Linux (AUR-style PKGBUILD)

Every release also ships a PKGBUILD (plus SRCINFO) as a release asset. To build and install a proper system package:

mkdir vivi-music-de && cd vivi-music-de
# copy the PKGBUILD file from the release assets into this folder
makepkg -si

The PKGBUILD pins the exact release commit with a real checksum, builds the app from source with ./gradlew, and installs it into /opt/vivi-music-de with a desktop entry, icon and a vivi-music-de launcher. It needs jdk21-openjdk and unzip (installed automatically as build dependencies).

Graphics note: if OpenGL isn't available on your system, the app switches to the software renderer by itself. It just works — no configuration needed.

Two formats are published, with Intel and Apple Silicon builds separately.

Option A — Disk image (.dmg)

  1. Download the .dmg for your architecture.
  2. Open it and drag VIVI Music into the Applications folder.
  3. Launch from Applications. If macOS warns that the app is from an unidentified developer (it's not notarized), right-click the app → Open → Open again, or run:
xattr -dr com.apple.quarantine /Applications/VIVI\ Music.app

Option B — Installer package (.pkg)

  1. Download the .pkg and double-click it.
  2. Follow the installer steps; the app lands in Applications.

Uninstall

Drag VIVI Music.app from Applications to the Trash. That's the whole ceremony.

System requirements

OS
Windows 10+ · Linux x86-64 (glibc) · macOS 10.15+
RAM
2 GB — the app itself uses ~350 MB
Disk
~500 MB free
Java
Bundled with the app — nothing to install
Graphics
Any GPU or driver; falls back to software rendering automatically
Platform testing note: the lead developer can currently test the app on Windows only, so that's the platform with the most compatibility attention. The Linux and macOS builds come from CI and lean on community testing — bug reports for those are especially appreciated.

First launch: signing in

  1. Open the app and go to Settings → Account.
  2. Choose Sign in with Google — an embedded sign-in window opens directly on Google. Sign in; when the page bounces back to YouTube Music, the window closes by itself and the session is saved.
  3. Prefer the manual route? Sign in with cookies: log in to music.youtube.com in your browser, open DevTools → Network, click any music.youtube.com request and paste the full Cookie header value into the app. The session is stored only on this device.

Pairing with the Android app (LAN or cloud) is covered on the Sync page.

Updating the app

  • In-app updater: go to Settings → Updates and check for updates. The new installer downloads (with progress) and opens for you — on Windows the .exe is preferred over the .msi.
  • Manual: grab the latest installer from GitHub Releases and install over the current version. Your settings, library and playlists are kept.

Where your data lives

WhatLocation
Settings, login session, pairing~/.vivimusic/
Playlists~/.vivimusic/playlists.json
Audio & lyrics cache~/.vivimusic/cache/
Backups~/.vivimusic/backups/
Downloaded updates~/.vivimusic/updates/

On Windows ~ is C:\Users\<you>; on Linux and macOS it's /home/<you> or /Users/<you>. Delete the folder and the app forgets you — that's the whole privacy model.

Troubleshooting

ProblemWhat to try
Crash at startup on Linux with UnsatisfiedLinkError: OpenGLApi.glFlush() Fixed in DE 1.41.14 — the app now detects the broken OpenGL stack, writes ~/.vivimusic/.gl-software and restarts once on the software renderer. Later launches go straight to software. If you fixed your GPU drivers and want OpenGL back, delete that marker file.
Login fails with 401 UNAUTHENTICATED Fixed in DE 1.41.13 — modern Google __Secure-*PAPISID cookies now authenticate correctly. Update to the latest version and try again.
The embedded sign-in window stays blank Make sure you're on the latest version. Fallback: use Sign in with cookies (see above).
Volume doesn't reach the speakers while paired Set the Windows mixer volume to 0 % (not muted) so the mobile app can drive it.
Playback stops / seekbar jumps while paired Update both apps to the latest version — older builds had sync races that are now fixed.
Still stuck? Check the log files under ~/.vivimusic/, or ask in the Telegram channel. The error codes page explains every code the app can show.

VIVI Music DE — free software under a modified GPL-3.0 license. The original mobile app is created by VIVIDH P ASHOKAN.