encoderPro/DASHBOARD-API.md

# encoderPro Dashboard API Reference

## Overview

The encoderPro dashboard provides a RESTful API for monitoring and controlling the encoding system. All endpoints return JSON responses with a consistent format:

```json
{
  "success": true,
  "data": { ... }
}
```

Or on error:
```json
{
  "success": false,
  "error": "Error message"
}
```

---

## Auto-Initialization

The dashboard automatically initializes the database on first run if it doesn't exist. No manual setup required!

**On first start:**
1. Dashboard creates empty database at `/db/state.db`
2. Database schema is created automatically
3. Dashboard is ready to use
4. Run a library scan to populate database

---

## API Endpoints

### Health & Status

#### `GET /api/health`
Health check with database status.

**Response:**
```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "3.1.0",
    "timestamp": "2025-12-19T18:45:00.000Z",
    "database": {
      "exists": true,
      "path": "/db/state.db",
      "file_count": 1250,
      "needs_scan": false
    }
  }
}
```

**Use cases:**
- Check if dashboard is running
- Check if database exists
- Check if library scan is needed
- Monitor file count

---

### Statistics

#### `GET /api/stats`
Get processing statistics.

**Response:**
```json
{
  "success": true,
  "data": {
    "pending": 850,
    "processing": 2,
    "completed": 145,
    "failed": 3,
    "skipped": 250,
    "original_size": 4500000000000,
    "encoded_size": 2200000000000,
    "space_saved": 2300000000000,
    "space_saved_percent": 51.1,
    "avg_fps": 8.5,
    "avg_encode_time": 3600,
    "encoder_usage": {
      "cpu_x265": 100,
      "nvidia_nvenc_h265": 45
    },
    "completed_24h": 12
  }
}
```

---

### Files

#### `GET /api/files`
Get list of files with filtering.

**Query Parameters:**
- `state` (optional): Filter by state (`pending`, `processing`, `completed`, `failed`, `skipped`)
- `limit` (optional): Number of results (default: 100)
- `offset` (optional): Pagination offset (default: 0)
- `search` (optional): Search in file paths

**Examples:**
```
GET /api/files?state=pending&limit=50
GET /api/files?search=action&limit=20
GET /api/files?offset=100&limit=100
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "filepath": "/movies/example.mkv",
      "relative_path": "example.mkv",
      "state": "completed",
      "has_subtitles": true,
      "original_size": 5000000000,
      "encoded_size": 2500000000,
      "subtitle_count": 2,
      "profile_name": "sweetspot_cpu",
      "encoder_used": "cpu_x265",
      "encode_time_seconds": 3600,
      "fps": 8.5,
      "created_at": "2025-12-19T10:00:00",
      "completed_at": "2025-12-19T11:00:00"
    }
  ]
}
```

---

#### `GET /api/file/<id>`
Get single file details.

**Response:**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "filepath": "/movies/example.mkv",
    "state": "completed",
    ...
  }
}
```

---

### Activity

#### `GET /api/activity`
Get recent file activity (completed/failed).

**Query Parameters:**
- `limit` (optional): Number of results (default: 20)

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "relative_path": "example.mkv",
      "state": "completed",
      "updated_at": "2025-12-19T11:00:00",
      "encoder_used": "cpu_x265",
      "fps": 8.5
    }
  ]
}
```

---

### Processing Status

#### `GET /api/processing`
Get currently processing files.

**Response:**
```json
{
  "success": true,
  "data": {
    "active": true,
    "files": [
      {
        "id": 2,
        "relative_path": "movie2.mkv",
        "started_at": "2025-12-19T18:30:00",
        "profile_name": "sweetspot_cpu"
      }
    ]
  }
}
```

---

### System Monitoring

#### `GET /api/system`
Get system resource statistics.

**Response:**
```json
{
  "success": true,
  "data": {
    "gpu": [
      {
        "index": 0,
        "name": "NVIDIA GeForce RTX 4090",
        "utilization": 85,
        "memory_used": 8192,
        "memory_total": 24576,
        "temperature": 72
      }
    ],
    "cpu": {
      "load_1m": 4.5,
      "load_5m": 3.8,
      "load_15m": 3.2,
      "cpu_count": 48,
      "load_percent": 9.4
    },
    "disk": {
      "work_total": 1000000000000,
      "work_used": 250000000000,
      "work_free": 750000000000,
      "work_percent": 25.0
    }
  }
}
```

