Accessible Navidrome desktop client built with PySide6. Keyboard-first controls, live region announcements, and XDG-compliant configuration keep the app friendly for screen readers and shared systems.

This project is vibe coded. If you have problems with fully AI generated code, move along, nothing to see here. For people with a brain, keep reading, you will be impressed.

Features

Browse Artists, Albums, Favorites, Playlists, Genres, and Discover in separate tabs with native tables
Keyboard-driven playback controls with live announcements
Queue management (play now, next/previous, clear/remove)
Track-change announcements (toggle in View → Announce Track Changes)
Persistent accessible checkboxes for combining artists, albums, and songs across library views
Context menus on library tables and search results (right click or Shift+F10/Menu) for play, queue, favorite
Search dialog uses a results tree (artists/albums/songs/genres) with expand/collapse, Enter to play, and context menus
Discover section with recently added/played, frequently played, random albums, server “Now Playing”, and “Similar to current track”
Favorites tab listing starred songs; Enter plays a song, and Collection actions can play or queue all favorites
Add-to-playlist from songs/albums/artists/genres/favorites via context menu (choose existing or create new)
Desktop integrations via MPRIS (playback control, metadata, notifications)
Config, data, and cache saved under XDG paths (~/.config/stormux/navipy, etc.)
Does not log credentials; server secrets live in servers.json

Requirements

Python 3.9+ (PySide6)
Qt multimedia runtime for audio playback (e.g., qt6-multimedia package when using system Qt)
Navidrome server credentials

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run

python3 navipy.py

Logs are written to ~/.local/share/stormux/navipy/navipy.log.

Configuration and Data Paths

Config: ~/.config/stormux/navipy/settings.json and servers.json
Honors $XDG_CONFIG_HOME. Default path is ~/.config/navipy.
Data (logs, runtime files): ~/.local/share/stormux/navipy/ ($XDG_DATA_HOME respected)
Cache: ~/.cache/stormux/navipy/ ($XDG_CACHE_HOME respected)

Keyboard Shortcuts

Playback: Space play/pause, X play/resume, C toggle pause, V stop
Navigation: Z previous, B next, Ctrl+Left/Right previous/next, Alt+S shuffle, Alt+R repeat
Announcements: Alt+C announce current track (live region), Ctrl+T announce track (dialog), Ctrl+P announce position
Volume: Ctrl+Up/Down or 0/9 to adjust
Library/Search: Ctrl+O connect, F5 refresh, Ctrl+F search, Alt+I context menu for current track/selection, Alt+A actions for checked library items, Shift+F10 or Menu key for item context menu

Browsing the Library

Switch categories with Ctrl+Tab / Ctrl+Shift+Tab, or focus the tab bar and use arrow keys.
Use arrow keys to navigate table rows and columns. Tab leaves the table for the next control.
Press Enter to open an artist's albums, an album's tracks, or a playlist or genre. On a song, Enter starts playback.
Use Backspace, Alt+Left, or the Back button to return to the previous table and selection.
Use Play selected to play an entire selected album, artist, playlist, or genre without leaving the table.
Use Shift+F10, the Menu key, or Actions for play, queue, playlist, and favorite actions.
Library tables have a first Selected checkbox column and initially focus the second, informational column. Press Space from either column to check or uncheck an artist, album, or song. Checks remain selected while you browse other tabs and collections. Alt+A opens actions for all checked items.
Collection actions applies to the collection currently being viewed, including all artists or favorites.
Albums and genre tracks have a Load more button when more results are available.
Each tab keeps its own browsing position. Refreshing the library resets the tables.
Ctrl+C copies the current row. Search remains available with Ctrl+F.

Playback Persistence

Volume, shuffle, and repeat preferences persist in settings.json
Repeat defaults to off; shuffle retains your last choice across launches

Accessibility Notes

Live region announcements for status updates and explicit announce commands
Accessible names/descriptions on interactive widgets
Keyboard-only navigation throughout the UI

Development Tips

Keep secrets out of logs; servers.json stores credentials and is not tracked
Respect XDG env vars in scripts/tests to avoid polluting real user data
Placeholder tests can be added under tests/ with pytest