diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..c85cdff --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/README.md b/README.md index 5c6ecc6..8ff2833 100644 --- a/README.md +++ b/README.md @@ -27,157 +27,6 @@ If you self-host a music server with other users than yourself, you almost certa image -## ✨ 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?** diff --git a/docs/user/albums.md b/docs/user/albums.md new file mode 100644 index 0000000..838d7bf --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/user/artists.md b/docs/user/artists.md new file mode 100644 index 0000000..34dd131 --- /dev/null +++ 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` \ No newline at end of file diff --git a/docs/user/configuration.md b/docs/user/configuration.md new file mode 100644 index 0000000..d1871f1 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/user/getting-started.md b/docs/user/getting-started.md new file mode 100644 index 0000000..a6c2291 --- /dev/null +++ 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 + +
+Linux / macOS + +```bash +python3 -m venv .venv && source .venv/bin/activate && pip install spotizerr-auth +```` + +
+ +
+Windows (PowerShell) + +```powershell +python -m venv .venv; .venv\Scripts\Activate.ps1; pip install spotizerr-auth +``` + +
+ +
+Windows (cmd.exe) + +```cmd +python -m venv .venv && .venv\Scripts\activate && pip install spotizerr-auth +``` + +
+ +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 \ No newline at end of file diff --git a/docs/user/history.md b/docs/user/history.md new file mode 100644 index 0000000..d1f0969 --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/user/multi-user.md b/docs/user/multi-user.md new file mode 100644 index 0000000..0030da8 --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/user/playlists.md b/docs/user/playlists.md new file mode 100644 index 0000000..adeab3b --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/user/tracks.md b/docs/user/tracks.md new file mode 100644 index 0000000..e51cf33 --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/user/watchlist.md b/docs/user/watchlist.md new file mode 100644 index 0000000..7e21baa --- /dev/null +++ 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` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..0b324b4 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index eb1861e..0e42ced 100755 --- a/requirements.txt +++ b/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 diff --git a/spotizerr-ui/package.json b/spotizerr-ui/package.json index 1473397..59c1f3a 100644 --- a/spotizerr-ui/package.json +++ b/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", diff --git a/spotizerr-ui/src/components/SearchResultCard.tsx b/spotizerr-ui/src/components/SearchResultCard.tsx index 7522bcd..9add427 100644 --- a/spotizerr-ui/src/components/SearchResultCard.tsx +++ b/spotizerr-ui/src/components/SearchResultCard.tsx @@ -49,7 +49,7 @@ export const SearchResultCard = ({ id, name, subtitle, imageUrl, type, onDownloa