ytmdesktop2: YouTube Music on the desktop, with lyrics, scrobbling and OBS overlays

An unofficial client, and the project says so in the description

ytmdesktop2 is described as an unofficial YouTube Music desktop app, and the package description is explicit that it is for Windows, Mac and Linux. The homepage is youtube-music.app.

The technical shape is the familiar one for a modern desktop wrapper: the topics list Electron, React, TypeScript, Node and tRPC, so the interface is a web application hosted in an Electron shell, and the data between the front end and the back end runs over tRPC rather than ad hoc HTTP calls.

The README opens with a note from the author about the project reaching a thousand stars, and says it was never imagined that a personal project for their own use would become that large. The same note records that v1.0 has been released with completely rewritten services and an updated interface, which is the kind of detail that tells you the early architecture is gone.

The credits are worth reading because they explain the feature list. The author says ytmdesktop and the th-ch and Pear Desktop projects inspired much of the work, in ideas and approaches, and that the project exists in the wider desktop YouTube Music space. Last.fm, Better Lyrics and LRCLIB are credited the same way, and those three names map directly onto the three most distinctive features.

The licence is CC0-1.0, the public domain dedication, which is an unusual choice for an application and is worth a note if you intend to reuse the code.

The features that go beyond a wrapped web player

A web player in an Electron window is easy to build and adds little. The interesting part of ytmdesktop2 is the list of things that a browser tab cannot do well.

Last.fm scrobbling and Now Playing updates while you listen. A tray view, described as a compact now-playing popup from the system tray. Timed lyrics in the player, with the sources named as Better Lyrics, Unison and LRCLIB, and the screenshot labelled as synced lyrics. Discord rich presence showing the current track. Themes, either bundled or custom SCSS and CSS for the YouTube Music interface. Shared links through a custom `ytmd://` scheme, which also works by swapping `https://` on music.youtube.com URLs, and which opens tracks, playlists and channels in the app.

There is also a Stream Deck integration, which is the least obvious of the set. The setup is three steps: enable the API and require authorization, install the Stream Deck plugin from a release tag in the repository, and then authorize from a YTMDesktop2 action. That is a different shape from a passive integration, because it requires the desktop app to expose an API and the plugin to be authorized against it.

The documentation for these features lives in the repository rather than only on the website, in the `apps/docs/content/docs/features` directory, and the README links it directly.

The OBS overlay is a local web server, and that has consequences

The OBS integration is the feature with a visible architecture. The app can serve first-party now-playing browser sources, and the instructions are to enable the API, open Settings, then OBS, and copy a URL into an OBS Browser Source.

The URL it gives is:

http://127.0.0.1:13091/embed/now-playing

So the overlay is not a screen share or a plugin. The desktop app runs a local HTTP server on port 13091 and serves a page that OBS fetches as a browser source. The port is the documented default, and the host is the loopback address, which means the server is only reachable from the same machine.

That design has two consequences. It works with OBS on another machine only if the loopback binding is changed, which the documentation does not describe, so the overlay is a same-machine feature. And OBS polls a local page, so the app has to be running and the API enabled for the overlay to update, which is why the instruction to enable the API comes before the URL.

The port also means the app binds a local port by default, which is worth checking against whatever else is running on the machine before you enable it.

A pnpm monorepo with the app and the Stream Deck plugin split out

The project setup is documented in a handful of lines, and the structure is the important part.

It is a monorepo using pnpm. The application lives in `apps/ytmdesktop2` and the Stream Deck plugin in `packages/streamdeck`. The build commands are:

# gh required for github packages (Venipa/xosms)
gh auth refresh -s read:packages
pnpm install
pnpm dev

The first line is the detail that will stop you if you skip it. One of the dependencies, `Venipa/xosms`, is published as a GitHub package rather than to a public registry, so the GitHub CLI has to be authenticated with read access to packages before `pnpm install` can resolve it. That is a deliberate publishing decision, and it makes the install step depend on a GitHub account with access to that namespace.

The repository root holds the workspace configuration, `pnpm-workspace.yaml` and `pnpm-lock.yaml`, plus `biome.json` for linting and formatting, `knip.json` for unused dependency detection, `lefthook.yml` for git hooks, `vitest.config.mts` for the test runner, and a `manifests/` directory. The `apps/` directory also holds the documentation site, since the feature screenshots live under `apps/docs/public/images`.

Every root script delegates to a filtered workspace command, for example `pnpm --filter ytmdesktop2 dev`, which is a clean way to keep a monorepo's entry points uniform.

A release script per platform, and release candidates in the tag list

The root `package.json` shows how wide the packaging matrix is. There are separate build commands for Windows, for Mac and for Linux, and the Linux line has three variants: `release:pack:linux:core`, `release:pack:linux:arm` and `release:pack:linux:flatpak`. The release flow is also split into stages, with `release:compile`, `release:pack` and `release:nocheck` as separate commands, and a `build:unpack` step for working with the unpacked application.

That is a lot of surface for a desktop app, and it reflects the reality of shipping one: the packaging for a Flatpak, a Flatpak for arm, a Windows installer and a Mac build are genuinely different problems, and a single command would hide which one broke.

The release tags show how the project ships in practice. The three most recent are v1.8.3-rc.0, a small fix regarding hybrid dGPU, from 2026-10-13, v1.8.2-rc.3, a fix regarding networkManager instance usage, from 2026-10-05, and v1.8.2-rc.2, with lyrics updated, from 2026-09-21. Every one of them is a release candidate, and the descriptions are short bug fixes rather than features.

So the current state of the project is a release candidate line with a patch-level focus, which tells you the maintainer is stabilising a release rather than shipping new functionality. The last push was on 2026-10-15, two days after the newest tag.

Where ytmdesktop2 is the wrong choice

The first wrong case is an environment that does not permit an unofficial client. The application re-implements the YouTube Music web experience outside the browser, and the licence of the service and the behaviour of its web app are not the project's to control. An organisation that blocks unapproved front ends, or that requires a vendor agreement, will not accept this, and that is a policy decision rather than a technical one.

The second is a need for offline playback. The client is a front end for a streaming service, and none of the features described in the README address local files or offline listening. A music player that plays your own library is a different application.

The third is a production streaming setup where the overlay must be reliable. The OBS overlay depends on a local server on a fixed port, on the API being enabled, and on OBS polling a page that the app serves. That is three moving parts, and the release candidates suggest the surrounding code is still being adjusted.

The fourth is a team that needs the code as a starting point. The repository is licensed CC0-1.0, the public domain dedication, which is unusual for an application of this size and means there is no warranty or attribution obligation to inherit, but it also means you are taking on the code as-is with no upstream support commitment beyond a personal project maintained in the author's spare time.

The fifth is a platform outside the release matrix. The packaging covers Windows, Mac, Linux for x64, Linux for arm and a Flatpak. Anything else has to be built from source.

Editorial conclusion

Adopt ytmdesktop2 if you want a dedicated desktop YouTube Music player with a system tray popup, synced lyrics, scrobbling to Last.fm and now-playing overlays for streaming, and you are comfortable with an unofficial client that follows the web app. Do not adopt it for a locked-down environment where an unofficial front end is not permitted, or if you need a guaranteed contract from Google. Before you install, check the release channel you want, since the recent tags are release candidates, and note that enabling the OBS overlay and the Stream Deck plugin both require turning on an API and authorizing it.

Frequently asked questions

Official sources

1. License: CC0-1.0
2. Project website
3. README
4. Releases
5. Venipa/ytmdesktop2 on GitHub