loreal-video-optimizer/ADMIN_GUIDE.md

# Admin Panel Guide

## Overview

The Admin Panel allows you to manage platform specifications, add new platforms, edit existing configurations, and import/export settings.

**Access:** http://localhost:8888/admin.html (or http://localhost:8000/admin.html for standard setup)

---

## Features

### 📊 Metrics Dashboard

View real-time statistics:
- **Total Platforms** - Number of configured platforms
- **Total Configurations** - Total format combinations across all platforms
- **Unique Codecs** - Number of different codecs in use
- **Aspect Ratios** - Total unique aspect ratios supported

### 🎛 Platform Management

**View All Platforms:**
- See all configured platforms with their specifications
- Each platform shows: Name, Key, Codec, Format count
- Detailed table of all aspect ratios with resolutions and bitrates

**Add New Platform:**
1. Click **"+ Add New Platform"**
2. Fill in platform details:
   - **Platform Key** (lowercase, no spaces - used in API)
   - **Platform Name** (display name)
   - **Video Codec** (H264, H265, or VP9)
   - **Container Format** (MP4, WebM, MOV)
3. Add format configurations (aspect ratios):
   - Aspect Ratio (e.g., 16:9)
   - Resolution (e.g., 1920x1080)
   - Bitrate (recommended, e.g., 1500k)
   - Min/Max Bitrate (range)
   - Audio Bitrate (e.g., 128k)
   - Audio Codec (optional - defaults to AAC)
   - Note (optional)
4. Click **"+ Add Format Configuration"** for multiple aspect ratios
5. Click **"Save Platform"**

**Edit Platform:**
1. Click **"Edit"** button on any platform card
2. Modify settings (platform key cannot be changed)
3. Add/remove format configurations
4. Click **"Save Platform"**

**Delete Platform:**
1. Click **"Delete"** button on any platform card
2. Confirm deletion
3. Platform is removed from system

### 📤 Export/Import

**Export Specifications:**
- Click **"Export Specs (JSON)"**
- Downloads `platform_specs_YYYY-MM-DD.json` file
- Contains all platform configurations
- Use for backups or sharing

**Import Specifications:**
- Click **"Import Specs (JSON)"**
- Select a previously exported JSON file
- Replaces ALL current specifications
- Use for restoring backups or bulk updates

**Reload from Server:**
- Click **"Reload from Server"**
- Refreshes display with current backend data
- Use after manual changes or testing

---

## Example: Adding a New Platform

### Scenario: Add Instagram Reels

**Platform Details:**
- **Key:** `instagram_reels`
- **Name:** `Instagram Reels`
- **Codec:** `libx264` (H264)
- **Container:** `mp4`

**Format Configuration:**
- **Aspect Ratio:** `9:16`
- **Resolution:** `1080x1920`
- **Bitrate:** `2500k`
- **Min Bitrate:** `2000k`
- **Max Bitrate:** `3000k`
- **Audio Bitrate:** `128k`
- **Audio Codec:** `aac`
- **Note:** `Optimized for Instagram Reels`

After saving, the platform will be immediately available in the main app!

---

## Data Persistence

### How Specs Are Saved

When you add, edit, or delete platforms:

1. Changes are applied to **in-memory** PLATFORM_SPECS
2. Automatically saved to **backend/platform_specs.json**
3. File is loaded on server startup
4. Changes persist across server restarts

### File Location

```
backend/platform_specs.json
```

This file is auto-generated and excluded from Git (.gitignore).

### Backup Strategy

**Recommended:**
1. Regularly **export specs** via Admin Panel
2. Save exported JSON files with date stamps
3. Store backups in version control or cloud storage
4. Import when needed to restore

---

## Platform Key Naming

Platform keys are used in:
- API endpoints
- Filename detection
- Internal references

**Rules:**
- Lowercase only
- No spaces (use underscores)
- Unique across all platforms
- Cannot be changed after creation

**Good examples:**
- `tiktok`
- `meta`
- `youtube_ctv`
- `amazon_prime`

**Bad examples:**
- `TikTok` (uppercase)
- `YouTube CTV` (spaces)
- `meta-fb` (hyphens - use underscores)

---

## Format Configuration Details

### Required Fields

- **Aspect Ratio** - Format ratio (e.g., 16:9, 1:1, 9:16)
- **Resolution** - Width x Height (e.g., 1920x1080)
- **Bitrate** - Recommended video bitrate (e.g., 1500k)
- **Min Bitrate** - Minimum acceptable bitrate
- **Max Bitrate** - Maximum acceptable bitrate
- **Audio Bitrate** - Audio bitrate (e.g., 128k)

