Files
Remus/README.md
T
Ansho Rei 5bb42ba834 feat: log out of or forget a saved server, and pick one on the login screen
The queue button on a server row in Settings opens a prompt with Cancel,
Log out and Forget, replacing the double-press Remove. Log out keeps the
address and username without credentials; Forget also deletes the
server's saved queue and cover cache. The login screen lists the saved
servers beside the form, and a saved login the server turns down at
startup is logged out and opens the login screen prefilled.

Bumps the version to 0.10.0.
2026-11-06 23:34:30 +01:00

110 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# remus
A controller-first music player for a Subsonic library, built for SteamOS on a Steam Deck or a TV.
It opens fullscreen. Its UI is sized from the window's physical height, not from the scale factor the compositor reports, so it keeps the same proportions at 1280×800 and at 4K. Cover art is requested at the size it is drawn.
## Requirements
- GStreamer 1.24 or newer with the base and good plugins, for playback. The Flatpak brings its own.
- To build outside the Flatpak: `libgstreamer1.0-dev` and `libgstreamer-plugins-base1.0-dev` (Debian/Ubuntu names).
- A Subsonic or OpenSubsonic server (Navidrome, Gonic, Airsonic...).
## Run
```
cargo run --release # fullscreen
cargo run --release -- --windowed
```
On first start remus asks for the server address, username and password. It stores the address, the username and an auth token (md5 of password + salt) in `~/.config/remus/config.toml`, mode 0600. The token is enough to log in to that server, so treat the file as a credential. To log in again, or to remove a server, select it under Settings and press the queue button (Y on a controller, Q on a keyboard). Log out drops the token and keeps the address and username, so the login screen lists the server and only asks for the password. Forget removes the server along with its saved queue and cached covers. If the server stops accepting the saved token, remus logs it out at startup and asks for the password.
Some servers refuse token logins (Subsonic error 41), Nextcloud Music among them. For those remus logs in with the password itself and stores that in `config.toml` instead of a token, still mode 0600. Nextcloud Music wants the API password generated in its Music settings, not the Nextcloud login password.
Covers are cached in `~/.cache/remus/covers`.
Preferences live apart from the login, in `~/.config/remus/settings.toml`, so logging in again keeps them. Change them under Settings in the sidebar. "Colours from album art" tints the interface with the cover of the playing track and fades to the next one when the track changes. It is off by default.
## Install on SteamOS
A published version has `remus-<version>.flatpak` attached to its release on Gitea (see [Versions](#versions)). Download that, or build the bundle on any Linux machine with Flatpak:
```
make flatpak-bundle # writes target/flatpak/remus.flatpak
```
`make flatpak` needs `org.flatpak.Builder` from Flathub. It fetches the freedesktop 26.08 SDK and its Rust extension on first use.
On the Steam machine, in Desktop Mode:
1. Copy the bundle over and install it from a terminal: `flatpak install --user remus.flatpak`. Flatpak pulls the freedesktop 26.08 runtime from Flathub.
2. In Steam, choose Games → Add a Non-Steam Game to My Library and pick Remus.
3. Back in Game Mode, open its controller settings and pick a Gamepad layout, so Steam passes the buttons through as a controller and not as keyboard and mouse.
The Flatpak keeps its login and cover cache in `~/.var/app/me.anshorei.Fettleshed.Remus/`, not in `~/.config` and `~/.cache`. Flatpak sets `XDG_CONFIG_HOME` itself there, so overriding it with `flatpak run --env` has no effect.
A bundle does not update itself. To update, install the next version's bundle the same way.
## Controls
| Gamepad | Keyboard | Action |
|---|---|---|
| D-pad / left stick | Arrows | Move |
| A | Enter | Open, play |
| B | Esc, Backspace | Back |
| X | Space | Play / pause |
| Y | Q | Add album, playlist or track to the queue |
| LB / RB | P / N | Previous / next track |
| LT / RT | Shift+Tab / Tab | Previous / next section |
| Right stick | , / . | Seek 10 s |
| Menu | F | Now playing |
| View | / | Search |
| | F11 | Toggle fullscreen |
| | Ctrl+Q | Quit |
With Steam running, remus listens only to Steam's virtual controller, so a pad Steam also exposes does not send every press twice. On a Deck, Steam + X opens the on-screen keyboard for the login and search fields.
## Development
`make` lists the targets. The ones you will use most:
```
make check # formatting, clippy with warnings as errors, unit tests
make test-live # every Subsonic call against the Navidrome demo server
make shots # fullscreen screenshots of the main screens into target/shots
```
`test-live` and `shots` take `DEMO_URL`, `DEMO_USER` and `DEMO_PASS` to point at another server. `shots` runs against a scratch config in `target/scratch`, never your own.
`make shots` is built on `REMUS_DEV_SCRIPT`, which replays actions and saves screenshots so layouts can be checked without a controller:
```
REMUS_DEV_SCRIPT="wait:3000,shot:home.png,right,activate,wait:2000,shot:album.png,quit" cargo run
```
A scripted run starts fullscreen like a normal one, so it also checks that startup reaches fullscreen. Add `--windowed` to capture a window instead. Steps: `size:WxH`, `size:full`, `wait:MS`, `shot:PATH`, `prompts:KIND` (hint icons for `xbox`, `playstation`, `switch`, `steamdeck` or `keyboard`), and action names (`up`, `down`, `left`, `right`, `activate`, `back`, `queue`, `next`, `play-pause`, `section-next`, `now-playing`, `search`, `quit`). Point `XDG_CONFIG_HOME` and `XDG_CACHE_HOME` at a scratch directory to keep test runs away from your own config.
### Versions
Every finished ticket bumps the version, so a build on the Deck can be matched to what it contains. The running version is shown at the bottom left of the controls bar. With Show controls bar turned off in Settings, it is listed as a Version row in Settings instead. The login screen always shows the bar.
- `make patch` for a bug fix, `make minor` for a feature, `make major` only when a breaking change has been decided.
- Before bumping, add a `## v<new> (<date>)` entry at the top of `CHANGELOG.md`, with `### Features` and `### Bug fixes` subsections (leave out an empty one), and commit it with the change. `make version` prints the current version.
- Bump on local `master` only: fast-forward `master` to the finished work, switch to it, then bump. The targets refuse any other branch.
- The bump writes the new version to `Cargo.toml`, `Cargo.lock` and the Flatpak metainfo, amends that into the last commit and tags it `v<new>`. It refuses a dirty tree, a commit that is already tagged or pushed, and a version the changelog has no entry for.
To release a version once it is bumped:
1. `git push --follow-tags origin master`
2. `make publish`
`make publish` builds the Flatpak bundle for the version tagged on HEAD and creates its Gitea release. The release has the tag as its title and the changelog entry as its notes, and `remus-<version>.flatpak` is attached. It needs a Gitea token with `write:repository`, from `GITEA_TOKEN` or the file `~/.config/gitea/token` (`GITEA_TOKEN_FILE` to put it elsewhere). It checks everything before the build and refuses when:
- the tree is dirty
- HEAD is not tagged with the version in `Cargo.toml`
- there is no token
- the tag is not on the remote, or the remote's tag is a different one
- the version already has a release
If the upload fails, it deletes the release again so the next run starts clean. `GITEA_URL`, `GITEA_REPO` and `GITEA_REMOTE` default to this repository on `gitea.anshorei.me`.