NaviPy

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.

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)
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. Reads legacy ~/.config/navipy if present.
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

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