---

### Job Control

#### `POST /api/jobs/start`
Start processing job.

**Request Body:**
```json
{
  "profile": "sweetspot_cpu",
  "dry_run": false
}
```

**Response:**
```json
{
  "success": true,
  "message": "Processing started",
  "dry_run": false
}
```

---

#### `POST /api/jobs/stop`
Stop processing job.

**Response:**
```json
{
  "success": true,
  "message": "Processing stopped"
}
```

---

#### `POST /api/jobs/scan`
Scan library to populate database.

**Response:**
```json
{
  "success": true,
  "message": "Library scan started"
}
```

**Use cases:**
- Initial library scan
- Refresh library after adding new files
- Re-scan if files were added manually

---

#### `POST /api/jobs/reencode-selected`
Queue selected files for re-encoding with specified profile.

**Request Body:**
```json
{
  "file_ids": [1, 5, 12, 23],
  "profile": "quality_cpu"
}
```

**Response:**
```json
{
  "success": true,
  "message": "4 files queued for re-encoding",
  "count": 4
}
```

**Use cases:**
- Re-encode specific files with different quality settings
- Re-process failed files with a different profile
- Upgrade completed files to higher quality

**Notes:**
- Resets file state from 'completed' or 'failed' to 'pending'
- Sets the profile_name for each file
- Files will be processed when the job is started

---

### Logs

#### `GET /api/logs`
Get recent log entries.

**Query Parameters:**
- `lines` (optional): Number of lines (default: 100)

**Response:**
```json
{
  "success": true,
  "data": [
    "2025-12-19 18:45:00 - INFO - Processing started",
    "2025-12-19 18:45:01 - INFO - Encoding example.mkv",
    ...
  ]
}
```

---

### Configuration

#### `GET /api/config`
Get current configuration.

**Response:**
```json
{
  "success": true,
  "data": {
    "movies_dir": "/movies",
    "archive_dir": "/archive",
    "parallel": {
      "max_workers": 8,
      "cpu_slots": 24
    },
    "profiles": {
      "default": "sweetspot_cpu",
      "definitions": { ... }
    },
    "quality_check": {
      "enabled": true,
      "warn_threshold": 10.0,
      "error_threshold": 20.0,
      "skip_on_degradation": false
    }
  }
}
```

---

#### `POST /api/config`
Save configuration.

**Request Body:** (full config object)
```json
{
  "movies_dir": "/movies",
  "archive_dir": "/archive",
  "quality_check": {
    "enabled": true,
    "warn_threshold": 15.0
  },
  ...
}
```

**Response:**
```json
{
  "success": true,
  "message": "Configuration saved successfully",
  "data": { ... }
}
```

**Notes:**
- Creates backup before saving (`config.yaml.backup`)
- Validates required fields
- Returns validation errors if invalid

---

#### `POST /api/config/validate`
Validate configuration without saving.

**Request Body:** (config object to validate)

**Response:**
```json
{
  "success": true,
  "data": {
    "valid": true,
    "errors": [],
    "warnings": [
      "max_workers=12 is very high, may cause system instability"
    ]
  }
}
```

---

### Profiles

#### `GET /api/profiles`
Get available encoding profiles.

**Response:**
```json
{
  "success": true,
  "data": {
    "default": "sweetspot_cpu",
    "profiles": {
      "sweetspot_cpu": {
        "encoder": "cpu_x265",
        "preset": "slow",
        "quality": 21,
        "description": "Perfect balance..."
      },
      "balanced_cpu": {
        "encoder": "cpu_x265",
        "preset": "medium",
        "quality": 23
      }
    }
  }
}
```

---

### Encoders

#### `GET /api/encoders`
Get available encoders on the system.

