loreal-video-optimizer/README.md

Video Optimizer for Social Media Platforms

L'Oréal Creative Optimization Tool - Based on L'Oréal CDMO Creative Optimization Documentation v1.1

Overview

This application optimizes video files for various social media platforms using platform-specific codecs and bitrate recommendations to minimize file sizes while maintaining quality.

Key Features

• 21 Platform Configurations across 8 social media platforms
• Automatic filename detection for platform and aspect ratio
• Side-by-side video comparison with synchronized playback
• Independent mute controls for each video player
• Detailed video specifications display (codec, bitrate, resolution, etc.)
• Aspect ratio mismatch warnings with visual indicators
• FFmpeg-powered conversion with optimal codec settings
• File size reduction tracking with percentage display
• Drag & drop interface with progress indication

---

Supported Platforms

Platform	Codec	Aspect Ratios	Bitrate Range	Notes
Meta (Facebook/Instagram)	H264	1:1, 16:9, 4:5, 9:16	840-1400 kbps	Mobile optimized
Pinterest	H264	1:1, 16:9, 2:3, 4:5, 9:16	1100-1690 kbps	2:3 for inspiration boards
Snapchat	H264	16:9, 9:16	1100-1400 kbps	Stories format
TikTok	H265	1:1, 16:9, 9:16	840-1300 kbps	Recommended for quality
YouTube & DV360	VP9	1:1, 16:9, 4:5, 9:16	1300-2000 kbps	All devices
YouTube CTV	VP9	16:9	3300-7000 kbps	Connected TV specific
Amazon Prime	H264	16:9	15000 kbps	Minimum bitrate required
Amazon Freevee	H264	16:9	4500-7000 kbps	CTV specific

---

Installation

Prerequisites

1. Python 3.8+
2. FFmpeg - Required for video processing

Install FFmpeg

macOS:

brew install ffmpeg

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install ffmpeg

Windows: Download from ffmpeg.org and add to PATH

---

Quick Start (Standard Setup)

Option 1: One-Command Start

./start.sh

This starts both backend (port 5000) and frontend (port 8000) automatically.

Option 2: Manual Start

Terminal 1 - Backend:

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Start backend
cd backend
python app.py

Terminal 2 - Frontend:

# Serve frontend
cd frontend
python3 -m http.server 8000

Then open: http://localhost:8000

---

MAMP Setup

For users who prefer MAMP for frontend hosting:

1. Start Python Backend

cd backend
source ../venv/bin/activate
python app.py

Keep this terminal running! Backend must be active on port 5000.

2. Configure MAMP

1. Open MAMP application
2. Go to Preferences → Web Server
3. Set Document Root to:

   /Users/[your-path]/Loreal-File-Reduction/frontend
   

4. Click Start Servers

3. Access Application

Navigate to: http://localhost:8888/index.html

(Or use your MAMP port if different)

See MAMP_SETUP.md for detailed MAMP configuration and troubleshooting.

---

Usage Guide

1. Upload Video

• Drag and drop a video file onto the upload area
• Or click to browse and select a file
• Supported formats: MP4, MOV, AVI, MKV, WEBM, FLV, WMV, M4V
• Max file size: 500MB (configurable in backend/app.py)

2. Automatic Detection

The app auto-detects platform and aspect ratio from filename patterns:

Platform Patterns

• Meta: _meta_, _fb_, _ig_, _facebook_, _instagram_
• Pinterest: _pinterest_, _pin_
• Snapchat: _snapchat_, _snap_
• TikTok: _tiktok_, _tt_
• YouTube: _youtube_, _yt_
• YouTube CTV: _youtube_ctv_, _yt_ctv_, _ctv_
• Amazon Prime: _prime_, _amazon_prime_
• Amazon Freevee: _freevee_, _amazon_freevee_

Aspect Ratio Patterns

• 1:1 - _1x1_, _square_, _1-1_
• 16:9 - _16x9_, _landscape_, _16-9_
• 4:5 - _4x5_, _4-5_
• 9:16 - _9x16_, _vertical_, _9-16_, _portrait_
• 2:3 - _2x3_, _2-3_

Example Filenames

• summer_campaign_tiktok_9x16.mp4 → Auto-detects TikTok + 9:16
• product_ad_meta_1x1_final.mov → Auto-detects Meta + 1:1
• youtube_16x9_v2.mp4 → Auto-detects YouTube + 16:9

