Website · Download · Features · Build · Troubleshooting · Contribute · Legal

Important

ZenMusic is still in development. Features may change and you may run into bugs. Updates are delivered through GitHub Releases.

The Windows desktop version is available as an installer: core playback, search, browsing, lyrics, the queue, Spotify integration (login, playback, playlist import) and lossless quality streaming are working.

Tip

Future Updates - Coming in the next update:

• More themes and skins
• And many more things, very soon. Stay tuned!

Note

Regional availability - If YouTube Music or JioSaavn is unavailable in your region, that source may not work without a VPN or proxy connecting to a supported region.

Table of Contents

• About
• Screenshots
• Features
• Supported Platforms
• Download Now
• Installation Guide
• Building from Source
• Project Structure
• Configuration & Data
• Troubleshooting
• FAQ
• Roadmap
• Contributing
• Support the Project
• Special Thanks
• Contributors
• Legal

About

ZenMusic is a Flutter-based music player that brings several streaming sources into one clean, fast interface. It pulls from JioSaavn, YouTube Music and Spotify, and wraps them in a polished player with synced lyrics, offline downloads, multiple player skins, and a Listen Together mode for syncing playback with friends.

It runs on Android (phone and tablet) and Windows (a full desktop experience with its own Spotify engine and a responsive layout).

Design goals

• One app, many sources: search and play across providers without switching apps.
• Great playback UX: gapless-feeling queue, sleep timer, equalizer, and lyrics that follow the song.
• Make it yours: player skins, slider styles, thumbnail radius, lyric layout and more.
• Open and hackable: GPL-3.0, with an extension system for adding sources.

Playback Multi-source streaming: JioSaavn (320 kbps AAC), YouTube Music, and Spotify Spotify login with your own account Offline downloads	Audio Lossless streaming (FLAC / Hi-Res) for YouTube Music and JioSaavn songs System equalizer Widevine DRM (Spotify)
Lyrics & Discovery Time-synced lyrics (LRCLIB) Adjustable lyric size, spacing and alignment Song recognition: identify music playing around you	Library Import playlists from Spotify Download and manage songs offline
Social Listen Together: create a room, share the code, and listen in sync Host controls playback for everyone	Interface 8 custom player skins: Classic, Turntable, Editorial, Lyrics, Polaroid, Tabletop Radio, Studio, Ring 22 progress slider styles (Wavy, RGB Glow, Equalizer, Neon, Orbit, DNA Helix and more) OTA update checks via GitHub Releases
Platforms Android: full experience (phone and tablet) Windows: full desktop experience with a custom Spotify engine, responsive UI, and an installer

Feature details

Sources

Source	Quality	Notes
JioSaavn	Up to 320 kbps AAC	May require a VPN/proxy outside supported regions
YouTube Music	Stream-dependent	Stream extraction via Innertube; login support planned
Spotify	Web Player protocol	Uses Widevine DRM; custom engine on Windows. Sign in with your Spotify account for playback and playlist import

Extra sources can be added through the extension system.

Lossless streaming

YouTube Music and JioSaavn songs can be upgraded to true lossless audio from Settings → Song quality: MP3 320, FLAC CD (16-bit / 44.1 kHz), Hi-Res Lossless (24-bit / 96 kHz) and Hi-Res Max (24-bit / 192 kHz). The tier ladder walks down, never up — the selected tier is the ceiling. If a song (or the service) can't provide the selected tier, playback silently continues through the lower tiers and then the normal stream, so it never breaks or stalls. YouTube videos keep their original audio, and the setting lives in its own page with live previews of each tier.

Lyrics

• Time-synced lyrics are fetched from LRCLIB.
• Customize font size, line spacing and alignment to taste.
• Lyrics scroll in sync with playback and can be shown alongside the player.

Listen Together

1. One person creates a room and becomes the host.
2. They share the room code.
3. Everyone who joins hears the same track in sync.
4. The host controls play, pause, seek and track changes for the whole room.

Offline downloads

Download songs for offline playback and manage them from your library. Downloaded tracks play without a network connection.

Song recognition

Tap the recognition button to identify music playing around you. It uses a fingerprinting flow based on the Shazam discovery API.

Player skins & appearance

Pick between eight player skins: Classic, Turntable, Editorial, Lyrics, Polaroid, Tabletop Radio, Studio and Ring — from a spinning record with a tonearm that follows the song, to a tabletop radio with a tuning dial, to a studio console with faders. Combine them with 22 progress-slider styles (Wavy, RGB Glow, Pill, Segments, Equalizer, Neon, Orbit, Heartbeat, DNA Helix, Comet and more), adjustable thumbnail radius and optional haptics. Ambient mode switches to a landscape player with an animated glow derived from the album art.

Supported Platforms

Platform	Status	Notes
Android (phone & tablet)	Full experience	APKs via GitHub Releases and Obtainium
Windows 10/11 (x64)	Full desktop experience	Installer (.exe), custom Spotify engine, responsive UI
iOS / macOS / Linux	Not supported	Not currently a build target

