# 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:**
```bash
brew install ffmpeg
```

**Ubuntu/Debian:**
```bash
sudo apt-get update
sudo apt-get install ffmpeg
```

**Windows:**
Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH

---

## Quick Start (Standard Setup)

### Option 1: One-Command Start

```bash
./start.sh
```

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

### Option 2: Manual Start

**Terminal 1 - Backend:**
```bash
# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Start backend
cd backend
python app.py
```

**Terminal 2 - Frontend:**
```bash
# 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

```bash
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`:
```javascript
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`:
```python
MAX_FILE_SIZE = 500 * 1024 * 1024  # Change this value (bytes)
```

---

## Troubleshooting

### Backend Won't Start

**Issue:** Port 5000 already in use

**Solution:**
```bash
# 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:**
```bash
ffmpeg -version
```

**If not installed:**
```bash
# 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:
```python
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:
```bash
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)
   ```bash
   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`:
   ```python
   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