Official Documentation

waving_hand Welcome to Vivi Music

Vivi Music is a free, open-source Android music streaming app built for people who want great audio, full control, and no bloat. Whether you're a casual listener or a power user who wants to fine-tune every setting, this documentation has you covered.

What is Vivi Music?

Vivi Music is developed by Vividh P Ashokan and is currently at version 6.0.2 (Stable). It streams music from sources like YouTube Music and JioSaavn, with deep customisation for audio quality, playback behaviour, and social features like Listen Together.

Key Features at a Glance

• High-quality audio streaming with JioSaavn and YouTube Music support
• ViviEqualizer — pro-grade acoustic tuning built into the app
• Listen Together — listen in real-time with friends via room codes
• AI Lyrics Translation — translate song lyrics using OpenRouter AI
• Discord Rich Presence and Last.fm scrobbling integrations
• Backup & restore, m3u/csv playlist import
• Privacy controls — pause history, disable screenshots
• Beta update channel for early access to new features

How to Use This Documentation

This guide is organised to take you from first install to advanced configuration. Casual users can stop after Chapter 3. Developers and contributors should read Chapter 5. If something breaks, jump straight to Chapter 6.

• New user? Start at Chapter 1 — Installation
• Already installed? Jump to Chapter 2 — Setting Up
• Something broken? Go to Chapter 6 — Troubleshooting

download_for_offline Chapter 1 — Installation

This chapter walks you through getting Vivi Music onto your Android device for the first time.

System Requirements

Minimum Requirements

• Android 8.0 or higher
• Stable internet connection for streaming
• ~50 MB free storage for the app

Recommended

• Latest Android for higher for best performance
• 1 GB+ free storage if you plan to download songs offline and for caching
• Headphones or a Bluetooth speaker for the best audio experience

Installing Vivi Music

Install from GitHub (Recommended)

Head over to the official GitHub Releases page, download the latest APK file, and install it on your device.

Install from Website

You can also download the latest version directly from the official Vivi Music website. Tap the Download button and the APK will be downloaded to your device.

Sideloading the APK

Since Vivi Music is not available on the Google Play Store, you'll need to sideload the APK:

• Download the APK file from GitHub Releases or the official website.
• On your Android device, go to Settings > Security and enable "Install from unknown sources" (exact path varies by device).
• Open the downloaded APK file and tap Install.
• Once installed, you can disable "Install from unknown sources" again for security.

Build Differences: vivi.apk vs. vividroid-foss.apk

Vivi Music is distributed in two different builds: vivi.apk (Official Release) and vividroid-universal-foss-release.apk (FOSS / IzzyOnDroid Build). It is helpful to know the differences when choosing which build to install on your device:

• vivi.apk (Official Build):
  • Includes a convenient in-built auto-updater and the option to receive beta/nightly updates directly within the app itself.
  • Supports the Google Cast (Chromecast) option, letting you stream music directly to Cast-enabled TV displays and smart speakers.
• vividroid-universal-foss-release.apk (IzzyOnDroid / FOSS Build):
  • Distributed on the IzzyOnDroid FOSS repository. Due to the strict guidelines of FOSS repositories, this build is not allowed to implement in-built updaters or request request-install-packages/install permission on your device. All updates must be managed through the IzzyOnDroid client.
  • Google Cast / Chromecast support is excluded from this build as the Google Play Services Cast API is closed-source and not compatible with pure FOSS requirements.

First Launch

Permissions Explained

Vivi Music will request the following permissions:

• Notifications — needed to show playback controls and update alerts
• Nearby Devices — required to show Nearby devices and Volume section
• Microphone — When using identify song feature

Account Creation or Sign-in

You can sign in using your Google account (which connects to YouTube Music) or use a login token. You can also explore the app without signing in, though some features like syncing and personalised recommendations will be unavailable.

Updating Vivi Music

Automatic Update Check

Vivi Music checks for updates automatically when you open the Update Settings screen. You can toggle this off if you prefer to check manually.

Manual Update Steps

Go to Settings > Update Settings. If a new version is available, tap the update option to download and install it. You can also view the Changelog and Commits from this screen to see what changed.

Beta Updates

Want early access to new features? Enable Beta Updates in Settings > Update Settings. Beta versions include nightly versions which have been tested by testers and have been committed to github and which may or might not be in new updates.

tune Chapter 2 — Setting Up

This chapter covers everything in the Settings section of Vivi Music. Each section below maps directly to a settings screen in the app.

Account & Profile

Access this screen from Settings > Account. This is where you manage how you're signed in and how your library syncs.

