encoderPro/DASHBOARD-GUIDE.md

# Enhanced Dashboard with Configuration UI - Complete Guide

## 🎉 What's New

The dashboard now includes **full configuration management**:

### ✨ New Features

1. **Configuration Editor**
   - Edit directory paths (movies, archive, work)
   - Adjust parallel processing settings
   - Toggle processing options
   - Real-time validation

2. **Profile Management**
   - Create custom encoding profiles
   - Edit existing profiles
   - Set default profile
   - Delete unused profiles

3. **Enhanced Job Control**
   - **Dry Run Mode** - Test without encoding
   - Profile selection per job
   - Visual status indicators

4. **Three-Tab Interface**
   - **Dashboard** - Monitoring and control
   - **Configuration** - System settings
   - **Profiles** - Encoding presets

## 🚀 Quick Start

```bash
# Start dashboard
docker-compose up -d dashboard

# Access at
http://YOUR-SERVER:5000
```

## 📋 Dashboard Tab (Monitoring & Control)

### Job Control Panel
- **Profile Selector**: Choose encoding profile for this run
- **Dry Run Checkbox**: Enable to scan only (no encoding)
- **Start Button**: Begin processing with selected options
- **Stop Button**: Gracefully stop current jobs
- **Refresh Button**: Manual data refresh
- **Status Badge**: Shows Idle or Processing

### Statistics Cards
- **Pending**: Files waiting to process
- **Processing**: Currently encoding
- **Completed**: Successfully processed
- **Failed**: Encoding errors
- **Skipped**: Files without subtitles

### Progress Overview
- Visual progress bar
- Original vs encoded sizes
- Space saved with percentage
- Average encoding FPS

### System Monitoring
- GPU utilization, memory, temperature
- CPU load average
- Real-time updates every 5 seconds

### Recent Activity
- Last 10 processed files
- Success/failure indicators
- Encoder used and FPS

### Live Logs
- Streaming log output
- Color-coded messages
- Auto-scrolls to latest

## ⚙️ Configuration Tab

### Directory Settings

**Movies Directory**
```
/mnt/user/movies
```
- Source directory containing your movie library
- Must exist and be readable

**Archive Directory**
```
/mnt/user/archive/movies
```
- Where original files are stored after re-encoding
- Will be created if doesn't exist

**Work Directory**
```
/mnt/user/temp/encoderpro-work
```
- Temporary encoding directory
- Should be on fast storage (SSD preferred)
- Needs space for largest movie file

### Parallel Processing Settings

**Max Workers** (1-10)
- Number of concurrent encoding jobs
- Recommended: 1-2 for GPU, 2-4 for CPU

**GPU Slots** (0-5)
- How many jobs can use GPU simultaneously
- Recommended: 1 for single GPU, 2 for high-end GPUs

**CPU Slots** (1-32)
- CPU threads available per job
- Recommended: Half of physical cores

### Processing Options

**✓ Skip files without subtitles**
- Automatically skip files that don't have subtitle streams
- Saves time by not processing unnecessary files

**✓ Cleanup stale work files**
- Remove abandoned work files on startup
- Keeps work directory clean

**✓ Prefer GPU encoders**
- Use GPU encoding when available
- Much faster than CPU

**✓ Fallback to CPU**
- Use CPU encoding if GPU fails
- Ensures processing continues

### Configuration Actions

**✓ Validate**
- Check configuration for errors
- Shows warnings and suggestions
- **Always validate before saving**

**💾 Save**
- Write configuration to file
- Creates backup of existing config
- Takes effect immediately

**🔄 Reload**
- Discard changes and reload from file
- Useful to undo modifications

## 🎯 Profiles Tab

### What are Profiles?

Profiles define encoding settings:
- **Encoder**: Hardware (NVENC, QSV) or software (CPU)
- **Preset**: Speed vs quality trade-off
- **Quality**: CRF/CQ value (lower = better)
- **Audio**: Copy or re-encode

### Built-in Profiles

