From 64f1fd6f80ef01a18f1458eda4487789d30862e7 Mon Sep 17 00:00:00 2001
From: DJP <DJP>
Date: Thu, 16 Oct 2025 18:14:13 -0400
Subject: [PATCH] Update all documentation with latest features and
 installation methods
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updates:
- Comprehensive README with all new features (mute controls, video specs, warnings)
- Both Standard and MAMP installation methods clearly documented
- Updated QUICKSTART with both setup methods and new features
- Updated START_WITH_MAMP with latest feature descriptions
- Added troubleshooting for both installation methods
- Documented aspect ratio warning system (yellow and red indicators)
- Added video specifications display details
- Production deployment guidance
- Performance expectations and file size reduction targets

All documentation now reflects current v1.0 feature set.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 QUICKSTART.md      | 232 +++++++++++++++++---
 README.md          | 513 ++++++++++++++++++++++++++++++++++++---------
 START_WITH_MAMP.md |  82 +++++++-
 3 files changed, 690 insertions(+), 137 deletions(-)

diff --git a/QUICKSTART.md b/QUICKSTART.md
index 9fafcf4..a30c4a8 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -2,13 +2,33 @@
 
 ## 🚀 Get Started in 3 Steps
 
+Choose your preferred setup method:
+
+---
+
+## Method 1: Standard Setup (Recommended)
+
 ### 1. Start the Application
 
+**Option A - One Command:**
 ```bash
 ./start.sh
 ```
 
-This will start both the backend (port 5000) and frontend (port 8000).
+**Option B - Manual (Two Terminals):**
+
+**Terminal 1 - Backend:**
+```bash
+cd backend
+source ../venv/bin/activate
+python app.py
+```
+
+**Terminal 2 - Frontend:**
+```bash
+cd frontend
+python3 -m http.server 8000
+```
 
 ### 2. Open Your Browser
 
@@ -17,10 +37,38 @@ Navigate to: **http://localhost:8000**
 ### 3. Upload and Convert
 
 1. **Drag & drop** a video file onto the upload area
-2. **Select platform** (e.g., TikTok, Meta, YouTube)
-3. **Select aspect ratio** (e.g., 1:1, 16:9, 9:16)
-4. Click **"Convert Video"**
-5. **Compare** side-by-side and download optimized file
+2. **Select platform** (e.g., TikTok, Meta, YouTube) - or let filename auto-detect
+3. **Select aspect ratio** (e.g., 1:1, 16:9, 9:16) - or let filename auto-detect
+4. ⚠️ **Check for yellow warning** if aspect ratio differs from original
+5. Click **"Convert Video"**
+6. **Compare** side-by-side and download optimized file
+
+---
+
+## Method 2: MAMP Setup
+
+### 1. Start Python Backend
+
+```bash
+cd backend
+source ../venv/bin/activate
+python app.py
+```
+
+**Keep this terminal running!**
+
+### 2. Configure MAMP
+
+1. Open **MAMP** application
+2. **Preferences** → **Web Server**
+3. Set **Document Root** to: `[path-to]/Loreal-File-Reduction/frontend`
+4. Click **"Start Servers"**
+
+### 3. Open Your Browser
+
+Navigate to: **http://localhost:8888/index.html**
+
+(Or your MAMP port)
 
 ---
 
@@ -28,24 +76,33 @@ Navigate to: **http://localhost:8000**
 
 Name your files with these patterns for automatic detection:
 
-**Examples:**
-- `summer_campaign_tiktok_9x16.mp4` → Auto-detects TikTok + 9:16
-- `product_ad_meta_1x1_v2.mov` → Auto-detects Meta + 1:1
-- `youtube_16x9_final.mp4` → Auto-detects YouTube + 16:9
+### Examples
 
-**Platform Keywords:**
-- TikTok: `_tiktok_`, `_tt_`
-- Meta: `_meta_`, `_fb_`, `_ig_`
-- YouTube: `_youtube_`, `_yt_`
-- Pinterest: `_pinterest_`, `_pin_`
-- Snapchat: `_snapchat_`, `_snap_`
+| Filename | Auto-Detects |
+|----------|-------------|
+| `summer_campaign_tiktok_9x16.mp4` | TikTok + 9:16 |
+| `product_ad_meta_1x1_v2.mov` | Meta + 1:1 |
+| `youtube_ctv_16x9_final.mp4` | YouTube CTV + 16:9 |
+| `pinterest_2x3_inspiration.mp4` | Pinterest + 2:3 |
 
