chore(docs): implement documentation

2025-08-23 08:28:10 -06:00
parent 1f81f75cbc
commit 2c07fdeccc
15 changed files with 317 additions and 154 deletions
--- a/docs/user/albums.md
+++ b/docs/user/albums.md
@@ -0,0 +1,17 @@
+## Albums
+
+Open an album from search or artist page.
+
+- Download
+  - Download full album
+  - Download individual tracks from the tracklist
+- Tracklist
+  - Shows order, artists, and duration
+  - Respects explicit filter (hidden if enabled)
+- Large albums
+  - Tracks load progressively as you scroll
+
+Backend endpoints used:
+- GET `/api/album/info?id=...&limit=50&offset=...` (metadata + paged tracks)
+- GET `/api/album/download/{album_id}` (queue download)
+- GET `/api/progress/stream` (live queue updates)
--- a/docs/user/artists.md
+++ b/docs/user/artists.md
@@ -0,0 +1,27 @@
+## Artists
+
+Open an artist from search.
+
+- Discography
+  - Albums, Singles, Compilations, Appears On sections
+  - Infinite loading as you scroll
+- Download
+  - Download all (queues albums respecting filters)
+  - Download any album individually
+- Watch
+  - Add/remove artist to Watchlist (auto-download new releases when enabled)
+
+How-to: monitor an artist
+1. Search for the artist and open their page
+2. Click Watch
+3. Configure release types and intervals in Configuration → Watch
+
+How-to: download discography
+1. Open the artist page
+2. Choose release types (e.g., Albums, Singles, Compilations)
+3. Click Download All; track progress in Queue and History
+
+Backend endpoints used:
+- GET `/api/artist/info?id=...&limit=20&offset=...` (metadata + paged albums)
+- GET `/api/artist/download/{artist_id}?album_type=album,single,compilation` (queue discography)
+- PUT `/api/artist/watch/{artist_id}` / DELETE `/api/artist/watch/{artist_id}` / GET `/api/artist/watch/{artist_id}/status`
--- a/docs/user/configuration.md
+++ b/docs/user/configuration.md
@@ -0,0 +1,42 @@
+## Configuration
+
+Open Configuration in the web UI. Tabs:
+
+- General (admin)
+  - App version, basic info
+- Downloads (admin)
+  - Concurrent downloads, retry behavior
+  - Quality/format defaults and conversion
+  - Real-time mode (Spotify only): aligns download time with track length
+- Formatting (admin)
+  - File/folder naming patterns (examples)
+    - `%artist%/%album%/%tracknum%. %title%`
+    - `%ar_album%/%album% (%year%)/%title%`
+- Accounts (admin)
+  - Spotify: use `spotizerr-auth` to add credentials
+  - Deezer ARL (optional):
+    - Chrome/Edge: devtools → Application → Cookies → https://www.deezer.com → copy `arl`
+    - Firefox: devtools → Storage → Cookies → https://www.deezer.com → copy `arl`
+    - Paste ARL in Accounts
+  - Select main account when multiple exist
+- Watch (admin)
+  - Enable/disable watch system
+  - Set check intervals
+  - Manually trigger checks (artists/playlists)
+- Server (admin)
+  - System info and advanced settings
+- Profile (all users when auth is enabled)
+  - Change password, view role and email
+
+Quality formats (reference):
+- Spotify: OGG 96k/160k/320k (320k requires Premium)
+- Deezer: MP3 128k/320k (320k may require Premium), FLAC (Premium)
+- Conversion: MP3/FLAC/AAC/OGG/OPUS/WAV/ALAC with custom bitrate
+
+Fallback system:
+- Configure primary and fallback services
+- Automatically switches if primary fails (useful for geo/account limits)
+
+Notes:
+- Explicit content filter applies in pages (e.g., hides explicit tracks on album/playlist views)
+- Watch system must be enabled before adding items
--- a/docs/user/getting-started.md
+++ b/docs/user/getting-started.md
@@ -0,0 +1,93 @@
+## Getting started
+
+### Prerequisites
+- Docker and Docker Compose
+- Spotify account(s)
+- Deezer account (optional, recommended for FLAC)
+- Spotify API `client_id` and `client_secret` (from Spotify Developer Dashboard)
+
+Quick start (Docker Compose):
+
+```bash
+# 1) Create a project directory
+mkdir spotizerr && cd spotizerr
+
+# 2) Add .env
+# Download .env.example from the repo and create .env with your values
+
+# 3) Add docker-compose.yaml
+# Download docker-compose.yaml from the repo to this folder
+
+# 4) Start
+docker compose up -d
+```
+
+### Initial setup
+- Open the web UI (default: `http://localhost:7171`)
+- Go to Configuration → Accounts
+- Use `spotizerr-auth` to register Spotify credentials quickly
+
+Spotify account setup with spotizerr-auth:
+
+```bash
+docker run --network=host --rm -it cooldockerizer93/spotizerr-auth
+```
+or, if docker doesn't work:
+
+#### Alternative installers
+
+<details>
+<summary>Linux / macOS</summary>
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate && pip install spotizerr-auth
+````
+
+</details>
+
+<details>
+<summary>Windows (PowerShell)</summary>
+
+```powershell
+python -m venv .venv; .venv\Scripts\Activate.ps1; pip install spotizerr-auth
+```
+
+</details>
+
+<details>
+<summary>Windows (cmd.exe)</summary>
+
+```cmd
+python -m venv .venv && .venv\Scripts\activate && pip install spotizerr-auth
+```
+
+</details>
+
+Then run `spotizerr-auth`.
+
+_Note: You will have to enable the virtual environment everytime you want to register a new account._
+
+### Registering account
+- Ensure Spotify client is opened before starting
+- Enter Spotizerr URL (e.g., http://localhost:7171)
+- Enter Spotify API `client_id` and `client_secret` if prompted (one-time)
+- Name the account + region code (e.g., US)
+- Transfer playback to the temporary device when asked
+- Credentials are posted to Spotizerr automatically
+
+**Next steps:**
+- Add Deezer ARL in Configuration → Accounts (optional, allows for FLAC availability if premium)
+- Adjust Download and Formatting options
+- Enable Watch system if you want automatic downloads
+
+**Troubleshooting (quick):**
+- Downloads not starting: verify service credentials and API keys
+- Watch not working: enable in Configuration → Watch and set intervals
+- Auth issues: ensure JWT secret and SSO creds (if used); try clearing browser cache
+- Queue stalling: force-refresh the page (ctrl+F5)
+
+**Logs:**
+```bash
+docker logs spotizerr
+```
+- Enable Watch system if you want auto-downloads
--- a/docs/user/history.md
+++ b/docs/user/history.md
@@ -0,0 +1,16 @@
+## History
+
+See all downloads and their outcomes.
+
+- Filters
+  - By type (track/album/playlist) and status (completed/failed/skipped/in_progress)
+  - Pagination for large histories
+- Drill-down
+  - Open an entry to view child tracks for albums/playlists
+  - Re-queue failures from the UI
+
+Backend endpoints used:
+- GET `/api/history?download_type=&status=&limit=&offset=`
+- GET `/api/history/{task_id}` (entry)
+- GET `/api/history/{task_id}/children` (child tracks)
+- GET `/api/history/stats`, `/api/history/recent`, `/api/history/failed` (summaries)
--- a/docs/user/multi-user.md
+++ b/docs/user/multi-user.md
@@ -0,0 +1,20 @@
+## Multi-user
+
+Authentication is optional. When enabled:
+
+- Login/Register
+  - Local accounts with username/password
+  - First registered user becomes admin
+  - Public registration can be disabled
+- SSO (optional)
+  - Google and GitHub when configured
+- Roles
+  - User: can search/download, manage their profile
+  - Admin: access to all Configuration tabs and user management
+- Admin actions
+  - Create/delete users, change roles
+  - Reset user passwords
+
+Where to find it in the UI:
+- User menu (top-right) → Profile settings
+- Configuration → User Management (admin)
--- a/docs/user/playlists.md
+++ b/docs/user/playlists.md
@@ -0,0 +1,26 @@
+## Playlists
+
+Open a playlist from search.
+
+- Download
+  - Download entire playlist
+  - Download individual tracks
+- Metadata and tracks
+  - Loads metadata first (fast, avoids rate limits)
+  - Tracks load in pages as you scroll
+- Watch
+  - Add/remove playlist to Watchlist (auto-download new additions when enabled)
+
+How-to: download a playlist
+1. Search for the playlist or paste its Spotify URL
+2. Click Download
+3. Monitor progress in the Queue; results appear in History
+
+Backend endpoints used:
+- GET `/api/playlist/metadata?id=...` (metadata only)
+- GET `/api/playlist/tracks?id=...&limit=50&offset=...` (paged tracks)
+- GET `/api/playlist/info?id=...&include_tracks=true` (full info when needed)
+- GET `/api/playlist/download/{playlist_id}` (queue download)
+- PUT `/api/playlist/watch/{playlist_id}` (watch)
+- DELETE `/api/playlist/watch/{playlist_id}` (unwatch)
+- GET `/api/playlist/watch/{playlist_id}/status` (status)
--- a/docs/user/tracks.md
+++ b/docs/user/tracks.md
@@ -0,0 +1,16 @@
+## Tracks
+
+Find a track via search or open a track page.
+
+- Download
+  - Click Download on result card or track page
+  - Progress visible in the Queue drawer
+- Open on Spotify
+  - From track page, open the Spotify link
+- Details shown
+  - Artists, album, duration, popularity
+
+Backend endpoints used:
+- GET `/api/track/info?id=...` (metadata)
+- GET `/api/track/download/{track_id}` (queue download)
+- GET `/api/progress/stream` (live queue updates)
--- a/docs/user/watchlist.md
+++ b/docs/user/watchlist.md
@@ -0,0 +1,17 @@
+## Watchlist
+
+Enable the watch system in Configuration → Watch first.
+
+- Add items
+  - From Artist or Playlist pages, click Watch
+- What it does
+  - Periodically checks watched items
+  - Queues new releases (artists) and/or newly added tracks (playlists)
+- Setup
+  - Enable watch system and set intervals in Configuration → Watch
+  - Trigger a manual check if you want immediate processing
+
+Backend endpoints used:
+- Artists: PUT/DELETE/GET status under `/api/artist/watch/*`
+- Playlists: PUT/DELETE/GET status under `/api/playlist/watch/*`
+- Manual triggers: POST `/api/artist/watch/trigger_check` and `/api/playlist/watch/trigger_check`