# Download Diagnostics Guide

## Quick Status Check

### 1. Check Download Status API
Visit this URL in your browser or use curl:
```
http://localhost:5140/api/download/status
```

This will show you:
- Current queue size
- Active downloads
- Recent download history
- Any errors

### 2. Check Server Logs
Look for these debug messages in your server console:
```
🔽 [DEBUG] Download request received: {data}
🔽 [DEBUG] Adding to download queue: {download_info}
🔽 [DEBUG] Emitted update_status with X items
```

### 3. Check Download Directory
Downloads are saved to: `/data/{artist}/{album} - ({year})/{artist} - {title}.mp3`

Default paths:
- **Download Path**: `/data` (or `ABSOLUTE_SERVER_PATH` env var)
- **Temp Path**: `/temp` (or `TEMP_PATH` env var)

## Common Issues & Solutions

### Issue 1: Downloads Not Starting
**Symptoms**: No progress shown, stuck on "Downloading..."
**Causes**:
- SpotDL not installed or not in PATH
- Network connectivity issues
- Invalid Spotify URLs

**Check**:
```bash
# Test SpotDL installation
spotdl --version

# Test manual download
spotdl download "https://open.spotify.com/track/TRACK_ID" --output "/data/test.mp3"
```

### Issue 2: Downloads Failing Silently
**Symptoms**: Status shows "Complete" but no files appear
**Causes**:
- Permission issues with download directory
- Disk space issues
- Invalid output path

**Check**:
```bash
# Check directory permissions
ls -la /data/

# Check disk space
df -h

# Check if directory is writable
touch /data/test.txt && rm /data/test.txt
```

### Issue 3: Progress Not Updating
**Symptoms**: Download starts but progress stays at 0%
**Causes**:
- SpotDL output format changed
- Progress parsing issues
- Network timeouts

**Debug**: Look for these log messages:
```
Progress update: X% for {song_name}
Successfully downloaded '{song_name}' with provider: {provider}
```

## SpotDL Configuration

Current settings:
- **Format**: MP3
- **Bitrate**: 320k
- **Lyrics**: Genius (with LRC generation)
- **Providers**: youtube-music, youtube (fallback)
- **Log Level**: INFO

## Troubleshooting Steps

### Step 1: Check Server Connection
```bash
curl http://localhost:5140/status
# Should return: OK
```

### Step 2: Check Download Status
```bash
curl http://localhost:5140/api/download/status
```

### Step 3: Test Manual Download
```bash
# SSH into your server/container
spotdl download "https://open.spotify.com/track/4iV5W9uYEdYUVa79Axb7Rh" --output "/data/test.mp3"
```

### Step 4: Check File System
```bash
# List recent downloads
find /data -name "*.mp3" -mtime -1 -ls

# Check total downloaded files
find /data -name "*.mp3" | wc -l
```

## Environment Variables to Check

```bash
echo $ABSOLUTE_SERVER_PATH  # Should be /data or your music path
echo $TEMP_PATH            # Should be /temp
echo $TRIGGER_JELLYFIN_SCAN # Should be True to refresh library
```

## Frontend Debug

Open browser console and look for:
```javascript
// Download request
🔽 [DEBUG] Download request received: {data}

// Status updates
update_status event with download progress
```

## Next Steps

1. **Check the download status API** first
2. **Look at server console logs** during download attempts
3. **Verify file system permissions** and disk space
4. **Test manual SpotDL download** to isolate issues

If downloads are completing but not showing in Jellyfin:
- Check if `TRIGGER_JELLYFIN_SCAN=True` is set
- Manually trigger library scan in Jellyfin
- Verify Jellyfin is monitoring the correct directory (`/data`)