| Profile | Encoder | Use Case |
|---------|---------|----------|
| balanced_gpu | NVENC H.265 | Best for most users |
| fast_gpu | NVENC H.264 | Quick processing |
| quality_gpu | NVENC H.265 | Archival quality |
| balanced_cpu | CPU H.265 | No GPU available |

### Managing Profiles

**Add Profile**
1. Click "➕ Add" button
2. Enter profile name (e.g., "my_profile")
3. Select encoder type
4. Set preset (p1-p7 for NVENC, ultrafast-veryslow for CPU)
5. Set quality (18-28 recommended)
6. Choose audio codec
7. Click "💾 Save"

**Edit Profile**
1. Click "✏️ Edit" on existing profile
2. Modify settings
3. Click "💾 Save"

**Delete Profile**
1. Click "🗑️ Delete"
2. Confirm deletion

**Set Default Profile**
1. Select profile from "Default Profile" dropdown
2. Click "💾 Save All Profiles"

### Encoder Options

**NVIDIA NVENC**
- `nvidia_nvenc_h265` - H.265 (recommended)
- `nvidia_nvenc_h264` - H.264 (faster, larger)
- Presets: p1 (fastest) to p7 (slowest)
- Quality: 20-25 recommended

**CPU Encoders**
- `cpu_x265` - H.265 (best compression)
- `cpu_x264` - H.264 (faster)
- Presets: ultrafast, fast, medium, slow, veryslow
- Quality: 18-24 recommended

**Intel QSV**
- `intel_qsv_h265` - H.265
- `intel_qsv_h264` - H.264
- Presets: fast, medium, slow

**AMD VAAPI**
- `amd_vaapi_h265` - H.265
- `amd_vaapi_h264` - H.264

## 🎮 Using Dry Run Mode

### What is Dry Run?

Dry run scans your library without encoding:
- Detects subtitle streams
- Updates database
- Shows what would be processed
- **No files are modified**

### When to Use Dry Run

1. **Initial Setup**
   - Test configuration before processing
   - See how many files need processing
   - Verify directory paths

2. **After Adding Movies**
   - Scan for new files
   - Update database
   - Plan processing time

3. **Testing Settings**
   - Check if subtitles detected correctly
   - Verify file extensions recognized

### How to Use

1. Go to **Dashboard** tab
2. Check **"Dry Run (Scan Only)"**
3. Select profile (optional)
4. Click **"▶ Start"**
5. Watch statistics update
6. Review results in activity log

### After Dry Run

- Check **Pending** count - files that will be processed
- Check **Skipped** count - files without subtitles
- Review **Statistics** to plan processing time
- Uncheck "Dry Run" and run for real

## 🔧 Common Workflows

### First-Time Setup

```
1. Open http://YOUR-SERVER:5000
2. Go to Configuration tab
3. Set directory paths
4. Click "✓ Validate"
5. Fix any errors shown
6. Click "💾 Save"
7. Go to Profiles tab
8. Review default profiles
9. Go to Dashboard tab
10. Enable "Dry Run"
11. Click "▶ Start"
12. Review results
13. Disable "Dry Run"
14. Click "▶ Start" to process
```

### Adding Custom Profile

```
1. Go to Profiles tab
2. Click "➕ Add"
3. Name: "my_quality"
4. Encoder: nvidia_nvenc_h265
5. Preset: p6
6. Quality: 20
7. Audio: copy
8. Click "💾 Save"
9. Set as default if desired
10. Click "💾 Save All Profiles"
```

### Processing with Custom Settings

```
1. Go to Dashboard tab
2. Select profile from dropdown
3. Optionally enable "Dry Run" first
4. Click "▶ Start"
5. Monitor progress in real-time
6. Click "⏹ Stop" if needed
```

### Changing Parallel Workers

```
1. Go to Configuration tab
2. Adjust "Max Workers" (try 1 first)
3. Adjust "GPU Slots" (1 for most GPUs)
4. Click "✓ Validate"
5. Click "💾 Save"
6. Restart dashboard container if needed
```

