initial comment
This commit is contained in:
707
DASHBOARD-API.md
Normal file
707
DASHBOARD-API.md
Normal file
@@ -0,0 +1,707 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user