ohm_streaming/docs/WATCHLIST_AUTO_DOWNLOAD.md

# Watchlist & Auto-Download System

## 🎯 Overview

The Watchlist & Auto-Download system allows users to automatically track and download new episodes of their favorite anime. It features periodic checking, automatic downloads, and a flexible scheduler.

## 📋 Features

### Core Functionality
- **Automatic Episode Tracking**: Track new episodes for anime in your watchlist
- **Periodic Checking**: Configurable check intervals (1-168 hours)
- **Auto-Download**: Automatically download new episodes when detected
- **Manual Checks**: Trigger checks on-demand via API
- **Per-Anime Settings**: Configure auto-download, quality, and status per anime
- **Scheduler Management**: Start/stop the automatic scheduler

### Status Types
- **ACTIVE**: Currently tracking for new episodes
- **PAUSED**: Temporarily paused (won't check)
- **COMPLETED**: Anime completed, no longer tracking
- **ARCHIVED**: Archived but kept for history

## 🚀 Installation

### 1. Install APScheduler

The system requires APScheduler for scheduling:

```bash
# If using virtual environment (recommended)
source venv/bin/activate
pip install apscheduler==3.11.0

# Or add to requirements.txt and install
pip install -r requirements.txt
```

### 2. Configuration Files

The system uses JSON files for persistence:

```
config/
├── watchlist.json           # User watchlist items (auto-created)
├── watchlist_settings.json  # Global settings (auto-created)
└── .gitkeep
```

## 📚 API Endpoints

### Watchlist Management

#### Add Anime to Watchlist
```http
POST /api/watchlist
Content-Type: application/json
Authorization: Bearer <token>

{
  "anime_title": "Naruto Shippuden",
  "anime_url": "https://anime-sama.si/catalogue/naruto-shippuden/saison1/vostfr/",
  "provider_id": "animesama",
  "lang": "vostfr",
  "auto_download": true,
  "quality_preference": "auto",
  "poster_image": "https://...",
  "synopsis": "Ninja anime...",
  "genres": ["Action", "Adventure"]
}
```

#### Get User's Watchlist
```http
GET /api/watchlist?status=active
Authorization: Bearer <token>
```

#### Get Specific Item
```http
GET /api/watchlist/{item_id}
Authorization: Bearer <token>
```

#### Update Watchlist Item
```http
PUT /api/watchlist/{item_id}
Content-Type: application/json
Authorization: Bearer <token>

{
  "auto_download": false,
  "status": "paused",
  "last_episode_downloaded": 12
}
```

#### Delete from Watchlist
```http
DELETE /api/watchlist/{item_id}
Authorization: Bearer <token>
```

### Episode Checking

#### Check Specific Anime
```http
POST /api/watchlist/{item_id}/check
Authorization: Bearer <token>
```

#### Check All Due Items
```http
POST /api/watchlist/check-all
Authorization: Bearer <token>
```

### Pause/Resume

#### Pause Tracking
```http
POST /api/watchlist/{item_id}/pause
Authorization: Bearer <token>
```

#### Resume Tracking
```http
POST /api/watchlist/{item_id}/resume
Authorization: Bearer <token>
```

### Settings

#### Get Settings
```http
GET /api/watchlist/settings
Authorization: Bearer <token>
```

Response:
```json
{
  "check_interval_hours": 6,
  "auto_download_enabled": true,
  "max_concurrent_auto_downloads": 2,
  "notify_on_new_episodes": false,
  "include_completed_anime": false
}
```

#### Update Settings
```http
PUT /api/watchlist/settings
Content-Type: application/json
Authorization: Bearer <token>

{
  "check_interval_hours": 12,
  "auto_download_enabled": true
}
```

### Statistics

#### Get Watchlist Stats
```http
GET /api/watchlist/stats
Authorization: Bearer <token>
```

Response:
```json
{
  "total": 15,
  "active": 12,
  "paused": 2,
  "completed": 1,
  "auto_download_enabled": 12,
  "providers": {
    "animesama": 8,
    "nekosama": 5,
    "animeultime": 2
  }
}
```

### Scheduler Control

#### Get Scheduler Status
```http
GET /api/watchlist/scheduler/status
Authorization: Bearer <token>
```

Response:
```json
{
  "running": true,
  "next_run": "2026-01-29T18:00:00Z",
  "settings": { ... }
}
```

#### Start Scheduler
```http
POST /api/watchlist/scheduler/start
Authorization: Bearer <token>
```

#### Stop Scheduler
```http
POST /api/watchlist/scheduler/stop
Authorization: Bearer <token>
```

## 🏗️ Architecture

### Components

1. **WatchlistManager** (`app/watchlist.py`)
   - Manages watchlist storage (JSON-based)
   - CRUD operations for watchlist items
   - Settings management
   - Statistics and queries

2. **EpisodeChecker** (`app/episode_checker.py`)
   - Checks for new episodes
   - Downloads episodes automatically
   - Integrates with existing downloaders
   - Handles errors and retries

3. **AutoDownloadScheduler** (`app/auto_download_scheduler.py`)
   - APScheduler-based periodic checking
   - Configurable intervals
   - Start/stop control
   - Next run tracking

4. **Pydantic Models** (`app/models/watchlist.py`)
   - WatchlistItem
   - WatchlistItemCreate
   - WatchlistItemUpdate
   - WatchlistSettings
   - AutoDownloadResult

### Data Flow

```
User Request → API Endpoint → WatchlistManager → JSON Storage
                                                ↓
Scheduler (periodic) → EpisodeChecker → Downloaders → DownloadManager
```

## 💡 Usage Examples

### Example 1: Add Anime and Enable Auto-Download

```bash
curl -X POST "http://localhost:3000/api/watchlist" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anime_title": "Frieren",
    "anime_url": "https://anime-sama.si/catalogue/frieren/saison1/vostfr/",
    "provider_id": "animesama",
    "lang": "vostfr",
    "auto_download": true
  }'
```

### Example 2: Check All Animes Manually

```bash
curl -X POST "http://localhost:3000/api/watchlist/check-all" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example 3: Pause Tracking for an Anime

```bash
curl -X POST "http://localhost:3000/api/watchlist/ITEM_ID/pause" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example 4: Update Settings to Check Every 3 Hours

```bash
curl -X PUT "http://localhost:3000/api/watchlist/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "check_interval_hours": 3,
    "auto_download_enabled": true
  }'
```

## 🔧 Configuration

### Environment Variables

No special environment variables required. The system uses:

- `DOWNLOAD_DIR`: From app/config.py (default: "downloads")
- `MAX_PARALLEL_DOWNLOADS`: From app/config.py (default: 3)

### Settings

Settings are stored in `config/watchlist_settings.json`:

```json
{
  "check_interval_hours": 6,
  "auto_download_enabled": true,
  "max_concurrent_auto_downloads": 2,
  "notify_on_new_episodes": false,
  "include_completed_anime": false
}
```

## 🎨 Frontend Integration (TODO)

The UI components to be implemented:

1. **Watchlist Page** (`/watchlist`)
   - List of tracked anime
   - Status indicators
   - Pause/Resume buttons
   - Settings modal

2. **Add to Watchlist Button**
   - On anime search results
   - On anime detail pages
   - Quick-add with confirmation

3. **Settings Panel**
   - Global toggle for auto-download
   - Check interval selector
   - Scheduler controls

4. **Notifications**
   - New episode alerts
   - Download progress
   - Error notifications

## 🧪 Testing

### Manual Testing

```python
# Test adding to watchlist
from app.watchlist import watchlist_manager
from app.models.watchlist import WatchlistItemCreate

item_data = WatchlistItemCreate(
    anime_title="Test Anime",
    anime_url="https://anime-sama.si/catalogue/test/vostfr/",
    provider_id="animesama",
    lang="vostfr"
)
item = watchlist_manager.create("user_id", item_data)
print(f"Created: {item.id}")

# Test getting stats
stats = watchlist_manager.get_stats("user_id")
print(f"Stats: {stats}")
```

### API Testing

```bash
# Start the server
uvicorn main:app --reload

# Test endpoints
curl -X GET "http://localhost:3000/api/watchlist" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Start scheduler
curl -X POST "http://localhost:3000/api/watchlist/scheduler/start" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## 🔍 Troubleshooting

### Scheduler Not Running

1. Check scheduler status:
   ```bash
   curl "http://localhost:3000/api/watchlist/scheduler/status"
   ```

2. Check logs for APScheduler errors

3. Ensure APScheduler is installed:
   ```bash
   pip list | grep apscheduler
   ```

### Episodes Not Downloading

1. Verify auto_download is enabled:
   ```json
   {
     "auto_download": true,
     "status": "active"
   }
   ```

2. Check global settings:
   ```json
   {
     "auto_download_enabled": true
   }
   ```

3. Check download manager has capacity

### Circular Import Errors

The system uses lazy initialization to avoid circular imports:
- `EpisodeChecker.set_download_manager()` is called by `main.py`
- Do not import `download_manager` directly in other modules

## 📊 Future Enhancements

Potential improvements:

1. **Notifications**: Email, Telegram, Discord alerts
2. **Quality Selection**: Choose 1080p/720p/480p per anime
3. **Smart Detection**: Detect completed anime automatically
4. **Batch Operations**: Add multiple anime at once
5. **Calendar View**: Visual schedule of episode releases
6. **Statistics Dashboard**: Charts of download history
7. **RSS Feeds**: Generate RSS feeds for watchlist
8. **Watchlist Sharing**: Share lists between users

## 📝 Notes

- The scheduler runs in the background and is started/stopped via API
- All operations are per-user (multi-tenant)
- Failed downloads are logged but don't stop the scheduler
- The system is resilient to temporary network failures
- Watchlist data is persisted in JSON format for easy backup