## 📊 Configuration Examples

### Conservative (Safe for all systems)
```yaml
Max Workers: 1
GPU Slots: 1
CPU Slots: 4
Profile: balanced_gpu
```

### Balanced (Recommended)
```yaml
Max Workers: 2
GPU Slots: 1
CPU Slots: 4
Profile: balanced_gpu
```

### High Throughput (Powerful systems)
```yaml
Max Workers: 3
GPU Slots: 2
CPU Slots: 8
Profile: fast_gpu
```

### CPU Only (No GPU)
```yaml
Max Workers: 2
GPU Slots: 0
CPU Slots: 4
Profile: balanced_cpu
```

## 🔍 Validation Messages

### ✓ Success
```
Configuration is valid!
```
All settings are correct, safe to save.

### ⚠️ Warnings
```
Warning: Movies directory does not exist
Warning: max_workers=5 is very high
```
Not critical but should be reviewed.

### ✗ Errors
```
Error: Missing required field: movies_dir
Error: max_workers must be at least 1
```
Must be fixed before saving.

## 🎨 UI Tips

### Color Coding
- **Green** - Completed, success, active
- **Blue** - Processing, info
- **Yellow** - Pending, warnings
- **Red** - Failed, errors
- **Gray** - Skipped, idle

### Keyboard Shortcuts
- **Ctrl+R** - Refresh page
- **Tab** - Navigate between fields
- **Enter** - Submit forms (in modals)
- **Esc** - Close modals

### Mobile Access
- Dashboard is fully responsive
- Works on tablets and phones
- All features available
- Touch-friendly buttons

## 🐛 Troubleshooting

### Configuration Won't Save
**Check:**
- All required fields filled
- Paths exist or can be created
- No validation errors
- Dashboard has write permissions

### Profiles Not Appearing
**Solution:**
1. Go to Profiles tab
2. Check if profiles list is empty
3. Click "🔄 Reload" in Configuration
4. Profiles may be in config file but not loaded

### Dry Run Doesn't Update Stats
**Wait:**
- Dry run takes time to scan
- Refresh happens every 5 seconds
- Check logs for progress
- May take minutes for large libraries

### GPU Not Available in Profiles
**Check:**
1. Go to browser console (F12)
2. Check for encoder detection errors
3. Verify nvidia-smi works in container
4. May need to restart dashboard

### Changes Not Taking Effect
**Solution:**
1. Save configuration
2. Stop any active processing
3. Restart dashboard container:
   ```bash
   docker-compose restart dashboard
   ```

## 📱 API Access

The dashboard provides REST API for automation:

### Get Configuration
```bash
curl http://localhost:5000/api/config
```

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

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

### Get Profiles
```bash
curl http://localhost:5000/api/profiles
```

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

## 🎓 Best Practices

1. **Always validate before saving**
2. **Use dry run for new configurations**
3. **Start with max_workers=1**
4. **Create custom profiles for different quality needs**
5. **Monitor first few files closely**
6. **Keep original config as backup**
7. **Test profile on one file before batch**
8. **Check logs for errors regularly**

## 🚀 Next Steps

1. ✓ Configure directories
2. ✓ Validate configuration
3. ✓ Test with dry run
4. ✓ Create custom profiles if needed
5. ✓ Process a few test files
6. ✓ Review quality and speed
7. ✓ Adjust settings as needed
8. ✓ Set up scheduled processing
9. ✓ Bookmark dashboard URL
10. ✓ Enjoy automated encoding!

## 📚 Summary

You now have a **complete web-based management system** for your media encoding:

- ✅ Real-time monitoring
- ✅ Configuration editor
- ✅ Profile management
- ✅ Dry run mode
- ✅ Job control
- ✅ Live system stats
- ✅ Activity tracking
- ✅ Log streaming

**Access:** `http://YOUR-SERVER:5000`

**No more editing YAML files manually!**