Files
Remus/README.md
T
Ansho Rei 4105554f68 feat: add a controller-driven Subsonic player for SteamOS
Browses a Subsonic library and plays it through mpv, driven by a
gamepad or keyboard. The UI scales from the window's physical height
rather than the compositor's scale factor, so it keeps its proportions
on a Steam Deck and on a 4K TV, where other players open small or
scale badly.
2026-11-04 01:17:29 +01:00

2.4 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

  • mpv on the PATH. remus runs it as a child process and controls it over its JSON IPC socket.
  • 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.

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

cargo test
REMUS_TEST_URL=https://demo.navidrome.org REMUS_TEST_USER=demo REMUS_TEST_PASS=demo \
  cargo test -- --ignored        # every API call against a real server

REMUS_DEV_SCRIPT replays actions and saves screenshots, which is how layouts are checked at different sizes without a controller:

REMUS_DEV_SCRIPT="size:full,wait:3000,shot:home.png,right,activate,wait:2000,shot:album.png,quit" cargo run

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.