Signing in with Google / YouTube Music

Tap your profile or the Account option in Settings. Choose "Sign in with Google" to connect your Google account, which also links your YouTube Music library. Your liked songs, playlists, and recommendations will sync automatically.

Login with Token

If you prefer not to use Google sign-in, Vivi Music supports token-based login. Go to Settings > Account and tap "Tap to show token" to view or enter your login token. This is useful for advanced users or alternative account setups.

More Content

When enabled, this toggle unlocks additional content beyond the standard catalogue — including region-restricted tracks and extended library access.

Auto Sync with Account

When turned on, Vivi Music automatically keeps your library, liked songs, and playlists in sync with your connected account. Disable this if you prefer manual control or want to save data.

Integrations

Vivi Music supports two integrations, accessible from Settings > Account > Integrations:

• Discord Integration — shows your currently playing song as Discord Rich Presence status
• Last.fm Integration — scrobbles your listening history to your Last.fm profile

Tap either integration to configure it with your account credentials.

Logging Out

Tap the "Log out" button next to your username on the Account screen. You will be signed out of your Google / YouTube Music account. Your local downloads and settings are not deleted.

Player & Audio

Access this from Settings > Player and audio. This is the most detailed settings screen in the app, covering everything from streaming quality to queue behaviour.

Audio Quality & JioSaavn

Set your preferred streaming quality under Audio quality. Higher quality uses more data. JioSaavn quality can be set separately for JioSaavn-sourced tracks — the recommended setting for best quality is 320 kbps.

Player Settings

• Crossfade — Smoothly blends between songs instead of a hard cut.
• Crossfade duration — Controls how many seconds the crossfade transition lasts.
• Disable for gapless albums — Skips crossfade on albums that are intended to play without gaps.
• History duration — Controls how many recent songs are kept in your listen history.
• Skip silence — Fast-forwards through silent parts of songs.
• Instantly skip silence — Jumps ahead during silent moments instead of speeding through them.
• Audio normalization — Keeps all tracks at a consistent volume level.
• Enable offload — Offloads audio processing to hardware. Note: this is automatically disabled when crossfade is active.
• Google Cast — Enables casting audio to Chromecast and Cast-enabled devices.
• Progressive seek — Each seek action adds 5 extra seconds incrementally.
• ViviEqualizer — Opens the pro-grade built-in equalizer for custom audio tuning.

Queue Settings

• Persistent queue — Restores your last queue when the app starts.
• Auto load more songs — Automatically adds more songs when the queue reaches the end.
• Disable load more when repeat all — Prevents auto-loading when repeat all mode is active.
• Auto download on like — Automatically downloads a song when you like it.
• Enable similar content — Adds similar songs when the queue runs out.
• Persistent shuffle — Keeps shuffle enabled when starting new songs or playlists.
• Remember shuffle and repeat — Restores your shuffle and repeat mode when restarting the app.
• Shuffle playlist/album first — Plays all tracks from the original playlist or album before adding similar content.
• Prevent duplicate tracks — Removes a track from its previous position in the queue when it's re-added.
• Auto skip on error — Automatically skips to the next song if a track fails to load.

Misc Settings

• Stop music on task clear — Stops playback when you swipe the app away from the recents screen.
• Pause when media is muted — Pauses playback when your device volume is muted.
• Resume on Bluetooth connect — Resumes music automatically when a Bluetooth device connects.
• Keep screen on when expanded — Keeps the screen awake while the player is in full-screen view.

Appearance

Access this from Settings > Appearance. This is one of the most detailed settings screens in the app, covering everything from the overall theme and colour palette to the player layout, lyrics styling, and navigation behaviour.

Theme

Vivi Music defaults to Material theming, which follows your device’s system-wide dark or light mode automatically. Tap Theme to customise it according to your preference — you can lock it to dark, lock it to light, or keep it on auto to follow the system. You can also enable a high refresh rate option that forces the display to run at the highest rate your device supports, such as 120Hz, for smoother animations throughout the app.

Mini-Player

This section controls the appearance and behaviour of the mini-player bar at the bottom of the screen.

• New mini player design — Switches to the updated mini-player layout with a refreshed visual style.
• Pure black mini-player — Forces a true #000000 black background on the mini-player bar. Ideal for AMOLED screens.
• Mini-player background style — Controls the visual treatment behind the mini-player. Options are:
  1. Follow theme
  2. Gradient, Blur
  3. Glow animated
  4. Live Mesh
  Live Mesh is the most visually dynamic option, generating an animated mesh background that reacts to the current song’s album art colours.
