chore(docs): implement documentation
This commit is contained in:
Xoconoch
11
.readthedocs.yaml
Normal file
11
.readthedocs.yaml
Normal file
@@ -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
|
||||
151
README.md
151
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?**
|
||||
|
||||
17
docs/user/albums.md
Normal file
17
docs/user/albums.md
Normal file
@@ -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)
|
||||
27
docs/user/artists.md
Normal file
27
docs/user/artists.md
Normal file
@@ -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`
|
||||
42
docs/user/configuration.md
Normal file
42
docs/user/configuration.md
Normal file
@@ -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
|
||||
93
docs/user/getting-started.md
Normal file
93
docs/user/getting-started.md
Normal file
@@ -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
|
||||
16
docs/user/history.md
Normal file
16
docs/user/history.md
Normal file
@@ -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)
|
||||
20
docs/user/multi-user.md
Normal file
20
docs/user/multi-user.md
Normal file
@@ -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)
|
||||
26
docs/user/playlists.md
Normal file
26
docs/user/playlists.md
Normal file
@@ -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)
|
||||
16
docs/user/tracks.md
Normal file
16
docs/user/tracks.md
Normal file
@@ -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)
|
||||
17
docs/user/watchlist.md
Normal file
17
docs/user/watchlist.md
Normal file
@@ -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`
|
||||
29
mkdocs.yml
Normal file
29
mkdocs.yml
Normal file
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "spotizerr-ui",
|
||||
"private": true,
|
||||
"version": "3.2.1",
|
||||
"version": "3.2.2",
|
||||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "vite",
|
||||
|
||||
@@ -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"
|
||||
|
||||
Reference in New Issue
Block a user