chore(docs): implement documentation

.readthedocs.yaml

@@ -0,0 +1,11 @@
+version: 2
+mkdocs:
+  configuration: mkdocs.yml
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_install:
+      - pip install --upgrade pip
+      - pip install mkdocs mkdocs-material

README.md

@@ -27,157 +27,6 @@ If you self-host a music server with other users than yourself, you almost certa
   <img width="1588" height="994" alt="image" src="https://github.com/user-attachments/assets/e34d7dbb-29e3-4d75-bcbd-0cee03fa57dc" />
 </details>
 
-## ✨ Key Features
-
-### 🎵 **Granular download support**
-- **Individual Tracks** - Download any single track
-- **Complete Albums** - Download entire albums with proper metadata
-- **Full Playlists** - Download complete playlists (even massive ones with 1000+ tracks)
-- **Artist Discographies** - Download an artist's complete catalog with filtering options
-- **Spotify URL Support** - Paste any Spotify URL directly to queue downloads
-
-### 📱 **Modern Web Interface**
-- **Progressive Web App (PWA)** - Install as a native client on mobile/desktop (installation process may vary depending on the browser/device)
-- **Multiple Themes** - Light, dark, and system themes
-- **Touch-friendly** - Swipe gestures and mobile-optimized controls
-
-### 🤖 **Intelligent Monitoring**
-- **Playlist Watching** - Automatically download new tracks added to Spotify playlists
-- **Artist Watching** - Monitor artists for new releases and download them automatically
-- **Configurable Intervals** - Set how often to check for updates
-- **Manual Triggers** - Force immediate checks when needed
-
-### ⚡ **Advanced Queue Management**
-- **Concurrent Downloads** - Configure multiple simultaneous downloads
-- **Real-time Updates** - Live progress updates via Server-Sent Events
-- **Duplicate Prevention** - Automatically prevents duplicate downloads
-- **Queue Persistence** - Downloads continue even after browser restart
-- **Cancellation Support** - Cancel individual downloads or clear entire queue
-
-### 🔧 **Extensive Configuration**
-- **Quality Control** - Configure audio quality per service (limitations per account tier apply)
-- **Format Options** - Convert to MP3, FLAC, AAC, OGG, OPUS, WAV, ALAC in various bitrates
-- **Custom Naming** - Flexible file and folder naming patterns
-- **Content Filtering** - Hide explicit content if desired
-
-### 📊 **Comprehensive History**
-- **Download Tracking** - Complete history of all downloads with metadata
-- **Success Analytics** - Track success rates, failures, and skipped items
-- **Search & Filter** - Find past downloads by title, artist, or status
-- **Detailed Logs** - View individual track status for album/playlist downloads
-- **Export Data** - Access complete metadata and external service IDs
-
-### 👥 **Multi-User Support**
-- **User Authentication** - Secure login system with JWT tokens
-- **SSO Integration** - Single Sign-On with Google and GitHub
-- **Admin Panel** - User management and system configuration
-
-## 🚀 Quick Start
-
-### Prerequisites
-- Docker and Docker Compose
-- Spotify account(s)
-- Deezer account(s) (optional, but recommended)
-- Spotify API credentials (Client ID & Secret from [Spotify Developer Dashboard](https://developer.spotify.com/dashboard))
-
-### Installation
-
-1. **Create project directory**
-   ```bash
-   mkdir spotizerr && cd spotizerr
-   ```
-
-2. **Setup environment file**
-   ```bash
-   # Download .env.example from the repository and create .env
-   # Update all variables (e.g. Redis credentials, PUID/PGID, UMASK)
-   ```
-
-3. **Copy docker-compose.yaml**
-   ```bash
-   # Download docker-compose.yaml from the repository
-   ```
-
-4. **Start the application**
-   ```bash
-   docker compose up -d
-   ```
-
-5. **Next steps**
-   - Before doing anything, it is recommended to go straight to [Configuration](#-configuration)
-
-## 🔧 Configuration
-
-### Service Accounts Setup
-
-1. **Spotify setup**
-   - Spotify is very restrictive, so use the [spotizerr-auth](https://github.com/Xoconoch/spotizerr-auth) tool on a computer with the spotify client installed to simplify this part of the setup.
-
-2. **Deezer setup (Optional but recommended for better stability, even if it's a free account)**
-   - Get your Deezer ARL token:
-     - **Chrome/Edge**: Open [Deezer](https://www.deezer.com/), press F12 → Application → Cookies → "https://www.deezer.com" → Copy "arl" value
-     - **Firefox**: Open [Deezer](https://www.deezer.com/), press F12 → Storage → Cookies → "https://www.deezer.com" → Copy "arl" value
-   - Add the ARL token in Settings → Accounts
-
-3. **Configure Download Settings**
-   - Set audio quality preferences
-   - Configure output format and naming
-   - Adjust concurrent download limits
-
-### Watch System Setup
-
-1. **Enable Monitoring**
-   - Go to Settings → Watch
-   - Enable the watch system
-   - Set check intervals
-
-2. **Add Items to Watch**
-   - Search for playlists or artists
-   - Click the "Watch" button
-   - New content will be automatically downloaded
-
-## 📋 Usage Examples
-
-### Download a Playlist
-1. Search for the playlist or paste its Spotify URL
-2. Click the download button
-3. Monitor progress in the real-time queue
-
-### Monitor an Artist
-1. Search for the artist
-2. Click "Add to Watchlist"
-3. Configure which release types to monitor (albums, singles, etc.)
-4. New releases will be automatically downloaded
-
-### Bulk Download an Artist's Discography
-1. Go to the artist page
-2. Select release types (albums, singles, compilations)
-3. Click "Download Discography"
-4. All albums will be queued automatically
-
-## 🔍 Advanced Features
-
-### Custom File Naming
-Configure how files and folders are named:
-- `%artist%/%album%/%tracknum%. %title%`
-- `%ar_album%/%album% (%year%)/%title%`
-- Support for track numbers, artists, albums, years, and more
-
-### Quality Settings
-- **Spotify**: OGG 96k, 160k, and 320k (320k requires Premium)
-- **Deezer**: MP3 128k, MP3 320k (sometimes requires Premium), and FLAC (Premium only)
-- **Conversion**: Convert to any supported format with custom bitrate
-
-### Fallback System
-- Configure primary and fallback services
-- Automatically switches if primary service fails
-- Useful for geographic restrictions or account limits
-
-### Real-time Mode
-- **Spotify only**: Matches track length with download time for optimal timing
-
-## 🆘 Support & Troubleshooting
-
 ### Common Issues
 
 **Downloads not starting?**

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)

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`

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

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

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)

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)

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)

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)

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`

mkdocs.yml

@@ -0,0 +1,29 @@
+site_name: Spotizerr Documentation
+site_description: Straight-to-the-point docs for Spotizerr
+site_dir: site
+use_directory_urls: true
+theme:
+  name: material
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - content.action.edit
+    - search.suggest
+    - search.highlight
+nav:
+  - Getting started: docs/user/getting-started.md
+  - Configuration: docs/user/configuration.md
+  - Tracks: docs/user/tracks.md
+  - Albums: docs/user/albums.md
+  - Playlists: docs/user/playlists.md
+  - Artists: docs/user/artists.md
+  - Watchlist: docs/user/watchlist.md
+  - History: docs/user/history.md
+  - Multi-user: docs/user/multi-user.md
+  - API: docs/API_DOCUMENTATION.md
+markdown_extensions:
+  - toc:
+      permalink: true
+  - admonition
+  - tables
+  - fenced_code

requirements.txt

@@ -1,7 +1,7 @@
 fastapi==0.116.1
 uvicorn[standard]==0.35.0
 celery==5.5.3
-deezspot-spotizerr==2.7.3
+deezspot-spotizerr==2.7.4
 httpx==0.28.1
 bcrypt==4.2.1
 PyJWT==2.10.1

spotizerr-ui/package.json

@@ -1,7 +1,7 @@
 {
   "name": "spotizerr-ui",
   "private": true,
-  "version": "3.2.1",
+  "version": "3.2.2",
   "type": "module",
   "scripts": {
     "dev": "vite",

spotizerr-ui/src/components/SearchResultCard.tsx

@@ -49,7 +49,7 @@ export const SearchResultCard = ({ id, name, subtitle, imageUrl, type, onDownloa
           <button
             onClick={onDownload}
             disabled={!!status && status !== "error"}
-            className="absolute bottom-2 right-2 p-2 bg-button-success hover:bg-button-success-hover text-button-success-text rounded-full transition-opacity shadow-lg opacity-0 group-hover:opacity-100 duration-300 z-10 disabled:opacity-50 disabled:cursor-not-allowed"
+            className="absolute bottom-2 right-2 p-2 bg-button-success hover:bg-button-success-hover text-button-success-text rounded-full transition-opacity shadow-lg opacity-100 sm:opacity-0 sm:group-hover:opacity-100 duration-300 z-10 disabled:opacity-50 disabled:cursor-not-allowed"
             title={
               status
                 ? status === "queued"