• Mini player swipe sensitivity — A slider to control how easily a swipe gesture on the mini-player registers. Adjust this if you find the mini-player expanding too easily or not easily enough.

Player

This section controls the full-screen player’s look and feel.

• New player design — Toggles the updated full-screen player design. When off, the old player layout is used.
• Show audio quality badge — Displays a small badge on the player indicating the current stream’s audio quality, such as High, Low, or Auto. Useful for quickly confirming which quality tier is being used for the currently playing track.
• Player background style — Controls the visual treatment behind the full-screen player. Available styles are:
  1. Follow theme
  2. Gradient
  3. Blur
  4. Glow animated
  5. Apple Music
  6. Live Mesh
• Hide player thumbnail — Replaces the album artwork in the full-screen player with the Vivi Music app logo.
• Thumbnail corner radius — Adjusts how rounded the corners of the album art thumbnail appear in the player. Measured in dp.
• Crop album art — Forces a square aspect ratio by cropping video thumbnails. Useful when YouTube video thumbnails appear with letterboxing in the player.
• Player button colors — Controls the colour applied to playback control buttons in the player. Options are Default, Primary color, and Tertiary color — each pulling from the current Material theme palette.
• Player slider style — Changes the visual shape of the seek bar in the player. Four styles are available:
  1. Default (standard thumb with track)
  2. Wavy (a fluid wave-shaped track)
  3. Slim (a thinner, minimalist bar)
  4. Squiggly (an animated squiggle that adds character to the seek bar)
• Enable swipe to change song — Allows swiping left or right on the album art in the full-screen player to skip to the previous or next track.
• Rotating thumbnail — Adds a slow spinning animation to the album art thumbnail while a song is playing.
• Show comment button — Shows a button in the player queue to view YouTube comments for the current track.

Canvas

Canvas replaces the static album artwork in the player with a looping animated video when one is available for the currently playing song. This is similar to Spotify Canvas. It is a visually impressive feature but does consume additional data, so consider disabling it if you are on a limited mobile data plan.

When Use canvas is enabled, you can choose a canvas source:

• Auto — Tries Apple Music first, then falls back to ViviMusic and Tidal. Picks the best available match automatically.
• Apple Music — Uses Apple Music’s animated visuals exclusively. Only shows a canvas if Apple Music has one for the playing song.
• ViviMusic — Uses the ViviMusic curated canvas library exclusively. Only shows a canvas if one has been added for the playing song.
• Tidal — Uses Tidal’s animated visuals exclusively. Only shows a canvas if Tidal has one for the playing song.

Lyrics

This section controls every visual aspect of the lyrics display in the full-screen player.

• Lyrics text position — Sets the horizontal alignment of lyrics text. Options include Left and Centre.
• Word-by-word animation style — Controls how individual words are highlighted as they are sung. Available styles are:
  1. None
  2. Fade
  3. Glow
  4. Slide
  5. Karaoke

  6. Apple Music
  7. Apple Music V2 (Letter by Letter)
  8. Vivimusic (Fluid)
  9. Lyrics V2 (Fluid)
  10. MetroLyrics

  Vivimusic (Fluid) is the default and produces a smooth flowing highlight that closely follows the vocal timing.

• Enable glowing lyrics effect — Adds a glowing animation and bounce effect to the currently active lyrics line.
• Apple Music lyrics blur — Applies a blur to inactive lyrics lines while keeping the current line sharp, mimicking the focus effect used in Apple Music’s lyrics view.
• Standard lyrics blur — An alternative blur mode for inactive lyrics lines. Similar to Apple Music lyrics blur but with a different intensity and transition style.
• Lyrics text size — Sets the font size of lyrics text in sp (scale-independent pixels).
• Lyrics line spacing — Controls the vertical gap between lyrics lines, expressed as a multiplier (e.g. 1.3x).
• Change lyrics on click — When enabled, tapping a lyrics line seeks the track to that timestamp.
• Auto scroll lyrics — Automatically keeps the current lyrics line centred on screen as the song progresses.
• Swipe to change song (lyrics view) — Allows swiping left or right on the artist and song name section in full-screen lyrics view to change the song.
• Show play/pause on thumbnail — Shows a play/pause button overlay on the song thumbnail in the full-screen lyrics view.

Misc

General navigation and layout options.

