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:

# 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

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

GET /api/watchlist?status=active
Authorization: Bearer <token>

Get Specific Item

GET /api/watchlist/{item_id}
Authorization: Bearer <token>

Update Watchlist Item

PUT /api/watchlist/{item_id}
Content-Type: application/json
Authorization: Bearer <token>

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

Delete from Watchlist

DELETE /api/watchlist/{item_id}
Authorization: Bearer <token>

Episode Checking

Check Specific Anime

POST /api/watchlist/{item_id}/check
Authorization: Bearer <token>

Check All Due Items

POST /api/watchlist/check-all
Authorization: Bearer <token>

Pause/Resume

Pause Tracking

POST /api/watchlist/{item_id}/pause
Authorization: Bearer <token>

Resume Tracking

POST /api/watchlist/{item_id}/resume
Authorization: Bearer <token>

Settings

Get Settings

GET /api/watchlist/settings
Authorization: Bearer <token>

Response:

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

Update Settings

PUT /api/watchlist/settings
Content-Type: application/json
Authorization: Bearer <token>

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

Statistics

Get Watchlist Stats

GET /api/watchlist/stats
Authorization: Bearer <token>

Response:

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

Scheduler Control

Get Scheduler Status

GET /api/watchlist/scheduler/status
Authorization: Bearer <token>

Response:

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

Start Scheduler

POST /api/watchlist/scheduler/start
Authorization: Bearer <token>

Stop Scheduler

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

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

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

Example 3: Pause Tracking for an Anime

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

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:

{
  "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

# 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

# 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:

   curl "http://localhost:3000/api/watchlist/scheduler/status"
   

2. Check logs for APScheduler errors

3. Ensure APScheduler is installed:

   pip list | grep apscheduler
   

Episodes Not Downloading

1. Verify auto_download is enabled:

   {
     "auto_download": true,
     "status": "active"
   }
   

2. Check global settings:

   {
     "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