3. Configure Settings

• Select platform (if not auto-detected)
• Select aspect ratio (if not auto-detected)
• ⚠️ Yellow warning appears if aspect ratio differs from original
• Optionally override bitrate (recommended values shown)
• View platform specifications and codec requirements

4. Convert Video

• Click "Convert Video" button
• Progress bar shows conversion status
• FFmpeg processes video with optimal settings

5. Compare & Download

Video Comparison Features:

• Side-by-side playback of original and optimized videos
• Detailed specifications for each video:
  • Platform, Resolution, Aspect Ratio
  • Codec, Bitrate, Duration, File Size
• File size reduction percentage displayed
• Independent mute controls for each player
• Synchronized playback button to play both simultaneously
• Pause both button for simultaneous pause

Aspect Ratio Changed Indicators:

• 🔴 Red warning message appears at top of comparison
• 🔴 Red outline with glow effect on optimized video
• Clear indication when video was converted to different aspect ratio

Download Options:

• Download original video
• Download optimized video
• Upload new file to start over

---

Features in Detail

Aspect Ratio Mismatch Warnings

Configuration Page (Yellow Warning):

• Appears when selected aspect ratio differs from original
• Warns about potential distortion before conversion
• Helps prevent accidental aspect ratio changes

Comparison Page (Red Warning):

• Red warning message at top of comparison section
• Red outline and glow effect on optimized video player
• Clear visual indication that aspect ratio was modified
• Alerts user to check for distortion, stretching, or cropping

Video Specifications Display

Below each video player, detailed specifications are shown:

Original Video:

• Platform: Unknown
• Resolution (e.g., 1920×1080)
• Aspect Ratio (e.g., 16:9)
• Codec (e.g., H264)
• Bitrate (e.g., 5000 kbps)
• Duration
• File Size

Optimized Video:

• Target Platform (e.g., TikTok)
• Output Resolution
• Aspect Ratio
• Codec used
• Applied Bitrate
• Duration
• File Size

Mute Controls

• Independent Mute/Unmute button for each video
• Listen to one video at a time or both together
• Useful for audio quality comparison
• Visual indication (button changes when muted)

---

API Endpoints

Endpoint	Method	Description
/api/health	GET	Health check and FFmpeg status
/api/platforms	GET	Get all platform specifications
/api/detect	POST	Detect platform from filename
/api/upload	POST	Upload video file
/api/convert	POST	Convert video to target format
/api/stream/<type>/<id>	GET	Stream video for playback
/api/download/<type>/<id>	GET	Download original or optimized file
/api/cleanup/<id>	DELETE	Delete uploaded and converted files

---

Project Structure

Loreal-File-Reduction/
├── backend/
│   ├── app.py                 # Flask REST API server
│   ├── video_processor.py     # FFmpeg conversion engine
│   ├── platform_specs.py      # 21 platform configurations
│   ├── requirements.txt       # Python dependencies
│   ├── uploads/               # Temporary upload storage
│   └── outputs/               # Converted video output
├── frontend/
│   ├── index.html            # Main user interface
│   ├── style.css             # Black + #FFC407 theme
│   ├── app.js                # Frontend application logic
│   └── config.js             # API endpoint configuration
├── venv/                     # Python virtual environment
├── docs/
│   ├── README.md            # This file
│   ├── QUICKSTART.md        # Quick start guide
│   ├── MAMP_SETUP.md        # Detailed MAMP setup
│   ├── START_WITH_MAMP.md   # Quick MAMP guide
│   ├── TESTING.md           # Testing procedures
│   └── PROJECT_SUMMARY.md   # Project overview
├── .gitignore
├── start.sh                  # One-command startup script
└── Impact Plus PDF           # Source documentation

---

Technical Specifications

Codec Settings

H264 (Meta, Pinterest, Snapchat, Amazon):

• Preset: medium
• CRF: 23
• Profile: main
• Pixel format: yuv420p

H265 (TikTok):

• Preset: medium
• CRF: 28
• Pixel format: yuv420p

VP9 (YouTube):

• Deadline: good
• CPU-used: 2
• Row-mt: enabled

Audio Settings

• AAC codec: 128 kbps for mobile, 192 kbps for CTV
• Opus codec: 128-192 kbps for VP9/YouTube

---

Configuration

