sohaibdevv/youtube-music: a portable Windows client for ad-free YouTube Music

The problem: YouTube Music in a browser tab

The browser is a competent music player until you close the tab. Background playback, media key handling and a persistent queue are exactly the things a tab does badly, and on the desktop the alternatives are a paid subscription or a wrapper that ships a full installer and leaves registry entries behind. This project aims at that gap: a client that streams from YouTube Music, keeps playing when minimized, and claims no install, no registry, no leftovers.

The audience is narrow and clearly implied by the distribution format. The README's download section offers a ZIP and a single EXE, and the feature table lists Windows-oriented conveniences: media keys, a dark theme, local playlists. There is no macOS or Linux artifact described, and the repository's own packaging config is named electron-builder.yml, which is the standard Electron packaging file. If you are on Linux and want this category of tool, the README gives you nothing to work with.

What the repository layout says about the build

The top-level entries are a conventional Electron and Vite project: src/, web/, tests/, vite-plugins/, electron.vite.config.mts, electron-builder.yml, tsconfig.json and a pnpm lockfile with pnpm-workspace.yaml. That is a real toolchain, not a repackaged binary drop. The presence of tests/ and a .devcontainer/ directory suggests the maintainers at least intend the project to be buildable in a container.

The package.json is where the picture gets confusing. Its name field is youtube-music, but its repository field points at pear-devs/pear-desktop, the author is listed as th-ch, and the description reads "YouTube Music Desktop App - including custom plugins". The version in package.json is 3.12.0, while the most recent release listed for this repository is v1.0.0, published on 2026-08-11. That mismatch is not explained anywhere in the README. It could mean the package.json was inherited from an upstream project and never rewritten, or that this repository is a fork whose metadata has drifted. Either way, anyone reading package.json to understand what they are installing will be misled about the project's identity. Treat the repository name and the release tag as authoritative, and treat the package metadata as inherited and stale.

How it streams: a browser engine behind an Electron shell

The disclaimer is the most informative paragraph in the README, and it is easy to skim past. It states the client streams audio like a browser, with no downloading and no DRM bypass. Combined with the Electron layout (main entry ./dist/main/index.js, a separate renderer under web/), the mechanism is a Chromium instance loading YouTube Music's web player, with the shell adding the parts a browser tab will not: a persistent window that survives minimize, media key bindings, and a local playlist store that the README describes as free of tracking.

This has a direct consequence. Because playback is a browser session against YouTube's own player, the client inherits whatever the web player does. The README does not claim to intercept, remux or cache audio, and it explicitly disclaims downloading. So the ad-free behaviour is a property of the wrapper, not of a modified media pipeline, and it depends on the web player's current behaviour continuing to work. The README does not describe a fallback for when it stops working.

Installing the portable build and playing a first track

There is no source build documented in the README. The only instructions are the four numbered steps under "How to use", which point at a release asset. The README states the archive is named youtube-music-free.zip and that it is password protected with the password ytm4all, which is printed in the same section.

The README's own steps are: download the ZIP, unzip with password ytm4all, run youtube-music-free.exe, then search and play. Those are the only commands the README gives, so there is no command line to reproduce here beyond naming the archive and the executable.

After extraction, the README says to run the executable directly. There is no installer step and no registry write according to the README.

What you should see is the application window shown in the README screenshot, with a search field. Searching for a track name, selecting a result and pressing play is the entire first-run flow the README documents. Background playback is then a matter of minimizing the window: the feature table states music keeps playing when minimized, and the media keys section lists Play/Pause, Next and Previous.

For anyone who wants to build from source instead, the README is silent. The repository does contain scripts, and package.json lists dev, build and dist entries driven by electron-vite and electron-builder, but the README never references them, and the package name in that file does not match this repository. Do not assume the documented release flow and the source tree produce the same artifact.

The password-protected ZIP is a real adoption cost

Publishing a Windows executable inside an encrypted archive, with the password in the same README, is a distribution choice worth naming plainly. It does not add security, since any reader has the password. What it does do is break automated download and extraction, and it defeats the casual inspection that a plain ZIP would allow, because the file listing is not visible until the password is supplied. The README does not explain why the archive is encrypted.

There is a second, larger limitation. The README's disclaimer says the project is not affiliated with Google and that all rights belong to owners. Nothing in the README states what happens when the underlying web player changes, and no update mechanism is described beyond pointing at the releases page. A portable executable with no documented updater means the user is responsible for checking releases manually. The README does not document rollback, and it does not describe how to pin or revert to a previous release if a new build breaks playback.

The maintenance picture is current rather than abandoned: the last push to the default branch was on 2026-08-11, the same day as the v1.0.0 release. But a single release and a README with no build, update or troubleshooting sections is thin ground for anything you depend on daily.

How this differs from building your own Electron wrapper

The obvious alternative is writing your own Electron shell around the YouTube Music web player. That is not a hypothetical: the project's own package.json carries the identity of pear-desktop, an existing YouTube Music desktop app with a plugin system, which is the more mature shape of the same idea. The difference in approach matters. A general-purpose desktop app of that kind exposes plugins and configuration, so behaviour is adjustable and the project documents its own build. This repository instead ships a fixed, portable artifact with a deliberately small feature list and no plugin surface described in the README.

The trade is predictability for control. A wrapper you build yourself will follow the web player wherever it goes, because you own the update loop; you also own the breakage. A portable EXE with no documented update path gives you a fixed artifact that will not silently change under you, at the cost of having to notice releases yourself. If you want the plugin surface, this project does not offer it. If you want a single file you can drop on a machine and run, the plugin-oriented alternative is heavier than the problem you are solving.

Licence and what it does not cover

The repository is MIT licensed, and package.json also declares MIT. That covers the code in the repository. It does not cover the audio, and the README is explicit on this point: the project is not affiliated with Google and all rights belong to the owners. Streaming audio through a client is a different act from redistributing it, and the README's own framing is that the client behaves like a browser. This is not legal advice; it is a statement of what the licence text in the repository does and does not say.

One practical consequence of MIT here: because the licence permits redistribution, a modified build of this client could circulate under the same name, and the README's password-in-public model gives you no way to tell an official archive from a rebuilt one. The only provenance signal available is the release page on the repository itself.

Editorial conclusion

This suits Windows users who want a portable, no-install way to stream YouTube Music without ads and are comfortable running an unsigned executable from a ZIP whose password is published in the README. It does not suit anyone who needs source-build instructions, a reproducible toolchain, macOS or Linux builds, or a documented update path, because the README describes none of those. Verify first that the release page actually contains youtube-music-free.zip and that the extracted youtube-music-free.exe runs on your machine before you rely on it for daily listening.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sohaibdevv/youtube-music on GitHub