-**Aspect Ratio Keywords:**
-- 1:1 → `_1x1_`, `_square_`
-- 16:9 → `_16x9_`, `_landscape_`
-- 9:16 → `_9x16_`, `_vertical_`, `_portrait_`
-- 4:5 → `_4x5_`
-- 2:3 → `_2x3_`
+### Platform Keywords
+
+- **TikTok:** `_tiktok_`, `_tt_`
+- **Meta:** `_meta_`, `_fb_`, `_ig_`
+- **YouTube:** `_youtube_`, `_yt_`
+- **YouTube CTV:** `_youtube_ctv_`, `_yt_ctv_`, `_ctv_`
+- **Pinterest:** `_pinterest_`, `_pin_`
+- **Snapchat:** `_snapchat_`, `_snap_`
+- **Amazon Prime:** `_prime_`, `_amazon_prime_`
+- **Amazon Freevee:** `_freevee_`, `_amazon_freevee_`
+
+### Aspect Ratio Keywords
+
+- **1:1** → `_1x1_`, `_square_`
+- **16:9** → `_16x9_`, `_landscape_`
+- **9:16** → `_9x16_`, `_vertical_`, `_portrait_`
+- **4:5** → `_4x5_`
+- **2:3** → `_2x3_`
 
 ---
 
@@ -58,18 +115,60 @@ Name your files with these patterns for automatic detection:
 | **YouTube** | Quality focus | VP9 | 1280×720, 1920×1080 |
 | **Pinterest** | Inspiration | H264 | 1000×1500 (2:3) |
 | **Snapchat** | Stories | H264 | 720×1280 |
+| **Amazon** | CTV/Streaming | H264 | 1920×1080 |
+
+---
+
+## ✨ Key Features
+
+### During Configuration:
+- ⚠️ **Yellow Warning** - Shows when aspect ratio differs from original
+- **Auto-detection** - Platform and aspect ratio from filename
+- **Bitrate recommendations** - Optimal ranges shown for each platform
+
+### During Comparison:
+- 🔴 **Red Warning** - Indicates aspect ratio was changed
+- 🔴 **Red Outline** - On optimized video when aspect ratio differs
+- **Video Specs** - Complete details for both videos shown below players
+- **Mute Controls** - Independent audio control for each video
+- **Sync Playback** - Play both videos simultaneously
+- **File Size Stats** - Shows reduction percentage
+
+### Video Specifications Shown:
+- Platform (target platform for optimized)
+- Resolution (e.g., 1920×1080)
+- Aspect Ratio (e.g., 16:9)
+- Codec (H264, H265, VP9)
+- Bitrate (e.g., 1500k)
+- Duration
+- File Size
 
 ---
 
 ## 🛠 Troubleshooting
 
-**Backend won't start?**
+### Backend won't start?
+
+**Check if something is on port 5000:**
 ```bash
-source venv/bin/activate
-pip install -r backend/requirements.txt
+lsof -ti:5000
 ```
 
-**FFmpeg not found?**
+**Kill it:**
+```bash
+lsof -ti:5000 | xargs kill
+```
+
+**Then restart:**
+```bash
+cd backend
+source ../venv/bin/activate
+python app.py
+```
+
+### FFmpeg not found?
+
+**Install FFmpeg:**
 ```bash
 # macOS
 brew install ffmpeg
@@ -78,24 +177,54 @@ brew install ffmpeg
 sudo apt-get install ffmpeg
 ```
 
-**Port already in use?**
+**Verify installation:**
+```bash
+ffmpeg -version
+```
+
+### Port already in use?
+
+**Standard Setup - Port 8000:**
 ```bash
-# Kill processes on port 5000 or 8000
-lsof -ti:5000 | xargs kill
 lsof -ti:8000 | xargs kill
 ```
 