### Optional Fields

- **Audio Codec** - Override default audio codec (aac, opus, etc.)
- **Note** - Special instructions or warnings

### Bitrate Format

Use FFmpeg bitrate notation:
- `1500k` = 1500 kbps
- `15000k` = 15 Mbps
- `128k` = 128 kbps

---

## Codec Reference

### Video Codecs

| Codec Value | Display Name | Best For | Notes |
|-------------|--------------|----------|-------|
| `libx264` | H264 | Universal compatibility | Most widely supported |
| `libx265` | H265/HEVC | Better compression | TikTok recommended |
| `libvpx-vp9` | VP9 | Quality & efficiency | YouTube preferred |

### Container Formats

| Container | Extensions | Compatible Codecs |
|-----------|-----------|-------------------|
| `mp4` | .mp4 | H264, H265 |
| `webm` | .webm | VP9 |
| `mov` | .mov | H264, H265 |

### Audio Codecs

- `aac` - Default, universal (for MP4)
- `opus` - High quality (for WebM/VP9)
- `mp3` - Legacy support

---

## Validation

The system validates:
- ✅ Duplicate platform keys (prevented)
- ✅ Required fields present
- ✅ Format array not empty
- ✅ Valid bitrate formats

**Not automatically validated:**
- Resolution format (ensure it's `WIDTHxHEIGHT`)
- Aspect ratio accuracy
- Codec compatibility with container

---

## API Endpoints

Admin endpoints require backend access:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/admin/platforms` | POST | Add new platform |
| `/api/admin/platforms/<key>` | PUT | Update platform |
| `/api/admin/platforms/<key>` | DELETE | Delete platform |
| `/api/admin/export` | GET | Export all specs as JSON |
| `/api/admin/import` | POST | Import specs from JSON |

---

## Troubleshooting

### Changes Not Showing in Main App

1. **Click "Reload from Server"** in Admin Panel
2. **Refresh** main app page (hard reload: Cmd+Shift+R)
3. **Check backend logs** for save errors
4. **Verify** platform_specs.json was updated

### Export Not Working

1. Check browser allows downloads
2. Check browser console (F12) for errors
3. Verify backend `/api/admin/export` endpoint works:
   ```bash
   curl http://localhost:5000/api/admin/export
   ```

### Import Fails

**Check JSON format:**
```json
{
  "platform_key": {
    "name": "Platform Name",
    "codec": "libx264",
    "container": "mp4",
    "formats": [
      {
        "ratio": "16:9",
        "size": "1920x1080",
        "bitrate": "1500k",
        "bitrate_min": "1300k",
        "bitrate_max": "1700k",
        "audio": "128k"
      }
    ]
  }
}
```

### Platform Key Can't Be Changed

Platform keys are immutable after creation to prevent breaking:
- Filename detection patterns
- API references
- Existing configurations

**Solution:** Delete and recreate platform with new key

---

## Best Practices

1. **Export regularly** - Create backups before major changes
2. **Test new platforms** - Verify conversions work after adding
3. **Use descriptive keys** - Clear, lowercase identifiers
4. **Document notes** - Add notes for unusual configurations
5. **Validate ranges** - Ensure min ≤ recommended ≤ max bitrates

---

## Security Note

**Current Setup:**
- Admin panel has **NO authentication**
- Suitable for **local development only**
- For production: Add authentication layer

**Production Recommendations:**
- Implement login system
- Use environment variables for credentials
- Restrict admin endpoints to authenticated users
- Add audit logging for changes

---

## Quick Reference

### Adding Platform Checklist

- [ ] Click "Add New Platform"
- [ ] Enter platform key (lowercase, unique)
- [ ] Enter platform name (display)
- [ ] Select codec
- [ ] Select container
- [ ] Add at least one format configuration
- [ ] Verify bitrate ranges
- [ ] Save platform
- [ ] Test in main app

### Editing Platform Checklist

- [ ] Click "Edit" on platform card
- [ ] Modify settings
- [ ] Add/remove format configurations
- [ ] Save changes
- [ ] Reload main app to see changes

---

**Access Admin Panel:** Add `/admin.html` to your frontend URL

**Repository:** https://bitbucket.org/zlalani/loreal-video-optimizer