Change API Endpoint

Edit frontend/config.js:

const CONFIG = {
    API_BASE: 'http://localhost:5000/api',  // ← Change this
    MAX_FILE_SIZE: 500 * 1024 * 1024,
    DEBUG: true
};

Adjust File Size Limit

Edit backend/app.py:

MAX_FILE_SIZE = 500 * 1024 * 1024  # Change this value (bytes)

---

Troubleshooting

Backend Won't Start

Issue: Port 5000 already in use

Solution:

# Find and kill process on port 5000
lsof -ti:5000 | xargs kill

# Or use a different port
python app.py --port 5001  # Then update frontend/config.js

FFmpeg Not Found

Verify installation:

ffmpeg -version

If not installed:

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows - Download from ffmpeg.org and add to PATH

Upload Fails

Check:

1. File size under 500MB (or configured limit)
2. Backend server is running
3. backend/uploads/ folder exists and is writable
4. File format is supported (MP4, MOV, etc.)

CORS Errors

Verify backend/app.py has:

from flask_cors import CORS
CORS(app)

Already included! If issues persist, check browser console for details.

Video Won't Play

Try:

1. Refresh page
2. Check backend logs for conversion errors
3. Verify FFmpeg is installed and working
4. Try a different browser (Chrome/Firefox/Safari)

---

Design

• Colors: Black (#000000) + Yellow (#FFC407)
• Font: Montserrat (Google Fonts)
• Theme: Dark UI with yellow accents
• Layout: Responsive, mobile-friendly design

---

Performance

Expected Conversion Times

1 minute 1080p video (varies by hardware):

Platform	Codec	Expected Time
Meta/Pinterest	H264	20-40 seconds
TikTok	H265	40-80 seconds
YouTube	VP9	60-120 seconds

File Size Reduction

Typical reduction rates:

Platform	Expected Reduction
TikTok (H265)	30-40%
Meta (H264)	25-35%
YouTube (VP9)	20-30%

Actual results vary based on source quality and content complexity

---

Documentation

• README.md - Complete documentation (this file)
• QUICKSTART.md - 3-step start guide
• MAMP_SETUP.md - Detailed MAMP configuration
• START_WITH_MAMP.md - Quick MAMP instructions
• TESTING.md - Testing procedures and validation
• PROJECT_SUMMARY.md - Project overview and stats

---

Based On

L'Oréal CDMO Creative Optimization Documentation v1.1

All platform specifications, codecs, and bitrate recommendations are sourced from official L'Oréal documentation for creative optimization and environmental impact reduction.

---

Repository

Bitbucket: https://bitbucket.org/zlalani/loreal-video-optimizer

---

Development

Running in Development Mode

Backend with debug mode:

cd backend
source ../venv/bin/activate
python app.py  # Debug mode is enabled by default

Frontend with hot reload - use your preferred tool or simple HTTP server.

Adding New Platforms

Edit backend/platform_specs.py:

1. Add platform configuration to PLATFORM_SPECS dictionary
2. Add filename patterns to FILENAME_PATTERNS
3. Backend will automatically expose via API

---

Production Deployment

For production use:

1. Use production WSGI server (Gunicorn, uWSGI)

   gunicorn -w 4 -b 0.0.0.0:5000 app:app
   

2. Set up reverse proxy (Nginx, Apache)

3. Configure SSL/HTTPS

4. Disable debug mode in backend/app.py:

   app.run(debug=False, host='0.0.0.0', port=5000)
   

5. Implement authentication if needed

6. Set up file cleanup cron job for uploads/outputs folders

7. Configure proper CORS restrictions for production domain

---

Credits

• Repository Owner: zlalani (Bitbucket)
• Built with: Claude Code
• Backend: Python + Flask + FFmpeg
• Frontend: HTML + JavaScript + CSS
• Documentation Source: L'Oréal CDMO Creative Optimization Documentation v1.1

---

License

Internal tool for L'Oréal creative optimization workflows.

---

Version

Current Version: 1.0 Last Updated: October 2025

Recent Updates:

• ✅ Independent mute controls for video comparison
• ✅ Detailed video specifications display
• ✅ Aspect ratio mismatch warnings (yellow + red)
• ✅ Red outline indicator for aspect ratio changes
• ✅ Platform field alignment in specifications
• ✅ Enhanced user experience and visual feedback