Stable Release

Obtainium (Android)	GitHub (Android)

Windows (Desktop)

Download Installer
Download the .exe installer from the latest Release.

Nightly Build

GitHub

Warning

Nightly builds are automatically generated and may be unstable. Use the stable release unless you want the newest changes and can tolerate bugs.

Installation Guide

Android

1. Open the latest release on your phone.
2. Download the APK that matches your device. If unsure, use the universal APK; otherwise pick your ABI (usually arm64-v8a).
3. Open the file and allow Install unknown apps for your browser or file manager when prompted.
4. Launch ZenMusic.

Tip: Add the repository to Obtainium using the badge above to get automatic update notifications.

Windows

1. Download the .exe installer from the latest release.
2. Run the installer and follow the prompts.
3. If Windows SmartScreen warns about an unrecognized app, choose More info → Run anyway.
4. Launch ZenMusic from the Start menu.

ZenMusic targets Android and Windows.

Prerequisites

Requirement	Android	Windows
Flutter SDK (stable channel)	✅	✅
Git	✅	✅
Android Studio / Android SDK	✅
Visual Studio 2022 with Desktop development with C++		✅
Windows Developer Mode (required for plugin symlinks)		✅
Inno Setup (only to build the installer)		✅

Run flutter doctor -v and make sure there are no errors for your target platform before building.

Android

git clone https://github.com/vorlon-dev/Zen-music.git
cd Zen-music
flutter pub get
flutter run                  # with a connected Android device or emulator

Release APKs (what the download badges serve):

flutter build apk --release --split-per-abi   # per-ABI splits
flutter build apk --release                   # universal APK

Windows (desktop)

The desktop app uses its own entrypoint, so always pass -t lib/desktop/main.dart.

1. Enable Developer Mode (Flutter needs it to create plugin symlinks):

   start ms-settings:developers

2. Clone and run:

   git clone https://github.com/vorlon-dev/Zen-music.git
   cd Zen-music
   flutter pub get
   flutter run -d windows -t lib/desktop/main.dart            # dev run
   flutter build windows --release -t lib/desktop/main.dart   # release exe

The release output is written to build\windows\x64\runner\Release\.

Building the Windows installer

Install Inno Setup, build the release exe as above, then compile the installer script:

iscc windows\installer.iss

(Or open windows/installer.iss in the Inno Setup IDE and press Compile.)

Blank player screen on older GPUs

On some GPUs (older iGPUs without Vulkan), Flutter's Impeller GL backend can render custom-painted screens blank. If the player screen appears white, run development builds with:

flutter run -d windows --no-enable-impeller -t lib/desktop/main.dart

Project Structure

A high-level overview of the parts you are most likely to touch:

Zen-music/
├── lib/
│   ├── main.dart            # Android / mobile entrypoint
│   └── desktop/
│       └── main.dart        # Windows desktop entrypoint (use with -t)
├── android/                 # Android host project
├── windows/                 # Windows host project
│   └── installer.iss        # Inno Setup installer script
├── assets/                  # Banners, badges, icons used by the app and README
├── screenshots/             # Images used in this README
└── pubspec.yaml             # Dependencies and asset declarations

The tree above is a simplified overview. See the repository for the full layout.

Configuration & Data

• Updates: the app checks GitHub Releases for new versions (OTA update checks).
• Song quality: lossless tiers (MP3 320, FLAC CD, Hi-Res 96, Hi-Res Max) are selectable in Settings → Song quality; playback falls back automatically when a tier is unavailable.
• Downloads: offline songs are stored locally on the device and can be managed from the Library.
• Lyrics: fetched on demand from LRCLIB.
• Accounts: Spotify uses the Web Player protocol with Widevine DRM — sign in with your own account for playback and playlist import. YouTube Music login is planned for an upcoming update.
• Regional access: some sources are region-locked. Use a VPN or proxy if a source is unavailable where you live.

Troubleshooting

Windows build fails: Cannot open include file 'flutter_inappwebview_windows_fx_plugin.h'

This means the compiler cannot find the plugin's own header. It is usually a broken plugin symlink or a stale build cache.

1. Enable Developer Mode (start ms-settings:developers) and reopen your terminal.

2. Do a full clean and regenerate the plugin links:

   flutter clean
   Remove-Item -Recurse -Force windows\flutter\ephemeral -ErrorAction SilentlyContinue
   Remove-Item -Recurse -Force build -ErrorAction SilentlyContinue
   flutter pub get
   flutter run -d windows --no-enable-impeller -t lib/desktop/main.dart

3. Verify the header exists in the package:

   dir windows\flutter\ephemeral\.plugin_symlinks\flutter_inappwebview_windows_fx\windows\include -Recurse

4. If the project and the Pub cache (%LOCALAPPDATA%\Pub\Cache) are on different drives, symlinks can break. Move the project to the same drive, or point PUB_CACHE to a folder on the project's drive.

5. If the header is genuinely missing from the package, pin a different version of the plugin in pubspec.yaml and run flutter pub get again.

