ckoch/encoderPro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
encoderPro/DASHBOARD-API.md
Christopher Koch fe40adfd38 initial comment
2026-01-24 17:43:28 -05:00

12 KiB
Raw Permalink Blame History

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:

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

Or on error:

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

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

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

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

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

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

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

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

{
  "profile": "sweetspot_cpu",
  "dry_run": false
}

Response:

{
  "success": true,
  "message": "Processing started",
  "dry_run": false
}

POST /api/jobs/stop

Stop processing job.

Response:

{
  "success": true,
  "message": "Processing stopped"
}

POST /api/jobs/scan

Scan library to populate database.

Response:

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

{
  "file_ids": [1, 5, 12, 23],
  "profile": "quality_cpu"
}

Response:

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

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

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

{
  "movies_dir": "/movies",
  "archive_dir": "/archive",
  "quality_check": {
    "enabled": true,
    "warn_threshold": 15.0
  },
  ...
}

Response:

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

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

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

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

{
  "paths": {
    "movies": "/movies",
    "archive": "/archive",
    "work": "/work"
  }
}

Response:

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

# 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

# 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

# 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

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

{
  "success": false,
  "error": "File not found"
}

500 - Server Error:

{
  "success": false,
  "error": "Database connection failed"
}

400 - Bad Request:

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

Reference in New Issue View Git Blame Copy Permalink