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:

   curl http://localhost:5000/api/admin/export
   

Import Fails

Check JSON format:

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