Clementine
Clementine is a modern music player and library organizer for Windows, Linux and macOS.
Opening an issue
Ask for a new feature
Please:
- Check if the new feature is not already implemented (Changelog)
- Check if another person didn't already open an issue
- If there is already an opened issue there is no need to comment "+1", it won't help. Instead, you can subscribe to the issue to be notified of anything new about it
Report a bug
Please:
- Try the latest build (https://github.com/clementine-player/Clementine/releases) to see if any bug is still present. If it works fine even though you see an open issue, please comment on it and explain that the issue has been fixed.
- Check if another person has already opened the same issue to avoid duplicates
- If there already is an open issue you could comment on it to add detail about the problem or confirm it
- In case there isn't, you can open a new issue with an explicit title and as much information as possible (OS, Clementine version, how to reproduce the problem...)
- Please use https://pastebin.com/ for logs/debug.
If there are no answers, it doesn't mean we don't care about your feature request/bug. It just means we can't reproduce the bug or haven't had time to implement it :o)
Compiling from source
Get the code (if you haven't already):
git clone https://github.com/clementine-player/Clementine.git && cd Clementine
Compile and install:
cd bin
cmake ..
make -j$(nproc)
sudo make install
See the Wiki for more instructions and a list of dependencies:
https://github.com/clementine-player/Clementine/wiki#compiling-and-installing-clementine
Formatting your changes
CI checks that C++ code under src/ is formatted with clang-format 23.1.0.
Other versions format some code differently, so install that exact version
with uv (or pipx), which puts it on your PATH:
uv tool install clang-format==23.1.0
If uv warns that its tool directory isn't on your PATH, run
uv tool update-shell and open a new terminal.
Then reformat the files you've changed since origin/master:
dist/format.py -i
Claude Code does this automatically after each edit, using a hook in
.claude/settings.json.
Python tools
The Python in this repository, the tools in tools/ and the release scripts
in dist/, is one uv project: pyproject.toml
and uv.lock here at the top. Run everything through uv, from anywhere in the
repository, and it uses the locked versions:
uv run clementine-remote --help # tools/remote-cli
uv run clementine-apt --help # tools/apt-repo
uv run clementine-mac-update --help # tools/mac-update
From here, as CI's Python job does, check them all with the versions of ruff
and ty pinned in pyproject.toml:
uv run python -m clementine_remote.proto # ty needs the remote's protobuf module
uv run ruff check
uv run ruff format --check
uv run ty check
uv run pytest
A new tool goes in tools/<name>/src/<package>, added to the wheel's
packages, with its command under [project.scripts] and its dependencies
with the rest.
Release notes
If your change is something users will notice, end its commit message with a
Release-note: trailer: one line, written for users (what's new, not how it
was done):
Show the song's lyrics in time with the song
Release-note: Lyrics scroll along with the song, when they're timed.
Git only reads trailers in a message's last paragraph, so keep the note there,
with any other trailers and no blank line between them. A note followed by a
blank line and then, say, Co-Authored-By: is ignored, and the commit never
makes an update. Together, as here, both are read:
Release-note: Lyrics scroll along with the song, when they're timed.
Co-Authored-By: Someone <[email protected]>
To check, git log -1 --format='%(trailers:key=Release-note,valueonly)'
should print the note.
Once a week, if the commits since the last release have notes, they make a
numbered release, with the notes as its release notes, for every platform:
the macOS update window shows them too. Commits without one (refactoring,
tests, CI, docs) never make a release on their own. See RELEASING.md.
