Groove is a PyQt5 desktop player for local files and music videos

Local files first, with a video and metadata layer on top

Groove Music is a cross-platform music player based on PyQt5, and the feature list is short enough to read at a glance. It plays local music, it lets you create and manage custom playlists, it lets you view and edit song metadata, and it watches and downloads music videos. That last one is the feature that marks it as a Chinese-market application, since the MV concept, a short music video attached to a track, comes from that ecosystem. The rest is a conventional local music player, and the value it offers over a system player is the combination: a playlist manager, a metadata editor and a video window in one PyQt application rather than three separate tools. The documentation lives on readthedocs, and the repository carries a Groove.pro project file alongside the app/ directory, a docs/ tree, requirements.txt and a tests/ directory, so it is laid out like a real application rather than a script collection.

The decoder is the part you install yourself

The quick start has three steps, and the middle one is the one people miss. You create a virtual environment, you install the decoder, and then you run the application. For Windows the decoder is LAV Filters, and the README links a specific installer release of it, version 0.74. For Linux it is GStreamer. Neither is bundled. That is a deliberate split, since a PyQt application that ships a media decoder stack on three platforms is a packaging nightmare, and asking the user to install the platform-native codec set is the normal approach on desktop. The cost is that the first run of a fresh machine has a step that fails with no output if it is skipped, which is the sort of thing that gets filed as a bug against the player rather than against the missing dependency. The features around the decoder are still documented, so the local music playback, the playlist management, the metadata editing and the MV viewing and downloading all sit on top of whatever the system provides.

Setting up the environment and launching the app

The environment step uses conda rather than a plain virtual environment, and the commands are short.

    conda create -n Groove python=3.8
    conda activate Groove
    pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

The Python version is pinned to 3.8 by the example and by the badge, and the PyQt version in the requirements is 5.15.2. The pip invocation points at the Tsinghua University mirror, which is a practical choice for users in China and a hint at who the project is for. Running the player is a directory change and a script.

    cd app
    conda activate Groove
    python Groove.py

The entry point is a single script in the app/ directory rather than an installed console entry point, which confirms that this is a source-run project. The repository also contains a Groove.pro file, which is the Qt Creator project file, another sign that the intended workflow is opening the source in that IDE.

A dependency set pinned to 2020

The requirements file is the clearest statement of the project's vintage, and it is worth reading before you plan to install anything. The pins are exact, not ranges. numpy is at 1.19.5, scipy at 1.5.2, opencv-python at 4.5.3.56, Pillow at 8.1.0 and PyQt5 at 5.15.2 with PyQt5-sip at 12.8.1. Those versions belong to the 2020 releases of each library, and several of them will not build against a modern Python, which is exactly why the documented environment is 3.8 rather than whatever is current. The rest of the list is more varied in purpose. mutagen at 1.45.1 and tinytag at 1.7.0 are the metadata readers, which is what makes the metadata editing feature work. colorthief pulls the dominant colour out of an image, fuzzywuzzy does the fuzzy matching, and pinyin and pycryptodome point at the Chinese-market specifics, with pinyin for search and pycryptodome for the cryptographic work that the online features need. Platform specifics are handled with environment markers, with pywin32 and pyqtkeybind on Windows only, xcffib on Linux, and pyobjc with PyCocoa on macOS. Sphinx and the readthedocs theme are included because the documentation site is built from this same repository.

A family of related PyQt projects

The README points at three neighbouring projects, and together they describe the ecosystem this player sits in. PyQt-Frameless-Window is a cross-platform frameless window based on pyqt5 supporting Win32, Linux and macOS, which is the layer that lets a desktop application like a music player draw its own title bar instead of the system one. PyQt-Fluent-Widgets is a fluent design widget library based on PyQt5, which is where the visual language of the interface comes from. The third is egg-player, described as a Groove Music like music player whose code is very elegant, and the compliment is a real one because it points at an alternative implementation of the same idea. Taken together, these links say something about the design approach. The player is assembled from general purpose PyQt components rather than written as a monolith, which is why the codebase stays small enough to read, and why a fork that wanted a different look could swap the widget layer without touching the playback logic.

The licence limits commercial use, and the last release is a year old

Two things to settle before you build on this. The first is the licence, and it is not the standard GPL. The README states that Groove is licensed under GPLv3 for non-commercial usage, with copyright 2020 by zhiyiYo, and the repository carries a LICENSE file. The project is filed under GPL-3.0, so the non-commercial restriction is an addition on top of the GPL text rather than a replacement for it. That is a meaningful constraint for a piece of software that looks like a general purpose desktop player, and it is a question for your own legal review rather than something this article can settle. The second is the maintenance record. The only tagged release is v1.3.7 from 2025-02-22, and the last push to the repository was on 2026-05-05, so the code has moved since that release without a new tag. There is also a notice attached to the licence section saying the software is for learning and communication and that the copyright of the songs and playlists belongs to each music platform, which is a reminder that the MV and online features in this player depend on other people's content and services. The topic tags on the repository, desktop-lyric, local-music, lyrics, music-player, online-music, online-mv, pyqt, python, qt and song-metadata, describe a project that started as a personal player and grew into a broader music client.

Editorial conclusion

Adopt Groove if you want a small desktop music player you can run from source on Windows, Linux or macOS and are happy to install a system decoder, and if your use of it is non-commercial, because the licence restricts use that way. Skip it if you need a player you can ship inside a product or redistribute, since the licence is GPLv3 for non-commercial usage, and skip it if you want a maintained music library with a regular release trail, because the only tagged release is v1.3.7 from 2025-02-22 and the last push was on 2026-05-05. Before you install, read the requirements file, since the pinned numpy, scipy, opencv and Pillow versions are from 2020 and will need a Python 3.8 environment to install cleanly.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. zhiyiYo/Groove on GitHub