Fresh start without large files

.github/workflows/deploy.yml

@@ -0,0 +1,44 @@
+name: Deploy to Vercel
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+      
+      - name: Run tests
+        run: |
+          # Add tests here when ready
+          python -c "import api.index; print('Import successful')"
+
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Deploy to Vercel
+        uses: vercel/action-deploy@v1
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
+          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}

.gitignore

@@ -0,0 +1,13 @@
+# Python
+__pycache__/
+*.pyc
+venv/
+.env
+
+# Large Binaries (Not needed on repo, Docker installs them)
+ffmpeg/
+yt-dlp.exe
+
+# Editor
+.vscode/
+.idea/

DEPLOYMENT.md

@@ -0,0 +1,341 @@
+# 🚀 Deployment Guide
+
+Complete guide to deploy the Viral Clip Extractor API to Vercel and GitHub.
+
+## Quick Deploy (Recommended)
+
+### Option 1: Vercel Dashboard (Easiest)
+
+1. **Push to GitHub**
+   ```bash
+   # Create a new repository on GitHub first
+   git init
+   git add .
+   git commit -m "Initial commit"
+   git branch -M main
+   git remote add origin https://github.com/YOUR_USERNAME/viral-clip-extractor-api.git
+   git push -u origin main
+   ```
+
+2. **Deploy on Vercel**
+   - Go to [vercel.com](https://vercel.com)
+   - Sign up/login with GitHub
+   - Click "New Project"
+   - Import your repository
+   - Vercel auto-detects Python
+   - Click "Deploy"
+
+3. **Done!** Your API is live at `https://your-project.vercel.app`
+
+---
+
+### Option 2: Vercel CLI
+
+1. **Install Vercel CLI**
+   ```bash
+   npm i -g vercel
+   ```
+
+2. **Login**
+   ```bash
+   vercel login
+   ```
+
+3. **Deploy**
+   ```bash
+   cd viral-clip-extractor-api
+   vercel --prod
+   ```
+
+4. **Follow prompts** - Vercel will detect Python automatically
+
+---
+
+## GitHub + Vercel Integration (Auto-Deploy)
+
+### Setup GitHub Repository
+
+1. **Create repository on GitHub**
+   - Go to github.com/new
+   - Name: `viral-clip-extractor-api`
+   - Make it Public or Private
+   - Don't initialize with README
+
+2. **Push local code**
+   ```bash
+   cd viral-okcomputer/output/viral-clip-api
+   git init
+   git add .
+   git commit -m "Initial commit"
+   git branch -M main
+   git remote add origin https://github.com/YOUR_USERNAME/viral-clip-extractor-api.git
+   git push -u origin main
+   ```
+
+### Setup Vercel Project
+
+1. **Import from GitHub**
+   - Go to [vercel.com/new](https://vercel.com/new)
+   - Select your repository
+   - Framework Preset: `Other`
+   - Root Directory: `./`
+   - Build Command: (leave empty for Python)
+   - Output Directory: (leave empty)
+
+2. **Environment Variables** (if needed)
+   - Click "Environment Variables"
+   - Add any required variables
+   - Click "Deploy"
+
+3. **Auto-Deploy Enabled**
+   - Every push to `main` branch auto-deploys
+   - Pull requests get preview deployments
+
+---
+
+## GitHub Actions CI/CD
+
+The repository includes a GitHub Actions workflow for automated deployment.
+
+### Setup Secrets
+
+1. **Get Vercel Tokens**
+   ```bash
+   vercel login
+   vercel tokens create
+   ```
+
+2. **Get Project ID**
+   ```bash
+   cd your-project
+   vercel
+   # Check .vercel/project.json
+   ```
+
+3. **Add to GitHub Secrets**
+   - Go to Repository → Settings → Secrets → Actions
+   - Add:
+     - `VERCEL_TOKEN` - Your token
+     - `VERCEL_ORG_ID` - From `.vercel/project.json`
+     - `VERCEL_PROJECT_ID` - From `.vercel/project.json`
+
+### Workflow Features
+
+- ✅ Runs tests on every PR
+- ✅ Auto-deploys on merge to main
+- ✅ Shows deployment status in PRs
+
+---
+
+## Configuration
+
+### Vercel Settings
+
+Edit `vercel.json` to customize:
+
+```json
+{
+  "version": 2,
+  "name": "viral-clip-extractor-api",
+  "functions": {
+    "api/index.py": {
+      "maxDuration": 60    // Max 60 seconds (Vercel limit)
+    }
+  }
+}
+```
+
+### Python Runtime
+
+Vercel uses Python 3.9 by default. To change:
+
+```json
+{
+  "builds": [{
+    "src": "api/index.py",
+    "use": "@vercel/python",
+    "config": {
+      "runtime": "python3.9"
+    }
+  }]
+}
+```
+
+### Custom Domain
+
+1. Go to Vercel Dashboard → Your Project → Settings → Domains
+2. Add your domain
+3. Follow DNS configuration instructions
+
+---
+
+## Testing Your Deployment
+
+### 1. Health Check
+```bash
+curl https://your-project.vercel.app/health
+```
+
+Expected:
+```json
+{"status": "healthy"}
+```
+
+### 2. API Info
+```bash
+curl https://your-project.vercel.app/
+```
+
+### 3. Test Analysis
+```bash
+curl -X POST https://your-project.vercel.app/analyze \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ", "num_clips": 3}'
+```
+
+---
+
+## Troubleshooting
+
+### Build Failures
+
+**Problem**: Build fails with dependency errors
+
+**Solution**:
+```bash
+# Update requirements.txt
+pip freeze > requirements.txt
+
+# Or manually specify versions
+flask==3.0.3
+yt-dlp==2024.8.6
+```
+
+### Timeout Issues
+
+**Problem**: 504 Gateway Timeout
+
+**Solution**:
+- Reduce `clip_length` or `num_clips` in requests
+- Videos > 2 hours may timeout
+- Consider splitting long videos
+
+### Import Errors
+
+**Problem**: `ModuleNotFoundError`
+
+**Solution**:
+- Ensure all dependencies in `requirements.txt`
+- Check Python version compatibility
+- Verify file structure matches `vercel.json`
+
+### CORS Errors
+
+**Problem**: Frontend can't access API
+
+**Solution**:
+- CORS is enabled by default in `api/index.py`
+- Check `flask-cors` is in requirements.txt
+
+---
+
+## Monitoring
+
+### Vercel Analytics
+
+1. Go to Vercel Dashboard → Your Project → Analytics
+2. View:
+   - Request count
+   - Response times
+   - Error rates
+   - Bandwidth usage
+
+### Logs
+
+```bash
+# View live logs
+vercel logs your-project --tail
+```
+
+Or in Dashboard → Project → Logs
+
+---
+
+## Updating Your API
+
+### Method 1: Git Push (Auto-Deploy)
+
+```bash
+# Make changes
+git add .
+git commit -m "Update feature"
+git push origin main
+# Vercel auto-deploys!
+```
+
+### Method 2: Vercel CLI
+
+```bash
+vercel --prod
+```
+
+---
+
+## Environment Variables
+
+### Add to Vercel
+
+1. Dashboard → Project → Settings → Environment Variables
+2. Or via CLI:
+   ```bash
+   vercel env add VARIABLE_NAME
+   ```
+
+### Use in Code
+
+```python
+import os
+
+api_key = os.environ.get('API_KEY')
+```
+
+---
+
+## Security Best Practices
+
+1. **Never commit `.env` files**
+   - Already in `.gitignore`
+
+2. **Use environment variables for secrets**
+   - API keys
+   - Database URLs
+   - Private tokens
+
+3. **Enable Vercel Authentication**
+   - Dashboard → Project → Settings → Security
+
+4. **Rate Limiting**
+   - Consider adding Flask-Limiter for production
+
+---
+
+## Next Steps
+
+- [ ] Add custom domain
+- [ ] Set up monitoring/alerts
+- [ ] Add rate limiting
+- [ ] Implement caching
+- [ ] Add more languages support
+- [ ] Create mobile app
+
+---
+
+## Support
+
+- **Vercel Docs**: [vercel.com/docs](https://vercel.com/docs)
+- **Python Runtime**: [vercel.com/docs/functions/serverless-functions/runtimes/python](https://vercel.com/docs/functions/serverless-functions/runtimes/python)
+- **yt-dlp Docs**: [github.com/yt-dlp/yt-dlp](https://github.com/yt-dlp/yt-dlp)
+
+---
+
+**Happy Deploying! 🚀**

Dockerfile

@@ -0,0 +1,29 @@
+# Use Python 3.9 Slim image
+FROM python:3.9-slim
+
+# Install system dependencies (FFmpeg)
+RUN apt-get update && \
+    apt-get install -y ffmpeg && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy requirements first (for caching)
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY api/ api/
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+
+# Expose port (Render sets PORT env var)
+EXPOSE 5000
+
+# Run with Gunicorn
+CMD gunicorn -w 4 -b 0.0.0.0:$PORT api.index:app

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Viral Clip Extractor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,79 @@
+# 🎬 Viral Clip Extractor API
+
+Turn long-form YouTube videos into engaging, viral-ready clips for TikTok, Shorts, and Reels using AI.
+
+**Live Demo / Docs:** `https://your-app-url.onrender.com/docs`
+
+## ✨ Features
+
+- **🧠 Three Powerful Modes:**
+  1.  **Heuristic (Free/Fast):** Uses keyword analysis and audio/visual cues. Great for high-energy content.
+  2.  **Gemini AI (Balanced):** Uses Google's Gemini 2.0 Flash for context-aware clipping.
+  3.  **Nvidia/DeepSeek AI (Advanced):** Uses DeepSeek V3/R1 via Nvidia API for deep reasoning and technical content.
+- **🚀 High Performance:** Optimized `yt-dlp` and `ffmpeg` integration for fast processing.
+- **☁️ Cloud Ready:** Dockerized and configured for [Render](https://render.com) deployment.
+- **🔒 Secure:** Environment variable support for API keys.
+- **📄 Auto-Documentation:** Built-in interactive API docs at `/docs`.
+
+## 🛠️ Installation
+
+### Option 1: Docker (Recommended)
+```bash
+docker build -t viral-clips .
+docker run -p 5000:5000 --env-file .env viral-clips
+```
+
+### Option 2: Local Python
+1.  **Install FFmpeg:** Ensure `ffmpeg` is in your system PATH.
+2.  **Install Requirements:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+3.  **Run API:**
+    ```bash
+    python api/index.py
+    ```
+
+## 🔑 Configuration
+
+Create a `.env` file or set these environment variables in your cloud dashboard:
+
+| Variable | Description | Required For |
+| :--- | :--- | :--- |
+| `GEMINI_API_KEY` | Google Gemini API Key | `mode=ai` |
+| `NVIDIA_API_KEY` | Nvidia/DeepSeek API Key | `mode=nvidia` |
+| `PORT` | Server Port (Default: 5000) | Deployment |
+
+## 📚 API Usage
+
+### Get Clips
+**Endpoint:** `GET /clips`
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `url` | string | **Required** | YouTube Video URL |
+| `mode` | string | `heuristic` | `heuristic`, `ai`, or `nvidia` |
+| `num` | int | `5` | Number of clips to generate |
+
+**Example:**
+```bash
+curl "http://localhost:5000/clips?url=https://youtu.be/VIDEO_ID&mode=ai"
+```
+
+### Download Clip
+**Endpoint:** `GET /download_file`
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `url` | string | Original YouTube URL |
+| `start` | float | Start time (seconds) |
+| `end` | float | End time (seconds) |
+
+## 📝 Credits
+Developed with ❤️ by **yash@dev**
+
+Powered by:
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+- [FFmpeg](https://ffmpeg.org/)
+- [Google Gemini](https://ai.google.dev/)
+- [Nvidia DeepSeek](https://build.nvidia.com/)

api/index.py

@@ -0,0 +1,1001 @@
+"""
+Viral Clip Extractor API
+Deploy to Vercel for YouTube viral clip analysis
+"""
+
+from flask import Flask, request, jsonify, send_file, after_this_request
+from flask_cors import CORS
+import yt_dlp
+import requests
+import google.generativeai as genai
+from openai import OpenAI
+import json
+import re
+from io import StringIO
+import os
+import re
+from typing import Dict, List, Optional, Any
+
+app = Flask(__name__)
+CORS(app)
+
+# ============== CONFIGURATION ==============
+DEFAULT_CLIP_LENGTH = 40
+DEFAULT_WINDOW_STEP = 10
+DEFAULT_MIN_CLIP_LENGTH = 25
+DEFAULT_MAX_CLIP_LENGTH = 60
+
+HOOK_WORDS = [
+    "wait", "shocking", "unbelievable", "secret", "crazy", "exposed", "omg", "wtf",
+    "plot twist", "insane", "cheating", "stunning", "mind blowing", "truth", "lie",
+    "revealed", "hidden", "discover", "amazing", "incredible", "must see", "urgent"
+]
+
+EMOTION_WORDS = [
+    "laugh", "cry", "angry", "shocked", "surprised", "scream", "love", "hate",
+    "disgusted", "horrified", "amazed", "excited", "sad", "happy", "furious"
+]
+
+# ============== UTILITY FUNCTIONS ==============
+
+def extract_video_id(url: str) -> Optional[str]:
+    """Extract YouTube video ID from various URL formats"""
+    patterns = [
+        r'(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/|youtube\.com\/v\/|youtube\.com\/shorts\/)([a-zA-Z0-9_-]{11})',
+        r'^([a-zA-Z0-9_-]{11})$'
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, url)
+        if match:
+            return match.group(1)
+    return None
+
+def time_to_seconds(t) -> float:
+    """Convert time string to seconds"""
+    if isinstance(t, (int, float)):
+        return float(t)
+    if ':' in str(t):
+        parts = list(map(int, str(t).split(':')))
+        if len(parts) == 3:
+            return parts[0] * 3600 + parts[1] * 60 + parts[2]
+        elif len(parts) == 2:
+            return parts[0] * 60 + parts[1]
+        elif len(parts) == 1:
+            return parts[0]
+    return float(t)
+
+def seconds_to_time(s: float) -> str:
+    """Convert seconds to MM:SS format"""
+    minutes = int(s // 60)
+    seconds = int(s % 60)
+    return f"{minutes}:{seconds:02d}"
+
+def parse_vtt_content(vtt_text: str) -> List[Dict]:
+    """Parse VTT subtitle content"""
+    segments = []
+    lines = vtt_text.strip().split('\n')
+    
+    i = 0
+    while i < len(lines) and not '-->' in lines[i]:
+        i += 1
+    
+    current_text = []
+    current_start = None
+    current_end = None
+    
+    while i < len(lines):
+        line = lines[i].strip()
+        
+        if '-->' in line:
+            if current_text and current_start is not None:
+                segments.append({
+                    'start': current_start,
+                    'end': current_end,
+                    'text': ' '.join(current_text)
+                })
+            
+            times = line.split('-->')
+            if len(times) == 2:
+                start_str = times[0].strip().split('.')[0]
+                end_str = times[1].strip().split()[0].split('.')[0]
+                
+                current_start = time_to_seconds(start_str)
+                current_end = time_to_seconds(end_str)
+                current_text = []
+        elif line and not line.startswith('NOTE') and not line.startswith('STYLE'):
+            clean_line = re.sub(r'<[^>]+>', '', line)
+            if clean_line:
+                current_text.append(clean_line)
+        
+        i += 1
+    
+    if current_text and current_start is not None:
+        segments.append({
+            'start': current_start,
+            'end': current_end,
+            'text': ' '.join(current_text)
+        })
+    
+    return segments
+
+import sys
+import logging
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ============== CORE CLASS ==============
+
+class ViralClipExtractor:
+    def __init__(self):
+        self.headers = {
+            'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36',
+        }
+        # Robust FFmpeg path resolution
+        import shutil
+        project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        
+        # 1. Check local ffmpeg folder (Windows/Dev)
+        ffmpeg_path_local = os.path.join(project_root, "ffmpeg", "bin", "ffmpeg.exe")
+        
+        # 2. Check system PATH (Linux/Render/Docker)
+        ffmpeg_path_system = shutil.which("ffmpeg")
+        
+        ffmpeg_location = None
+        if os.path.exists(ffmpeg_path_local):
+            ffmpeg_location = ffmpeg_path_local
+            ffmpeg_dir = os.path.dirname(ffmpeg_location)
+            if ffmpeg_dir not in os.environ["PATH"]:
+                 os.environ["PATH"] += os.pathsep + ffmpeg_dir
+            logger.info(f"Using Local FFmpeg: {ffmpeg_location}")
+        elif ffmpeg_path_system:
+            # If on system path, we don't need to specify location for yt-dlp usually, 
+            # but getting the dir is good practice
+            ffmpeg_location = ffmpeg_path_system
+            logger.info(f"Using System FFmpeg: {ffmpeg_location}")
+        else:
+            logger.warning("FFmpeg NOT FOUND! Clip cutting will fail.")
+
+
+        self.base_ydl_opts = {
+            'quiet': False,
+            'no_warnings': False,
+            # 'extractor_args': {'youtube': {'player_client': ['web']}},
+            'http_headers': self.headers,
+            # 'ffmpeg_location': ffmpeg_dir # Removed, relying on PATH
+        }
+        
+        if ffmpeg_dir:
+            logger.info(f"Added FFmpeg to PATH: {ffmpeg_dir}")
+        else:
+            logger.warning("FFmpeg NOT FOUND! Clip cutting will fail.")
+    
+    def download_clip(self, url: str, start: float, end: float, quality: str = "720") -> Optional[str]:
+        """Download and cut a clip"""
+        import uuid
+        output_dir = "downloads"
+        os.makedirs(output_dir, exist_ok=True)
+        clip_id = f"clip_{uuid.uuid4().hex[:8]}"
+        output_template = os.path.join(output_dir, f"{clip_id}.%(ext)s")
+        
+        ydl_opts = {
+            **self.base_ydl_opts,
+            'format': f'bestvideo[height<={quality}]+bestaudio/best[height<={quality}]/best',
+            'outtmpl': output_template,
+            'download_ranges': lambda info, ydl: [{
+                'start_time': start,
+                'end_time': end
+            }],
+            'force_keyframes_at_cuts': True, 
+        }
+        
+        try:
+            with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+                ydl.download([url])
+            
+            # Find the downloaded file
+            for file in os.listdir(output_dir):
+                if file.startswith(clip_id):
+                    return os.path.abspath(os.path.join(output_dir, file))
+            return None
+        except Exception as e:
+            with open("error.log", "a") as f:
+                f.write(f"Download Error: {e}\n")
+            logger.error(f"Error downloading clip: {e}")
+            return None
+
+    def analyze_with_gemini(self, transcript_segments: List[Dict], api_key: str) -> List[Dict]:
+        """Analyze full transcript using Gemini AI"""
+        try:
+            genai.configure(api_key=api_key)
+            # Using 2.0 Flash as 1.5 is unavailable for this key/region
+            model = genai.GenerativeModel('gemini-2.0-flash')
+            
+            # Helper to check if API key is likely valid (heuristic)
+            if "YOUR_GEMINI" in api_key:
+                raise ValueError("Invalid API Key placeholder used")
+
+            # Construct prompt
+            formatted_text = ""
+            for seg in transcript_segments:
+                start = int(seg['start'])
+                text = seg['text']
+                formatted_text += f"[{start}s] {text} "
+            
+            # Truncate
+            full_context = formatted_text[:30000] # Safe limit
+
+            prompt = f"""
+            You are a viral content expert. Analyze the video transcript (with timestamps) and identify the top 3-5 most engaging clips for Shorts/TikTok.
+            
+            Transcript:
+            {full_context}
+            
+            Return ONLY a raw JSON array (no markdown) of objects:
+            [
+                {{
+                    "start": <number_seconds>,
+                    "end": <number_seconds>,
+                    "viral_score": <0-100>,
+                    "reason": "<short explanation>"
+                }}
+            ]
+            """
+            
+            logger.info("Sending request to Gemini AI...")
+            response = model.generate_content(prompt)
+            text = response.text
+            # Clean markdown
+            text = re.sub(r"```json\s*", "", text)
+            text = re.sub(r"```\s*", "", text)
+            return json.loads(text)
+        except Exception as e:
+            logger.error(f"Gemini API Error: {e}")
+            raise e # Create visibility for the error
+
+    def analyze_with_nvidia(self, transcript_segments: List[Dict], api_key: str) -> List[Dict]:
+        """Analyze full transcript using Nvidia/DeepSeek AI"""
+        try:
+            client = OpenAI(
+                base_url = "https://integrate.api.nvidia.com/v1",
+                api_key = api_key
+            )
+
+            # Construct prompt
+            formatted_text = ""
+            for seg in transcript_segments:
+                start = int(seg['start'])
+                text = seg['text']
+                formatted_text += f"[{start}s] {text} "
+            
+            full_context = formatted_text[:30000]
+
+            prompt = f"""
+            You are a viral content expert. Analyze the video transcript (with timestamps) and identify the top 3-5 most engaging clips for Shorts/TikTok.
+            
+            Transcript:
+            {full_context}
+            
+            Return ONLY a raw JSON array (no markdown) of objects:
+            [
+                {{
+                    "start": <number_seconds>,
+                    "end": <number_seconds>,
+                    "viral_score": <0-100>,
+                    "reason": "<short explanation>"
+                }}
+            ]
+            """
+            
+            logger.info("Sending request to Nvidia/DeepSeek AI...")
+            completion = client.chat.completions.create(
+                model="deepseek-ai/deepseek-v3.1-terminus",
+                messages=[{"role":"user","content":prompt}],
+                temperature=0.2,
+                top_p=0.7,
+                max_tokens=8192,
+                extra_body={"chat_template_kwargs": {"thinking":True}},
+                stream=False
+            )
+            
+            text = completion.choices[0].message.content
+            # Clean markdown
+            text = re.sub(r"```json\s*", "", text)
+            text = re.sub(r"```\s*", "", text)
+            # Remove thinking content
+            text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL)
+            
+            return json.loads(text)
+        except Exception as e:
+            logger.error(f"Nvidia API Error: {e}")
+            raise e
+
+    def extract_video_info(self, url: str) -> Dict:
+        """Get video metadata"""
+        logger.info(f"Extracting video info for: {url}")
+        ydl_opts = {
+            **self.base_ydl_opts,
+            'simulate': True,
+        }
+        
+        try:
+            with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+                info = ydl.extract_info(url, download=False)
+                
+                chapters = []
+                if 'chapters' in info and info['chapters']:
+                    for ch in info['chapters']:
+                        chapters.append({
+                            "start": ch['start_time'],
+                            "end": ch.get('end_time') or ch['start_time'] + DEFAULT_CLIP_LENGTH,
+                            "title": ch.get('title', 'Untitled')
+                        })
+                
+                logger.info(f"Video info extracted: {info.get('title')}")
+                return {
+                    "id": info.get("id"),
+                    "title": info.get("title"),
+                    "uploader": info.get("uploader"),
+                    "duration": info.get("duration"),
+                    "description": info.get("description", "")[:500],
+                    "view_count": info.get("view_count"),
+                    "like_count": info.get("like_count"),
+                    "chapters": chapters
+                }
+        except Exception as e:
+            logger.error(f"Error extracting video info: {e}")
+            raise
+    
+    def fetch_full_transcript(self, url: str) -> List[Dict]:
+        """Fetch full transcript once"""
+        logger.info(f"Fetching full transcript for: {url}")
+        ydl_opts = {
+            **self.base_ydl_opts,
+            'skip_download': True,
+            'writesubtitles': True,
+            'writeautomaticsub': True,
+            'subtitleslangs': ['en'],
+        }
+        
+        try:
+            with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+                info = ydl.extract_info(url, download=False)
+                
+                sub_url = None
+                if 'en' in info.get('subtitles', {}):
+                    sub_url = info['subtitles']['en'][-1].get('url')
+                elif 'en' in info.get('automatic_captions', {}):
+                    sub_url = info['automatic_captions']['en'][-1].get('url')
+                
+                if not sub_url:
+                    logger.warning("No transcript found")
+                    return []
+                
+                response = requests.get(sub_url, headers=self.headers, timeout=15)
+                response.raise_for_status()
+                sub_text = response.text
+                
+                segments = []
+                if sub_url.endswith('.vtt') or 'vtt' in sub_url:
+                    segments = parse_vtt_content(sub_text)
+                elif sub_url.endswith('.srt') or 'srt' in sub_url:
+                    # Reuse vtt logic as simple fallback
+                     segments = parse_vtt_content(sub_text)
+                
+                # If we have segments, return them
+                if segments:
+                    return segments
+                
+                # Fallback to json3 if available/needed
+                try:
+                    import json
+                    data = json.loads(sub_text)
+                    if 'events' in data:
+                        for event in data['events']:
+                            if 'segs' in event:
+                                start_time = event.get('tStartMs', 0) / 1000
+                                duration = event.get('dDurationMs', 0) / 1000
+                                text = ''.join(seg.get('utf8', '') for seg in event['segs'])
+                                segments.append({
+                                    'start': start_time,
+                                    'end': start_time + duration,
+                                    'text': text
+                                })
+                except:
+                    pass
+                    
+                return segments
+                
+        except Exception as e:
+            logger.error(f"Transcript error: {e}")
+            return []
+    
+    def get_transcript_text(self, segments: List[Dict], start: float, end: float) -> str:
+        """Filter transcript from pre-fetched segments"""
+        relevant = [
+            seg["text"] for seg in segments
+            if seg["end"] >= start and seg["start"] <= end and seg["text"].strip()
+        ]
+        return " ".join(relevant)
+    
+    def get_transcript(self, url: str, start: float, end: float) -> str:
+        """Legacy method for backward compatibility"""
+        segments = self.fetch_full_transcript(url)
+        return self.get_transcript_text(segments, start, end)
+
+    def score_clip(self, url: str, start: float, end: float, transcript_segments: List[Dict] = None) -> Dict:
+        """Calculate viral score for clip"""
+        if transcript_segments:
+            transcript = self.get_transcript_text(transcript_segments, start, end).lower()
+        else:
+            # Fallback
+            transcript = self.get_transcript(url, start, end).lower()
+        
+        score = 0
+        reasons = []
+        
+        # Hook words (up to 50 points)
+        hooks = [w for w in HOOK_WORDS if w in transcript]
+        hook_score = min(len(hooks) * 10, 50)
+        score += hook_score
+        if hooks:
+            reasons.append(f"Hooks: {', '.join(hooks[:3])}")
+        
+        # Emotion words (up to 30 points)
+        emotions = [w for w in EMOTION_WORDS if w in transcript]
+        emotion_score = min(len(emotions) * 6, 30)
+        score += emotion_score
+        if emotions:
+            reasons.append(f"Emotion: {', '.join(emotions[:2])}")
+        
+        # Conflict indicators (20 points)
+        conflict_words = ["but", "however", "argument", "fight", "wrong", "disagree"]
+        if any(w in transcript for w in conflict_words):
+            score += 20
+            reasons.append("Conflict detected")
+        
+        # Duration bonus
+        duration = end - start
+        if DEFAULT_MIN_CLIP_LENGTH <= duration <= DEFAULT_MAX_CLIP_LENGTH:
+            score += 10
+            reasons.append("Optimal duration")
+        elif duration < DEFAULT_MIN_CLIP_LENGTH:
+            score -= 10
+            reasons.append("Short clip")
+        elif duration > DEFAULT_MAX_CLIP_LENGTH:
+            score -= 5
+            reasons.append("Long clip")
+        
+        # Transcript quality bonus
+        word_count = len(transcript.split())
+        if word_count > 10:
+            score += 5
+            reasons.append("Good content density")
+        
+        return {
+            "start": start,
+            "end": end,
+            "duration": round(duration, 1),
+            "viral_score": max(0, min(score, 100)),
+            "reasons": reasons,
+            "transcript_preview": transcript[:150] + "..." if len(transcript) > 150 else transcript,
+            "word_count": word_count
+        }
+    
+    def generate_candidates(self, video_info: Dict, clip_length: int = None, window_step: int = None) -> List[Dict]:
+        """Generate candidate clips"""
+        duration = video_info.get("duration", 0)
+        clip_length = clip_length or DEFAULT_CLIP_LENGTH
+        window_step = window_step or DEFAULT_WINDOW_STEP
+        candidates = []
+        
+        # Use chapters if available
+        if video_info.get("chapters"):
+            logger.info(f"Using {len(video_info['chapters'])} chapters for candidates")
+            for ch in video_info["chapters"]:
+                clip_start = ch["start"]
+                clip_end = min(ch["end"], clip_start + clip_length)
+                if clip_end - clip_start >= DEFAULT_MIN_CLIP_LENGTH:
+                    candidates.append({
+                        "start": clip_start,
+                        "end": clip_end,
+                        "title": ch.get("title", "Untitled")
+                    })
+        else:
+            # Sliding windows
+            logger.info("Using sliding windows for candidates")
+            for start in range(0, int(duration) - clip_length, window_step):
+                candidates.append({
+                    "start": start,
+                    "end": min(start + clip_length, duration)
+                })
+        
+        return candidates
+
+# ============== API ROUTES ==============
+
+@app.route('/', methods=['GET'])
+def index():
+    """Root endpoint - API info"""
+    return jsonify({
+        "name": "Viral Clip Extractor API",
+        "version": "1.3.0 (AI Enabled)",
+        "description": "Extract and analyze viral clips from YouTube videos",
+        "quick_start": {
+            "endpoint": "/clips",
+            "method": "GET",
+            "usage": "/clips?url=YOUTUBE_URL&quality=720&seconds=40&num=5&mode=ai&gemini_key=YOUR_KEY",
+            "example": "/clips?url=https://youtube.com/watch?v=dQw4w9WgXcQ&seconds=30&num=3"
+        },
+        "endpoints": {
+            "/clips": "GET - Extract clips (Heuristic or AI)",
+            "/health": "Health check",
+            "/analyze": "POST - Full analysis",
+            "/extract": "POST - Extract video info only",
+            "/download_file": "GET - Download clip file"
+        }
+    })
+
+@app.route('/health', methods=['GET'])
+def health():
+    """Health check endpoint"""
+    return jsonify({
+        "status": "healthy",
+        "service": "viral-clip-extractor"
+    })
+
+@app.route('/clips', methods=['GET'])
+def get_clips():
+    """
+    Get viral clips (Heuristic, Gemini AI, or Nvidia AI)
+    """
+    try:
+        url = request.args.get('url')
+        if not url:
+            return jsonify({"error": "Missing 'url' parameter"}), 400
+        
+        quality = request.args.get('quality', '720')
+        seconds = int(request.args.get('seconds', DEFAULT_CLIP_LENGTH))
+        num_clips = int(request.args.get('num', 5))
+        
+        mode = request.args.get('mode', 'heuristic') # 'heuristic', 'ai' (defaults to gemini), 'nvidia'
+        ai_provider = request.args.get('ai_provider', 'gemini') # 'gemini' or 'nvidia'
+        
+        # Handle API Keys
+        nvidia_key = request.args.get('nvidia_key') or os.environ.get('NVIDIA_API_KEY')
+        gemini_key = request.args.get('gemini_key') or os.environ.get('GEMINI_API_KEY')
+        
+        # Unified key handling if user passes 'api_key' generic param
+        generic_key = request.args.get('api_key')
+        if generic_key:
+            if mode == 'nvidia' or ai_provider == 'nvidia':
+                nvidia_key = generic_key
+            else:
+                gemini_key = generic_key
+
+        extractor = ViralClipExtractor()
+        
+        # 1. Get video info
+        video_info = extractor.extract_video_info(url)
+        video_id = extract_video_id(url)
+        
+        if not video_id:
+             return jsonify({"error": "Invalid YouTube URL"}), 400
+
+        # 2. Fetch transcript ONCE
+        transcript_segments = extractor.fetch_full_transcript(url)
+        
+        scored_clips = []
+        
+        if mode == 'ai' or mode == 'nvidia' or request.args.get('ai_provider'):
+            # Determine provider
+            provider = 'nvidia' if (mode == 'nvidia' or ai_provider == 'nvidia') else 'gemini'
+            
+            try:
+                if provider == 'nvidia':
+                    if not nvidia_key:
+                         return jsonify({"error": "Nvidia API Key required"}), 400
+                    logger.info("Using Nvidia DeepSeek for analysis...")
+                    scored_clips = extractor.analyze_with_nvidia(transcript_segments, nvidia_key)
+                else:
+                    if not gemini_key:
+                         return jsonify({"error": "Gemini API Key required"}), 400
+                    logger.info("Using Gemini AI for analysis...")
+                    scored_clips = extractor.analyze_with_gemini(transcript_segments, gemini_key)
+                
+                # Normalize response
+                for clip in scored_clips:
+                    clip['title'] = clip.get('reason', f'{provider.title()} Selected Clip')
+                    clip.setdefault('start', 0)
+                    clip.setdefault('end', clip['start'] + seconds)
+                    clip.setdefault('viral_score', 80)
+                    
+            except Exception as e:
+                return jsonify({"error": f"AI Analysis Failed ({provider}): {str(e)}"}), 500
+        else:
+            # Heuristic
+            candidates = extractor.generate_candidates(video_info, seconds, DEFAULT_WINDOW_STEP)
+            
+            logger.info(f"Scoring {len(candidates)} candidates...")
+            for i, cand in enumerate(candidates):
+                score_data = extractor.score_clip(url, cand['start'], cand['end'], transcript_segments)
+                score_data['title'] = cand.get('title', f'Clip {i+1}')
+                scored_clips.append(score_data)
+            
+            scored_clips.sort(key=lambda x: x['viral_score'], reverse=True)
+        
+        # Select top non-overlapping clips
+        final_clips = []
+        used_ranges = []
+        
+        for clip in scored_clips:
+            overlaps = False
+            for used in used_ranges:
+                if not (clip['end'] <= used['start'] or clip['start'] >= used['end']):
+                    overlaps = True
+                    break
+            
+            if not overlaps:
+                final_clips.append(clip)
+                used_ranges.append(clip)
+                
+                if len(final_clips) >= num_clips:
+                    break
+        
+        import urllib.parse
+        encoded_url = urllib.parse.quote(url)
+        
+        for clip in final_clips:
+            # Ensure start/end are floats
+            clip['start'] = float(clip['start'])
+            clip['end'] = float(clip['end'])
+            clip['start_formatted'] = seconds_to_time(clip['start'])
+            clip['end_formatted'] = seconds_to_time(clip['end'])
+            clip['youtube_url'] = f"https://youtube.com/watch?v={video_id}&t={int(clip['start'])}"
+            clip['download_link'] = f"/download_file?url={encoded_url}&start={clip['start']}&end={clip['end']}&quality={quality}"
+            
+        return jsonify({
+            "success": True,
+            "video_id": video_id,
+            "video_title": video_info.get('title'),
+            "video_duration": video_info.get('duration'),
+            "mode": mode,
+            "clips": final_clips,
+            "clips_count": len(final_clips)
+        })
+        
+    except Exception as e:
+        logger.error(f"Error in /clips: {e}")
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 500
+
+@app.route('/extract', methods=['POST'])
+def extract_video():
+    """Extract basic video information"""
+    try:
+        data = request.get_json()
+        if not data or 'url' not in data:
+            return jsonify({"error": "Missing 'url' parameter"}), 400
+        
+        url = data['url']
+        video_id = extract_video_id(url)
+        
+        if not video_id:
+            return jsonify({"error": "Invalid YouTube URL"}), 400
+        
+        extractor = ViralClipExtractor()
+        info = extractor.extract_video_info(url)
+        
+        return jsonify({
+            "success": True,
+            "video_id": video_id,
+            "data": info
+        })
+        
+    except Exception as e:
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 500
+
+@app.route('/analyze', methods=['POST'])
+def analyze_video():
+    """Full viral clip analysis"""
+    try:
+        data = request.get_json()
+        if not data or 'url' not in data:
+            return jsonify({"error": "Missing 'url' parameter"}), 400
+        
+        url = data['url']
+        video_id = extract_video_id(url)
+        
+        if not video_id:
+            return jsonify({"error": "Invalid YouTube URL"}), 400
+        
+        num_clips = data.get('num_clips', 5)
+        clip_length = data.get('clip_length', DEFAULT_CLIP_LENGTH)
+        window_step = data.get('window_step', DEFAULT_WINDOW_STEP)
+        quality = data.get('quality', '720')
+        mode = data.get('mode', 'heuristic')
+        gemini_key = data.get('gemini_key') or os.environ.get('GEMINI_API_KEY')
+        
+        extractor = ViralClipExtractor()
+        
+        # 1. Get video info
+        video_info = extractor.extract_video_info(url)
+        
+        # 2. Fetch transcript ONCE
+        transcript_segments = extractor.fetch_full_transcript(url)
+        
+        if mode == 'ai':
+            if not gemini_key:
+                return jsonify({"error": "Gemini API Key required for AI mode"}), 400
+            
+            logger.info("Using Gemini AI for analysis")
+            scored_clips = extractor.analyze_with_gemini(transcript_segments, gemini_key)
+            
+            # Normalize AI response
+            for clip in scored_clips:
+                clip['title'] = clip.get('reason', 'AI Selected Clip')
+                clip.setdefault('start', 0)
+                clip.setdefault('end', clip['start'] + clip_length)
+                clip.setdefault('viral_score', 80)
+        else:
+            # 3. Generate candidates
+            candidates = extractor.generate_candidates(video_info, clip_length, window_step)
+            
+            # 4. Score candidates
+            scored_clips = []
+            logger.info(f"Scoring {len(candidates)} candidates...")
+            for i, cand in enumerate(candidates):
+                score_data = extractor.score_clip(url, cand['start'], cand['end'], transcript_segments)
+                score_data['title'] = cand.get('title', f'Clip {i+1}')
+                scored_clips.append(score_data)
+            
+            # Sort by viral score
+            scored_clips.sort(key=lambda x: x['viral_score'], reverse=True)
+        
+        # Select top non-overlapping clips
+        final_clips = []
+        used_ranges = []
+        
+        for clip in scored_clips:
+            overlaps = False
+            for used in used_ranges:
+                if not (clip['end'] <= used['start'] or clip['start'] >= used['end']):
+                    overlaps = True
+                    break
+            
+            if not overlaps:
+                final_clips.append(clip)
+                used_ranges.append(clip)
+                
+                if len(final_clips) >= num_clips:
+                    break
+        
+        # Add formatted times and YouTube URLs and Download Links
+        import urllib.parse
+        encoded_url = urllib.parse.quote(url)
+        
+        for clip in final_clips:
+            clip['start'] = float(clip['start'])
+            clip['end'] = float(clip['end'])
+            clip['start_formatted'] = seconds_to_time(clip['start'])
+            clip['end_formatted'] = seconds_to_time(clip['end'])
+            clip['youtube_url'] = f"https://youtube.com/watch?v={video_id}&t={int(clip['start'])}"
+            clip['download_link'] = f"/download_file?url={encoded_url}&start={clip['start']}&end={clip['end']}&quality={quality}"
+        
+        return jsonify({
+            "success": True,
+            "video_id": video_id,
+            "video_title": video_info.get('title'),
+            "video_duration": video_info.get('duration'),
+            "clips": final_clips
+        })
+        
+    except Exception as e:
+        logger.error(f"Error in /analyze: {e}")
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 500
+
+@app.route('/download_file', methods=['GET'])
+def download_file_endpoint():
+    """Download the actual clip file"""
+    try:
+        url = request.args.get('url')
+        if not url:
+            return jsonify({"error": "Missing 'url' parameter"}), 400
+        
+        start = float(request.args.get('start', 0))
+        end = float(request.args.get('end', 0))
+        quality = request.args.get('quality', '720')
+        
+        if end <= start:
+             return jsonify({"error": "Invalid time range"}), 400
+        
+        extractor = ViralClipExtractor()
+        file_path = extractor.download_clip(url, start, end, quality)
+        
+        if file_path and os.path.exists(file_path):
+            @after_this_request
+            def remove_file(response):
+                try:
+                   pass # windows file locking might prevent removal if not closed, but send_file should handle it
+                   # os.remove(file_path) # Defer removal or use a temp dir cleaner properly
+                except Exception as error:
+                    app.logger.error("Error removing file", error)
+                return response
+            
+            return send_file(file_path, as_attachment=True, download_name=os.path.basename(file_path))
+        else:
+            return jsonify({"error": "Failed to download clip"}), 500
+            
+    except Exception as e:
+        logger.error(f"Error in /download: {e}")
+        return jsonify({
+            "success": False,
+            "error": str(e)
+        }), 500
+
+@app.route('/docs', methods=['GET'])
+def docs():
+    """API Documentation & Credits"""
+    html = """
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>Viral Clip Extractor API | Documentation</title>
+        <style>
+            :root { --primary: #3b82f6; --secondary: #8b5cf6; --bg: #0f172a; --text: #f8fafc; --card-bg: #1e293b; }
+            body { 
+                font-family: 'Segoe UI', system-ui, sans-serif; 
+                line-height: 1.6; 
+                color: var(--text); 
+                background: var(--bg); 
+                max-width: 900px; 
+                margin: 0 auto; 
+                padding: 40px 20px;
+                opacity: 0;
+                animation: fadeIn 0.8s ease-out forwards;
+            }
+            
+            @keyframes fadeIn { from { opacity: 0; transform: translateY(20px); } to { opacity: 1; transform: translateY(0); } }
+            @keyframes pulse { 0% { transform: scale(1); } 50% { transform: scale(1.05); } 100% { transform: scale(1); } }
+            @keyframes gradient { 0% { background-position: 0% 50%; } 50% { background-position: 100% 50%; } 100% { background-position: 0% 50%; } }
+
+            h1 { font-size: 3rem; margin-bottom: 0.5rem; background: linear-gradient(to right, #60a5fa, #c084fc); -webkit-background-clip: text; -webkit-text-fill-color: transparent; }
+            h2 { margin-top: 3rem; border-bottom: 2px solid #334155; padding-bottom: 0.5rem; color: #94a3b8; }
+            h3 { color: #60a5fa; margin-top: 0; }
+            
+            .badge { background: linear-gradient(135deg, var(--primary), var(--secondary)); color: white; padding: 4px 12px; border-radius: 20px; font-size: 0.9rem; vertical-align: middle; box-shadow: 0 4px 6px -1px rgba(0,0,0,0.3); }
+            
+            .card { 
+                background: var(--card-bg); 
+                padding: 25px; 
+                border-radius: 16px; 
+                box-shadow: 0 10px 15px -3px rgba(0,0,0,0.3); 
+                margin-bottom: 25px; 
+                border: 1px solid #334155; 
+                transition: transform 0.3s ease, box-shadow 0.3s ease;
+            }
+            .card:hover { transform: translateY(-5px); box-shadow: 0 20px 25px -5px rgba(0,0,0,0.4); border-color: #60a5fa; }
+            
+            code { font-family: 'Consolas', monospace; background: #0f172a; padding: 4px 8px; border-radius: 6px; color: #f472b6; border: 1px solid #334155; }
+            pre { background: #020617; color: #e2e8f0; padding: 20px; border-radius: 12px; overflow-x: auto; font-size: 0.9rem; border: 1px solid #334155; }
+            
+            table { width: 100%; border-collapse: collapse; margin: 15px 0; }
+            th, td { text-align: left; padding: 12px; border-bottom: 1px solid #334155; }
+            th { color: #94a3b8; font-weight: 600; }
+            
+            .method { font-weight: bold; color: #34d399; }
+            .url { color: #cbd5e1; }
+            
+            .warning { background: rgba(249, 115, 22, 0.1); border-left: 4px solid #f97316; padding: 15px; margin: 20px 0; border-radius: 0 8px 8px 0; }
+            .tip { background: rgba(34, 197, 94, 0.1); border-left: 4px solid #22c55e; padding: 15px; margin: 20px 0; border-radius: 0 8px 8px 0; }
+            
+            .creator-highlight {
+                background: linear-gradient(270deg, #ff00cc, #333399, #60a5fa);
+                background-size: 600% 600%;
+                -webkit-background-clip: text;
+                -webkit-text-fill-color: transparent;
+                font-weight: 900;
+                font-size: 1.5em;
+                animation: gradient 3s ease infinite;
+                display: inline-block;
+                padding: 0 5px;
+            }
+            
+            footer { margin-top: 80px; text-align: center; color: #64748b; font-size: 1.1rem; border-top: 1px solid #334155; padding-top: 40px; }
+        </style>
+    </head>
+    <body>
+        <h1>Viral Clip Extractor API <span class="badge">v1.3</span></h1>
+        <p class="lead">Transform long-form YouTube videos into engaging viral clips using sophisticated AI analysis.</p>
+        
+        <div class="warning">
+            <strong>🔐 Security Best Practice:</strong> Do not pass API keys in URLs for public applications. 
+            Configure <code>GEMINI_API_KEY</code> and <code>NVIDIA_API_KEY</code> as Environment Variables on your server.
+        </div>
+
+        <h2>🧠 Analysis Modes & Usage</h2>
+        
+        <div class="card">
+            <h3>1. Heuristic Mode (Non-AI)</h3>
+            <p><strong>Best for:</strong> High-energy content, gaming, reactions. Fast and free.</p>
+            <div class="tip">No API Key required.</div>
+            <pre>GET /clips?url={youtube_url}&mode=heuristic&num=5</pre>
+        </div>
+
+        <div class="card">
+            <h3>2. Gemini AI Mode</h3>
+            <p><strong>Best for:</strong> Podcasts, storytelling, general dialogue. Balanced performance.</p>
+            <div class="warning">Requires <code>GEMINI_API_KEY</code> environment variable (or param).</div>
+            <pre>GET /clips?url={youtube_url}&mode=ai&num=5</pre>
+        </div>
+
+        <div class="card">
+            <h3>3. Nvidia/DeepSeek AI Mode</h3>
+            <p><strong>Best for:</strong> Technical content, debates, complex reasoning.</p>
+            <div class="warning">Requires <code>NVIDIA_API_KEY</code> environment variable (or param).</div>
+            <pre>GET /clips?url={youtube_url}&mode=nvidia&num=5</pre>
+        </div>
+
+        <h2>📚 Endpoints</h2>
+
+        <div class="card">
+            <h3>GET /clips</h3>
+            <p>Main endpoint to analyze and get clip suggestions.</p>
+            
+            <h4>Parameters</h4>
+            <table>
+                <tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr>
+                <tr><td><code>url</code></td><td>string</td><td>Yes</td><td>YouTube Video URL</td></tr>
+                <tr><td><code>mode</code></td><td>string</td><td>No</td><td><code>heuristic</code> (default), <code>ai</code>, <code>nvidia</code></td></tr>
+                <tr><td><code>num</code></td><td>int</td><td>No</td><td>Number of clips (default: 5)</td></tr>
+                <tr><td><code>quality</code></td><td>string</td><td>No</td><td>Video height (e.g., <code>720</code>, <code>1080</code>)</td></tr>
+            </table>
+
+            <h4>Example Response</h4>
+            <pre>{
+  "success": true,
+  "video_title": "Podcast Episode 1",
+  "mode": "ai",
+  "clips": [
+    {
+      "title": "Shocking Reveal",
+      "start": 120.5,
+      "end": 150.0,
+      "viral_score": 95,
+      "download_link": "/download_file?url=...&start=120.5&end=150"
+    }
+  ]
+}</pre>
+        </div>
+
+        <div class="card">
+            <h3>GET /download_file</h3>
+            <p>Download a specific clip directly.</p>
+            <pre>GET /download_file?url={url}&start={start}&end={end}</pre>
+        </div>
+
+        <footer>
+            <p>Developed with ❤️ by <span class="creator-highlight">yash@dev</span></p>
+            <p>&copy; 2026 Viral Clip Extractor API</p>
+        </footer>
+    </body>
+    </html>
+    """
+    return html
+
+# Local development and Production
+if __name__ == '__main__':
+    port = int(os.environ.get('PORT', 5000))
+    app.run(debug=True, host='0.0.0.0', port=port)
+

debug_ffmpeg.log

@@ -0,0 +1,113 @@
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Using Dir: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Using Dir: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin
+Project Root: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Checking: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe -> True
+Selected File: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin\ffmpeg.exe
+Adding to PATH: C:\Users\YASHWANTH\Downloads\Kimi_Agent_Viral Clip Extractor\ffmpeg\bin

diagnose_api.py

@@ -0,0 +1,47 @@
+
+import requests
+import time
+import sys
+
+BASE_URL = "http://127.0.0.1:5000"
+
+def test_health():
+    print("Checking /health...")
+    try:
+        t0 = time.time()
+        resp = requests.get(f"{BASE_URL}/health", timeout=5)
+        print(f"Health Status: {resp.status_code}")
+        print(f"Response: {resp.text}")
+        print(f"Time: {time.time() - t0:.2f}s")
+        return True
+    except Exception as e:
+        print(f"Health Check Failed: {e}")
+        return False
+
+def test_clips():
+    print("\nChecking /clips (simplified)...")
+    url = "https://youtu.be/uVkFrqugXFQ" # The user's URL
+    try:
+        t0 = time.time()
+        print(f"Requesting clips for {url}...")
+        resp = requests.get(f"{BASE_URL}/clips", params={
+            "url": url,
+            "seconds": 30,
+            "num": 2
+        }, timeout=60)
+        print(f"Clips Status: {resp.status_code}")
+        print(f"Time: {time.time() - t0:.2f}s")
+        if resp.status_code == 200:
+            data = resp.json()
+            print(f"Success! Got {len(data.get('clips', []))} clips")
+            print(f"Video: {data.get('video_title')}")
+        else:
+            print(f"Error: {resp.text}")
+    except requests.exceptions.Timeout:
+        print("❌ Request timed out after 60s")
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    if test_health():
+        test_clips()

error.log

@@ -0,0 +1,3 @@
+Download Error: ERROR: You have requested downloading the video partially, but ffmpeg is not installed. Aborting
+Download Error: ERROR: You have requested downloading the video partially, but ffmpeg is not installed. Aborting
+Download Error: ERROR: You have requested downloading the video partially, but ffmpeg is not installed. Aborting

examples/frontend-example.html

@@ -0,0 +1,492 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Viral Clip Extractor - Frontend Demo</title>
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+        
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+            min-height: 100vh;
+            color: #fff;
+            padding: 20px;
+        }
+        
+        .container {
+            max-width: 900px;
+            margin: 0 auto;
+        }
+        
+        h1 {
+            text-align: center;
+            margin-bottom: 10px;
+            font-size: 2.5rem;
+            background: linear-gradient(90deg, #ff6b6b, #feca57);
+            -webkit-background-clip: text;
+            -webkit-text-fill-color: transparent;
+        }
+        
+        .subtitle {
+            text-align: center;
+            color: #888;
+            margin-bottom: 30px;
+        }
+        
+        .input-section {
+            background: rgba(255,255,255,0.05);
+            border-radius: 16px;
+            padding: 25px;
+            margin-bottom: 20px;
+            border: 1px solid rgba(255,255,255,0.1);
+        }
+        
+        .form-group {
+            margin-bottom: 15px;
+        }
+        
+        label {
+            display: block;
+            margin-bottom: 8px;
+            color: #aaa;
+            font-size: 0.9rem;
+        }
+        
+        input, select {
+            width: 100%;
+            padding: 12px 16px;
+            border: 1px solid rgba(255,255,255,0.2);
+            border-radius: 8px;
+            background: rgba(0,0,0,0.3);
+            color: #fff;
+            font-size: 1rem;
+        }
+        
+        input:focus, select:focus {
+            outline: none;
+            border-color: #ff6b6b;
+        }
+        
+        .row {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+            gap: 15px;
+        }
+        
+        button {
+            width: 100%;
+            padding: 14px 24px;
+            background: linear-gradient(90deg, #ff6b6b, #feca57);
+            border: none;
+            border-radius: 8px;
+            color: #1a1a2e;
+            font-size: 1rem;
+            font-weight: 600;
+            cursor: pointer;
+            transition: transform 0.2s, box-shadow 0.2s;
+        }
+        
+        button:hover {
+            transform: translateY(-2px);
+            box-shadow: 0 8px 25px rgba(255,107,107,0.3);
+        }
+        
+        button:disabled {
+            opacity: 0.6;
+            cursor: not-allowed;
+            transform: none;
+        }
+        
+        .loading {
+            text-align: center;
+            padding: 40px;
+        }
+        
+        .spinner {
+            width: 50px;
+            height: 50px;
+            border: 3px solid rgba(255,255,255,0.1);
+            border-top-color: #ff6b6b;
+            border-radius: 50%;
+            animation: spin 1s linear infinite;
+            margin: 0 auto 20px;
+        }
+        
+        @keyframes spin {
+            to { transform: rotate(360deg); }
+        }
+        
+        .results {
+            display: none;
+        }
+        
+        .video-info {
+            background: rgba(255,255,255,0.05);
+            border-radius: 12px;
+            padding: 20px;
+            margin-bottom: 20px;
+        }
+        
+        .video-info h3 {
+            margin-bottom: 10px;
+            color: #feca57;
+        }
+        
+        .clip-card {
+            background: rgba(255,255,255,0.05);
+            border-radius: 12px;
+            padding: 20px;
+            margin-bottom: 15px;
+            border-left: 4px solid #ff6b6b;
+            transition: transform 0.2s;
+        }
+        
+        .clip-card:hover {
+            transform: translateX(5px);
+        }
+        
+        .clip-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 10px;
+        }
+        
+        .clip-rank {
+            font-size: 1.5rem;
+            font-weight: bold;
+            color: #ff6b6b;
+        }
+        
+        .clip-score {
+            background: linear-gradient(90deg, #ff6b6b, #feca57);
+            padding: 5px 15px;
+            border-radius: 20px;
+            font-weight: bold;
+            color: #1a1a2e;
+        }
+        
+        .clip-time {
+            color: #888;
+            font-size: 0.9rem;
+            margin-bottom: 10px;
+        }
+        
+        .clip-reasons {
+            display: flex;
+            flex-wrap: wrap;
+            gap: 8px;
+            margin-bottom: 10px;
+        }
+        
+        .reason-tag {
+            background: rgba(255,255,255,0.1);
+            padding: 4px 10px;
+            border-radius: 12px;
+            font-size: 0.8rem;
+            color: #aaa;
+        }
+        
+        .transcript-preview {
+            color: #888;
+            font-style: italic;
+            font-size: 0.9rem;
+            margin-top: 10px;
+            padding-top: 10px;
+            border-top: 1px solid rgba(255,255,255,0.1);
+        }
+        
+        .clip-actions {
+            margin-top: 15px;
+            display: flex;
+            gap: 10px;
+        }
+        
+        .btn-small {
+            padding: 8px 16px;
+            font-size: 0.85rem;
+        }
+        
+        .btn-secondary {
+            background: rgba(255,255,255,0.1);
+            color: #fff;
+        }
+        
+        .error {
+            background: rgba(255,107,107,0.1);
+            border: 1px solid #ff6b6b;
+            border-radius: 8px;
+            padding: 15px;
+            color: #ff6b6b;
+            text-align: center;
+        }
+        
+        .api-config {
+            margin-bottom: 20px;
+        }
+        
+        .endpoint-selector {
+            display: flex;
+            gap: 10px;
+            margin-bottom: 15px;
+            flex-wrap: wrap;
+        }
+        
+        .endpoint-btn {
+            padding: 8px 16px;
+            background: rgba(255,255,255,0.1);
+            border: 1px solid rgba(255,255,255,0.2);
+            border-radius: 6px;
+            color: #fff;
+            cursor: pointer;
+            transition: all 0.2s;
+        }
+        
+        .endpoint-btn.active {
+            background: #ff6b6b;
+            border-color: #ff6b6b;
+        }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <h1>🔥 Viral Clip Extractor</h1>
+        <p class="subtitle">Extract the most viral moments from any YouTube video</p>
+        
+        <div class="input-section">
+            <div class="api-config">
+                <label>API Base URL</label>
+                <input type="text" id="apiUrl" placeholder="https://your-api.vercel.app" value="">
+            </div>
+            
+            <div class="endpoint-selector">
+                <button class="endpoint-btn active" data-endpoint="analyze">Analyze</button>
+                <button class="endpoint-btn" data-endpoint="extract">Extract Info</button>
+                <button class="endpoint-btn" data-endpoint="transcript">Transcript</button>
+            </div>
+            
+            <div class="form-group">
+                <label>YouTube URL</label>
+                <input type="text" id="videoUrl" placeholder="https://youtube.com/watch?v=...">
+            </div>
+            
+            <div id="analyzeOptions" class="options-section">
+                <div class="row">
+                    <div class="form-group">
+                        <label>Number of Clips</label>
+                        <input type="number" id="numClips" value="5" min="1" max="20">
+                    </div>
+                    <div class="form-group">
+                        <label>Clip Length (sec)</label>
+                        <input type="number" id="clipLength" value="40" min="10" max="120">
+                    </div>
+                    <div class="form-group">
+                        <label>Quality</label>
+                        <select id="quality">
+                            <option value="360">360p</option>
+                            <option value="720" selected>720p</option>
+                            <option value="1080">1080p</option>
+                        </select>
+                    </div>
+                </div>
+            </div>
+            
+            <div id="transcriptOptions" class="options-section" style="display:none;">
+                <div class="row">
+                    <div class="form-group">
+                        <label>Start Time (sec)</label>
+                        <input type="number" id="startTime" value="0" min="0">
+                    </div>
+                    <div class="form-group">
+                        <label>End Time (sec)</label>
+                        <input type="number" id="endTime" value="60" min="10">
+                    </div>
+                </div>
+            </div>
+            
+            <button id="analyzeBtn" onclick="analyzeVideo()">
+                🔍 Analyze Video
+            </button>
+        </div>
+        
+        <div id="loading" class="loading" style="display:none;">
+            <div class="spinner"></div>
+            <p>Analyzing video for viral clips...</p>
+        </div>
+        
+        <div id="error" class="error" style="display:none;"></div>
+        
+        <div id="results" class="results">
+            <div id="videoInfo" class="video-info"></div>
+            <div id="clipsList"></div>
+        </div>
+    </div>
+
+    <script>
+        let currentEndpoint = 'analyze';
+        
+        // Endpoint selector
+        document.querySelectorAll('.endpoint-btn').forEach(btn => {
+            btn.addEventListener('click', () => {
+                document.querySelectorAll('.endpoint-btn').forEach(b => b.classList.remove('active'));
+                btn.classList.add('active');
+                currentEndpoint = btn.dataset.endpoint;
+                
+                // Show/hide options
+                document.getElementById('analyzeOptions').style.display = 
+                    currentEndpoint === 'analyze' ? 'block' : 'none';
+                document.getElementById('transcriptOptions').style.display = 
+                    currentEndpoint === 'transcript' ? 'block' : 'none';
+                
+                // Update button text
+                const btnText = {
+                    'analyze': '🔍 Analyze Video',
+                    'extract': '📹 Extract Info',
+                    'transcript': '📝 Get Transcript'
+                };
+                document.getElementById('analyzeBtn').textContent = btnText[currentEndpoint];
+            });
+        });
+        
+        async function analyzeVideo() {
+            const apiUrl = document.getElementById('apiUrl').value.trim();
+            const videoUrl = document.getElementById('videoUrl').value.trim();
+            
+            if (!apiUrl) {
+                showError('Please enter your API base URL');
+                return;
+            }
+            if (!videoUrl) {
+                showError('Please enter a YouTube URL');
+                return;
+            }
+            
+            // Show loading
+            document.getElementById('loading').style.display = 'block';
+            document.getElementById('results').style.display = 'none';
+            document.getElementById('error').style.display = 'none';
+            
+            const endpoint = `${apiUrl.replace(/\/$/, '')}/${currentEndpoint}`;
+            
+            let body = { url: videoUrl };
+            
+            if (currentEndpoint === 'analyze') {
+                body.num_clips = parseInt(document.getElementById('numClips').value);
+                body.clip_length = parseInt(document.getElementById('clipLength').value);
+                body.quality = document.getElementById('quality').value;
+            } else if (currentEndpoint === 'transcript') {
+                body.start = parseInt(document.getElementById('startTime').value);
+                body.end = parseInt(document.getElementById('endTime').value);
+            }
+            
+            try {
+                const response = await fetch(endpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(body)
+                });
+                
+                const data = await response.json();
+                
+                if (!data.success) {
+                    throw new Error(data.error || 'Unknown error');
+                }
+                
+                if (currentEndpoint === 'analyze') {
+                    displayResults(data);
+                } else if (currentEndpoint === 'extract') {
+                    displayVideoInfo(data.data);
+                } else if (currentEndpoint === 'transcript') {
+                    displayTranscript(data);
+                }
+                
+            } catch (err) {
+                showError(err.message);
+            } finally {
+                document.getElementById('loading').style.display = 'none';
+            }
+        }
+        
+        function displayResults(data) {
+            document.getElementById('results').style.display = 'block';
+            
+            // Video info
+            const videoInfo = document.getElementById('videoInfo');
+            videoInfo.innerHTML = `
+                <h3>📹 ${data.video_title}</h3>
+                <p>Duration: ${formatTime(data.video_duration)} | Clips found: ${data.clips.length}</p>
+            `;
+            
+            // Clips
+            const clipsList = document.getElementById('clipsList');
+            clipsList.innerHTML = data.clips.map((clip, i) => `
+                <div class="clip-card">
+                    <div class="clip-header">
+                        <span class="clip-rank">#${i + 1}</span>
+                        <span class="clip-score">${clip.viral_score}% Viral</span>
+                    </div>
+                    <div class="clip-time">
+                        ⏱️ ${clip.start_formatted} - ${clip.end_formatted} (${clip.duration}s)
+                    </div>
+                    <div class="clip-reasons">
+                        ${clip.reasons.map(r => `<span class="reason-tag">${r}</span>`).join('')}
+                    </div>
+                    ${clip.transcript_preview ? `
+                        <div class="transcript-preview">
+                            "${clip.transcript_preview}"
+                        </div>
+                    ` : ''}
+                    <div class="clip-actions">
+                        <a href="${clip.youtube_url}" target="_blank" class="btn-small">Open on YouTube</a>
+                    </div>
+                </div>
+            `).join('');
+        }
+        
+        function displayVideoInfo(data) {
+            document.getElementById('results').style.display = 'block';
+            document.getElementById('videoInfo').innerHTML = `
+                <h3>📹 ${data.title}</h3>
+                <p><strong>Channel:</strong> ${data.uploader}</p>
+                <p><strong>Duration:</strong> ${formatTime(data.duration)}</p>
+                <p><strong>Views:</strong> ${data.view_count?.toLocaleString() || 'N/A'}</p>
+                <p><strong>Upload Date:</strong> ${data.upload_date || 'N/A'}</p>
+                <p><strong>Chapters:</strong> ${data.chapters?.length || 0}</p>
+            `;
+            document.getElementById('clipsList').innerHTML = '';
+        }
+        
+        function displayTranscript(data) {
+            document.getElementById('results').style.display = 'block';
+            document.getElementById('videoInfo').innerHTML = `
+                <h3>📝 Transcript</h3>
+                <p>Time: ${data.start_formatted} - ${data.end_formatted}</p>
+                <p>Words: ${data.word_count}</p>
+            `;
+            document.getElementById('clipsList').innerHTML = `
+                <div class="clip-card">
+                    <p style="line-height: 1.6;">${data.transcript || 'No transcript available'}</p>
+                </div>
+            `;
+        }
+        
+        function showError(message) {
+            document.getElementById('error').textContent = message;
+            document.getElementById('error').style.display = 'block';
+        }
+        
+        function formatTime(seconds) {
+            if (!seconds) return 'N/A';
+            const mins = Math.floor(seconds / 60);
+            const secs = seconds % 60;
+            return `${mins}:${secs.toString().padStart(2, '0')}`;
+        }
+    </script>
+</body>
+</html>

examples/postman-collection.json

@@ -0,0 +1,152 @@
+{
+  "info": {
+    "name": "Viral Clip Extractor API",
+    "description": "API collection for extracting viral clips from YouTube videos",
+    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
+  },
+  "item": [
+    {
+      "name": "Health Check",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": {
+          "raw": "{{base_url}}/health",
+          "host": ["{{base_url}}"],
+          "path": ["health"]
+        },
+        "description": "Check if API is running"
+      }
+    },
+    {
+      "name": "API Info",
+      "request": {
+        "method": "GET",
+        "header": [],
+        "url": {
+          "raw": "{{base_url}}",
+          "host": ["{{base_url}}"]
+        },
+        "description": "Get API information"
+      }
+    },
+    {
+      "name": "Extract Video Info",
+      "request": {
+        "method": "POST",
+        "header": [
+          {
+            "key": "Content-Type",
+            "value": "application/json"
+          }
+        ],
+        "body": {
+          "mode": "raw",
+          "raw": "{\n  \"url\": \"https://youtube.com/watch?v=VIDEO_ID\"\n}"
+        },
+        "url": {
+          "raw": "{{base_url}}/extract",
+          "host": ["{{base_url}}"],
+          "path": ["extract"]
+        },
+        "description": "Extract basic video information"
+      }
+    },
+    {
+      "name": "Analyze Video (Full)",
+      "request": {
+        "method": "POST",
+        "header": [
+          {
+            "key": "Content-Type",
+            "value": "application/json"
+          }
+        ],
+        "body": {
+          "mode": "raw",
+          "raw": "{\n  \"url\": \"https://youtube.com/watch?v=VIDEO_ID\",\n  \"num_clips\": 5,\n  \"clip_length\": 40,\n  \"window_step\": 10,\n  \"quality\": \"720\"\n}"
+        },
+        "url": {
+          "raw": "{{base_url}}/analyze",
+          "host": ["{{base_url}}"],
+          "path": ["analyze"]
+        },
+        "description": "Full viral clip analysis"
+      }
+    },
+    {
+      "name": "Score Time Range",
+      "request": {
+        "method": "POST",
+        "header": [
+          {
+            "key": "Content-Type",
+            "value": "application/json"
+          }
+        ],
+        "body": {
+          "mode": "raw",
+          "raw": "{\n  \"url\": \"https://youtube.com/watch?v=VIDEO_ID\",\n  \"start\": \"2:00\",\n  \"end\": \"2:40\"\n}"
+        },
+        "url": {
+          "raw": "{{base_url}}/score",
+          "host": ["{{base_url}}"],
+          "path": ["score"]
+        },
+        "description": "Score a specific time range"
+      }
+    },
+    {
+      "name": "Get Transcript",
+      "request": {
+        "method": "POST",
+        "header": [
+          {
+            "key": "Content-Type",
+            "value": "application/json"
+          }
+        ],
+        "body": {
+          "mode": "raw",
+          "raw": "{\n  \"url\": \"https://youtube.com/watch?v=VIDEO_ID\",\n  \"start\": 120,\n  \"end\": 180\n}"
+        },
+        "url": {
+          "raw": "{{base_url}}/transcript",
+          "host": ["{{base_url}}"],
+          "path": ["transcript"]
+        },
+        "description": "Get transcript for a time range"
+      }
+    },
+    {
+      "name": "Get Download URL",
+      "request": {
+        "method": "POST",
+        "header": [
+          {
+            "key": "Content-Type",
+            "value": "application/json"
+          }
+        ],
+        "body": {
+          "mode": "raw",
+          "raw": "{\n  \"url\": \"https://youtube.com/watch?v=VIDEO_ID\",\n  \"start\": \"2:00\",\n  \"end\": \"2:40\",\n  \"quality\": \"720\"\n}"
+        },
+        "url": {
+          "raw": "{{base_url}}/download",
+          "host": ["{{base_url}}"],
+          "path": ["download"]
+        },
+        "description": "Get download URL for a clip"
+      }
+    }
+  ],
+  "variable": [
+    {
+      "key": "base_url",
+      "value": "https://your-api.vercel.app",
+      "type": "string",
+      "description": "Your API base URL"
+    }
+  ]
+}

examples/python-client.py

@@ -0,0 +1,253 @@
+"""
+Viral Clip Extractor - Python Client Example
+Usage: python python-client.py
+"""
+
+import requests
+import json
+
+# Configuration
+API_BASE_URL = "https://your-api.vercel.app"  # Replace with your API URL
+
+
+def analyze_video(url: str, num_clips: int = 5, clip_length: int = 40, quality: str = "720"):
+    """
+    Analyze a YouTube video for viral clips
+    
+    Args:
+        url: YouTube video URL
+        num_clips: Number of clips to return
+        clip_length: Target clip length in seconds
+        quality: Video quality (360, 720, 1080)
+    """
+    endpoint = f"{API_BASE_URL}/analyze"
+    
+    payload = {
+        "url": url,
+        "num_clips": num_clips,
+        "clip_length": clip_length,
+        "quality": quality
+    }
+    
+    print(f"🔍 Analyzing: {url}")
+    print(f"   Clips: {num_clips} | Length: {clip_length}s | Quality: {quality}p")
+    print("-" * 60)
+    
+    try:
+        response = requests.post(endpoint, json=payload, timeout=60)
+        response.raise_for_status()
+        data = response.json()
+        
+        if not data.get("success"):
+            print(f"❌ Error: {data.get('error')}")
+            return None
+        
+        print(f"✅ Found {len(data['clips'])} viral clips!")
+        print(f"📹 Video: {data['video_title']}")
+        print()
+        
+        for i, clip in enumerate(data['clips'], 1):
+            print(f"CLIP #{i}")
+            print(f"  Score: {clip['viral_score']}% viral")
+            print(f"  Time: {clip['start_formatted']} - {clip['end_formatted']}")
+            print(f"  Reasons: {', '.join(clip['reasons'])}")
+            print(f"  Preview: {clip['transcript_preview'][:80]}...")
+            print(f"  URL: {clip['youtube_url']}")
+            print()
+        
+        return data
+        
+    except requests.exceptions.RequestException as e:
+        print(f"❌ Request failed: {e}")
+        return None
+
+
+def extract_video_info(url: str):
+    """Extract basic video information"""
+    endpoint = f"{API_BASE_URL}/extract"
+    
+    print(f"📹 Extracting info: {url}")
+    
+    try:
+        response = requests.post(endpoint, json={"url": url}, timeout=30)
+        response.raise_for_status()
+        data = response.json()
+        
+        if data.get("success"):
+            info = data["data"]
+            print(f"✅ Title: {info['title']}")
+            print(f"   Channel: {info['uploader']}")
+            print(f"   Duration: {info['duration']}s")
+            print(f"   Views: {info.get('view_count', 'N/A')}")
+            return info
+        else:
+            print(f"❌ Error: {data.get('error')}")
+            return None
+            
+    except requests.exceptions.RequestException as e:
+        print(f"❌ Request failed: {e}")
+        return None
+
+
+def get_transcript(url: str, start: int = 0, end: int = 60):
+    """Get transcript for a specific time range"""
+    endpoint = f"{API_BASE_URL}/transcript"
+    
+    payload = {
+        "url": url,
+        "start": start,
+        "end": end
+    }
+    
+    print(f"📝 Getting transcript: {start}s - {end}s")
+    
+    try:
+        response = requests.post(endpoint, json=payload, timeout=30)
+        response.raise_for_status()
+        data = response.json()
+        
+        if data.get("success"):
+            print(f"✅ Transcript ({data['word_count']} words):")
+            print(f"   {data['transcript'][:200]}...")
+            return data
+        else:
+            print(f"❌ Error: {data.get('error')}")
+            return None
+            
+    except requests.exceptions.RequestException as e:
+        print(f"❌ Request failed: {e}")
+        return None
+
+
+def score_clip(url: str, start: str, end: str):
+    """Score a specific time range for viral potential"""
+    endpoint = f"{API_BASE_URL}/score"
+    
+    payload = {
+        "url": url,
+        "start": start,
+        "end": end
+    }
+    
+    print(f"🎯 Scoring clip: {start} - {end}")
+    
+    try:
+        response = requests.post(endpoint, json=payload, timeout=30)
+        response.raise_for_status()
+        data = response.json()
+        
+        if data.get("success"):
+            clip = data["clip"]
+            print(f"✅ Viral Score: {clip['viral_score']}%")
+            print(f"   Reasons: {', '.join(clip['reasons'])}")
+            print(f"   Words: {clip['word_count']}")
+            return clip
+        else:
+            print(f"❌ Error: {data.get('error')}")
+            return None
+            
+    except requests.exceptions.RequestException as e:
+        print(f"❌ Request failed: {e}")
+        return None
+
+
+def get_download_url(url: str, start: str, end: str, quality: str = "720"):
+    """Get download URL for a clip"""
+    endpoint = f"{API_BASE_URL}/download"
+    
+    payload = {
+        "url": url,
+        "start": start,
+        "end": end,
+        "quality": quality
+    }
+    
+    print(f"⬇️ Getting download URL: {start} - {end}")
+    
+    try:
+        response = requests.post(endpoint, json=payload, timeout=30)
+        response.raise_for_status()
+        data = response.json()
+        
+        if data.get("success"):
+            info = data["download_info"]
+            print(f"✅ Download ready!")
+            print(f"   URL: {info['download_url'][:80]}...")
+            print(f"   Formats available: {len(info['formats'])}")
+            return info
+        else:
+            print(f"❌ Error: {data.get('error')}")
+            return None
+            
+    except requests.exceptions.RequestException as e:
+        print(f"❌ Request failed: {e}")
+        return None
+
+
+def batch_analyze(urls: list, num_clips: int = 3):
+    """Analyze multiple videos in batch"""
+    results = []
+    
+    print(f"🔄 Batch analyzing {len(urls)} videos...")
+    print("=" * 60)
+    
+    for i, url in enumerate(urls, 1):
+        print(f"\n[{i}/{len(urls)}]")
+        result = analyze_video(url, num_clips=num_clips)
+        if result:
+            results.append(result)
+    
+    print("\n" + "=" * 60)
+    print(f"✅ Batch complete! Analyzed {len(results)} videos")
+    
+    return results
+
+
+# Example usage
+if __name__ == "__main__":
+    # Replace with your API URL
+    API_BASE_URL = input("Enter your API base URL: ").strip()
+    
+    # Example YouTube URL (replace with actual URL)
+    test_url = input("Enter YouTube URL: ").strip()
+    
+    print("\n" + "=" * 60)
+    print("VIRAL CLIP EXTRACTOR - Python Client")
+    print("=" * 60 + "\n")
+    
+    # Menu
+    print("Choose an option:")
+    print("1. Full Analysis (find viral clips)")
+    print("2. Extract Video Info")
+    print("3. Get Transcript")
+    print("4. Score Specific Range")
+    print("5. Get Download URL")
+    
+    choice = input("\nEnter choice (1-5): ").strip()
+    
+    if choice == "1":
+        num = int(input("Number of clips (default 5): ") or "5")
+        length = int(input("Clip length in seconds (default 40): ") or "40")
+        analyze_video(test_url, num_clips=num, clip_length=length)
+    
+    elif choice == "2":
+        extract_video_info(test_url)
+    
+    elif choice == "3":
+        start = int(input("Start time in seconds: "))
+        end = int(input("End time in seconds: "))
+        get_transcript(test_url, start, end)
+    
+    elif choice == "4":
+        start = input("Start time (MM:SS or seconds): ")
+        end = input("End time (MM:SS or seconds): ")
+        score_clip(test_url, start, end)
+    
+    elif choice == "5":
+        start = input("Start time (MM:SS or seconds): ")
+        end = input("End time (MM:SS or seconds): ")
+        quality = input("Quality (360/720/1080, default 720): ") or "720"
+        get_download_url(test_url, start, end, quality)
+    
+    else:
+        print("Invalid choice!")

install_ffmpeg.py

@@ -0,0 +1,51 @@
+
+import urllib.request
+import zipfile
+import os
+import shutil
+
+FFMPEG_URL = "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip"
+DOWNLOAD_path = "ffmpeg.zip"
+EXTRACT_DIR = "ffmpeg_temp"
+FINAL_DIR = "ffmpeg"
+
+def install_ffmpeg():
+    print(f"Downloading FFmpeg from {FFMPEG_URL}...")
+    try:
+        urllib.request.urlretrieve(FFMPEG_URL, DOWNLOAD_path)
+        print("Download complete.")
+        
+        print("Extracting...")
+        with zipfile.ZipFile(DOWNLOAD_path, 'r') as zip_ref:
+            zip_ref.extractall(EXTRACT_DIR)
+        
+        # Move bin folder to top level
+        # The zip structure is usually ffmpeg-master-latest-win64-gpl/bin/ffmpeg.exe
+        # We want ffmpeg/bin/ffmpeg.exe
+        
+        extracted_root = os.path.join(EXTRACT_DIR, os.listdir(EXTRACT_DIR)[0])
+        
+        if os.path.exists(FINAL_DIR):
+            print("Removing old installation...")
+            shutil.rmtree(FINAL_DIR)
+            
+        shutil.move(extracted_root, FINAL_DIR)
+        
+        # Cleanup
+        os.remove(DOWNLOAD_path)
+        shutil.rmtree(EXTRACT_DIR)
+        
+        print(f"FFmpeg installed to {os.path.abspath(FINAL_DIR)}")
+        
+        # Verify
+        bin_path = os.path.join(FINAL_DIR, "bin", "ffmpeg.exe")
+        if os.path.exists(bin_path):
+            print(f"✅ Verified: {bin_path}")
+        else:
+            print("❌ Error: ffmpeg.exe not found in expected path")
+            
+    except Exception as e:
+        print(f"Error installing FFmpeg: {e}")
+
+if __name__ == "__main__":
+    install_ffmpeg()

list_models.py

@@ -0,0 +1,14 @@
+
+import google.generativeai as genai
+import os
+
+API_KEY = "AIzaSyAOXzvcFroHyNa5UtYRi3c8AGX0MJ1Tb5E"
+genai.configure(api_key=API_KEY)
+
+print("Listing available models...")
+try:
+    for m in genai.list_models():
+        if 'generateContent' in m.supported_generation_methods:
+            print(m.name)
+except Exception as e:
+    print(f"Error: {e}")

requirements.txt

@@ -0,0 +1,36 @@
+# Viral Clip Extractor API - Dependencies
+# Python 3.9+
+
+# Web Framework
+flask==3.0.3
+flask-cors==4.0.1
+werkzeug==3.0.3
+
+# YouTube Download
+yt-dlp==2024.8.6
+google-generativeai==0.7.2
+openai==1.61.0 # For Nvidia API
+gunicorn==21.2.0 # Production Server
+
+# HTTP Requests
+requests==2.32.3
+urllib3==2.2.2
+certifi==2024.7.4
+charset-normalizer==3.3.2
+idna==3.7
+
+# Data Processing
+# (Using built-in json, re, typing modules)
+
+# Serverless Support
+# Vercel Python runtime handles these automatically
+# python-dateutil is often useful
+python-dateutil==2.8.2
+
+# Optional: For better JSON handling
+# (Using built-in json module)
+
+# Development dependencies (not needed for deployment)
+# pytest==8.3.2
+# black==24.8.0
+# flake8==7.1.1

test_ai_mode.py

@@ -0,0 +1,63 @@
+
+import requests
+import os
+import json
+import sys
+
+# REPLACE THIS WITH YOUR KEY or set GEMINI_API_KEY env var
+# Get from: https://aistudio.google.com/app/apikey
+DEFAULT_KEY = "AIzaSyAOXzvcFroHyNa5UtYRi3c8AGX0MJ1Tb5E"
+API_KEY = os.environ.get("GEMINI_API_KEY", DEFAULT_KEY) 
+
+URL = "https://youtu.be/uVkFrqugXFQ"
+BASE_URL = "http://127.0.0.1:5000"
+
+def test_ai():
+    print("Testing AI Mode...")
+    
+    # Check if key is set
+    if "YOUR_GEMINI" in API_KEY:
+        print("\nWARNING: You haven't set your Gemini API Key!")
+        print("1. Get a key here: https://aistudio.google.com/app/apikey")
+        print("2. Open this script and replace 'YOUR_GEMINI_API_KEY_HERE'")
+        print("   OR set env var: $env:GEMINI_API_KEY='your_key'")
+        return
+
+    print(f"Analyzing {URL} using Gemini...")
+    print("This may take 10-20 seconds...")
+    
+    try:
+        # Test the GET /clips endpoint with mode=ai
+        resp = requests.get(f"{BASE_URL}/clips", params={
+            "url": URL,
+            "mode": "ai",
+            "gemini_key": API_KEY,
+            "num": 3,
+            "seconds": 30
+        }, timeout=120)
+        
+        if resp.status_code == 200:
+            data = resp.json()
+            print("\nSUCCESS! AI Candidates Found:")
+            clips = data.get('clips', [])
+            
+            if not clips:
+                print("   (No clips found. AI might have filtered everything or returned empty)")
+                
+            for i, clip in enumerate(clips):
+                print(f"\nClip {i+1}: {clip.get('title')}")
+                print(f"   Score: {clip.get('viral_score')}")
+                print(f"   Download: {clip.get('download_link')}")
+                print(f"   Reason: {clip.get('reason')}")
+        else:
+            print(f"\nError: {resp.status_code}")
+            try:
+                print(json.dumps(resp.json(), indent=2))
+            except:
+                print(resp.text)
+            
+    except Exception as e:
+        print(f"\nException: {e}")
+
+if __name__ == "__main__":
+    test_ai()

test_api.py

@@ -0,0 +1,110 @@
+"""
+Test suite for Viral Clip Extractor API
+Run with: python -m pytest test_api.py
+"""
+
+import pytest
+import json
+from api.index import app, extract_video_id, time_to_seconds, seconds_to_time
+
+@pytest.fixture
+def client():
+    """Create test client"""
+    app.config['TESTING'] = True
+    with app.test_client() as client:
+        yield client
+
+def test_health_endpoint(client):
+    """Test health check"""
+    response = client.get('/health')
+    assert response.status_code == 200
+    data = json.loads(response.data)
+    assert data['status'] == 'healthy'
+
+def test_index_endpoint(client):
+    """Test API info endpoint"""
+    response = client.get('/')
+    assert response.status_code == 200
+    data = json.loads(response.data)
+    assert 'name' in data
+    assert 'endpoints' in data
+
+def test_extract_video_id():
+    """Test video ID extraction from various URLs"""
+    # Standard URL
+    assert extract_video_id('https://youtube.com/watch?v=dQw4w9WgXcQ') == 'dQw4w9WgXcQ'
+    # Short URL
+    assert extract_video_id('https://youtu.be/dQw4w9WgXcQ') == 'dQw4w9WgXcQ'
+    # Embed URL
+    assert extract_video_id('https://youtube.com/embed/dQw4w9WgXcQ') == 'dQw4w9WgXcQ'
+    # Shorts URL
+    assert extract_video_id('https://youtube.com/shorts/dQw4w9WgXcQ') == 'dQw4w9WgXcQ'
+    # Just ID
+    assert extract_video_id('dQw4w9WgXcQ') == 'dQw4w9WgXcQ'
+    # Invalid
+    assert extract_video_id('not-a-valid-url') is None
+
+def test_time_conversions():
+    """Test time conversion functions"""
+    # Seconds to time
+    assert seconds_to_time(120) == '2:00'
+    assert seconds_to_time(65) == '1:05'
+    assert seconds_to_time(0) == '0:00'
+    
+    # Time to seconds
+    assert time_to_seconds('2:00') == 120
+    assert time_to_seconds('1:30') == 90
+    assert time_to_seconds('1:30:45') == 5445
+    assert time_to_seconds(120) == 120
+
+def test_extract_endpoint_missing_url(client):
+    """Test extract endpoint with missing URL"""
+    response = client.post('/extract', 
+                          data=json.dumps({}),
+                          content_type='application/json')
+    assert response.status_code == 400
+    data = json.loads(response.data)
+    assert 'error' in data
+
+def test_extract_endpoint_invalid_url(client):
+    """Test extract endpoint with invalid URL"""
+    response = client.post('/extract',
+                          data=json.dumps({'url': 'invalid-url'}),
+                          content_type='application/json')
+    assert response.status_code == 400
+    data = json.loads(response.data)
+    assert 'error' in data
+
+def test_analyze_endpoint_missing_url(client):
+    """Test analyze endpoint with missing URL"""
+    response = client.post('/analyze',
+                          data=json.dumps({}),
+                          content_type='application/json')
+    assert response.status_code == 400
+
+def test_score_endpoint_missing_params(client):
+    """Test score endpoint with missing parameters"""
+    response = client.post('/score',
+                          data=json.dumps({'url': 'https://youtube.com/watch?v=test'}),
+                          content_type='application/json')
+    assert response.status_code == 400
+
+def test_transcript_endpoint(client):
+    """Test transcript endpoint structure"""
+    response = client.post('/transcript',
+                          data=json.dumps({
+                              'url': 'https://youtube.com/watch?v=test',
+                              'start': 0,
+                              'end': 60
+                          }),
+                          content_type='application/json')
+    # Will fail due to invalid video, but tests structure
+    assert response.status_code in [400, 500]
+
+def test_cors_headers(client):
+    """Test CORS is enabled"""
+    response = client.get('/')
+    assert 'Access-Control-Allow-Origin' in response.headers
+
+if __name__ == '__main__':
+    pytest.main([__file__, '-v'])

test_download_clip.py

@@ -0,0 +1,33 @@
+
+from api.index import ViralClipExtractor
+import os
+
+def test_download():
+    extractor = ViralClipExtractor()
+    url = "https://youtu.be/uVkFrqugXFQ"
+    print("Testing download of 5s clip...")
+    try:
+        # Try to download 5s segment
+        path = extractor.download_clip(url, "0:00", "0:05") # Method doesn't exist yet in my class, I need to add it or test raw yt-dlp
+        print(f"Downloaded to: {path}")
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    # monkey patch for testing purposes or just write raw yt-dlp code here
+    import yt_dlp
+    
+    url = "https://youtu.be/uVkFrqugXFQ"
+    ydl_opts = {
+        'format': 'bestvideo[height<=720]+bestaudio/best',
+        'outtmpl': 'test_clip.%(ext)s',
+        'download_ranges': lambda info, ydl: [{'start_time': 0, 'end_time': 5}],
+        'force_keyframes_at_cuts': True,
+    }
+    
+    try:
+        with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+            ydl.download([url])
+        print("Download success")
+    except Exception as e:
+        print(f"Download failed: {e}")

test_download_e2e.py

@@ -0,0 +1,64 @@
+
+import requests
+import time
+import os
+
+BASE_URL = "http://127.0.0.1:5000"
+
+def test_e2e_download():
+    print("Testing /clips and download link...")
+    url = "https://youtu.be/uVkFrqugXFQ" 
+    
+    try:
+        # 1. Get Clips
+        print("Fetching clips...")
+        resp = requests.get(f"{BASE_URL}/clips", params={
+            "url": url,
+            "seconds": 5, # Short clip for speed
+            "num": 1
+        }, timeout=60)
+        
+        if resp.status_code != 200:
+            print(f"Failed to get clips: {resp.text}")
+            return
+            
+        data = resp.json()
+        clips = data.get('clips', [])
+        if not clips:
+            print("No clips found in response")
+            return
+            
+        clip = clips[0]
+        download_link = clip.get('download_link')
+        if not download_link:
+            print("No download_link in clip data")
+            print(clip)
+            return
+            
+        print(f"Found download link: {download_link}")
+        
+        # 2. Download File
+        full_download_url = f"{BASE_URL}{download_link}"
+        print(f"Downloading from {full_download_url}...")
+        
+        t0 = time.time()
+        file_resp = requests.get(full_download_url, stream=True, timeout=120)
+        
+        if file_resp.status_code == 200:
+            filename = "test_clip_downloaded.mp4"
+            with open(filename, 'wb') as f:
+                for chunk in file_resp.iter_content(chunk_size=8192):
+                    f.write(chunk)
+            
+            size = os.path.getsize(filename)
+            print(f"Downloaded file: {filename} ({size/1024:.2f} KB)")
+            print(f"Time: {time.time() - t0:.2f}s")
+        else:
+            print(f"Failed to download file: {file_resp.status_code}")
+            print(file_resp.text)
+            
+    except Exception as e:
+        print(f"Error: {e}")
+
+if __name__ == "__main__":
+    test_e2e_download()

test_nvidia_mode.py

@@ -0,0 +1,69 @@
+
+import requests
+import os
+import json
+import sys
+
+# REPLACE THIS WITH YOUR NVIDIA KEY or set NVIDIA_API_KEY env var
+# Get from: https://build.nvidia.com/explore/discover
+DEFAULT_KEY = "YOUR_NVIDIA_API_KEY_HERE" 
+API_KEY = os.environ.get("NVIDIA_API_KEY", DEFAULT_KEY)
+
+URL = "https://youtu.be/uVkFrqugXFQ"
+BASE_URL = "http://127.0.0.1:5000"
+
+def test_nvidia():
+    print("Testing Nvidia/DeepSeek Mode...")
+    
+    # Check if key is set (simple length check or placeholder check)
+    if "YOUR_NVIDIA" in API_KEY:
+        print("\nWARNING: You haven't set your Nvidia API Key!")
+        print("1. Get a key here: https://build.nvidia.com/explore/discover")
+        print("2. Open this script and replace 'YOUR_NVIDIA_API_KEY_HERE'")
+        print("   OR set env var: $env:NVIDIA_API_KEY='your_key'")
+        return
+
+    if API_KEY.startswith("AIza"):
+        print("\nERROR: You are using a Google Gemini Key (starts with AIza...)!")
+        print("       Nvidia keys usually start with 'nvapi-'.")
+        print("       Please use 'mode=ai' for Gemini, or get an Nvidia key.")
+        return
+
+    print(f"Analyzing {URL} using DeepSeek V3 (via Nvidia)...")
+    print("This may take 15-30 seconds...")
+    
+    try:
+        # Test the GET /clips endpoint with mode=nvidia
+        resp = requests.get(f"{BASE_URL}/clips", params={
+            "url": URL,
+            "mode": "nvidia",
+            "nvidia_key": API_KEY,
+            "num": 3,
+            "seconds": 30
+        }, timeout=120)
+        
+        if resp.status_code == 200:
+            data = resp.json()
+            print("\nSUCCESS! AI Candidates Found (DeepSeek):")
+            clips = data.get('clips', [])
+            
+            if not clips:
+                print("   (No clips found. AI might have filtered everything or returned empty)")
+                
+            for i, clip in enumerate(clips):
+                print(f"\nClip {i+1}: {clip.get('title')}")
+                print(f"   Score: {clip.get('viral_score')}")
+                print(f"   Download: {clip.get('download_link')}")
+                print(f"   Reason: {clip.get('reason')}")
+        else:
+            print(f"\nError: {resp.status_code}")
+            try:
+                print(json.dumps(resp.json(), indent=2))
+            except:
+                print(resp.text)
+            
+    except Exception as e:
+        print(f"\nException: {e}")
+
+if __name__ == "__main__":
+    test_nvidia()

vercel.json

@@ -0,0 +1,28 @@
+{
+  "version": 2,
+  "name": "viral-clip-extractor-api",
+  "builds": [
+    {
+      "src": "api/index.py",
+      "use": "@vercel/python",
+      "config": {
+        "maxLambdaSize": "50mb",
+        "runtime": "python3.9"
+      }
+    }
+  ],
+  "routes": [
+    {
+      "src": "/(.*)",
+      "dest": "api/index.py"
+    }
+  ],
+  "env": {
+    "PYTHONUNBUFFERED": "1"
+  },
+  "functions": {
+    "api/index.py": {
+      "maxDuration": 60
+    }
+  }
+}