• Default open tab — Chooses which tab the app opens to on launch. Defaults to Home.
• Change default library chip — Sets which filter chip is selected by default when you open the Library tab.
• Swipe song to add to queue or play next — Enables swipe gestures on song rows in lists — swipe left to add to queue, swipe right to play next.
• Swipe song to remove from playlist — Enables a swipe gesture inside playlists to remove a song from that playlist.
• Slim bottom navigation bar — Reduces the height of the bottom navigation bar for a more compact look.
• Listen Together in top bar — Shows the Listen Together shortcut in the top app bar instead of in the bottom navigation bar.
• Grid cell size — Controls the size of items in grid-view screens like Albums and Artists.
• Display density — Scales the overall UI density as a percentage. Native (100%) matches your device’s default. Reducing this makes the interface more compact; increasing it makes elements larger.

Auto Playlists

Controls which automatically generated playlists appear in your Library. Toggle any of the following on or off to show or hide them: Liked, Downloaded, Top, Cached, and Uploaded.

Listen Together

Access from the main menu > Together. This feature lets you listen to music in real-time with friends. One person creates a room (host) and others join using a room code.

Creating a Room (Host)

• Open the Together screen from the main menu.
• Enter your username in the Username field.
• Tap Connect — a room code will be generated.
• Share the room code with your friends.

Joining a Room

• Open the Together screen.
• Enter your username and the room code you received.
• Tap Connect to join the session.

Listen Together Settings

Access from Settings > Together > Settings.

• Blocked users — View and manage users you have blocked from your rooms.
• Server URL — The sync server used for real-time listening. Defaults to Hugging Face Sync – Global.
• Username — Your display name shown to others in the room.
• Auto-approve join requests — Automatically lets people in without requiring manual approval.
• Sync host volume — Guests follow the host's volume level.
• Smart Network Resync — Automatically catches up with the host after a connection drop.
• View logs — Displays raw connection and message logs for debugging.

AI Lyrics Translation

Access from Settings > AI Lyrics Translation. This feature uses an AI model to translate song lyrics into your chosen language in real-time while you listen.

Choosing a Provider

The default provider is OpenRouter, which gives access to a wide range of AI models. Tap Provider to see available options and select one.

Setting Your API Key

To use AI lyrics translation, you need an API key from your chosen provider. Tap "API Key" and enter your key. Without a key, translation will not work.

Choosing a Model

The default model is google/gemini-2.5-flash-lite, which is fast and free-tier friendly. You can change this to any model available through your provider.

Translation Mode

Two modes are available — Translation converts lyrics to another language, while Transliteration converts the script (for example, converting Japanese lyrics to Roman letters while preserving the original pronunciation). Select whichever suits your needs.

Target Language

Choose the language you want lyrics translated into. The default is English (US).

Privacy & Storage

Privacy

Access from Settings > Privacy. Control what Vivi Music remembers about your listening habits.

• Listen History
  • Pause listen history — Stops recording the songs you play.
  • Clear listen history — Permanently deletes all recorded listening history.
• Search History
  • Pause search history — Stops saving your search queries.
  • Clear search history — Permanently deletes all saved search queries.
• Misc
  • Disable screenshot — Prevents screenshots and hides the app in the Recents screen when enabled.

Storage

Access from Settings > Storage. Manage how much space Vivi Music uses on your device.

• Downloads
  • Downloaded songs — Shows the total size of your offline downloads.
  • Clear all downloads — Deletes all downloaded songs from your device.
• Song Cache
  • Max song cache size — Limits how much space songs can use in the cache.
  • Clear song cache — Deletes cached songs to free up space.
• Image Cache
  • Max image cache size — Limits how much space album art and images can use.
  • Clear image cache — Deletes cached images to free up space.

Backup and Restore

Access from Settings > Backup and restore. Use this screen to protect your playlists and settings, or to migrate your data to a new device.

• Backup: Tap Backup to create a snapshot of your current library, liked songs, playlists, and settings. The backup file is saved to your device storage and can be shared or copied elsewhere.
• Restore: Tap Restore and select a previously created backup file to bring your data back. This will overwrite your current library and settings with the backup.

Import Playlists

Vivi Music supports importing playlists in two formats:

• Import a "m3u" playlist — standard format used by most music apps and players
• Import a "csv" playlist — spreadsheet-style format listing track details

headphones Chapter 3 — Using the App

This chapter covers day-to-day use: searching for music, managing your queue, and getting the most out of the player.

Searching and Browsing

Search

Tap the search icon to find songs, albums, artists, or playlists. Results pull from YouTube Music. Tap any result to play it immediately or long-press to get more options like adding to a playlist or downloading.

Home Screen

