mirror of
https://lavaforge.org/spotizerr/spotizerr.git
synced 2025-12-24 02:39:14 -05:00
chore(docs): implement documentation
This commit is contained in:
Xoconoch
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?**
|
||||
|
||||
Reference in New Issue
Block a user