+**MAMP - Port 8888:**
+Check MAMP settings or change port in Preferences
+
+### "Failed to fetch" error?
+
+**Checklist:**
+1. ✅ Backend running? (`curl http://localhost:5000/api/health`)
+2. ✅ Frontend accessible? (Open http://localhost:8000)
+3. ✅ Check browser console (F12) for errors
+4. ✅ Verify `frontend/config.js` has correct API_BASE
+
 ---
 
-## 📊 File Size Expectations
+## 📊 Expected Results
 
-Typical reduction rates based on L'Oréal documentation:
+### File Size Reduction
 
-- **TikTok 9:16**: 30-40% reduction (using H265)
-- **Meta 1:1**: 25-35% reduction
-- **YouTube 16:9**: 20-30% reduction (VP9 is efficient)
+Typical results:
 
-*Actual results vary based on source quality and content complexity*
+| Platform | Reduction |
+|----------|-----------|
+| **TikTok** (H265) | 30-40% |
+| **Meta** (H264) | 25-35% |
+| **YouTube** (VP9) | 20-30% |
+
+### Conversion Times
+
+For 1 minute 1080p video:
+
+| Platform | Time |
+|----------|------|
+| **Meta/Pinterest** | 20-40 seconds |
+| **TikTok** | 40-80 seconds |
+| **YouTube** | 60-120 seconds |
+
+*Times vary based on hardware*
 
 ---
 
@@ -107,4 +236,39 @@ Typical reduction rates based on L'Oréal documentation:
 
 ---
 
+## 📚 More Information
+
+- **README.md** - Complete documentation
+- **MAMP_SETUP.md** - Detailed MAMP configuration
+- **START_WITH_MAMP.md** - Quick MAMP instructions
+- **TESTING.md** - Testing procedures
+
+---
+
+## 🚦 Status Indicators
+
+### Yellow Warning (Configuration Page)
+- Appears when selected aspect ratio ≠ original
+- Prevents accidental distortion
+- Shows **before** conversion
+
+### Red Warning (Comparison Page)
+- Appears when aspect ratio **was** changed
+- Red outline on optimized video
+- Visual alert for quality check
+
+---
+
+## 💡 Tips
+
+1. **Use descriptive filenames** with platform and aspect ratio for auto-detection
+2. **Check yellow warning** before converting to avoid distortion
+3. **Use mute controls** to compare audio quality
+4. **Compare videos side-by-side** before downloading
+5. **Watch for red indicators** if aspect ratio was changed
+
+---
+
 **Need help?** Check the full README.md for detailed documentation.
+
+**Repository:** https://bitbucket.org/zlalani/loreal-video-optimizer
diff --git a/README.md b/README.md
index aa15f91..49367d7 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,39 @@
 # Video Optimizer for Social Media Platforms
 
-L'Oréal Creative Optimization Tool - Based on Impact Plus Documentation v1.1
+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. It features:
+This application optimizes video files for various social media platforms using platform-specific codecs and bitrate recommendations to minimize file sizes while maintaining quality.
 
-- **21 Platform Configurations** across 8 platforms
+### Key Features
+
+- **21 Platform Configurations** across 8 social media platforms
 - **Automatic filename detection** for platform and aspect ratio
-- **Side-by-side video comparison** for quality assurance
+- **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 | Notes |
-|----------|-------|---------------|-------|
-| **Meta (Facebook/Instagram)** | H264 | 1:1, 16:9, 4:5, 9:16 | - |
-| **Pinterest** | H264 | 1:1, 16:9, 2:3, 4:5, 9:16 | 2:3 not fully tested |
-| **Snapchat** | H264 | 16:9, 9:16 | - |
-| **TikTok** | H265 | 1:1, 16:9, 9:16 | Recommended for quality |
-| **YouTube & DV360** | VP9 | 1:1, 16:9, 4:5, 9:16 | All devices |
-| **YouTube CTV** | VP9 | 16:9 | Connected TV specific |
-| **Amazon Prime** | H264 | 16:9 | 15Mbit/s minimum |
-| **Amazon Freevee** | H264 | 16:9 | CTV specific |
+| 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
 
@@ -31,7 +42,7 @@ This application optimizes video files for various social media platforms using
 1. **Python 3.8+**
 2. **FFmpeg** - Required for video processing
 
-#### Install FFmpeg:
+#### Install FFmpeg
 
 **macOS:**
 ```bash
@@ -45,92 +56,195 @@ sudo apt-get install ffmpeg
 ```
 
 **Windows:**
-Download from [ffmpeg.org](https://ffmpeg.org/download.html)
+Download from [ffmpeg.org](https://ffmpeg.org/download.html) and add to PATH
 
-### Setup
+---
 
-1. **Clone or navigate to the project directory**
+## Quick Start (Standard Setup)
+
+### Option 1: One-Command Start
 
-2. **Create and activate virtual environment:**
 ```bash
-python3 -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
+./start.sh
 ```
 
-3. **Install Python dependencies:**
-```bash
-pip install -r backend/requirements.txt
-```
-
-## Running the Application
-
-### Start the Backend Server
-
+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
 ```
 
-The backend will start on `http://localhost:5000`
-
-### Open the Frontend
-
-Open `frontend/index.html` in your web browser, or serve it with a simple HTTP server:
-
+**Terminal 2 - Frontend:**
 ```bash
+# Serve frontend
 cd frontend
 python3 -m http.server 8000
 ```
 
-Then navigate to `http://localhost:8000`
+Then open: **http://localhost:8000**
 
-## Usage
+---
+
+## 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
 
-### 2. Filename Auto-Detection
+- **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)
 
-The app can auto-detect platform and aspect ratio from filename patterns:
+### 2. Automatic Detection
 
-**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_`
+The app auto-detects platform and aspect ratio from filename patterns:
 
-**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_`
+#### 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_`
 
-**Example filenames:**
-- `summer_ad_tiktok_9x16.mp4` → Auto-detects TikTok, 9:16
-- `product_launch_meta_1x1_final.mov` → Auto-detects Meta, 1:1
+#### 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)
-- Optionally override bitrate (recommended values are shown)
 
-### 4. Convert
-- Click "Convert Video"
-- Wait for FFmpeg to process
+- 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
-- View both videos side-by-side
-- Check file size reduction
-- Use sync playback to compare quality
-- Download optimized version
+
+#### 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
 
@@ -140,31 +254,45 @@ The app can auto-detect platform and aspect ratio from filename patterns:
 | `/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 |
+| `/api/convert` | POST | Convert video to target format |
 | `/api/stream/<type>/<id>` | GET | Stream video for playback |
-| `/api/download/<type>/<id>` | GET | Download file |
-| `/api/cleanup/<id>` | DELETE | Delete files |
+| `/api/download/<type>/<id>` | GET | Download original or optimized file |
+| `/api/cleanup/<id>` | DELETE | Delete uploaded and converted files |
+
+---
 
 ## Project Structure
 
 ```
 Loreal-File-Reduction/
-├── venv/                       # Virtual environment
 ├── backend/
-│   ├── app.py                 # Flask application
-│   ├── video_processor.py     # FFmpeg processing logic
-│   ├── platform_specs.py      # Platform configurations
+│   ├── app.py                 # Flask REST API server
+│   ├── video_processor.py     # FFmpeg conversion engine
+│   ├── platform_specs.py      # 21 platform configurations
 │   ├── requirements.txt       # Python dependencies
-│   ├── uploads/               # Uploaded files (auto-created)
-│   └── outputs/               # Converted files (auto-created)
+│   ├── uploads/               # Temporary upload storage
+│   └── outputs/               # Converted video output
 ├── frontend/
-│   ├── index.html            # Main UI
-│   ├── style.css             # Styling (Black + #FFC407)
-│   └── app.js                # Frontend logic
-└── README.md                 # This file
+│   ├── 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 Details
+---
+
+## Technical Specifications
 
 ### Codec Settings
 
@@ -185,44 +313,227 @@ Loreal-File-Reduction/
 - Row-mt: enabled
 
 ### Audio Settings
-- AAC codec (128 kbps for mobile, 192 kbps for CTV)
-- Opus codec for VP9/YouTube (128-192 kbps)
+- **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
 
-### FFmpeg Not Found
-```bash
-# Verify FFmpeg installation
-ffmpeg -version
+### Backend Won't Start
 
-# If not installed, install it:
-# macOS:
+**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:
+# Ubuntu/Debian
 sudo apt-get install ffmpeg
+
+# Windows - Download from ffmpeg.org and add to PATH
 ```
 
-### CORS Issues
-If frontend and backend are on different ports/domains, ensure Flask-CORS is installed and configured.
+### Upload Fails
 
-### Large File Uploads
-Default max file size is 500MB. To change, edit `app.py`:
+**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
-MAX_FILE_SIZE = 500 * 1024 * 1024  # Change this value
+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
 
-Based on **L'Oréal CDMO Creative Optimization Documentation v1.1**
-Impact Plus - March 2025
+- **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
diff --git a/START_WITH_MAMP.md b/START_WITH_MAMP.md
index 76a0340..fc75ba6 100644
--- a/START_WITH_MAMP.md
+++ b/START_WITH_MAMP.md
@@ -53,6 +53,48 @@ Go to: **http://localhost:8888/index.html**
 - You see the black page with yellow "Video Optimizer" title
 - You can drag & drop a video file
 - After uploading, you see platform options (Meta, TikTok, YouTube, etc.)
+- Video specifications display below each player after conversion
+- Mute buttons work independently for each video
+
+---
+
+## ✨ New Features You'll See
+
+### 1. Aspect Ratio Warnings
+
+**Yellow Warning (Page 1 - Configuration):**
+- Shows when you select an aspect ratio different from your original video
+- Helps prevent accidental distortion **before** converting
+
+**Red Warning (Page 2 - Comparison):**
+- Shows when aspect ratio **was** changed during conversion
+- Red outline with glow effect around optimized video
+- Visual alert to check for distortion
+
+### 2. Video Specifications
+
+Below each video player:
+- **Platform** - Shows target platform (Optimized) or "Unknown" (Original)
+- **Resolution** - Exact pixel dimensions
+- **Aspect Ratio** - Format ratio (16:9, 1:1, etc.)
+- **Codec** - Video codec used (H264, H265, VP9)
+- **Bitrate** - Video bitrate in kbps
+- **Duration** - Video length
+- **File Size** - Total file size
+
+### 3. Mute Controls
+
+- **🔊 Mute/🔇 Unmute** button for each video
+- Listen to one video at a time or both together
+- Great for comparing audio quality
+- Button highlights when muted
+
+### 4. File Size Reduction
+
+At the top of comparison page:
+- Original file size
+- Optimized file size
+- **Reduction percentage** (typically 20-40%)
 
 ---
 
@@ -93,7 +135,7 @@ curl http://localhost:5000/api/platforms
 Should show a JSON response with platform data.
 
 ### Test Frontend:
-Open http://localhost:8888/index.html in browser - page should load.
+Open http://localhost:8888/index.html in browser - page should load with black background and yellow title.
 
 ---
 
@@ -117,9 +159,45 @@ Click "Stop Servers" in MAMP application
 
 ## Current Status
 
-✅ Python backend is **running** on port 5000
+✅ Python backend is ready (activate venv and run app.py)
 ✅ All platform configurations loaded (21 total)
 ✅ FFmpeg is installed and detected
 ✅ Ready to accept requests from MAMP frontend
+✅ New features: Mute controls, video specs, aspect ratio warnings
 
 **Next:** Configure MAMP and open http://localhost:8888/index.html
+
+---
+
+## 🎯 Usage Flow
+
+1. **Upload** - Drag & drop video file
+2. **Detect** - Filename auto-detection works (or manual selection)
+3. **Warn** - Yellow warning if aspect ratio will change
+4. **Convert** - Click button, watch progress bar
+5. **Compare** - See both videos side-by-side with full specs
+6. **Alert** - Red warning and outline if aspect ratio was changed
+7. **Listen** - Use mute controls to compare audio
+8. **Download** - Get optimized file
+
+---
+
+## 💡 Tips for MAMP Users
+
+1. **Always start backend first** before opening MAMP
+2. **Check terminal** for backend logs and errors
+3. **Use browser console (F12)** to debug frontend issues
+4. **Verify document root** is set to `frontend` folder
+5. **Port 5000** must be available for backend
+
+---
+
+## 📚 Need More Help?
+
+- **MAMP_SETUP.md** - Detailed MAMP setup and troubleshooting
+- **README.md** - Complete application documentation
+- **TESTING.md** - Testing procedures
+
+---
+
+**Repository:** https://bitbucket.org/zlalani/loreal-video-optimizer