65 lines
3.2 KiB
Markdown
65 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
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
|
|
```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`. 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`
|