Files
Remus/README.md
T
Ansho Rei a74fd1bd5c build: package remus as a Flatpak for SteamOS
SteamOS has a read-only root filesystem, so a Flatpak is the way to
install it. The build is offline from vendored crates. make
flatpak-bundle writes one file to copy to a Steam machine, and
make sdk-check runs the checks inside the SDK for hosts without the
GStreamer development files.
2026-11-04 02:19:07 +01:00

3.9 KiB
Raw Blame History

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. Delete it to log in again.

Covers are cached in ~/.cache/remus/covers.

Install on SteamOS

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 remus.flatpak 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.

To update, build a new bundle and install it 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, 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.