The home screen surfaces personalised recommendations, recently played items, and curated mixes based on your listening history. These update dynamically as you use the app.

Playback Controls

Mini Player

Whenever a song is playing, the mini player appears at the bottom of the screen. Tap it to expand to the full player view. From the mini player you can play/pause, skip to the next track, and like the current song.

Full Player

The full player shows the album art, track title, artist, and the full set of controls — seek bar, previous, play/pause, next, shuffle, and repeat. The overflow menu (three dots) gives access to additional actions like adding to a playlist, viewing the queue, and sleep timer.

Shuffle, Repeat, and Sleep Timer

• Shuffle — randomises your queue order
• Repeat one — loops the current song
• Repeat all — loops the full queue
• Sleep timer — stops playback after a set time (find this in the player overflow menu)

Playlists & Library

Create and Edit Playlists

Long-press any song and select "Add to playlist" to add it to an existing playlist or create a new one. Tap a playlist to open it, then use the edit button to rename, reorder, or remove songs.

Liked Songs and Followed Artists

Tap the heart icon on any song to like it. Liked songs appear in your Library. Tap Follow on an artist page to follow them and see their new releases on your home screen.

integration_instructions Chapter 5 — For Developers & Contributors

Vivi Music is open-source and welcomes contributions from the community. This chapter covers how to get involved.

Architecture Overview

Vivi Music is an Android app built in Kotlin. It uses a modular architecture with separate components for playback, UI, networking, and local storage. The app integrates with multiple streaming APIs and supports plugin-style integrations for Discord and Last.fm.

Tech Stack

• Language: Kotlin
• UI: Jetpack Compose
• Playback: ExoPlayer / Media3
• Networking: Ktor / Retrofit
• AI features: OpenRouter API
• Sync server: Hugging Face Spaces (Listen Together)

Contributing to Vivi Music

Code of Conduct

Be respectful, constructive, and patient. Contributions of all sizes are welcome — from fixing a typo to building a new feature.

Pull Request Process

1. Fork the repository on GitHub.
2. Create a new branch for your feature or fix.
3. Make your changes and test thoroughly.
4. Submit a pull request with a clear description of what changed and why.

Translation Guide

Want to help translate Vivi Music into your language? Translation files are located in the app's res/values/ directory. Submit translated strings as a pull request or contact the developer via Telegram.

Community & Links

• GitHub Repository — https://github.com/vivizzz007/vivi-music
• Telegram — t.me/vivimusicapp
• Website — https://vivimusic.mkmdevilmi.workers.dev/

handyman Chapter 6 — Troubleshooting

If something isn't working as expected, this chapter covers the most common issues and how to fix them. For anything not listed here, reach out via Telegram or GitHub Issues.

Migration Issues

If you are migrating from version 5.0.3, please clear app data before using the app, otherwise it will keep crashing.

Playback Issues

Music doesn't play

• Check your internet connection — switch between Wi-Fi and mobile data.
• Force stop the app and check.
• Go to Settings → Content → switch to IPv4 or IPv6 (make sure proxy is enabled).
• Clear app data and cache.

Songs Won't Load

• Check if the track is available in your region.
• Use a VPN.
• Force-stop the app and reopen it.

Login & Account Issues

Can't Sign In

Vivi Music uses Google sign-in. If you can't sign in, make sure your Google account is working by trying to sign in at google.com. If you use token login, go to Settings > Account > Tap to show token and verify your token is correct.

Account Not Syncing

• Go to Settings > Account and make sure "Auto sync with account" is enabled.
• Try logging out and logging back in.
• Check that you have a stable internet connection.

Download & Offline Issues

Download Stuck or Failed

• Check your available storage in Settings > Storage.
• Tap the download again to retry.
• Try clearing the song cache and downloading again.

Offline Songs Not Appearing

• Make sure Offline mode is not accidentally enabled — it hides undownloaded content.
• Go to Settings > Storage and check that Downloaded songs shows a size greater than 0 B.

App Crashes & Performance

App Freezing or Crashing

• Force-stop the app from Android Settings > Apps > Vivi Music.
• Clear the cache and data from the same screen.
• Reopen the app.
• If crashes persist, try uninstalling and reinstalling the app.
• Report the crash log in telegram group.

Reporting a Bug

Found a repeatable bug? Open an issue on the Vivi Music GitHub repository. Include your Android version, Vivi Music version (found in Settings > About), and a description of what happened and how to reproduce it.

Contact & Support

Need help or want to get involved? Reach out through any of these channels:

Tip: The Telegram community is usually the fastest way to get help.