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, playlists, and genres from your Navidrome server
Keyboard-driven playback controls with live announcements
Queue management (play now, next/previous, clear/remove)
Track-change announcements (toggle in View → Announce Track Changes)
Context menus on library/search trees (right click or Shift+F10/Menu) for play, queue, favorite
Search dialog mirrors the 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 section listing all starred songs; press Enter to play all or open individual tracks
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, Shift+F10 or Menu key for item context menu

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