**Response:**
```json
{
  "success": true,
  "data": {
    "cpu": {
      "x265": true,
      "x264": true
    },
    "nvidia": {
      "nvenc_h265": true,
      "nvenc_h264": true
    },
    "intel": {
      "qsv_h265": false,
      "qsv_h264": false
    },
    "amd": {
      "vaapi_h265": false,
      "vaapi_h264": false
    }
  }
}
```

---

### Directory Validation

#### `POST /api/directories/validate`
Validate directory paths.

**Request Body:**
```json
{
  "paths": {
    "movies": "/movies",
    "archive": "/archive",
    "work": "/work"
  }
}
```

**Response:**
```json
{
  "success": true,
  "data": {
    "movies": {
      "path": "/movies",
      "exists": true,
      "is_directory": true,
      "is_writable": false,
      "is_readable": true
    },
    "archive": {
      "path": "/archive",
      "exists": true,
      "is_directory": true,
      "is_writable": true,
      "is_readable": true
    }
  }
}
```

---

## Workflow Examples

### Initial Setup

```bash
# 1. Start dashboard (auto-creates database)
docker exec encoderpro python3 /app/dashboard.py

# 2. Check health
curl http://localhost:5000/api/health

# 3. Trigger library scan via API
curl -X POST http://localhost:5000/api/jobs/scan

# 4. Monitor scan progress
curl http://localhost:5000/api/stats
```

---

### Start Processing

```bash
# Start with default profile
curl -X POST http://localhost:5000/api/jobs/start \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false}'

# Start with specific profile
curl -X POST http://localhost:5000/api/jobs/start \
  -H "Content-Type: application/json" \
  -d '{"profile": "quality_cpu", "dry_run": false}'
```

---

### Monitor Progress

```bash
# Get statistics
curl http://localhost:5000/api/stats

# Get currently processing files
curl http://localhost:5000/api/processing

# Get recent activity
curl http://localhost:5000/api/activity?limit=10

# View logs
curl http://localhost:5000/api/logs?lines=50
```

---

### Update Configuration

```bash
# Get current config
curl http://localhost:5000/api/config > config.json

# Edit config.json

# Validate changes
curl -X POST http://localhost:5000/api/config/validate \
  -H "Content-Type: application/json" \
  -d @config.json

# Save if valid
curl -X POST http://localhost:5000/api/config \
  -H "Content-Type: application/json" \
  -d @config.json
```

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `STATE_DB` | `/db/state.db` | Database file path |
| `LOG_DIR` | `/logs` | Log directory |
| `CONFIG_FILE` | `/config/config.yaml` | Config file path |
| `REENCODE_SCRIPT` | `/app/reencode-v3.py` | Main script path |
| `DASHBOARD_HOST` | `0.0.0.0` | Dashboard bind address |
| `DASHBOARD_PORT` | `5000` | Dashboard port |
| `DASHBOARD_DEBUG` | `false` | Enable debug mode |

---

## Error Handling

All endpoints follow consistent error handling:

**404 - Not Found:**
```json
{
  "success": false,
  "error": "File not found"
}
```

**500 - Server Error:**
```json
{
  "success": false,
  "error": "Database connection failed"
}
```

**400 - Bad Request:**
```json
{
  "success": false,
  "error": "Missing required field: movies_dir"
}
```

---

## WebSocket Support (Future)

Real-time updates will be added via WebSocket in a future version:
- Live encoding progress
- Real-time log streaming
- File state changes
- System resource updates

---

## Security Considerations

**Current version (3.1.0):**
- No authentication (intended for private networks)
- CORS enabled for all origins
- No HTTPS (use reverse proxy if needed)

**Recommendations:**
- Run behind reverse proxy (nginx, Traefik)
- Use firewall to restrict access
- Enable HTTPS at reverse proxy level
- Consider adding basic auth if exposed

---

## Summary

The dashboard provides a complete REST API for:
- ✅ Auto-initializing database
- ✅ Monitoring processing status
- ✅ Controlling encoding jobs
- ✅ Viewing system resources
- ✅ Managing configuration
- ✅ Triggering library scans
- ✅ Viewing logs and activity

No manual database setup required - just start the dashboard and it's ready to use!