Initial commit

README.md

@@ -0,0 +1,57 @@
+# 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
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Run
+```bash
+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`