Please help me install and set up "Cardinal" from veered.org on my own computer or server.

What it is: A shuffle music player for any folder, with media keys and resume. It runs on: Any Linux desktop. On COSMIC the keyboard shortcuts install themselves.
Project page: https://veered.org/linux-music-player/
Source code download (zip): https://veered.org/linux-music-player/cardinal-music-player.zip

How I'd like you to help:
1. First ask me what you need to know: my operating system and version, my desktop environment if it matters, whether I'm comfortable with the terminal, and any accounts or hardware this project needs.
2. Then take me through it one step at a time. For each command, say briefly what it does, and wait for me to paste back the result before moving on.
3. Before any step that changes system settings, uses sudo, or edits an existing configuration file, tell me, and have me make a backup first.
4. If something fails, help me work out why. If the instructions below don't fit my system, say so rather than guessing.
5. At the end, show me how to check that it works, and how to uninstall it.

The project is shared as-is by its author, with no warranty. If we find a problem in the project itself, please help me write a short, clear note I can send to support@veered.org.

Here is the project's documentation (README files from the download):

===== README.md =====
# Linux Music Folder Player with Media Keys (Cardinal)

*Why Cardinal? A red, and a songbird.*

**Runs on** any Linux desktop. The keyboard shortcuts install themselves on COSMIC; on other desktops you add them in your own settings, in a minute.

**Version 1.0.**