Player screen is blank or white on Windows

Run with Impeller disabled:

flutter run -d windows --no-enable-impeller -t lib/desktop/main.dart

The app builds but shows the wrong (mobile) UI on Windows

You forgot the desktop entrypoint. Always pass -t lib/desktop/main.dart for Windows runs and builds.

A source (YouTube Music / JioSaavn) returns no results

The source may be unavailable in your region. Connect through a VPN or proxy in a supported region and try again.

Spotify tracks will not play

Spotify playback relies on Widevine DRM. Make sure you are signed in with your own Spotify account, are on a supported build (Android or the Windows installer), and that your network is not blocking DRM license requests.

Android install is blocked

Allow Install unknown apps for the app you used to download the APK (browser or file manager) in Android settings.

flutter doctor reports Visual Studio problems

Open the Visual Studio Installer and make sure the Desktop development with C++ workload is installed, including the Windows 10/11 SDK and CMake tools.

FAQ

Is ZenMusic free? Yes. It is open source under GPL-3.0.

Does it work on iOS, macOS or Linux? Not at the moment. Android and Windows are the supported targets.

Does ZenMusic host music? No. It acts as a client for publicly available APIs. All content is served by the respective platforms.

Do I need a Spotify account? Spotify login, playback and playlist import require signing in with your own account. Other sources work without one.

How do I get updates? The app checks GitHub Releases for updates. Android users can also use Obtainium.

Can I add my own sources? Yes. ZenMusic supports source extensions.

Roadmap

• More themes and skins
• YouTube Music login
• Lossless streaming (FLAC / Hi-Res)
• Spotify login and playlist import
• Windows desktop app with installer
• Listen Together
• Time-synced lyrics
• Offline downloads
• Song recognition

Contributions are welcome!

How to contribute

1. Fork the repository.

2. Create a branch for your change:

   git checkout -b feature/my-feature

3. Make your changes and commit with a clear message.

4. Push to your fork and open a Pull Request describing what changed and why.

Guidelines

• Keep pull requests focused on a single change.
• Test on a real device before submitting (and on Windows if you touched desktop code).
• Run flutter analyze and fix warnings in the files you changed.
• Match the existing code style and naming.
• When reporting a bug, include your platform, app version, steps to reproduce, and logs or screenshots if possible.

Credits for the BitChord-derived features

The extra lyric providers (lrc.red, BiniLyrics, PaxSenix, LyricsPlus, Unison, Musixmatch, Megalobiz, Genius), the multi-source lyric ordering and the two-deck crossfade / Automix design follow BitChord by kushagrasinghx (GPL-3.0), reimplemented in Dart. The lyric data itself comes from those services; thanks to BetterLyrics, binimum (BiniLyrics, am-lyrics), PaxSenix, LyricsPlus, Unison (boidu.dev), Megalobiz, KuGou, LRCLIB, Musixmatch and Genius. Automix here is tempo-matched using a tempo lookup; BitChord's on-device beat tracker (ONNX + native analysis) is not ported.

Support the Project

ZenMusic is free and open source, and it is built in spare time. If you enjoy it and want to help keep it improving, you can buy me a chai. It is completely optional, and starring the repo or sharing the app helps just as much.

ZenMusic stands on the shoulders of incredible open-source work.

Main Inspirations

Project	Contribution
Echo music	basis of the Windows desktop shell
Stopify	Spotify Web Player protocol reverse-engineering and Widevine integration
Metrolist / metroserver	Listen Together server protocol and deployment
Musify	Streaming and app architecture reference

Libraries & Integrations

Project	Contribution
youtube_explode_dart / Innertube	YouTube stream extraction
audio_service / just_audio / media_kit	Playback engine (Android / Windows)
flutter_lyric	Lyrics rendering
LRCLIB	Synced lyrics provider

We also thank the entire open-source community, for every library, tool, and API that powers this project.

This project wouldn't exist without these amazing people!

⚠️ Disclaimer & Legal Notice

ZenMusic is created strictly for educational and research purposes only.

• No Affiliation: This application is not affiliated with, authorized, endorsed by, or in any way officially connected with YouTube, Google LLC, JioSaavn, Spotify, or any of their subsidiaries or affiliates. All product names, logos, and brands are property of their respective owners.
• No Hosting or Storage: We do not host, upload, distribute, or store any audio, video, or copyrighted media files on our servers. The app acts strictly as a client that accesses publicly available APIs. All content is served directly by the respective platforms.
• User Responsibility: By using this software, you agree that you are solely responsible for your actions. The developers of ZenMusic are not responsible for any misuse, copyright infringement, or Terms of Service violations committed by the end user.
• "AS IS" Warranty: This software is provided "AS IS", without warranty of any kind, express or implied. The developers hold no liability for any legal issues, damages, or data loss that may arise from using this software.

If you do not agree with these terms, please do not download or use the application.

License

Licensed under GPL-3.0. See the LICENSE file for details.

Made with ❤️ by vorlon-dev