Part of [Veered](https://veered.org): free tools, shared as-is. Questions: support@veered.org

Point it at the folder your music lives in and it shuffles everything in there,
all the way down through the sub-folders. Start it with a keyboard shortcut, stop
it with the same one, and your keyboard's own Play and Next keys work on it.

- **Your own folder of music.** Anything in it plays: mp3, m4a, aac, opus, ogg, flac, wav, webm.
- **Start it with a key, not a window.** One shortcut starts it and pauses it; another skips a track.
- **It picks up where you left off.** Stop in the middle of a song and it resumes there next time.
- **A big library starts instantly**, even one on a network drive.
- **More bass, just for the music.** A bass control that leaves the rest of your computer alone.
- **It plays in the background.** No window to keep open, nothing in the way of your work.

![music, at the command line](docs/screenshot.jpg)

*Everything else — the panel button, the media keys, the COSMIC shortcuts — drives these same commands.*

## Please test before relying on it

This is shared as-is, with no warranty. It works on my own computers, but your system,
settings and software versions may differ, so please try it in a safe setting first.
If something doesn't work, you can ask Claude (or another AI coding assistant) to look
into it, and I'd appreciate hearing what you found and how you fixed it. You are also
welcome to just let me know at support@veered.org, and I'll look into it.

## Information for nerds: requirements and install

Debian / Ubuntu / Pop!_OS package names:

```sh
sudo apt install mpv python3
# optional
sudo apt install libnotify-bin                # notifications
sudo apt install python3-gi python3-pydbus    # so the Play/Pause keys reach it
sudo apt install playerctl                    # so other players still get the keys when this one is not running
```

### Install

```sh
./install.sh                           # commands only, library = ~/Music
./install.sh --dir ~/Audio/Library     # choose the folder
./install.sh --shortcuts               # Super+M play/pause, Super+N next (below)
./install.sh --shortcuts fkeys         # F9 play/pause, F10 next instead
./install.sh --shortcuts --media-keys  # also take over the Play/Pause media keys
```

Everything goes to `~/.local/bin`, `~/.local/share/cosmic-tools/music` and
`~/.config/cosmic-tools`. Make sure `~/.local/bin` is on your `PATH`.

Uninstall with `./uninstall.sh` (it removes the shortcuts it added, after a
backup). `--purge` also deletes settings and the resume position.

## How you use it

```
music                   shuffle the whole library in this terminal
music TEXT              only files whose path contains TEXT (case-insensitive)
music bg [TEXT]         start in the background
music start             pause/resume if playing, otherwise start in the background
music next | prev       skip
music toggle            pause / resume
music stop              stop and remember the position
music now               print the current track (exit status 1 if nothing plays)
music bass [dB]         show or set the bass shelf (-12 .. 12)
music rescan            rebuild the track list cache
music set-dir PATH      save a new library folder
music --dir PATH ...    use another folder for one command
```

In the terminal player: `>` next, `<` previous, space pause, `9`/`0` volume, `q` quit.

## Information for nerds: settings and environment

`~/.config/cosmic-tools/music.conf` (sourced by bash):

| Key | Default | Meaning |
| --- | --- | --- |
| `MUSIC_ROOT` | `"$HOME/Music"` | Library folder. `music set-dir` writes it, using `$HOME` for paths inside your home |
| `MUSIC_MPV_OPTS` | empty | Extra mpv options, e.g. `"--volume=70"` |
| `MUSIC_NOTIFY` | `1` | Desktop notifications |

Environment variables: `MUSIC_ROOT` overrides the file for one run,
`MUSIC_DRYRUN=1` lists matching files instead of playing, `MUSIC_SOCKET` changes
the IPC socket (default `$XDG_RUNTIME_DIR/mpv-music.sock`).

Files used: track list cache in `~/.cache/cosmic-tools/music/`, resume position
in `~/.local/state/cosmic-tools/music-last`, bass setting in
`~/.config/cosmic-tools/music-bass`.

## COSMIC shortcuts

Two keys are all you need: one starts, pauses and resumes, the other skips.
To stop completely (and remember the position), run `music stop`.

| Preset | Play / pause (starts if stopped) | Next track | Notes |
| --- | --- | --- | --- |
| `--shortcuts` (or `--shortcuts super`) | Super+M | Super+N | Super+M replaces COSMIC's default Maximize shortcut; double-click a title bar to maximize instead. |
| `--shortcuts fkeys` | F9 | F10 | COSMIC takes plain F-keys before applications see them, so F9/F10 no longer work inside apps. |
| `--play-key K --next-key K` | your choice | your choice | e.g. `--play-key Super+Ctrl+m --next-key Super+Ctrl+n` |

With `--media-keys` it also makes **Play** and **Pause** run `music-playpause`,
which controls `music` while it runs and otherwise forwards the key with
`playerctl play-pause`. That replaces COSMIC's built-in handling of those two
keys, so it is opt-in.

How the edit is done (`tools/cosmic-shortcuts.py`):

- Shortcuts live in `~/.config/cosmic/com.system76.CosmicSettings.Shortcuts/v1/custom`.
- The file is copied to `~/.config/cosmic-tools/backups/shortcuts-<timestamp>/`
  before any change, then replaced atomically. COSMIC watches the file, and an
  in-place rewrite may not be picked up.
- A key combination that is already bound to something else is left alone and
  reported. Nothing is overwritten.
- Each action has its own argument-free wrapper script, because a COSMIC
  shortcut runs a single program path.

You can also create the keyboard shortcuts yourself, in the custom shortcuts section of the
Keyboard Shortcuts page in COSMIC Settings. Avoid plain Alt combinations: many
applications treat them as menu accelerators.

To see or manage custom shortcuts:

```sh
python3 ~/.local/share/cosmic-tools/music/cosmic-shortcuts.py list
python3 ~/.local/share/cosmic-tools/music/cosmic-shortcuts.py add --bind "Super+p=$HOME/.local/bin/music-start" --dry-run
```

## License

MIT, see the top-level LICENSE.

## Information for nerds: conventions

- The installer is per-user: it writes to `~/.local/bin`, `~/.local/share/cosmic-tools`
  and `~/.config/cosmic-tools`, never to system directories, and needs no `sudo`.
- Any step that edits a COSMIC config file makes a timestamped backup under
  `~/.config/cosmic-tools/backups/` first.
- Configuration files are plain text with comments.


----- For Claude Code users -----

Download https://veered.org/linux-music-player/cardinal-music-player.zip, unzip it into a new folder, read every README.md in it, and help me install and set up "Cardinal" (A shuffle music player for any folder, with media keys and resume) on this machine. Check the requirements against this system first and tell me what is missing. Ask me before running anything with sudo, installing packages, or changing existing configuration files, and back those files up first. Finish by showing me how to test it and how to uninstall it.