squash commit

.env.example

@@ -1 +0,0 @@
-GOOGLE_API_KEY=*****

.github/workflows/check-file-size.yml

@@ -0,0 +1,23 @@
+name: Check file size
+on:
+  pull_request:
+    branches: [main]
+
+  # Allow manual trigger from Actions tab
+  workflow_dispatch:
+
+permissions: write-all
+
+jobs:
+  check-file-size:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Check large files
+        uses: ppremk/lfs-warning@v3.3
+        with:
+          filesizelimit: 10485760 # 10MB limit for HF Spaces sync

.github/workflows/lint.yml

@@ -0,0 +1,43 @@
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+  # Allow manual trigger from Actions tab
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          version: latest
+          virtualenvs-create: false
+          virtualenvs-in-project: false
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-3.12-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+
+      - name: Run black check
+        run: poetry run black --check src/ tests/

.github/workflows/sync-to-hf.yml

@@ -0,0 +1,24 @@
+name: Sync to Hugging Face Space
+on:
+  push:
+    branches: [main]
+
+  # Allow manual trigger from Actions tab
+  workflow_dispatch:
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+          git push https://MCP-1st-Birthday:$HF_TOKEN@huggingface.co/spaces/MCP-1st-Birthday/vidzly main --force

.gitignore

@@ -1,3 +1,7 @@
 __pycache__/
 
-.env
+.env
+
+.vscode/
+
+tests/data/

ADDING_MCP_TOOLS.md

@@ -1,204 +0,0 @@
-# Adding a New MCP Tool
-
-This guide will walk you through creating and integrating a new MCP (Model Context Protocol) tool into the Vidzly application.
-
-## Overview
-
-MCP tools in this project are Python functions that can be exposed through Gradio's MCP server. Each tool is a standalone function that performs a specific task and can be used by AI agents or directly through the Gradio interface.
-
-## Step-by-Step Guide
-
-### Step 1: Create the Tool Function
-
-Create a new Python file in the `src/app/tools/` directory. Name it descriptively (e.g., `word_reverser.py`, `text_analyzer.py`).
-
-**Example: Creating `word_reverser.py`**
-
-```python
-def word_reverser(text):
-    """
-    Reverse the order of words in a given text.
-
-    Args:
-        text (str): The input text to reverse
-
-    Returns:
-        str: The text with words in reverse order
-    """
-    words = text.split()
-    reversed_words = ' '.join(reversed(words))
-    return reversed_words
-```
-
-**Key Requirements:**
-
-- The function should have a clear, descriptive name
-- Include a docstring explaining what the function does
-- Document all parameters in the docstring
-- Document the return value
-- Keep the function focused on a single task
-
-### Step 2: Import the Tool in `app.py`
-
-Open `src/app/app.py` and add an import statement at the top:
-
-```python
-from tools.word_reverser import word_reverser
-```
-
-### Step 3: Create a Gradio Interface
-
-In `app.py`, within the `with gr.Tab("MCP Tools"):` block, add a new tab for your tool:
-
-```python
-with gr.Tab("Demo Word Reverser"):
-    gr.Interface(
-        fn=word_reverser,
-        inputs=[gr.Textbox("Hello world from Vidzly")],
-        outputs=[gr.Textbox()],
-        title="Word Reverser",
-        description="Enter text to reverse the order of words.",
-        api_name="word_reverser",
-    )
-```
-
-**Gradio Interface Parameters:**
-
-- `fn`: Your tool function
-- `inputs`: List of Gradio input components (e.g., `gr.Textbox()`, `gr.Number()`, `gr.Slider()`)
-- `outputs`: List of Gradio output components
-- `title`: Display title for the interface
-- `description`: Helpful description for users
-- `api_name`: Unique API endpoint name (used for MCP server)
-
-### Step 4: Test Your Tool
-
-1. Run the application:
-
-   ```bash
-   poetry run python src/app/app.py
-   ```
-
-2. Navigate to the "MCP Tools" tab in the web interface
-3. Click on your new tool's tab
-4. Test the tool with various inputs
-5. Verify the MCP server exposes your tool correctly
-
-## Complete Example
-
-Here's a complete example showing how the existing `letter_counter` tool is implemented:
-
-**File: `src/app/tools/letter_counter.py`**
-
-```python
-def letter_counter(word, letter):
-    """
-    Count the number of occurrences of a letter in a word or text.
-
-    Args:
-        word (str): The input text to search through
-        letter (str): The letter to search for
-
-    Returns:
-        str: A message indicating how many times the letter appears
-    """
-    word = word.lower()
-    letter = letter.lower()
-    count = word.count(letter)
-    return count
-```
-
-**Integration in `app.py`:**
-
-```python
-from tools.letter_counter import letter_counter
-
-# ... inside the MCP Tools tab ...
-with gr.Tab("Demo Letter Counter"):
-    gr.Interface(
-        fn=letter_counter,
-        inputs=[gr.Textbox("strawberry"), gr.Textbox("r")],
-        outputs=[gr.Textbox()],
-        title="Letter Counter",
-        description="Enter text and a letter to count how many times the letter appears in the text.",
-        api_name="predict",
-    )
-```
-
-## Best Practices
-
-1. **Function Design:**
-
-   - Keep functions pure when possible (no side effects)
-   - Handle edge cases and invalid inputs gracefully
-   - Return meaningful error messages if needed
-
-2. **Documentation:**
-
-   - Write clear docstrings with parameter descriptions
-   - Include examples in docstrings if helpful
-   - Use type hints if possible (optional but recommended)
-
-3. **Naming:**
-
-   - Use descriptive function names (e.g., `word_reverser` not `rev`)
-   - Use descriptive file names matching the function name
-   - Use clear `api_name` values for MCP endpoints
-
-4. **Testing:**
-
-   - Test with various inputs including edge cases
-   - Verify the tool works both in the Gradio UI and via MCP
-   - Check that error handling works correctly
-
-5. **Gradio Components:**
-   - Choose appropriate input/output components:
-     - `gr.Textbox()` for text input/output
-     - `gr.Number()` for numeric values
-     - `gr.Slider()` for numeric ranges
-     - `gr.Checkbox()` for boolean values
-     - `gr.Dropdown()` for selections
-   - Provide default values in inputs for better UX
-
-## Advanced: Multiple Parameters
-
-If your tool requires multiple parameters, simply add them to your function signature and corresponding Gradio inputs:
-
-```python
-def text_processor(text, operation, case_sensitive):
-    """
-    Process text with various operations.
-
-    Args:
-        text (str): The input text
-        operation (str): Operation to perform ('upper', 'lower', 'reverse')
-        case_sensitive (bool): Whether operations should be case sensitive
-
-    Returns:
-        str: Processed text
-    """
-    # Implementation here
-    pass
-```
-
-```python
-gr.Interface(
-    fn=text_processor,
-    inputs=[
-        gr.Textbox("Hello World"),
-        gr.Dropdown(["upper", "lower", "reverse"]),
-        gr.Checkbox(False)
-    ],
-    outputs=[gr.Textbox()],
-    title="Text Processor",
-    description="Process text with various operations.",
-    api_name="text_processor",
-)
-```
-
-## Troubleshooting
-
-- **Import errors:** Make sure your function is in the `src/app/tools/` directory and the import path matches
-- **MCP not exposing tool:** Verify `api_name` is unique and the function is properly defined
-- **Type errors:** Ensure your function's return type matches the Gradio output component type
-- **UI not showing:** Check that the tab is properly nested within `with gr.Tab("MCP Tools"):`

IMPLEMENTATION_PLAN.md

@@ -1,388 +0,0 @@
-# Complete Vidzly Workflow Implementation Plan
-
-## System Architecture Overview
-
-The Vidzly system will process user-uploaded videos and descriptions to create polished 30-second short videos through the following workflow:
-
-1. **Input**: Multiple video files + user description
-2. **Analysis**: Understand video content and user requirements
-3. **Script Generation**: Create detailed script/storyboard for the final video
-4. **Selection**: Choose relevant scenes and music based on script
-5. **Processing**: Clip, edit, and combine videos according to script
-6. **Output**: Final 30-second video
-
-## Required MCP Tools
-
-### Phase 1: Video Analysis Tools
-
-#### 1.1 Video Summarizer (`video_summarizer.py`)
-
-- **Purpose**: Analyze video content and generate text summaries
-- **Input**: Video file path
-- **Output**: JSON with video summary, key scenes, detected objects/activities, mood tags
-- **Technology**: OpenCV for frame extraction, Google Gemini Vision API for analysis
-- **Returns**: Structured summary including duration, scene descriptions, visual elements
-
-#### 1.2 Video Metadata Extractor (`video_metadata.py`)
-
-- **Purpose**: Extract technical metadata from videos
-- **Input**: Video file path
-- **Output**: Duration, resolution, fps, codec, file size
-- **Technology**: MoviePy or ffmpeg-python
-- **Returns**: Technical specifications for processing decisions
-
-### Phase 2: Content Understanding Tools
-
-#### 2.1 Description Parser (`description_parser.py`)
-
-- **Purpose**: Parse and understand user descriptions to extract requirements
-- **Input**: User description text
-- **Output**: Structured requirements (mood, style, key elements, target length)
-- **Technology**: Google Gemini API for natural language understanding
-- **Returns**: JSON with extracted mood, style preferences, key topics, pacing
-
-#### 2.2 Scene Matcher (`scene_matcher.py`)
-
-- **Purpose**: Match video scenes to user requirements
-- **Input**: Video summaries + parsed requirements
-- **Output**: List of matching scenes with timestamps and relevance scores
-- **Technology**: Semantic similarity matching using embeddings
-- **Returns**: Ranked list of scene segments to use
-
-### Phase 3: Script Generation & Planning
-
-#### 3.1 Video Script Generator (`video_script_generator.py`)
-
-- **Purpose**: Create a detailed script/storyboard for the final 30-second video
-- **Input**: Video summaries, matched scenes, parsed user requirements
-- **Output**: Detailed script with scene sequence, timings, transitions, and structure
-- **Technology**: Google Gemini API for intelligent script generation
-- **Returns**: JSON script containing:
-  - Scene sequence with source video and timestamps
-  - Duration for each scene segment (must sum to ~30 seconds)
-  - Transition types between scenes (cut, fade, crossfade, etc.)
-  - Pacing and rhythm plan
-  - Music synchronization points (beat markers, mood changes)
-  - Overall narrative structure and flow
-  - Visual style recommendations
-
-### Phase 4: Video Processing Tools
-
-#### 4.1 Video Clipper (`video_clipper.py`)
-
-- **Purpose**: Extract specific segments from videos based on script
-- **Input**: Video path, start time, end time
-- **Output**: Clipped video file path
-- **Technology**: MoviePy or ffmpeg-python
-- **Returns**: Path to clipped video segment
-
-#### 4.2 Scene Selector (`scene_selector.py`)
-
-- **Purpose**: Intelligently select best scenes to fit 30-second target (if script needs refinement)
-- **Input**: List of matched scenes, target duration (30s), script requirements
-- **Output**: Optimized scene selection with timestamps
-- **Technology**: Algorithm to maximize relevance while fitting duration
-- **Returns**: Final scene list with precise timestamps aligned to script
-
-### Phase 5: Audio & Composition Tools
-
-#### 5.1 Music Selector (`music_selector.py`)
-
-- **Purpose**: Select appropriate background music based on mood/style from script
-- **Input**: Mood/style tags, target duration, script rhythm requirements
-- **Output**: Music file path or URL
-- **Technology**: Music library/database or API (e.g., Free Music Archive, YouTube Audio Library)
-- **Returns**: Music file path with BPM and mood information
-
-#### 5.2 Video Composer (`video_composer.py`)
-
-- **Purpose**: Combine video clips, add music, apply transitions according to script
-- **Input**: List of video clip paths, music path, script with transitions
-- **Output**: Final composed video file path
-- **Technology**: MoviePy for video composition, transitions, audio mixing
-- **Returns**: Path to final 30-second video
-
-### Phase 6: Workflow Orchestration
-
-#### 6.1 Video Workflow Orchestrator (`video_workflow.py`)
-
-- **Purpose**: Main workflow that coordinates all tools
-- **Input**: List of video files, user description
-- **Output**: Final video file path, processing summary, generated script
-- **Technology**: Orchestrates all MCP tools in sequence
-- **Returns**: Final video, processing report, and script JSON
-
-## Implementation Phases
-
-### Phase 1: Foundation (Dependencies & Basic Tools)
-
-1. Add video processing dependencies (opencv-python, moviepy, ffmpeg-python, numpy, pillow)
-2. Implement Video Metadata Extractor
-3. Implement Video Summarizer
-4. Set up temporary file storage system
-
-### Phase 2: Understanding Layer
-
-1. Implement Description Parser
-2. Implement Scene Matcher
-3. Test analysis and matching pipeline
-
-### Phase 3: Script Generation
-
-1. Implement Video Script Generator
-2. Test script generation with various inputs
-3. Validate script timing (must sum to ~30 seconds)
-
-### Phase 4: Processing Layer
-
-1. Implement Video Clipper
-2. Implement Scene Selector
-3. Test video clipping and selection based on scripts
-
-### Phase 5: Composition Layer
-
-1. Implement Music Selector (start with simple mood-based selection)
-2. Implement Video Composer
-3. Test full composition pipeline with script
-
-### Phase 6: Integration & UI
-
-1. Implement Video Workflow Orchestrator
-2. Create main Vidzly UI in app.py (upload, description, progress, script preview, output)
-3. Integrate all MCP tools into Gradio interface
-4. Add error handling and user feedback
-
-### Phase 7: Polish & Optimization
-
-1. Add progress tracking
-2. Optimize processing speed
-3. Add preview functionality
-4. Improve error messages and edge case handling
-5. Add script editing/refinement capability
-
-## File Structure
-
-```
-src/app/
-├── app.py                    # Main Gradio app with Vidzly workflow UI
-├── introduction.py           # Existing intro component
-├── tools/
-│   ├── __init__.py
-│   ├── video_metadata.py     # Extract video technical info
-│   ├── video_summarizer.py   # Analyze and summarize video content
-│   ├── description_parser.py # Parse user descriptions
-│   ├── scene_matcher.py      # Match scenes to requirements
-│   ├── video_script_generator.py # Generate detailed video script
-│   ├── video_clipper.py      # Extract video segments
-│   ├── scene_selector.py     # Select optimal scenes for 30s video
-│   ├── music_selector.py     # Choose background music
-│   ├── video_composer.py     # Combine clips and add music
-│   └── video_workflow.py     # Main workflow orchestrator
-└── utils/
-    ├── __init__.py
-    ├── file_manager.py       # Handle temporary file storage
-    └── video_utils.py        # Shared video processing utilities
-```
-
-## File Storage Strategy
-
-### Storage Locations
-
-1. **Uploaded Videos (Gradio Temporary Directory)**
-
-   - Gradio automatically stores uploaded files in system temp directory
-   - Can be customized with `GRADIO_TEMP_DIR` environment variable
-   - Files accessible via file paths returned by `gr.File` component
-   - These are temporary and may be cleaned up by Gradio
-
-2. **Processing Working Directory**
-
-   - Create: `src/app/temp/` or use system temp with unique session IDs
-   - Store: Clipped video segments, intermediate processing files
-   - Structure: `temp/{session_id}/clips/`, `temp/{session_id}/final/`
-   - Cleanup: Delete after processing completes or on session timeout
-
-3. **Final Output Storage**
-   - Store final videos in: `src/app/outputs/` or `temp/{session_id}/final/`
-   - Return file path to Gradio `gr.Video` component for display/download
-   - Gradio will serve the file from this path
-   - Implement cleanup policy (e.g., delete after 24 hours)
-
-### File Manager Implementation
-
-The `file_manager.py` utility should:
-
-- Create session-based temporary directories
-- Generate unique file names to avoid conflicts
-- Provide cleanup functions (session cleanup, old file cleanup)
-- Handle path resolution (absolute paths for Gradio serving)
-- Track file lifecycle (uploaded, processing, final, deleted)
-
-### Gradio File Handling
-
-- **Input**: Use `gr.File(file_count="multiple")` for video uploads
-  - Returns list of file paths (temporary Gradio paths)
-  - Copy to working directory immediately for processing
-- **Output**: Use `gr.Video()` component
-  - Accepts file path (absolute or relative to working directory)
-  - Gradio serves the file and provides download capability
-  - File must exist at the path when component renders
-
-### Best Practices
-
-1. **Immediate Copy**: Copy uploaded files from Gradio temp to working directory
-2. **Absolute Paths**: Use absolute paths for all file operations
-3. **Session Management**: Use unique session IDs to isolate user workflows
-4. **Cleanup Strategy**:
-   - Clean up intermediate files after final video is created
-   - Keep final videos for a retention period (e.g., 1 hour)
-   - Implement background cleanup task for old files
-5. **Error Handling**: Ensure cleanup happens even if processing fails
-
-## Technical Stack
-
-### Dependencies to Add
-
-- `opencv-python` - Video frame extraction and basic processing
-- `moviepy` - Video editing, clipping, composition
-- `ffmpeg-python` - Alternative/additional video processing
-- `numpy` - Array operations for video processing
-- `pillow` - Image processing for frame analysis
-
-### Existing Dependencies
-
-- `gradio` (with MCP) - UI and MCP server
-- `google-genai` - AI analysis and understanding
-
-## Main Workflow UI Design
-
-The "Vidzly" tab in app.py will include:
-
-1. **Video Upload Section**: Multiple file upload component
-2. **Description Input**: Text area for user description
-3. **Process Button**: Trigger workflow
-4. **Progress Display**: Show current step (analyzing, generating script, selecting scenes, composing, etc.)
-5. **Script Preview**: Display generated script (optional, collapsible)
-6. **Output Video**: Display final 30-second video
-7. **Download Button**: Allow user to download result
-
-## Workflow Sequence
-
-1. User uploads multiple videos
-2. User provides description
-3. System analyzes all videos (parallel processing)
-4. System parses user description
-5. System matches scenes to requirements
-6. **System generates detailed script for 30-second video**
-7. System clips selected scenes based on script
-8. System selects appropriate music based on script
-9. System composes final video according to script
-10. System returns final video and script
-
-## Script Format Example
-
-```json
-{
-  "total_duration": 30.0,
-  "scenes": [
-    {
-      "scene_id": 1,
-      "source_video": "video1.mp4",
-      "start_time": 5.2,
-      "end_time": 8.5,
-      "duration": 3.3,
-      "description": "Opening shot of landscape",
-      "transition_in": "fade",
-      "transition_out": "crossfade"
-    },
-    {
-      "scene_id": 2,
-      "source_video": "video2.mp4",
-      "start_time": 12.0,
-      "end_time": 18.5,
-      "duration": 6.5,
-      "description": "Action sequence",
-      "transition_in": "crossfade",
-      "transition_out": "cut"
-    }
-  ],
-  "music": {
-    "mood": "energetic",
-    "bpm": 120,
-    "sync_points": [0.0, 7.5, 15.0, 22.5, 30.0]
-  },
-  "pacing": "fast",
-  "narrative_structure": "hook -> build -> climax -> resolution"
-}
-```
-
-## Error Handling Strategy
-
-- Validate video file formats on upload
-- Handle corrupted or unsupported videos gracefully
-- Provide clear error messages for each failure point
-- Allow partial success (e.g., if one video fails, continue with others)
-- Timeout handling for long processing operations
-- Validate script timing (must sum to ~30 seconds)
-- Handle script generation failures with fallback
-
-## Performance Considerations
-
-- Process videos in parallel where possible
-- Use efficient frame sampling (not every frame)
-- Cache video summaries to avoid re-analysis
-- Optimize video composition for speed
-- Consider async processing for long operations
-- Generate script before heavy processing to validate feasibility
-
-## Testing Strategy
-
-- Unit tests for each MCP tool
-- Integration tests for workflow steps
-- Test script generation with various inputs
-- End-to-end test with sample videos
-- Test with various video formats and sizes
-- Test edge cases (very short videos, very long videos, etc.)
-- Test script validation (timing, scene availability)
-
-## Implementation Todos
-
-1. **Phase 1: Foundation**
-
-   - Add video processing dependencies to pyproject.toml
-   - Implement video_metadata.py
-   - Implement video_summarizer.py
-   - Create utils/file_manager.py
-
-2. **Phase 2: Understanding**
-
-   - Implement description_parser.py
-   - Implement scene_matcher.py
-
-3. **Phase 3: Script Generation**
-
-   - Implement video_script_generator.py
-   - Add script validation logic
-
-4. **Phase 4: Processing**
-
-   - Implement video_clipper.py
-   - Implement scene_selector.py
-
-5. **Phase 5: Composition**
-
-   - Implement music_selector.py
-   - Implement video_composer.py
-
-6. **Phase 6: Integration**
-
-   - Implement video_workflow.py
-   - Create main Vidzly UI in app.py
-   - Integrate all MCP tools
-   - Add error handling
-
-7. **Phase 7: Polish**
-   - Add progress tracking
-   - Optimize performance
-   - Add preview functionality
-   - Improve UX

README.md

@@ -1,18 +1,22 @@
+<p align="center">
+  <img src="https://cdn.tihado.com/app.png" alt="Vidzly Logo"/>
+</p>
+
 # 🎬 Vidzly - Your AI-Powered Short Video Creator
 
 > **Transform raw footage into viral-ready content in seconds. No skills required. No expensive gear needed. Just your vision and our AI.**
 
 ## ✨ What is Vidzly?
 
-Vidzly is an intelligent automation platform that revolutionizes short-form video creation. Whether you're a micro-influencer, content creator, or business owner, Vidzly transforms your raw clips into polished, engaging 30-second videos that stop the scroll.
+Vidzly is an intelligent automation platform that revolutionizes short-form video creation. Whether you're a micro-influencer, content creator, or business owner, Vidzly transforms your raw clips into polished, engaging videos that stop the scroll.
 
 ### 🚀 Why Vidzly?
 
-- **Zero Learning Curve**: No video editing skills? No problem. Just upload and describe your vibe.
-- **AI-Powered Magic**: Advanced AI handles cutting, transitions, music sync, and visual effects automatically.
+- **Zero Learning Curve**: No video editing skills? No problem. Use our intuitive web interface.
+- **AI-Powered Magic**: Advanced AI handles video analysis, cutting, transitions, music generation, and thumbnail creation automatically.
 - **Lightning Fast**: What takes hours in traditional editing software takes minutes with Vidzly.
 - **Professional Quality**: Get studio-quality results without the studio price tag.
-- **Your Style, Your Way**: Customize the mood, pace, and aesthetic to match your brand.
+- **MCP Tools Integration**: All tools are available as MCP (Model Context Protocol) tools for AI agent integration.
 
 ### 🎯 Perfect For
 
@@ -24,24 +28,35 @@ Vidzly is an intelligent automation platform that revolutionizes short-form vide
 
 ## 🎬 How It Works
 
-1. **Upload Your Raw Footage** - Drop your clips, no matter how rough
-2. **Describe Your Vision** - Tell us your vibe, mood, or style preferences
-3. **AI Works Its Magic** - Our intelligent system edits, enhances, and polishes
-4. **Download & Share** - Get your scroll-stopping 30-second masterpiece
+1. **Upload Your Raw Footage** - Drop your clips through the Gradio web interface
+2. **Describe Your Vision** - Optionally provide a description of the mood, style, or vibe you want
+3. **AI Agents Work Their Magic** - Our two-agent system intelligently plans and executes:
+   - **Script Writer/Director Agent**: Analyzes videos, creates composition scripts, and generates music
+   - **Video Editor Agent**: Executes video composition, extracts frames, and generates thumbnails
+4. **Get Your Masterpiece** - Receive a polished video with thumbnail overlay on the first frame
 
-## 🛠️ Features
+## 🛠️ Available Tools
 
-- 🎞️ **Smart Auto-Editing**: Intelligent scene detection and cutting
-- 🎵 **Music Synchronization**: Perfect beat-matching and audio enhancement
-- 🎨 **Style Transfer**: Apply filters and effects that match your brand
-- ⚡ **Real-Time Preview**: See your video come together as it's being created
-- 📊 **Analytics Ready**: Optimized for maximum engagement
+Vidzly provides a comprehensive suite of MCP tools accessible through a Gradio web interface:
 
-## 📅 Release Date
+- 🎥 **Video Summarizer**: Uses Google Gemini AI to analyze video content and generate detailed summaries including key scenes, detected objects, mood tags, and recommended thumbnail timestamps
+- ✂️ **Video Clipper**: Extract specific segments from videos by specifying start and end times
+- 🖼️ **Frame Extractor**: Extract representative frames from videos, with AI-powered selection or manual timestamp specification
+- 🎨 **Thumbnail Generator**: Automatically generate engaging thumbnails with AI-generated text and stickers based on video frames and summaries
+- 🎬 **Video Composer**: Combine multiple video clips with transitions (fade, crossfade, cut) and optional background music according to a JSON script. Supports optional thumbnail image overlay on the first frame
+- 🎵 **Music Selector**: Generate background music and sound effects using ElevenLabs API based on mood, style, duration, BPM, and other parameters
 
-**Coming Soon: November 30, 2025**
+## 🏗️ Architecture
 
-Join us on this journey to democratize video creation and empower creators everywhere!
+- **Web Interface**: Built with Gradio (with MCP server support)
+- **AI Agents**: Google ADK (Agent Development Kit) with two specialized agents:
+  - **Script Writer/Director Agent**: Plans video composition using video analysis and script generation
+  - **Video Editor Agent**: Executes video composition, frame extraction, and thumbnail generation
+- **AI Integration**: Google Gemini for video understanding, analysis, and script generation
+- **Audio Generation**: ElevenLabs API for music and sound effect generation
+- **Video Processing**: MoviePy for video editing and composition
+- **Image Processing**: OpenCV and Pillow for frame extraction and thumbnail generation
+- **Testing**: Comprehensive pytest test suite with unit and integration tests
 
 ## Setup
 
@@ -115,27 +130,105 @@ To update all dependencies to their latest compatible versions:
 poetry update
 ```
 
+### Code Formatting with Black and Lefthook
+
+This project uses [Black](https://black.readthedocs.io/) for code formatting and [Lefthook](https://github.com/evilmartians/lefthook) for git hooks to automatically format code before commits.
+
+After installing dependencies, set up lefthook:
+
+```bash
+poetry run lefthook install
+```
+
+This will install git hooks that will:
+
+- **Before commit**: Automatically format staged Python files with Black
+- **Before push**: Check that all Python files in `src/` and `tests/` are properly formatted
+
+To manually format code:
+
+```bash
+poetry run black src/ tests/
+```
+
+To check formatting without making changes:
+
+```bash
+poetry run black --check src/ tests/
+```
+
 ### Setting Up Environment Variables
 
 Create a `.env` file in the root directory and add your environment variables.
 
 ```bash
 GOOGLE_API_KEY=your_google_api_key
+ELEVENLABS_API_KEY=your_elevenlabs_api_key
 ```
 
+**Note**: The application requires Google ADK (Agent Development Kit) to be installed. The `google-adk` package is required for the two-agent workflow architecture.
+
 ### Running the Application
 
+Start the Gradio web interface:
+
 ```bash
 poetry run python src/app/app.py
 ```
 
-## Adding a New MCP Tool
+This will launch a web interface with:
+
+- **Vidzly Tab**: Project introduction and overview
+- **MCP Tools Tab**: Access to all 6 video processing tools
+
+The application runs with MCP server support, allowing AI agents to interact with the tools programmatically.
+
+## Testing
+
+This project includes comprehensive unit and integration tests. See [tests/README.md](tests/README.md) for detailed testing documentation.
+
+### Running Tests
+
+Run all tests:
+
+```bash
+poetry run pytest
+```
+
+Run with coverage:
+
+```bash
+poetry run pytest --cov=src/app/tools --cov-report=html
+```
+
+Run specific test file:
+
+```bash
+poetry run pytest tests/test_video_summarizer.py
+```
+
+### Test Structure
+
+- **Unit Tests**: Mocked tests for input validation, error handling, and logic
+- **Integration Tests**: Real video file tests for actual functionality
+- All tools have corresponding test files in the `tests/` directory
+
+## Technology Stack
 
-For detailed instructions on how to add a new MCP tool to the application, see [ADDING_MCP_TOOLS.md](ADDING_MCP_TOOLS.md).
+- **Python 3.12+**: Core language
+- **Gradio 6.0+**: Web interface with MCP support
+- **Google ADK (Agent Development Kit)**: Two-agent architecture for intelligent workflow orchestration
+- **Google Gemini API**: Video understanding, analysis, script generation, and thumbnail creation
+- **ElevenLabs API**: Music and sound effect generation
+- **MoviePy 2.2.1**: Video editing, composition, and image overlay
+- **OpenCV 4.12+**: Video processing and frame extraction
+- **Pillow 11**: Image processing for thumbnails
+- **Poetry**: Dependency management
+- **pytest**: Testing framework
 
 ### Contributors
 
-- 🐱 [honghanhh](https://github.com/honghanhh)🐱
-- 🦊 [nvti](https://github.com/nvti)🦊
-- 🐻 [Nlag](https://github.com/NLag)🐻
-- 🐰 [DaphneeCh](https://github.com/DaphneeCh)🐰
+- 🐱 [honghanhh](https://github.com/honghanhh) 🐱
+- 🦊 [nvti](https://github.com/nvti) 🦊
+- 🐻 [Nlag](https://github.com/NLag) 🐻
+- 🐰 [DaphneeCh](https://github.com/DaphneeCh) 🐰

lefthook.yml

@@ -0,0 +1,14 @@
+pre-commit:
+  parallel: true
+  commands:
+    black:
+      run: poetry run black {staged_files}
+      glob: "*.py"
+      stage_fixed: true
+
+pre-push:
+  parallel: true
+  commands:
+    black-check:
+      run: poetry run black --check src/ tests/
+      glob: "*.py"

pyproject.toml

@@ -14,8 +14,62 @@ opencv-python = "^4.12.0.88"
 moviepy = "^2.2.1"
 pillow = "11"
 python-dotenv = "^1.0.0"
+elevenlabs = "^2.24.0"
+gtts = "^2.5.0"
+langchain-google-genai = "^3.2.0"
+langchain-core = "^1.1.0"
+langchain = "^1.1.0"
 
 
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.0.1"
+black = "^24.0.0"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.1,<10.0.0)",
+    "pytest-mock (>=3.15.1,<4.0.0)",
+    "pytest-cov (>=7.0.0,<8.0.0)",
+    "black (>=24.0.0,<25.0.0)",
+    "lefthook (>=2.0.4,<3.0.0)"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--strict-markers",
+    "--tb=short",
+]
+markers = [
+    "unit: Unit tests",
+    "integration: Integration tests",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py312']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # directories
+  \.eggs
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.tox
+  | \.venv
+  | venv
+  | _build
+  | buck-out
+  | build
+  | dist
+)/
+'''

src/app/app.py

@@ -7,15 +7,61 @@ load_dotenv()
 import gradio as gr
 from introduction import introduction
 from tools.video_summarizer import video_summarizer
+from tools.video_clipper import video_clipper
+from tools.frame_extractor import frame_extractor
+from tools.thumbnail_generator import thumbnail_generator
+from tools.video_composer import video_composer
+from tools.music_selector import music_selector
+from tools.video_script_generator import video_script_generator
+from workflow_ui import workflow_ui
+from tools.text_to_speech import text_to_speech_simple
+from tools.script_generator import script_generator
+from tools.subtitle_creator import subtitle_creator
+
+
+def text_to_speech_wrapper(
+    text, voice, language, speed, format_type, generate_segments
+):
+    """
+    Wrapper to return audio file for Gradio.
+    """
+    result = text_to_speech_simple(
+        text, voice, language, speed, format_type, generate_segments
+    )
+    # Always return audio file path (Gradio will render audio player)
+    return result
+
+
+def video_composer_wrapper(script, video_clips, music_path=None):
+    """
+    Wrapper to return both video and script JSON for easy workflow.
+    """
+    video_path = video_composer(video_clips, music_path)
+    # Return video path and the original script (for subtitle generator)
+    return video_path
+
+
+def frame_extractor_wrapper(video_input, thumbnail_timeframe=None):
+    """
+    Wrapper function for frame_extractor to handle Gradio interface inputs.
+    Maps the Gradio inputs to the correct function parameters.
+    """
+    return frame_extractor(
+        video_input=video_input,
+        output_path=None,
+        thumbnail_timeframe=thumbnail_timeframe,
+    )
 
 
 with gr.Blocks() as demo:
     with gr.Tab("Vidzly"):
-        # Tell about this project
-        # Agent full workflow here
-
+        # Introduction section
         introduction()
 
+        # Full workflow UI
+        gr.Markdown("---")
+        workflow_ui()
+
     with gr.Tab("MCP Tools"):
         with gr.Tab("Video Summarizer"):
             gr.Interface(
@@ -36,6 +82,284 @@ with gr.Blocks() as demo:
                 api_name="video_summarizer",
             )
 
+        with gr.Tab("Video Clipper"):
+            gr.Interface(
+                fn=video_clipper,
+                inputs=[
+                    gr.Video(label="Upload Video"),
+                    gr.Number(
+                        value=0.0,
+                        label="Start Time (seconds)",
+                        minimum=0.0,
+                        step=0.1,
+                    ),
+                    gr.Number(
+                        value=10.0,
+                        label="End Time (seconds)",
+                        minimum=0.1,
+                        step=0.1,
+                    ),
+                ],
+                outputs=[gr.Video(label="Clipped Video")],
+                title="Video Clipper",
+                description="Extract a specific segment from a video file. Enter the start and end times in seconds to create a clipped version of your video.",
+                api_name="video_clipper",
+            )
+
+        with gr.Tab("Frame Extractor"):
+            gr.Interface(
+                fn=frame_extractor_wrapper,
+                inputs=[
+                    gr.Video(label="Upload Video"),
+                    gr.Number(
+                        value=None,
+                        label="Thumbnail Timeframe (Optional - seconds)",
+                        minimum=0.0,
+                        step=0.1,
+                        info="Optional: Provide a timestamp in seconds to extract a frame at that specific time. If not provided, AI will analyze the video to find the best frame. You can get this value from the 'thumbnail_timeframe' field in Video Summarizer's JSON output.",
+                    ),
+                ],
+                outputs=[gr.Image(label="Extracted Frame", type="filepath")],
+                title="Frame Extractor",
+                description="Extract a representative frame from a video. If you provide a thumbnail timeframe (e.g., from Video Summarizer), it will use that timestamp directly without calling AI. Otherwise, it uses Gemini AI to analyze the video and select the most engaging frame.",
+                api_name="frame_extractor",
+            )
+
+        with gr.Tab("Thumbnail Generation"):
+            gr.Interface(
+                fn=thumbnail_generator,
+                inputs=[
+                    gr.Image(
+                        label="Frame Image",
+                        type="filepath",
+                    ),
+                    gr.Textbox(
+                        label="Video Summary",
+                        placeholder="Enter the video summary text here...",
+                        lines=10,
+                        info="Enter the video summary text (extract the 'summary' field from Video Summarizer JSON output).",
+                    ),
+                ],
+                outputs=[gr.Image(label="Generated Thumbnail", type="filepath")],
+                title="Thumbnail Generation",
+                description="Automatically generate engaging thumbnails with AI-generated text and stickers. Uses Gemini AI to analyze the frame and video summary to create context-aware thumbnail designs with optimal text placement and sticker recommendations.",
+                api_name="thumbnail_generation",
+            )
+
+        with gr.Tab("Video Composer"):
+            gr.Interface(
+                fn=video_composer_wrapper,
+                inputs=[
+                    gr.Textbox(
+                        label="Script (JSON)",
+                        placeholder='{"total_duration": 30.0, "scenes": [{"scene_id": 1, "source_video": 0, "start_time": 0.0, "end_time": 5.0, "duration": 5.0, "transition_in": "fade", "transition_out": "crossfade"}]}',
+                        lines=10,
+                    ),
+                    gr.File(
+                        label="Video Clips (Required - source videos)",
+                        file_count="multiple",
+                        file_types=["video"],
+                    ),
+                    gr.File(
+                        label="Music File (Optional)",
+                        file_count="single",
+                        file_types=["audio"],
+                    ),
+                    gr.Image(
+                        label="Thumbnail Image (Optional)",
+                        type="filepath",
+                    ),
+                ],
+                outputs=[
+                    gr.Video(label="Composed Video"),
+                    gr.Textbox(
+                        label="Script JSON (Copy this to Subtitle Generator)", lines=10
+                    ),
+                ],
+                title="Video Composer",
+                description="Combine video clips, add music, and apply transitions according to a script. Upload source videos, then provide a JSON script where each scene's 'source_video' references a video by index (0-based) or filename. The same video can be used in multiple scenes with different time ranges. The script JSON output can be copied directly to Subtitle Generator.",
+                api_name="video_composer",
+            )
+
+        with gr.Tab("Music Selector"):
+            gr.Interface(
+                fn=music_selector,
+                inputs=[
+                    gr.Textbox(
+                        label="Mood",
+                        placeholder="energetic, calm, dramatic, fun",
+                        value="energetic",
+                        info="Enter mood tags (comma-separated) or a single mood",
+                    ),
+                    gr.Textbox(
+                        label="Style (Optional)",
+                        placeholder="cinematic, modern, retro",
+                        value="",
+                    ),
+                    gr.Number(
+                        value=5.0,
+                        label="Target Duration (seconds)",
+                        minimum=1.0,
+                        maximum=30.0,
+                        step=0.5,
+                        info="Maximum 30 seconds for ElevenLabs",
+                    ),
+                    gr.Number(
+                        value=60,
+                        label="BPM (Optional)",
+                        minimum=60,
+                        maximum=200,
+                        step=1,
+                        info="Beats per minute for rhythm matching (optional)",
+                    ),
+                    gr.Checkbox(
+                        value=True,
+                        label="Looping",
+                        info="Enable seamless looping for continuous playback",
+                    ),
+                    gr.Slider(
+                        value=0.3,
+                        label="Prompt Influence",
+                        minimum=0,
+                        maximum=1,
+                        step=0.01,
+                        info="How closely the output matches the prompt (0-1)",
+                    ),
+                ],
+                outputs=[gr.Audio(label="Generated Sound Effect (MP3)")],
+                title="Music Selector",
+                description="Generate background sound effects using ElevenLabs API based on mood, style, and duration. The generated audio can be used as background music or sound effects for videos. Requires ELEVENLABS_API_KEY in your .env file.",
+                api_name="music_selector",
+            )
+
+        with gr.Tab("Video Script Generator"):
+            gr.Interface(
+                fn=video_script_generator,
+                inputs=[
+                    gr.Textbox(
+                        label="Video Summaries (JSON)",
+                        placeholder='[{"duration": 30.0, "summary": "...", "mood_tags": ["energetic"]}] or paste JSON string from Video Summarizer',
+                        lines=15,
+                        info="Enter video summaries as JSON. Can be a single JSON string, or a JSON array of summary objects. You can copy the JSON output from Video Summarizer tool.",
+                    ),
+                    gr.Textbox(
+                        label="User Description (Optional)",
+                        placeholder="e.g., Create an energetic and fast-paced video with dynamic transitions...",
+                        lines=3,
+                        info="Optional description of desired mood, style, or content for the final video",
+                    ),
+                    gr.Number(
+                        value=30.0,
+                        label="Target Duration (seconds)",
+                        minimum=1.0,
+                        maximum=300.0,
+                        step=0.5,
+                        info="Target duration for the final video in seconds",
+                    ),
+                ],
+                outputs=[gr.Textbox(label="Generated Script (JSON)", lines=20)],
+                title="Video Script Generator",
+                description="Create a detailed script/storyboard for a video composition. Uses Google Gemini AI to intelligently generate a script based on video summaries and user requirements. The script includes scene sequences, timings, transitions, music configuration, pacing, and narrative structure. Requires GOOGLE_API_KEY in your .env file.",
+                api_name="video_script_generator",
+            )
+
+        with gr.Tab("Text-to-Speech"):
+            gr.Interface(
+                fn=text_to_speech_wrapper,
+                inputs=[
+                    gr.Textbox(
+                        label="Text or Subtitle Content",
+                        placeholder='Enter text or paste subtitle content (SRT/VTT/JSON)...\n\nPlain text example:\n"Welcome to our video tutorial on AI."\n\nSRT example:\n1\n00:00:00,000 --> 00:00:03,500\nWelcome to our video.\n\n2\n00:00:03,500 --> 00:00:07,000\nToday we will learn.',
+                        lines=8,
+                        info="Enter plain text OR paste subtitle content. Format will be auto-detected. All subtitle dialogues will be combined into narration.",
+                    ),
+                    gr.Radio(
+                        choices=["neutral", "male", "female"],
+                        value="neutral",
+                        label="Voice Type",
+                        info="Select voice accent: Male (British), Female (Australian), or Neutral (US)",
+                    ),
+                    gr.Dropdown(
+                        choices=[
+                            ("English", "en"),
+                            ("Spanish", "es"),
+                            ("French", "fr"),
+                            ("German", "de"),
+                            ("Italian", "it"),
+                            ("Portuguese", "pt"),
+                            ("Chinese", "zh"),
+                            ("Japanese", "ja"),
+                            ("Korean", "ko"),
+                            ("Arabic", "ar"),
+                        ],
+                        value="en",
+                        label="Language",
+                        info="Select the language for text-to-speech conversion",
+                    ),
+                    gr.Radio(
+                        choices=["normal", "slow"],
+                        value="normal",
+                        label="Speed",
+                        info="Speech speed: Normal or Slow (for learning/clarity)",
+                    ),
+                    gr.Radio(
+                        choices=["auto", "text", "srt", "vtt", "json"],
+                        value="auto",
+                        label="Input Format",
+                        info="Auto-detect format or manually specify: Plain text, SRT subtitle, VTT subtitle, or JSON scenario",
+                    ),
+                    gr.Checkbox(
+                        value=False,
+                        label="Generate Timed Segments",
+                        info="Create separate audio files for each subtitle segment with timing info (for video synchronization). Only works with subtitle input formats.",
+                    ),
+                ],
+                outputs=[gr.Audio(label="Generated Audio", type="filepath")],
+                title="Text-to-Speech Converter",
+                description="Convert text or subtitles to audio using Google Text-to-Speech. Supports plain text, SRT, VTT, and JSON formats. Enable 'Generate Timed Segments' to create individual audio files for each subtitle with timing metadata (perfect for video synchronization with Video Composer output).",
+                api_name="text_to_speech",
+            )
+
+        with gr.Tab("Script Generator"):
+            gr.Interface(
+                fn=script_generator,
+                inputs=[
+                    gr.File(
+                        label="Video Materials (Required - upload multiple videos)",
+                        file_count="multiple",
+                        file_types=["video"],
+                    ),
+                    gr.Textbox(
+                        label="User Prompt (Optional)",
+                        placeholder="e.g., 'Create an energetic travel montage with upbeat pacing' or 'Make a dramatic product reveal video'",
+                        lines=3,
+                        info="Optional: Provide specific instructions or creative direction. If left empty, the AI will generate a script based on the video content analysis.",
+                    ),
+                ],
+                outputs=[gr.Textbox(label="Video Production Script (JSON)", lines=25)],
+                title="Script Generator",
+                description="Generate comprehensive video production scripts from multiple video materials. Upload your source videos and optionally provide creative direction. The AI will analyze the content and create a detailed script including scene breakdowns, timing, transitions, audio recommendations, and visual effects. Outputs both structured JSON and narrative formats.",
+                api_name="script_generator",
+            )
+
+        with gr.Tab("Subtitle Creator"):
+            gr.Interface(
+                fn=subtitle_creator,
+                inputs=[
+                    gr.Video(label="Upload Video"),
+                    gr.Textbox(
+                        label="Transcript (JSON)",
+                        placeholder='{"subtitles": [{"start": 0.0, "end": 2.5, "text": "Hello!", "position": "bottom", "fontsize": 48, "color": "white"}], "default_style": {"fontsize": 48, "color": "white", "bg_color": "#00000042", "position": "bottom", "transparent": true}}',
+                        lines=15,
+                        info="Provide subtitle transcript in JSON format with timestamps, text, and optional styling (position, font, fontsize, color, bg_color, stroke_color, stroke_width).",
+                    ),
+                ],
+                outputs=[gr.Video(label="Video with Subtitles")],
+                title="Subtitle Creator",
+                description="Add customizable subtitles to your videos. Upload a video and provide a JSON transcript with timestamps, text content, and styling options. Supports multiple subtitle segments with individual positioning (top/center/bottom), fonts, colors, and background styling.",
+                api_name="subtitle_creator",
+            )
+
 
 if __name__ == "__main__":
     demo.launch(mcp_server=True)

src/app/tools/frame_extractor.py

@@ -0,0 +1,152 @@
+import cv2
+import os
+import re
+from pathlib import Path
+from typing import Optional
+import mimetypes
+import google.genai as genai
+
+
+def frame_extractor(
+    video_input,
+    output_path: Optional[str] = None,
+    thumbnail_timeframe: Optional[float] = None,
+) -> str:
+    """
+    Extract a representative frame from video.
+
+    If thumbnail_timeframe is provided, uses that timestamp directly. Otherwise,
+    uses Gemini AI to analyze the video and determine the best timestamp for
+    frame extraction.
+
+    Args:
+        video_input: Video file path (str) or tuple (video_path, subtitle_path) from Gradio
+        output_path: Optional output path for frame image
+        thumbnail_timeframe: Optional timestamp in seconds to use for frame extraction.
+                           If provided, skips AI analysis and uses this timestamp directly.
+
+    Returns:
+        str: Path to extracted frame image (PNG format)
+    """
+    try:
+        # Handle Gradio video input format (can be tuple or string)
+        if isinstance(video_input, tuple):
+            video_path = video_input[0]
+        elif isinstance(video_input, str):
+            video_path = video_input
+        else:
+            raise ValueError("Invalid video input format")
+
+        # Validate video file exists
+        if not video_path or not os.path.exists(video_path):
+            raise ValueError(f"Video file not found: {video_path}")
+
+        # Get video metadata
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            raise ValueError(f"Could not open video file: {video_path}")
+
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        duration = total_frames / fps if fps > 0 else 0
+
+        if duration == 0:
+            cap.release()
+            raise ValueError("Video has zero duration")
+
+        cap.release()
+
+        # Use provided thumbnail_timeframe if available, otherwise use Gemini API
+        if thumbnail_timeframe is not None:
+            # Use the provided timestamp directly
+            best_timestamp = float(thumbnail_timeframe)
+            # Ensure timestamp is within video duration
+            best_timestamp = max(0.0, min(best_timestamp, duration - 0.1))
+        else:
+            api_key = os.getenv("GOOGLE_API_KEY")
+            if not api_key:
+                raise ValueError(
+                    "GOOGLE_API_KEY environment variable is required for AI frame extraction when thumbnail_timeframe is not provided"
+                )
+
+            # Use Gemini Vision API to analyze video and get best timestamp
+            client = genai.Client(api_key=api_key)
+
+            # Read video file as bytes
+            with open(video_path, "rb") as f:
+                video_data = f.read()
+
+            # Determine MIME type
+            mime_type, _ = mimetypes.guess_type(video_path)
+            if not mime_type or not mime_type.startswith("video/"):
+                # Default to mp4 if cannot determine
+                mime_type = "video/mp4"
+
+            # Create prompt asking for best timestamp
+            prompt = f"""Analyze this video and identify the best timestamp (in seconds) to extract a representative, engaging frame for a thumbnail.
+
+Consider these factors:
+- Visual appeal and composition quality
+- Subject clarity and focus
+- Color and lighting quality
+- Overall engagement and representativeness of the video content
+- Avoid frames with motion blur or poor quality
+
+The video duration is approximately {duration:.2f} seconds.
+
+Respond with ONLY the timestamp in seconds as a number (e.g., "12.5" or "8.3"). Do not include any other text or explanation."""
+
+            # Create VideoMetadata with fps parameter for efficient processing
+            # Using 2.0 fps for good balance between speed and accuracy
+            video_metadata = genai.types.VideoMetadata(fps=2.0)
+            video_blob = genai.types.Blob(data=video_data, mime_type=mime_type)
+            video_part = genai.types.Part(
+                inline_data=video_blob,
+                videoMetadata=video_metadata,
+            )
+
+            # Use Gemini's native video understanding to analyze the entire video
+            response = client.models.generate_content(
+                model="gemini-2.5-flash-lite",
+                contents=[prompt, video_part],
+            )
+
+            # Extract timestamp from response
+            response_text = response.text.strip()
+
+            # Try to extract numeric timestamp from response
+            # Look for patterns like "12.5", "8.3", "15", etc.
+            timestamp_match = re.search(r"(\d+\.?\d*)", response_text)
+            if timestamp_match:
+                best_timestamp = float(timestamp_match.group(1))
+                # Ensure timestamp is within video duration
+                best_timestamp = max(0.0, min(best_timestamp, duration - 0.1))
+            else:
+                # Fallback: use middle of video if we can't parse the response
+                best_timestamp = duration / 2
+
+        # Extract frame at the selected timestamp
+        cap = cv2.VideoCapture(video_path)
+        frame_number = int(best_timestamp * fps)
+        cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
+        ret, best_frame = cap.read()
+        cap.release()
+
+        if not ret:
+            raise ValueError(f"Could not extract frame at timestamp {best_timestamp}s")
+
+        # Generate output path if not provided
+        if output_path is None:
+            video_name = Path(video_path).stem
+            output_dir = Path(video_path).parent / "frames"
+            output_dir.mkdir(parents=True, exist_ok=True)
+            output_path = str(
+                output_dir / f"{video_name}_frame_ai_{int(best_timestamp)}s.png"
+            )
+
+        # Save selected frame
+        cv2.imwrite(output_path, best_frame)
+        return output_path
+
+    except Exception as e:
+        raise Exception(f"Error extracting frame: {str(e)}")

src/app/tools/langchain_tools.py

@@ -0,0 +1,196 @@
+"""
+LangChain tool wrappers for video processing tools.
+
+This module wraps existing video processing tools as LangChain tools
+so they can be used by the LangChain ReAct agent.
+"""
+
+import json
+from typing import Optional, List, Union
+from langchain_core.tools import tool
+
+from .video_summarizer import video_summarizer
+from .video_script_generator import video_script_generator
+from .music_selector import music_selector
+from .frame_extractor import frame_extractor
+from .thumbnail_generator import thumbnail_generator
+from .video_composer import video_composer
+
+
+@tool
+def video_summarizer_tool(video_path: str, fps: float = 2.0) -> str:
+    """
+    Analyze video content and generate a comprehensive summary.
+
+    This tool analyzes a video file and returns a JSON summary containing:
+    - Overall video description
+    - Key scenes and moments with timestamps
+    - Detected objects, people, and activities
+    - Mood and style tags (e.g., energetic, calm, dramatic, fun)
+    - Visual style description
+    - Recommended thumbnail timestamp (in seconds)
+
+    Args:
+        video_path: Path to the video file to analyze
+        fps: Frames per second for video processing (default: 2.0, range: 0.1-24.0)
+
+    Returns:
+        JSON string containing video summary with all analysis details
+    """
+    return video_summarizer(video_path, fps=fps)
+
+
+@tool
+def video_script_generator_tool(
+    video_summaries: str,
+    user_description: Optional[str] = None,
+    target_duration: float = 30.0,
+) -> str:
+    """
+    Generate a detailed video composition script from video summaries.
+
+    This tool creates a comprehensive script/storyboard for video composition that includes:
+    - Scene sequence with source video references and timestamps
+    - Duration for each scene segment (sums to approximately target_duration)
+    - Transition types between scenes (cut, fade, crossfade)
+    - Pacing and rhythm plan
+    - Music synchronization points
+    - Overall narrative structure and flow
+    - Visual style recommendations
+
+    Args:
+        video_summaries: JSON string containing video summaries (can be single summary or array)
+        user_description: Optional description of desired mood, style, or content
+        target_duration: Target duration in seconds for the final video (default: 30.0)
+
+    Returns:
+        JSON string containing detailed script with scene information and composition details
+    """
+    return video_script_generator(video_summaries, user_description, target_duration)
+
+
+@tool
+def music_selector_tool(
+    mood: str,
+    style: Optional[str] = None,
+    target_duration: float = 30.0,
+    bpm: Optional[int] = None,
+    looping: bool = True,
+    prompt_influence: float = 0.3,
+) -> str:
+    """
+    Generate background music or sound effects matching the video's mood and style.
+
+    This tool uses ElevenLabs API to generate appropriate background music that matches
+    the video content. The music is generated based on mood tags, style preferences,
+    and duration requirements.
+
+    Args:
+        mood: Mood tags describing the desired mood (e.g., "energetic", "calm, dramatic")
+        style: Optional style description (e.g., "cinematic", "modern", "retro")
+        target_duration: Target duration in seconds (default: 30.0, max: 30.0)
+        bpm: Optional beats per minute for rhythm matching
+        looping: Whether the sound effect should be loopable (default: True)
+        prompt_influence: How closely output matches prompt (0-1, default: 0.3)
+
+    Returns:
+        Path to the generated audio file (MP3 format)
+    """
+    return music_selector(
+        mood=mood,
+        style=style,
+        target_duration=target_duration,
+        bpm=bpm,
+        looping=looping,
+        prompt_influence=prompt_influence,
+    )
+
+
+@tool
+def frame_extractor_tool(
+    video_path: str, thumbnail_timeframe: Optional[float] = None
+) -> str:
+    """
+    Extract a representative frame from a video for thumbnail creation.
+
+    This tool extracts a frame from a video at a specific timestamp. If no timestamp
+    is provided, it uses AI to analyze the video and select the best frame.
+
+    Args:
+        video_path: Path to the video file
+        thumbnail_timeframe: Optional timestamp in seconds to extract frame.
+                           If not provided, AI will select the best frame.
+
+    Returns:
+        Path to the extracted frame image (PNG format)
+    """
+    return frame_extractor(video_path, thumbnail_timeframe=thumbnail_timeframe)
+
+
+@tool
+def thumbnail_generator_tool(image_path: str, summary: str) -> str:
+    """
+    Generate an engaging thumbnail image with text overlays and stickers.
+
+    This tool creates a professional thumbnail image using the provided frame image
+    as a background. It adds catchy text, stickers, and visual elements based on the
+    video summary to create an attention-grabbing thumbnail.
+
+    Args:
+        image_path: Path to the frame image to use as background
+        summary: Text summary of the video content (used to generate appropriate text and stickers)
+
+    Returns:
+        Path to the generated thumbnail image (PNG format)
+    """
+    return thumbnail_generator(image_path, summary)
+
+
+@tool
+def video_composer_tool(
+    script: str,
+    video_clips: str,
+    music_path: Optional[str] = None,
+    thumbnail_image: Optional[str] = None,
+) -> str:
+    """
+    Compose a final video from multiple clips according to a script.
+
+    This tool combines video clips, adds music, applies transitions, and optionally
+    overlays a thumbnail image on the first frame. It follows the script exactly to
+    create the final composed video.
+
+    Args:
+        script: JSON string containing scene information with transitions and timing
+        video_clips: JSON string array of video file paths, or comma-separated paths
+        music_path: Optional path to background music file
+        thumbnail_image: Optional path to thumbnail image to overlay on first frame
+
+    Returns:
+        Path to the final composed video file
+    """
+    # Handle video_clips - can be JSON array string or comma-separated paths
+    if video_clips.strip().startswith("["):
+        # JSON array
+        clips_list = json.loads(video_clips)
+    else:
+        # Comma-separated paths
+        clips_list = [path.strip() for path in video_clips.split(",") if path.strip()]
+
+    return video_composer(
+        script=script,
+        video_clips=clips_list,
+        music_path=music_path,
+        thumbnail_image=thumbnail_image,
+    )
+
+
+# List of all tools for easy import
+ALL_TOOLS = [
+    video_summarizer_tool,
+    video_script_generator_tool,
+    music_selector_tool,
+    frame_extractor_tool,
+    thumbnail_generator_tool,
+    video_composer_tool,
+]

src/app/tools/music_selector.py

@@ -0,0 +1,187 @@
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Optional, List, Union
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+try:
+    from elevenlabs import ElevenLabs
+except ImportError:
+    ElevenLabs = None
+
+
+def music_selector(
+    mood: Union[str, List[str]] = "energetic",
+    style: Optional[str] = None,
+    target_duration: float = 30.0,
+    bpm: Optional[int] = None,
+    looping: bool = True,
+    prompt_influence: float = 0.3,
+    output_path: Optional[str] = None,
+) -> str:
+    """
+    Generate appropriate background sound effects based on mood/style from script.
+    Uses ElevenLabs API to generate sound effects that match the video's mood and style.
+
+    Args:
+        mood: Mood tags (str or list of str) describing the desired mood.
+              Can be comma-separated string or list (e.g., "energetic", "calm, dramatic, fun")
+        style: Optional style description (e.g., "cinematic", "modern", "retro")
+        target_duration: Target duration in seconds (default: 30.0, max: 30.0 for ElevenLabs)
+        bpm: Optional beats per minute for rhythm matching (used in prompt generation)
+        sync_points: Optional list of sync points in seconds for beat alignment (used in prompt)
+        looping: Whether the sound effect should be loopable (default: True).
+                Maps to ElevenLabs API parameter "loop"
+        prompt_influence: How closely the output should match the prompt (0-1, default: 0.3).
+                         Higher values = more literal interpretation, lower = more creative
+        output_path: Optional path where the audio file should be saved.
+                    If not provided, saves to a temporary file.
+
+    Returns:
+        str: Path to the generated audio file (MP3 format)
+
+    Raises:
+        ImportError: If elevenlabs package is not installed
+        ValueError: If ELEVENLABS_API_KEY is not set in environment
+        Exception: If sound effect generation fails
+    """
+    try:
+        # Check if ElevenLabs is available
+        if ElevenLabs is None:
+            raise ImportError(
+                "elevenlabs package is not installed. Install it with: pip install elevenlabs"
+            )
+
+        # Get API key from environment
+        api_key = os.getenv("ELEVENLABS_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "ELEVENLABS_API_KEY environment variable is not set. "
+                "Please set it in your .env file or environment."
+            )
+
+        # Initialize ElevenLabs client
+        client = ElevenLabs(api_key=api_key)
+
+        # Process mood input (can be string or list)
+        if isinstance(mood, str):
+            # Handle comma-separated mood tags
+            mood_tags = [m.strip() for m in mood.split(",") if m.strip()]
+            if not mood_tags:
+                mood_tags = ["energetic"]  # Default
+        elif isinstance(mood, list):
+            mood_tags = [str(m).strip() for m in mood if str(m).strip()]
+            if not mood_tags:
+                mood_tags = ["energetic"]  # Default
+        else:
+            mood_tags = ["energetic"]  # Default
+
+        # Build prompt for sound effect generation
+        prompt_parts = []
+
+        # Add mood description
+        mood_description = ", ".join(mood_tags)
+        prompt_parts.append(f"{mood_description} background sound")
+
+        # Add style if provided
+        if style and str(style).strip():
+            prompt_parts.append(f"{str(style).strip()} style")
+
+        # Add rhythm information if provided
+        if bpm is not None and bpm > 0:
+            prompt_parts.append(f"{int(bpm)} BPM rhythm")
+
+        # Combine into final prompt
+        prompt = ", ".join(prompt_parts)
+
+        # Clamp duration to ElevenLabs limits (max 30 seconds)
+        if target_duration > 30.0:
+            target_duration = 30.0
+        elif target_duration <= 0:
+            target_duration = 5.0  # Minimum reasonable duration
+
+        # Clamp prompt_influence to valid range (0-1)
+        prompt_influence = max(0, min(1, prompt_influence))
+
+        # Generate sound effect using ElevenLabs API
+        # According to ElevenLabs API documentation:
+        # - Required: text
+        # - Optional: duration_seconds (0.5 to 30 seconds)
+        # - Optional: loop (boolean) - enables seamless looping
+        # - Optional: prompt_influence (float 0-1) - how closely output matches prompt
+        # - Optional: output_format (e.g., "mp3_44100_128")
+
+        # Build parameters for the API call
+        api_params = {
+            "text": prompt,
+        }
+
+        # Add duration_seconds parameter (must be between 0.5 and 30 seconds)
+        if target_duration and 0.5 <= target_duration <= 30.0:
+            api_params["duration_seconds"] = target_duration
+
+        # Add looping parameter (API uses "loop" not "looping")
+        if looping:
+            api_params["loop"] = looping
+
+        # Add prompt_influence parameter (0-1 range)
+        if prompt_influence is not None:
+            api_params["prompt_influence"] = prompt_influence
+
+        # Add output format for MP3
+        api_params["output_format"] = "mp3_44100_128"
+
+        # Call the API
+        audio_data = client.text_to_sound_effects.convert(**api_params)
+
+        # Determine output path
+        if output_path is None:
+            # Create a temporary file with appropriate extension
+            temp_dir = tempfile.gettempdir()
+            timestamp = int(time.time())
+            output_path = os.path.join(
+                temp_dir,
+                f"sound_effect_{mood_tags[0]}_{int(target_duration)}s_{timestamp}.mp3",
+            )
+
+        # Ensure output directory exists
+        output_dir = os.path.dirname(output_path)
+        if output_dir and not os.path.exists(output_dir):
+            os.makedirs(output_dir, exist_ok=True)
+
+        # Save audio data to file
+        # The audio_data should be bytes that can be written directly
+        if isinstance(audio_data, bytes):
+            with open(output_path, "wb") as f:
+                f.write(audio_data)
+        elif hasattr(audio_data, "__iter__"):
+            # If it's an iterable (generator, list, etc.), read all chunks
+            with open(output_path, "wb") as f:
+                for chunk in audio_data:
+                    if isinstance(chunk, bytes):
+                        f.write(chunk)
+                    else:
+                        # Try to convert to bytes
+                        try:
+                            f.write(bytes(chunk))
+                        except (TypeError, ValueError):
+                            # If conversion fails, try string encoding
+                            if isinstance(chunk, str):
+                                f.write(chunk.encode())
+        else:
+            # Try to write directly
+            with open(output_path, "wb") as f:
+                try:
+                    f.write(bytes(audio_data))
+                except (TypeError, ValueError):
+                    raise ValueError(f"Unexpected audio data type: {type(audio_data)}")
+
+        # Return absolute path
+        return os.path.abspath(output_path)
+
+    except Exception as e:
+        raise Exception(f"Error generating sound effect: {str(e)}")

src/app/tools/script_generator.py

@@ -0,0 +1,210 @@
+import cv2
+import json
+import os
+import mimetypes
+import google.genai as genai
+from typing import Optional
+
+
+def script_generator(video_inputs, user_prompt: Optional[str] = None) -> str:
+    """
+    Generate a detailed video script based on multiple video materials.
+    Uses Google Gemini's native video understanding to analyze material videos
+    and create a comprehensive script for making a short video.
+
+    Args:
+        video_inputs: List of video file paths or Gradio video inputs
+        user_prompt (str, optional): User's custom prompt/request. If not provided,
+                                    AI will generate a script based on material analysis.
+
+    Returns:
+        str: JSON string containing a detailed video script with scene breakdowns,
+             timing, transitions, and creative suggestions
+    """
+    try:
+        # Handle various input formats
+        if not video_inputs:
+            return json.dumps({"error": "No video files provided"})
+
+        # Normalize video inputs to list of paths
+        video_paths = []
+        if isinstance(video_inputs, list):
+            for video_input in video_inputs:
+                if isinstance(video_input, tuple):
+                    video_paths.append(video_input[0])
+                elif isinstance(video_input, str):
+                    video_paths.append(video_input)
+        elif isinstance(video_inputs, str):
+            video_paths = [video_inputs]
+        elif isinstance(video_inputs, tuple):
+            video_paths = [video_inputs[0]]
+        else:
+            return json.dumps({"error": "Invalid video input format"})
+
+        # Validate all video files exist and extract metadata
+        videos_metadata = []
+        for idx, video_path in enumerate(video_paths):
+            if not os.path.exists(video_path):
+                return json.dumps({"error": f"Video file not found: {video_path}"})
+
+            cap = cv2.VideoCapture(video_path)
+            if not cap.isOpened():
+                return json.dumps({"error": f"Could not open video file: {video_path}"})
+
+            video_fps = cap.get(cv2.CAP_PROP_FPS)
+            frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+            duration = frame_count / video_fps if video_fps > 0 else 0
+            width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+            height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+            cap.release()
+
+            videos_metadata.append(
+                {
+                    "index": idx,
+                    "filename": os.path.basename(video_path),
+                    "duration": round(duration, 2),
+                    "resolution": f"{width}x{height}",
+                    "fps": round(video_fps, 2),
+                    "frame_count": frame_count,
+                }
+            )
+
+        # Check for API key
+        api_key = os.getenv("GOOGLE_API_KEY")
+        if not api_key:
+            return json.dumps(
+                {
+                    "error": "GOOGLE_API_KEY environment variable not set",
+                    "videos_analyzed": videos_metadata,
+                    "script": "AI script generation requires GOOGLE_API_KEY",
+                }
+            )
+
+        # Initialize Gemini client
+        client = genai.Client(api_key=api_key)
+
+        # Prepare video parts for multimodal input
+        video_parts = []
+        for video_path in video_paths:
+            with open(video_path, "rb") as f:
+                video_data = f.read()
+
+            mime_type, _ = mimetypes.guess_type(video_path)
+            if not mime_type or not mime_type.startswith("video/"):
+                mime_type = "video/mp4"
+
+            video_metadata = genai.types.VideoMetadata(fps=2.0)
+            video_blob = genai.types.Blob(data=video_data, mime_type=mime_type)
+            video_part = genai.types.Part(
+                inline_data=video_blob,
+                videoMetadata=video_metadata,
+            )
+            video_parts.append(video_part)
+
+        # Create comprehensive prompt
+        if user_prompt and user_prompt.strip():
+            # Use user's prompt
+            base_prompt = f"""User Request: {user_prompt}
+
+Based on the user's request above and the provided video materials, create a detailed video production script."""
+        else:
+            # Generate default prompt
+            base_prompt = """Analyze the provided video materials and create a comprehensive video production script for making an engaging short video."""
+
+        full_prompt = f"""{base_prompt}
+
+I have {len(video_paths)} video file(s) as source material. Please analyze each video and create a detailed script that includes:
+
+1. **Concept Overview**: Describe the overall theme, message, and creative direction for the final video.
+
+2. **Target Duration**: Recommend optimal video length based on content (typically 15-60 seconds for short-form).
+
+3. **Scene Breakdown**: For each scene in the final video, specify:
+   - Scene number and description
+   - Which source video to use (reference by index: 0, 1, 2, etc.)
+   - Exact start and end timestamps from the source video
+   - Duration of the scene
+   - Visual description and key moments
+   - Suggested transitions (e.g., "fade", "crossfade", "wipe", "zoom")
+
+4. **Audio Recommendations**: 
+   - Background music mood and style
+   - BPM (beats per minute) suggestion
+   - Volume levels and audio effects
+   - Any voiceover or text-to-speech suggestions
+
+5. **Text Overlays**: Suggest any text, captions, or titles to add, including:
+   - Text content
+   - Timing (when to appear)
+   - Style suggestions (font, size, position, animation)
+
+6. **Visual Effects**: Recommend any filters, color grading, speed adjustments, or special effects.
+
+7. **Pacing & Flow**: Explain the rhythm and flow of the video, including any build-ups, climaxes, or emotional arcs.
+
+8. **Call-to-Action**: Suggest ending elements (e.g., logo, text, link, subscribe prompt).
+
+Please provide the script in a structured JSON format that includes:
+- "concept": overall theme and message
+- "target_duration": recommended total duration in seconds
+- "total_duration": sum of all scene durations
+- "scenes": array of scene objects with fields:
+  - "scene_id": integer
+  - "source_video": index of source video (0-based)
+  - "start_time": start timestamp in source video (seconds)
+  - "end_time": end timestamp in source video (seconds)
+  - "duration": scene duration (seconds)
+  - "description": what happens in this scene
+  - "transition_in": transition effect when entering scene
+  - "transition_out": transition effect when exiting scene
+- "audio": object with "mood", "style", "bpm", "volume"
+- "text_overlays": array of text overlay objects
+- "visual_effects": array of suggested effects
+- "call_to_action": string description
+
+Also provide a human-readable narrative version of the script."""
+
+        # Call Gemini API with all video materials
+        contents = [full_prompt] + video_parts
+        response = client.models.generate_content(
+            model="gemini-2.5-flash-lite",
+            contents=contents,  # type: ignore
+        )
+
+        # Parse response
+        script_text: str = response.text if response.text else ""
+
+        # Try to extract JSON if present
+        json_match = None
+        if "```json" in script_text:
+            # Extract JSON code block
+            import re
+
+            json_pattern = r"```json\s*([\s\S]*?)\s*```"
+            match = re.search(json_pattern, script_text)
+            if match:
+                json_match = match.group(1)
+
+        # Structure the response
+        result = {
+            "videos_analyzed": videos_metadata,
+            "user_prompt": (
+                user_prompt if user_prompt else "Auto-generated based on materials"
+            ),
+            "script_narrative": script_text,
+        }
+
+        # If we found structured JSON, try to parse and include it
+        if json_match:
+            try:
+                structured_script = json.loads(json_match)
+                result["structured_script"] = structured_script
+            except json.JSONDecodeError:
+                result["structured_script_parse_error"] = (
+                    "Could not parse JSON from response"
+                )
+
+        return json.dumps(result, indent=2)
+
+    except Exception as e:
+        return json.dumps({"error": f"Error generating script: {str(e)}"})

src/app/tools/subtitle_creator.py

@@ -0,0 +1,274 @@
+import os
+import json
+import tempfile
+from pathlib import Path
+from typing import List, Optional, Union, TypedDict, Tuple
+from moviepy import VideoFileClip, TextClip, CompositeVideoClip
+
+
+class SubtitleSegment(TypedDict, total=False):
+    """Subtitle segment definition with timing and styling."""
+
+    start: float  # Start time in seconds
+    end: float  # End time in seconds
+    text: str  # Subtitle text content
+    position: Optional[str]  # Position: 'bottom', 'top', 'center', or tuple (x, y)
+    font: Optional[str]  # Font name (default: 'Arial')
+    fontsize: Optional[int]  # Font size (default: 48)
+    color: Optional[str]  # Text color (default: 'white')
+    bg_color: Optional[str]  # Background color (default: 'black')
+    stroke_color: Optional[str]  # Stroke/outline color (optional)
+    stroke_width: Optional[int]  # Stroke width (optional)
+
+
+class RequiredSubtitleSegment(TypedDict):
+    """Required fields for a subtitle segment."""
+
+    start: float
+    end: float
+    text: str
+
+
+class TranscriptData(TypedDict, total=False):
+    """Complete transcript structure with subtitle segments."""
+
+    subtitles: List[SubtitleSegment]
+    default_style: Optional[dict]  # Default styling for all subtitles
+
+
+# Type alias for Gradio video input
+GradioVideoInput = Union[
+    str,  # Single file path
+    Tuple[str, str],  # Gradio video format: (video_path, subtitle_path)
+]
+
+
+def subtitle_creator(
+    video_input: GradioVideoInput,
+    transcript_json: str,
+    output_path: Optional[str] = None,
+) -> str:
+    """
+    Add subtitles to a video based on a JSON transcript with timestamps.
+    Creates text overlays at specified times with customizable styling.
+
+    Args:
+        video_input: Video file path (str) or tuple (video_path, subtitle_path) from Gradio
+        transcript_json (str): JSON string containing subtitle segments with timing and styling
+        output_path (str, optional): Path where the subtitled video should be saved.
+                                     If not provided, saves to a temporary file.
+
+    Returns:
+        str: Path to the subtitled video file
+
+    Example transcript JSON format:
+    {
+        "subtitles": [
+            {
+                "start": 0.0,
+                "end": 2.5,
+                "text": "Hello, welcome to the video!",
+                "position": "bottom",
+                "fontsize": 48,
+                "color": "white"
+            },
+            {
+                "start": 2.5,
+                "end": 5.0,
+                "text": "This is a subtitle example.",
+                "fontsize": 52,
+                "color": "yellow"
+            }
+        ],
+        "default_style": {
+            "fontsize": 48,
+            "color": "white",
+            "bg_color": "black",
+            "position": "bottom",
+            "transparent": True
+        }
+    }
+    """
+    try:
+        # Handle Gradio video input format
+        if isinstance(video_input, tuple):
+            video_path = video_input[0]
+        elif isinstance(video_input, str):
+            video_path = video_input
+        else:
+            raise ValueError("Invalid video input format. Expected string or tuple.")
+
+        # Validate video file exists
+        if not video_path or not os.path.exists(video_path):
+            raise FileNotFoundError(f"Video file not found: {video_path}")
+
+        # Parse transcript JSON
+        try:
+            transcript_data: TranscriptData = json.loads(transcript_json)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON format in transcript: {str(e)}")
+
+        # Validate transcript structure
+        if "subtitles" not in transcript_data or not transcript_data["subtitles"]:
+            raise ValueError(
+                "Transcript must contain 'subtitles' array with at least one subtitle"
+            )
+
+        subtitles = transcript_data["subtitles"]
+        default_style = transcript_data.get("default_style", {})
+
+        # Set default styling values
+        default_font = default_style.get("font", None) if default_style else None
+        default_fontsize = default_style.get("fontsize", 48) if default_style else 48
+        default_color = (
+            default_style.get("color", "white") if default_style else "white"
+        )
+        default_bg_color = (
+            default_style.get("bg_color", "black") if default_style else "black"
+        )
+        default_position = (
+            default_style.get("position", "bottom") if default_style else "bottom"
+        )
+        default_transparent = (
+            default_style.get("transparent", True) if default_style else True
+        )
+
+        # Load the video
+        video = VideoFileClip(video_path)
+        video_duration = video.duration
+        video_width, video_height = video.size
+
+        # Validate all subtitle timings
+        for idx, subtitle in enumerate(subtitles):
+            if (
+                "start" not in subtitle
+                or "end" not in subtitle
+                or "text" not in subtitle
+            ):
+                raise ValueError(
+                    f"Subtitle {idx} must have 'start', 'end', and 'text' fields"
+                )
+
+            start = subtitle["start"]
+            end = subtitle["end"]
+
+            if start < 0 or end < 0:
+                raise ValueError(f"Subtitle {idx}: start and end times must be >= 0")
+
+            if end <= start:
+                raise ValueError(
+                    f"Subtitle {idx}: end time must be greater than start time"
+                )
+
+            if start >= video_duration:
+                raise ValueError(
+                    f"Subtitle {idx}: start time {start}s exceeds video duration {video_duration}s"
+                )
+
+        # Create text clips for each subtitle
+        text_clips = []
+
+        for idx, subtitle in enumerate(subtitles):
+            # Access required fields with validation already done above
+            text = str(subtitle.get("text", ""))
+            start = float(subtitle.get("start", 0.0))
+            end = float(subtitle.get("end", 0.0))
+
+            # Get styling for this subtitle (use segment-specific or default)
+            font = subtitle.get("font", default_font)
+            fontsize = int(subtitle.get("fontsize", default_fontsize))  # type: ignore
+            color = str(subtitle.get("color", default_color))
+            bg_color = subtitle.get("bg_color", default_bg_color)
+            position = subtitle.get("position", default_position)
+            stroke_color = subtitle.get("stroke_color")
+            stroke_width = int(subtitle.get("stroke_width", 2))  # type: ignore
+            transparent = subtitle.get("transparent", default_transparent)
+
+            # Clamp end time to video duration
+            if end > video_duration:
+                end = video_duration
+
+            # Calculate position
+            if isinstance(position, str):
+                if position == "bottom":
+                    text_position = ("center", video_height - 100)
+                elif position == "top":
+                    text_position = ("center", 100)
+                elif position == "center":
+                    text_position = ("center", "center")
+                else:
+                    # Default to bottom if invalid
+                    text_position = ("center", video_height - 100)
+            elif isinstance(position, (list, tuple)) and len(position) == 2:
+                text_position = tuple(position)
+            else:
+                text_position = ("center", video_height - 100)
+
+            # Create text clip with styling
+            try:
+                text_clip = TextClip(
+                    text=text,
+                    font=font,
+                    font_size=fontsize,
+                    color=color,
+                    bg_color=bg_color,
+                    stroke_color=stroke_color if stroke_color else None,
+                    stroke_width=stroke_width if stroke_color and stroke_width else 0,
+                    size=(video_width - 100, None),  # Max width with padding
+                    method="caption",  # Wrap text
+                    transparent=transparent,
+                )
+
+                # Set timing and position
+                text_clip = text_clip.with_start(start).with_end(end)
+                text_clip = text_clip.with_position(text_position)
+
+                text_clips.append(text_clip)
+
+            except Exception as e:
+                raise ValueError(
+                    f"Error creating subtitle {idx} ('{text[:30]}...'): {str(e)}"
+                )
+
+        # Composite video with all text overlays
+        final_video = CompositeVideoClip([video] + text_clips)
+
+        # Determine output path
+        if output_path is None:
+            # Create temporary file
+            temp_dir = tempfile.gettempdir()
+            output_path = os.path.join(
+                temp_dir, f"subtitled_video_{os.urandom(8).hex()}.mp4"
+            )
+        else:
+            # Ensure output directory exists
+            output_dir = os.path.dirname(output_path)
+            if output_dir:
+                Path(output_dir).mkdir(parents=True, exist_ok=True)
+
+        # Write the final video with subtitles
+        final_video.write_videofile(
+            output_path,
+            codec="libx264",
+            audio_codec="aac",
+            temp_audiofile=os.path.join(
+                tempfile.gettempdir(), f"temp_audio_{os.urandom(8).hex()}.m4a"
+            ),
+            remove_temp=True,
+            fps=video.fps,
+        )
+
+        # Clean up
+        video.close()
+        final_video.close()
+        for clip in text_clips:
+            clip.close()
+
+        return output_path
+
+    except FileNotFoundError as e:
+        raise e
+    except ValueError as e:
+        raise e
+    except Exception as e:
+        raise RuntimeError(f"Error creating subtitled video: {str(e)}")

src/app/tools/text_to_speech.py

@@ -0,0 +1,531 @@
+"""
+Text-to-Speech Converter
+Converts text transcription to audio using Google's Text-to-Speech API.
+Supports plain text, SRT, VTT, and JSON subtitle formats.
+"""
+
+import os
+import re
+import json
+from pathlib import Path
+from typing import Literal, Optional
+
+
+def parse_srt(content: str) -> list[str]:
+    """Parse SRT subtitle content and extract dialogue text."""
+    dialogues = []
+    blocks = content.strip().split("\n\n")
+
+    for block in blocks:
+        lines = block.strip().split("\n")
+        if len(lines) < 3:
+            continue
+
+        # Get dialogue (lines after timestamp)
+        dialogue = " ".join(lines[2:])
+        # Remove speaker labels
+        dialogue = re.sub(r"\[.*?\]|\(.*?\)|^.*?:", "", dialogue).strip()
+        if dialogue:
+            dialogues.append(dialogue)
+
+    return dialogues
+
+
+def parse_srt_with_timing(content: str) -> list[dict]:
+    """Parse SRT subtitle content with timing information."""
+    segments = []
+    blocks = content.strip().split("\n\n")
+
+    for block in blocks:
+        lines = block.strip().split("\n")
+        if len(lines) < 3:
+            continue
+
+        # Parse timestamp line (format: 00:00:00,000 --> 00:00:05,000)
+        timestamp_line = lines[1]
+        if "-->" not in timestamp_line:
+            continue
+
+        times = timestamp_line.split("-->")
+        if len(times) != 2:
+            continue
+
+        start_time = _parse_timestamp_to_seconds(times[0].strip())
+        end_time = _parse_timestamp_to_seconds(times[1].strip())
+
+        # Get dialogue
+        dialogue = " ".join(lines[2:])
+        # Remove speaker labels
+        dialogue = re.sub(r"\[.*?\]|\(.*?\)|^.*?:", "", dialogue).strip()
+
+        if dialogue and start_time is not None and end_time is not None:
+            segments.append(
+                {"start_time": start_time, "end_time": end_time, "dialogue": dialogue}
+            )
+
+    return segments
+
+
+def parse_vtt(content: str) -> list[str]:
+    """Parse VTT subtitle content and extract dialogue text."""
+    dialogues = []
+    # Remove WEBVTT header
+    content = re.sub(r"^WEBVTT.*?\n\n", "", content, flags=re.MULTILINE)
+    blocks = content.strip().split("\n\n")
+
+    for block in blocks:
+        lines = block.strip().split("\n")
+        if len(lines) < 2:
+            continue
+
+        # Find timestamp line
+        timestamp_idx = -1
+        for i, line in enumerate(lines):
+            if "-->" in line:
+                timestamp_idx = i
+                break
+
+        if timestamp_idx == -1:
+            continue
+
+        # Get dialogue after timestamp
+        dialogue = " ".join(lines[timestamp_idx + 1 :])
+        # Remove speaker labels
+        dialogue = re.sub(r"\[.*?\]|\(.*?\)|^.*?:", "", dialogue).strip()
+        if dialogue:
+            dialogues.append(dialogue)
+
+    return dialogues
+
+
+def parse_vtt_with_timing(content: str) -> list[dict]:
+    """Parse VTT subtitle content with timing information."""
+    segments = []
+    # Remove WEBVTT header
+    content = re.sub(r"^WEBVTT.*?\n\n", "", content, flags=re.MULTILINE)
+    blocks = content.strip().split("\n\n")
+
+    for block in blocks:
+        lines = block.strip().split("\n")
+        if len(lines) < 2:
+            continue
+
+        # Find timestamp line
+        timestamp_idx = -1
+        for i, line in enumerate(lines):
+            if "-->" in line:
+                timestamp_idx = i
+                break
+
+        if timestamp_idx == -1:
+            continue
+
+        # Parse timestamp
+        timestamp_line = lines[timestamp_idx]
+        times = timestamp_line.split("-->")
+        if len(times) != 2:
+            continue
+
+        start_time = _parse_timestamp_to_seconds(times[0].strip())
+        end_time = _parse_timestamp_to_seconds(times[1].strip())
+
+        # Get dialogue
+        dialogue = " ".join(lines[timestamp_idx + 1 :])
+        # Remove speaker labels
+        dialogue = re.sub(r"\[.*?\]|\(.*?\)|^.*?:", "", dialogue).strip()
+
+        if dialogue and start_time is not None and end_time is not None:
+            segments.append(
+                {"start_time": start_time, "end_time": end_time, "dialogue": dialogue}
+            )
+
+    return segments
+
+
+def parse_json_scenario(content: str) -> list[str]:
+    """Parse JSON scenario format and extract dialogue text."""
+    try:
+        data = json.loads(content)
+        if isinstance(data, str):
+            data = json.loads(data)
+
+        dialogues = []
+        if "scenes" in data:
+            for scene in data["scenes"]:
+                if "dialogue" in scene and scene["dialogue"]:
+                    dialogues.append(scene["dialogue"])
+
+        return dialogues
+    except (json.JSONDecodeError, KeyError, TypeError):
+        raise ValueError("Invalid JSON scenario format")
+
+
+def parse_json_with_timing(content: str) -> list[dict]:
+    """Parse JSON scenario format with timing information."""
+    try:
+        data = json.loads(content)
+        if isinstance(data, str):
+            data = json.loads(data)
+
+        segments = []
+        if "scenes" in data:
+            for scene in data["scenes"]:
+                start_time = scene.get("start_time")
+                end_time = scene.get("end_time")
+                duration = scene.get("duration")
+                dialogue = scene.get("dialogue", "")
+
+                # Calculate end_time if not provided but duration is
+                if end_time is None and duration is not None and start_time is not None:
+                    end_time = start_time + duration
+
+                # Skip if no timing info
+                if start_time is None or end_time is None:
+                    continue
+
+                # Use placeholder if no dialogue
+                if not dialogue:
+                    dialogue = f"Scene {scene.get('scene_id', '?')}"
+
+                segments.append(
+                    {
+                        "start_time": float(start_time),
+                        "end_time": float(end_time),
+                        "dialogue": dialogue,
+                    }
+                )
+
+        return segments
+    except (json.JSONDecodeError, KeyError, TypeError, ValueError):
+        raise ValueError("Invalid JSON scenario format")
+
+
+def _parse_timestamp_to_seconds(timestamp: str) -> Optional[float]:
+    """
+    Convert timestamp string to seconds.
+    Supports formats: HH:MM:SS,mmm or HH:MM:SS.mmm
+    """
+    try:
+        # Replace comma with dot for milliseconds
+        timestamp = timestamp.replace(",", ".")
+
+        # Parse time components
+        parts = timestamp.split(":")
+        if len(parts) != 3:
+            return None
+
+        hours = int(parts[0])
+        minutes = int(parts[1])
+        seconds_parts = parts[2].split(".")
+        seconds = int(seconds_parts[0])
+        milliseconds = int(seconds_parts[1]) if len(seconds_parts) > 1 else 0
+
+        # Convert to total seconds
+        total_seconds = hours * 3600 + minutes * 60 + seconds + milliseconds / 1000.0
+        return total_seconds
+    except (ValueError, IndexError):
+        return None
+
+
+def detect_format(content: str) -> str:
+    """Auto-detect subtitle format from content."""
+    content_stripped = content.strip()
+
+    if content_stripped.startswith("WEBVTT"):
+        return "vtt"
+    elif content_stripped.startswith("{"):
+        return "json"
+    elif re.search(r"^\d+\s*\n\d{2}:\d{2}:\d{2},\d{3}\s*-->", content, re.MULTILINE):
+        return "srt"
+    else:
+        return "text"
+
+
+def text_to_speech(
+    text: str,
+    voice: Literal["male", "female", "neutral"] = "neutral",
+    speed: float = 1.0,
+    output_path: Optional[str] = None,
+) -> str:
+    """
+    Convert text to speech audio.
+
+    Args:
+        text: The text to convert to speech
+        voice: Voice type - "male", "female", or "neutral"
+        speed: Speech speed (0.5 to 2.0, where 1.0 is normal speed)
+        output_path: Optional custom output path for the audio file
+
+    Returns:
+        Path to the generated audio file
+
+    Raises:
+        ValueError: If text is empty or parameters are invalid
+        RuntimeError: If audio generation fails
+    """
+    # Validate inputs
+    if not text or not text.strip():
+        raise ValueError("Text cannot be empty")
+
+    if not (0.5 <= speed <= 2.0):
+        raise ValueError("Speed must be between 0.5 and 2.0")
+
+    if voice not in ["male", "female", "neutral"]:
+        raise ValueError("Voice must be 'male', 'female', or 'neutral'")
+
+    # Import genai only when needed for advanced features
+    try:
+        import google.generativeai as genai
+    except ImportError:
+        raise ImportError("Please install google-genai: pip install google-genai")
+
+    # Configure API
+    api_key = os.getenv("GEMINI_API_KEY")
+    if not api_key:
+        raise ValueError("GEMINI_API_KEY environment variable is not set")
+
+    genai.configure(api_key=api_key)
+
+    # Determine output path
+    if output_path is None:
+        output_dir = Path("outputs/audio")
+        output_dir.mkdir(parents=True, exist_ok=True)
+        output_path = str(output_dir / "generated_speech.mp3")
+    else:
+        # Ensure directory exists
+        output_dir = Path(output_path).parent
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Use Gemini to generate audio description/narration prompt
+        # Since Gemini doesn't have direct TTS, we'll use a workaround with available APIs
+        # For now, we'll create a simple implementation that can be extended
+
+        # Voice characteristics mapping
+        voice_prompts = {
+            "male": "deep, masculine, authoritative voice",
+            "female": "clear, feminine, warm voice",
+            "neutral": "balanced, professional, clear voice",
+        }
+
+        speed_description = ""
+        if speed < 0.8:
+            speed_description = "speaking slowly and clearly"
+        elif speed > 1.2:
+            speed_description = "speaking at a brisk pace"
+        else:
+            speed_description = "speaking at a normal pace"
+
+        # Generate enhanced text with voice instructions
+        model = genai.GenerativeModel("gemini-1.5-flash")
+
+        prompt = f"""
+        Prepare this text for text-to-speech conversion with a {voice_prompts[voice]}, {speed_description}:
+        
+        Text: {text}
+        
+        Provide the text in a format optimized for speech synthesis, with appropriate pauses marked by commas and periods.
+        Only return the optimized text, nothing else.
+        """
+
+        response = model.generate_content(prompt)
+        optimized_text = response.text.strip()
+
+        # Note: Since Google Gemini doesn't provide direct TTS API in the SDK,
+        # we'll save the optimized text and return a placeholder
+        # In production, you would integrate with Google Cloud Text-to-Speech API
+        # or another TTS service like ElevenLabs, Azure TTS, etc.
+
+        # For now, create a text file with instructions
+        text_output_path = output_path.replace(".mp3", ".txt")
+        with open(text_output_path, "w", encoding="utf-8") as f:
+            f.write(f"Voice: {voice}\n")
+            f.write(f"Speed: {speed}x\n")
+            f.write(f"Original Text:\n{text}\n\n")
+            f.write(f"Optimized for TTS:\n{optimized_text}\n")
+
+        # Return the path with a note
+        result_message = f"""
+Audio generation prepared successfully!
+
+Text file created at: {text_output_path}
+
+To generate actual audio, you need to:
+1. Install Google Cloud Text-to-Speech: pip install google-cloud-texttospeech
+2. Set up Google Cloud credentials
+3. Or use alternative TTS services like:
+   - ElevenLabs (https://elevenlabs.io/)
+   - Azure Speech Services
+   - Amazon Polly
+   - gTTS (free, but limited)
+
+The text has been optimized for {voice} voice at {speed}x speed.
+"""
+
+        return result_message
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to generate audio: {str(e)}")
+
+
+def text_to_speech_simple(
+    text: str,
+    voice: str = "neutral",
+    language: str = "en",
+    speed: str = "normal",
+    format_type: str = "text",
+    generate_segments: bool = False,
+) -> str:
+    """
+    Text-to-speech using gTTS (Google Text-to-Speech) - free tier.
+    Supports plain text, SRT, VTT, and JSON subtitle formats.
+    Can generate single audio file or timed segments matching subtitle timing.
+
+    Args:
+        text: The text/subtitle content to convert to speech
+        voice: Voice type - "male", "female", or "neutral" (affects language variant)
+        language: Language code (e.g., "en" for English, "es" for Spanish)
+        speed: Speech speed - "normal" or "slow"
+        format_type: Input format - "text", "srt", "vtt", "json", or "auto" to detect
+        generate_segments: If True and input is subtitles, generates individual audio files
+                          for each subtitle segment with timing info (for video sync)
+
+    Returns:
+        Path to the generated audio file(s).
+        - If generate_segments=False: Returns single combined audio file path
+        - If generate_segments=True: Returns JSON string with audio segments and timing info
+
+    Note:
+        gTTS doesn't directly support voice gender, but we can use different
+        language variants (TLDs) that may sound slightly different:
+        - male: uses .co.uk (British English - often perceived as more masculine)
+        - female: uses .com.au (Australian English - often perceived as more feminine)
+        - neutral: uses .com (Standard English)
+
+    Timed Audio Segments Format (when generate_segments=True):
+        {
+            "segments": [
+                {
+                    "segment_id": 1,
+                    "start_time": 0.0,
+                    "end_time": 5.0,
+                    "dialogue": "Welcome to our video",
+                    "audio_file": "outputs/audio/segment_1.mp3"
+                },
+                ...
+            ],
+            "total_duration": 15.0
+        }
+    """
+    try:
+        from gtts import gTTS
+    except ImportError:
+        return "Please install gTTS: pip install gtts"
+
+    if not text or not text.strip():
+        raise ValueError("Text cannot be empty")
+
+    # Auto-detect format if requested
+    if format_type == "auto":
+        format_type = detect_format(text)
+
+    # Parse subtitles based on format
+    subtitle_segments = []
+    if format_type == "srt":
+        dialogues = parse_srt(text)
+        if not dialogues:
+            raise ValueError("No dialogue found in SRT content")
+        if generate_segments:
+            subtitle_segments = parse_srt_with_timing(text)
+            if not subtitle_segments:
+                raise ValueError("Failed to parse SRT timing information")
+        else:
+            final_text = " ".join(dialogues)
+    elif format_type == "vtt":
+        dialogues = parse_vtt(text)
+        if not dialogues:
+            raise ValueError("No dialogue found in VTT content")
+        if generate_segments:
+            subtitle_segments = parse_vtt_with_timing(text)
+            if not subtitle_segments:
+                raise ValueError("Failed to parse VTT timing information")
+        else:
+            final_text = " ".join(dialogues)
+    elif format_type == "json":
+        dialogues = parse_json_scenario(text)
+        if not dialogues:
+            raise ValueError("No dialogue found in JSON content")
+        if generate_segments:
+            subtitle_segments = parse_json_with_timing(text)
+            if not subtitle_segments:
+                raise ValueError("Failed to parse JSON timing information")
+        else:
+            final_text = " ".join(dialogues)
+    else:
+        # Plain text - use as is
+        final_text = text
+        generate_segments = False  # Can't generate segments without timing info
+
+    # Map voice preference to gTTS TLD (top-level domain)
+    # Different accents can give perception of different voice characteristics
+    voice_tld_map = {
+        "male": "co.uk",  # British English (deeper/masculine perception)
+        "female": "com.au",  # Australian English (lighter/feminine perception)
+        "neutral": "com",  # US English (neutral)
+    }
+
+    tld = voice_tld_map.get(voice, "com")
+    slow = speed == "slow"
+
+    # Create output directory
+    output_dir = Path("outputs/audio")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        if generate_segments and subtitle_segments:
+            # Generate individual audio files for each subtitle segment
+            result_segments = []
+            total_duration = 0.0
+
+            for idx, segment in enumerate(subtitle_segments, 1):
+                segment_text = segment["dialogue"]
+                start_time = segment["start_time"]
+                end_time = segment["end_time"]
+                total_duration = max(total_duration, end_time)
+
+                # Generate audio for this segment
+                segment_path = str(output_dir / f"segment_{idx}.mp3")
+                tts = gTTS(text=segment_text, lang=language, slow=slow, tld=tld)
+                tts.save(segment_path)
+
+                result_segments.append(
+                    {
+                        "segment_id": idx,
+                        "start_time": start_time,
+                        "end_time": end_time,
+                        "duration": end_time - start_time,
+                        "dialogue": segment_text,
+                        "audio_file": segment_path,
+                    }
+                )
+
+            # Return JSON with segment information
+            result = {
+                "segments": result_segments,
+                "total_duration": total_duration,
+                "voice": voice,
+                "language": language,
+                "speed": speed,
+            }
+            return json.dumps(result, indent=2)
+        else:
+            # Generate single combined audio file
+            output_path = str(output_dir / "generated_speech.mp3")
+            tts = gTTS(text=final_text, lang=language, slow=slow, tld=tld)
+            tts.save(output_path)
+
+            # Return the path so Gradio can load the audio file
+            return output_path
+
+    except Exception as e:
+        raise RuntimeError(f"Failed to generate audio: {str(e)}")

src/app/tools/thumbnail_generator.py

@@ -0,0 +1,212 @@
+import os
+import tempfile
+import time
+from typing import Optional
+from dotenv import load_dotenv
+import google.genai as genai
+from PIL import Image
+from io import BytesIO
+import mimetypes
+
+# Load environment variables
+load_dotenv()
+
+
+def thumbnail_generator(
+    image_input,
+    summary: str,
+    output_path: Optional[str] = None,
+) -> str:
+    """
+    Generate a highly engaging and funny thumbnail image for a TikTok video/social media post.
+    Uses Gemini AI to generate the complete thumbnail image directly, using the input image as
+    a background and adding strategically placed text overlays and humorous stickers/emojis.
+
+    Args:
+        image_input: Image file path (str) or tuple from Gradio - used as the background image
+        summary: Text summary of the video content (used to generate appropriate text and stickers)
+        output_path: Optional path where the thumbnail should be saved.
+                    If not provided, saves to a temporary file.
+
+    Returns:
+        str: Path to the generated thumbnail image (PNG format)
+
+    Raises:
+        ValueError: If image file not found or GOOGLE_API_KEY not set
+        Exception: If thumbnail generation fails
+    """
+    try:
+        # Handle Gradio image input format (can be tuple or string)
+        if isinstance(image_input, tuple):
+            image_path = image_input[0]
+        elif isinstance(image_input, str):
+            image_path = image_input
+        else:
+            raise ValueError("Invalid image input format")
+
+        # Validate image file exists
+        if not image_path or not os.path.exists(image_path):
+            raise ValueError(f"Image file not found: {image_path}")
+
+        # Get API key from environment
+        api_key = os.getenv("GOOGLE_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "GOOGLE_API_KEY environment variable is not set. "
+                "Please set it in your .env file or environment."
+            )
+
+        # Initialize Gemini client
+        client = genai.Client(api_key=api_key)
+
+        # Read image file as bytes
+        with open(image_path, "rb") as f:
+            image_data = f.read()
+
+        # Determine MIME type
+        mime_type, _ = mimetypes.guess_type(image_path)
+        if not mime_type or not mime_type.startswith("image/"):
+            # Default to png if cannot determine
+            mime_type = "image/png"
+
+        # Create comprehensive prompt for thumbnail generation
+        prompt = f"""Generate a highly engaging and funny thumbnail image for a TikTok video/social media post.
+
+Use the provided background image as the foundation, and create a complete thumbnail that includes:
+
+BACKGROUND IMAGE: Use the provided image as the base. This is a high-quality, captivating photograph that should fill the entire thumbnail area.
+
+TEXT OVERLAY: Add prominent, dramatic text that is:
+- Catchy, attention-grabbing, and creates curiosity based on this video summary: "{summary}"
+- Keep it short (3-8 words max) and impactful
+- Use bright, contrasting colors (neon yellow, electric green, vibrant orange) with a dark outline for maximum readability
+- Position the text in an empty or less busy area (upper left, upper right, or bottom) so it doesn't obscure key subjects
+- Make the text bold and large enough to be easily readable
+
+STICKER/EMOJI: Add a large, expressive, high-contrast sticker or emoji that enhances the comedic effect:
+- Options: 🚨 (siren/emergency), 😰 (sweating face), ☠️ (skull), 😱 (screaming), 🔥 (fire), ⚠️ (warning), 💥 (explosion)
+- Position it near the main subject or focal point, as if it's an extension of the dramatic reaction
+- Make it large and prominent without covering the main subject entirely
+
+OVERALL DESIGN:
+- Vibe: absurd, dramatic, high-energy, slightly chaotic
+- Colors: vibrant and eye-catching
+- Style: professional yet intentionally over-the-top
+- Integration: all overlays should be seamlessly integrated for comedic effect
+- The final image should be engaging, funny, and make viewers curious to watch the video
+
+Generate the complete thumbnail image with all these elements integrated."""
+
+        # Create image blob
+        image_blob = genai.types.Blob(data=image_data, mime_type=mime_type)
+        image_part = genai.types.Part(inline_data=image_blob)
+
+        # Use Gemini to generate the thumbnail image directly
+        # Use gemini-2.5-flash-image model which supports image generation
+        response = None
+        last_error = None
+
+        # Try with response_modalities first
+        try:
+            response = client.models.generate_content(
+                model="gemini-2.5-flash-image",
+                contents=[prompt, image_part],
+                config={
+                    "response_modalities": ["IMAGE"],
+                },
+            )
+        except (AttributeError, TypeError) as e:
+            # If response_modalities attribute error, try without config
+            last_error = e
+            try:
+                response = client.models.generate_content(
+                    model="gemini-2.5-flash-image",
+                    contents=[prompt, image_part],
+                )
+            except Exception as e2:
+                raise Exception(
+                    f"Failed to generate image with Gemini (response_modalities error: {str(e)}): {str(e2)}"
+                )
+        except Exception as e:
+            # For other errors, also try without response_modalities
+            last_error = e
+            try:
+                response = client.models.generate_content(
+                    model="gemini-2.5-flash-image",
+                    contents=[prompt, image_part],
+                )
+            except Exception as e2:
+                raise Exception(
+                    f"Failed to generate image with Gemini: {str(e)} (fallback also failed: {str(e2)})"
+                )
+
+        # Check if response is None
+        if response is None:
+            raise Exception("Gemini API returned None response")
+
+        # Extract the generated image from the response
+        generated_image = None
+
+        # Check if response has image data
+        if hasattr(response, "candidates") and response.candidates:
+            for candidate in response.candidates:
+                if hasattr(candidate, "content") and candidate.content:
+                    if hasattr(candidate.content, "parts"):
+                        for part in candidate.content.parts:
+                            # Check for inline_data (image data)
+                            if hasattr(part, "inline_data") and part.inline_data:
+                                generated_image = part.inline_data.data
+                                break
+                            # Check for blob (alternative format)
+                            elif hasattr(part, "blob") and part.blob:
+                                generated_image = part.blob.data
+                                break
+
+        # If no image found in candidates, try alternative response structure
+        if generated_image is None:
+            # Try to get image from response directly
+            if hasattr(response, "parts"):
+                for part in response.parts:
+                    if hasattr(part, "inline_data") and part.inline_data:
+                        generated_image = part.inline_data.data
+                        break
+                    elif hasattr(part, "blob") and part.blob:
+                        generated_image = part.blob.data
+                        break
+
+        # If still no image, the model might have returned text describing the image
+        # In that case, we'll need to handle it differently or raise an error
+        if generated_image is None:
+            # Check if response has text (might indicate the model didn't generate an image)
+            if hasattr(response, "text") and response.text:
+                raise Exception(
+                    f"Gemini returned text instead of image. This model may not support image generation. "
+                    f"Response: {response.text[:200]}"
+                )
+            else:
+                raise Exception(
+                    "Failed to extract generated image from Gemini response"
+                )
+
+        # Convert image data to PIL Image
+        thumbnail = Image.open(BytesIO(generated_image)).convert("RGB")
+
+        # Determine output path
+        if output_path is None:
+            temp_dir = tempfile.gettempdir()
+            timestamp = int(time.time())
+            output_path = os.path.join(temp_dir, f"thumbnail_{timestamp}.png")
+
+        # Ensure output directory exists
+        output_dir = os.path.dirname(output_path)
+        if output_dir and not os.path.exists(output_dir):
+            os.makedirs(output_dir, exist_ok=True)
+
+        # Save thumbnail
+        thumbnail.save(output_path, "PNG", quality=95)
+
+        # Return absolute path
+        return os.path.abspath(output_path)
+
+    except Exception as e:
+        raise Exception(f"Error generating thumbnail: {str(e)}")

src/app/tools/video_clipper.py

@@ -0,0 +1,102 @@
+import os
+import tempfile
+from pathlib import Path
+from moviepy import VideoFileClip
+
+
+def video_clipper(
+    video_input, start_time: float, end_time: float, output_path: str = None
+) -> str:
+    """
+    Extract a specific segment from a video file based on start and end times.
+
+    Args:
+        video_input: Video file path (str) or tuple (video_path, subtitle_path) from Gradio
+        start_time (float): Start time in seconds (0-based)
+        end_time (float): End time in seconds (must be > start_time)
+        output_path (str, optional): Path where the clipped video should be saved.
+                                    If not provided, saves to a temporary file.
+
+    Returns:
+        str: Path to the clipped video file
+    """
+    try:
+        # Handle Gradio video input format (can be tuple or string)
+        if isinstance(video_input, tuple):
+            video_path = video_input[0]
+        elif isinstance(video_input, str):
+            video_path = video_input
+        else:
+            raise ValueError("Invalid video input format. Expected string or tuple.")
+
+        # Validate video file exists
+        if not video_path or not os.path.exists(video_path):
+            raise FileNotFoundError(f"Video file not found: {video_path}")
+
+        # Validate time parameters
+        if start_time < 0:
+            raise ValueError("Start time must be >= 0")
+
+        if end_time <= start_time:
+            raise ValueError("End time must be greater than start time")
+
+        # Load the video file
+        video = VideoFileClip(video_path)
+
+        # Validate time range against video duration
+        video_duration = video.duration
+        if start_time >= video_duration:
+            video.close()
+            raise ValueError(
+                f"Start time ({start_time}s) exceeds video duration ({video_duration:.2f}s)"
+            )
+
+        # Clamp end_time to video duration if necessary
+        if end_time > video_duration:
+            end_time = video_duration
+
+        # Extract the segment (using subclipped for MoviePy 2.1.2+)
+        clipped_video = video.subclipped(start_time, end_time)
+
+        # Determine output path
+        if output_path is None:
+            # Create a temporary file with appropriate extension
+            video_ext = Path(video_path).suffix or ".mp4"
+            temp_dir = tempfile.gettempdir()
+            output_path = os.path.join(
+                temp_dir,
+                f"clipped_{os.path.basename(video_path)}_{start_time}_{end_time}{video_ext}",
+            )
+
+        # Ensure output directory exists
+        output_dir = os.path.dirname(output_path)
+        if output_dir and not os.path.exists(output_dir):
+            os.makedirs(output_dir, exist_ok=True)
+
+        # Write the clipped video
+        clipped_video.write_videofile(
+            output_path,
+            codec="libx264",
+            audio_codec="aac",
+            temp_audiofile=tempfile.mktemp(suffix=".m4a"),
+            remove_temp=True,
+            logger=None,
+        )
+
+        # Clean up
+        clipped_video.close()
+        video.close()
+
+        # Return absolute path
+        return os.path.abspath(output_path)
+
+    except Exception as e:
+        # Clean up video object if it exists
+        try:
+            if "video" in locals() and video is not None:
+                video.close()
+            if "clipped_video" in locals() and clipped_video is not None:
+                clipped_video.close()
+        except:
+            pass
+        raise Exception(f"Error clipping video: {str(e)}")

src/app/tools/video_composer.py

@@ -0,0 +1,495 @@
+import os
+import json
+import tempfile
+from pathlib import Path
+from typing import List, Optional, Union, TypedDict, Literal, Tuple
+from moviepy import (
+    VideoFileClip,
+    CompositeVideoClip,
+    AudioFileClip,
+    concatenate_videoclips,
+    ImageClip,
+)
+
+try:
+    from moviepy.audio import concatenate_audioclips
+except ImportError:
+    from moviepy import concatenate_audioclips
+
+
+# Type definitions for script structure
+TransitionType = Literal["cut", "fade", "crossfade"]
+
+
+class Scene(TypedDict, total=False):
+    """Scene definition in the video composition script."""
+
+    scene_id: int
+    source_video: Union[
+        int, str
+    ]  # Index (int) or filename (str) referencing video_clips
+    start_time: float
+    end_time: Optional[float]
+    duration: Optional[float]
+    transition_in: TransitionType
+    transition_out: TransitionType
+
+
+class Music(TypedDict, total=False):
+    """Music configuration in the video composition script."""
+
+    mood: str
+    bpm: int
+    sync_points: List[float]
+    volume: float
+
+
+class ScriptData(TypedDict, total=False):
+    """Complete script structure for video composition."""
+
+    total_duration: float
+    scenes: List[Scene]
+    music: Music
+
+
+# Type aliases for Gradio file inputs
+GradioVideoInput = Union[
+    str,  # Single file path
+    Tuple[str, str],  # Gradio video format: (video_path, subtitle_path)
+    List[Union[str, Tuple[str, str]]],  # List of files
+]
+
+GradioMusicInput = Union[
+    str,  # File path
+    Tuple[str, ...],  # Gradio file format: (file_path, ...)
+]
+
+GradioImageInput = Union[
+    str,  # File path
+    Tuple[str, ...],  # Gradio file format: (file_path, ...)
+]
+
+
+def video_composer(
+    script: Union[str, ScriptData],
+    video_clips: GradioVideoInput,
+    music_path: Optional[GradioMusicInput] = None,
+    thumbnail_image: Optional[GradioImageInput] = None,
+    output_path: Optional[str] = None,
+) -> str:
+    """
+    Combine video clips, add music, and apply transitions according to a script.
+    Creates a final composed video from multiple video segments.
+
+    Args:
+        script: Script JSON string or dict containing scene information with transitions.
+                Expected format:
+                {
+                    "total_duration": 30.0,
+                    "scenes": [
+                        {
+                            "scene_id": 1,
+                            "source_video": 0,  # Index into video_clips list, or filename
+                            "start_time": 5.2,
+                            "end_time": 8.5,
+                            "duration": 3.3,
+                            "transition_in": "fade",
+                            "transition_out": "crossfade"
+                        },
+                        {
+                            "scene_id": 2,
+                            "source_video": 0,  # Same video can be used in multiple scenes
+                            "start_time": 10.0,
+                            "end_time": 15.0,
+                            "duration": 5.0,
+                            "transition_in": "crossfade",
+                            "transition_out": "fade"
+                        },
+                        ...
+                    ],
+                    "music": {
+                        "mood": "energetic",
+                        "bpm": 120,
+                        "sync_points": [0.0, 7.5, 15.0, 22.5, 30.0]
+                    }
+                }
+                Note: source_video can be:
+                - An integer index (0-based) into the video_clips list
+                - A filename (string) that matches the basename of one of the videos in video_clips
+                The same source_video can be used in multiple scenes with different
+                time ranges. Each scene will extract its own clip from the referenced video.
+        video_clips: Required list of source video file paths or single path.
+                     Each scene's source_video references a video from this list.
+                     Can be a list, single string (from Gradio File component).
+        music_path: Optional path to background music file. If provided, will be added
+                   to the final video. Can be a string path or tuple (from Gradio File component).
+        thumbnail_image: Optional path to thumbnail image file. If provided, will be overlaid
+                        on the first frame of the video. Can be a string path or tuple (from Gradio File component).
+        output_path: Optional path where the composed video should be saved.
+                    If not provided, saves to a temporary file.
+
+    Returns:
+        str: Path to the final composed video file
+    """
+    try:
+        # Handle Gradio file input formats
+        if isinstance(video_clips, tuple):
+            # Single tuple from Gradio: (video_path, subtitle_path)
+            video_clips = [video_clips[0]] if video_clips else []
+        elif isinstance(video_clips, str):
+            # Single file path
+            video_clips = [video_clips]
+        elif isinstance(video_clips, list):
+            # List of file paths (may contain tuples from Gradio)
+            processed_clips = []
+            for clip in video_clips:
+                if isinstance(clip, tuple):
+                    # Gradio video format: (video_path, subtitle_path)
+                    processed_clips.append(clip[0])
+                elif isinstance(clip, str):
+                    processed_clips.append(clip)
+            video_clips = processed_clips if processed_clips else []
+        else:
+            raise ValueError(
+                "video_clips must be a string, tuple, or list of strings/tuples"
+            )
+
+        # Validate video_clips is not empty
+        if not video_clips:
+            raise ValueError("video_clips is required and cannot be empty")
+
+        # Validate all video files exist
+        for clip_path in video_clips:
+            if not os.path.exists(clip_path):
+                raise FileNotFoundError(f"Video clip not found: {clip_path}")
+
+        # Handle Gradio music file input format
+        if music_path is not None:
+            if isinstance(music_path, tuple):
+                # Gradio file format: (file_path, ...)
+                music_path = music_path[0] if music_path else None
+            elif not isinstance(music_path, str):
+                music_path = None
+
+        # Handle Gradio thumbnail image input format
+        thumbnail_path = None
+        if thumbnail_image is not None:
+            if isinstance(thumbnail_image, tuple):
+                # Gradio file format: (file_path, ...)
+                thumbnail_path = thumbnail_image[0] if thumbnail_image else None
+            elif isinstance(thumbnail_image, str):
+                thumbnail_path = thumbnail_image
+            else:
+                thumbnail_path = None
+
+        # Validate thumbnail image exists if provided
+        if thumbnail_path and not os.path.exists(thumbnail_path):
+            raise FileNotFoundError(f"Thumbnail image not found: {thumbnail_path}")
+
+        # Parse script if it's a string
+        if isinstance(script, str):
+            try:
+                script_data: ScriptData = json.loads(script)
+            except json.JSONDecodeError:
+                raise ValueError("Invalid JSON format for script")
+        else:
+            script_data = script
+
+        # Validate script structure
+        if not isinstance(script_data, dict) or "scenes" not in script_data:
+            raise ValueError(
+                "Script must contain a 'scenes' key with scene information"
+            )
+
+        scenes: List[Scene] = script_data.get("scenes", [])
+        if not scenes:
+            raise ValueError("Script must contain at least one scene")
+
+        # Helper function to resolve source_video reference
+        def resolve_source_video(
+            source_video_ref: Union[int, str], video_clips_list: List[str]
+        ) -> str:
+            """Resolve source_video reference to actual video path.
+
+            Args:
+                source_video_ref: Can be an integer index or a filename string
+                video_clips_list: List of video file paths
+
+            Returns:
+                str: Path to the source video
+            """
+            if isinstance(source_video_ref, int):
+                # Index-based reference
+                if source_video_ref < 0 or source_video_ref >= len(video_clips_list):
+                    raise ValueError(
+                        f"source_video index {source_video_ref} is out of range. "
+                        f"Must be between 0 and {len(video_clips_list) - 1}"
+                    )
+                return video_clips_list[source_video_ref]
+            elif isinstance(source_video_ref, str):
+                # Filename-based reference - match by basename
+                for clip_path in video_clips_list:
+                    if os.path.basename(clip_path) == source_video_ref:
+                        return clip_path
+                    # Also try matching the full path
+                    if clip_path == source_video_ref:
+                        return clip_path
+                raise ValueError(
+                    f"source_video '{source_video_ref}' not found in video_clips. "
+                    f"Available videos: {[os.path.basename(v) for v in video_clips_list]}"
+                )
+            else:
+                raise ValueError(
+                    f"source_video must be an integer index or filename string, "
+                    f"got {type(source_video_ref).__name__}"
+                )
+
+        # Extract clips from source videos based on script
+        clip_paths = []
+        for scene in scenes:
+            source_video_ref = scene.get("source_video")
+            start_time = scene.get("start_time", 0.0)
+            end_time = scene.get("end_time")
+            duration = scene.get("duration")
+
+            if source_video_ref is None:
+                raise ValueError(
+                    f"Scene {scene.get('scene_id', 'unknown')} missing 'source_video'"
+                )
+
+            # Resolve source_video reference to actual video path
+            source_video = resolve_source_video(source_video_ref, video_clips)
+
+            # Calculate end_time from duration if not provided
+            if end_time is None and duration is not None:
+                end_time = start_time + duration
+            elif end_time is None:
+                # Load video to get duration
+                temp_video = VideoFileClip(source_video)
+                end_time = temp_video.duration
+                temp_video.close()
+
+            # Clip the video segment
+            from .video_clipper import video_clipper
+
+            clipped_path = video_clipper(source_video, start_time, end_time)
+            clip_paths.append(clipped_path)
+
+        # Load all video clips
+        video_clips_loaded = []
+        for clip_path in clip_paths:
+            if not os.path.exists(clip_path):
+                raise FileNotFoundError(f"Video clip not found: {clip_path}")
+            video_clips_loaded.append(VideoFileClip(clip_path))
+
+        # Apply transitions and compose clips
+        transition_duration = 0.5  # Default transition duration in seconds
+        has_crossfade = False
+
+        # Check if any scene uses crossfade
+        for scene in scenes:
+            if (
+                scene.get("transition_in") == "crossfade"
+                or scene.get("transition_out") == "crossfade"
+            ):
+                has_crossfade = True
+                break
+
+        processed_clips = []
+
+        for i, (clip, scene) in enumerate(zip(video_clips_loaded, scenes)):
+            transition_in = scene.get("transition_in", "cut")
+            transition_out = scene.get("transition_out", "cut")
+
+            # Apply transition in (except for first clip)
+            if i > 0 and transition_in != "cut":
+                if transition_in in ("fade", "crossfade"):
+                    # Try fadein if available, otherwise skip transition
+                    if hasattr(clip, "fadein"):
+                        clip = clip.fadein(transition_duration)
+                    # If fadein not available, continue without transition
+
+            # Apply transition out (except for last clip)
+            if i < len(video_clips_loaded) - 1 and transition_out != "cut":
+                if transition_out in ("fade", "crossfade"):
+                    # Try fadeout if available, otherwise skip transition
+                    if hasattr(clip, "fadeout"):
+                        clip = clip.fadeout(transition_duration)
+                    # If fadeout not available, continue without transition
+
+            processed_clips.append(clip)
+
+        # Compose clips based on transition type
+        if has_crossfade:
+            # Use CompositeVideoClip for crossfades (overlapping clips)
+            final_clips = []
+            current_time = 0.0
+
+            for i, (clip, scene) in enumerate(zip(processed_clips, scenes)):
+                transition_in = scene.get("transition_in", "cut")
+
+                if i > 0 and transition_in == "crossfade":
+                    # Overlap for crossfade
+                    clip_start = current_time - transition_duration
+                else:
+                    clip_start = current_time
+
+                clip = clip.with_start(clip_start)
+                final_clips.append(clip)
+                current_time = clip_start + clip.duration
+
+            final_video = CompositeVideoClip(final_clips)
+        else:
+            # Use concatenate_videoclips for simple sequential composition
+            final_video = concatenate_videoclips(processed_clips, method="compose")
+
+        # Add thumbnail image to first frame if provided
+        if thumbnail_path and os.path.exists(thumbnail_path):
+            try:
+                from PIL import Image as PILImage
+
+                # Get video dimensions
+                video_width = final_video.w
+                video_height = final_video.h
+
+                # Load and resize thumbnail image using PIL
+                pil_image = PILImage.open(thumbnail_path)
+                pil_image = pil_image.resize(
+                    (video_width, video_height), PILImage.Resampling.LANCZOS
+                )
+
+                # Save resized image to temporary file
+                import tempfile
+
+                temp_thumbnail = tempfile.NamedTemporaryFile(
+                    suffix=".png", delete=False
+                )
+                pil_image.save(temp_thumbnail.name, "PNG")
+                temp_thumbnail.close()
+
+                # Load the resized thumbnail as ImageClip
+                thumbnail_clip = ImageClip(temp_thumbnail.name)
+
+                # Set duration to match one frame duration (very short)
+                # This ensures it only appears on the first frame
+                # MoviePy 2.x uses with_duration instead of set_duration
+                fps = final_video.fps if final_video.fps > 0 else 30.0
+                frame_duration = 1.0 / fps
+                thumbnail_clip = thumbnail_clip.with_duration(frame_duration)
+
+                # Position at the start (t=0) so it overlays the first frame
+                # MoviePy 2.x uses with_start instead of set_start
+                thumbnail_clip = thumbnail_clip.with_start(0)
+
+                # Composite the thumbnail over the video
+                # The thumbnail will appear on top of the first frame
+                final_video = CompositeVideoClip([final_video, thumbnail_clip])
+
+                # Clean up temporary file after composition
+                try:
+                    os.unlink(temp_thumbnail.name)
+                except:
+                    pass
+            except Exception as e:
+                # If thumbnail overlay fails, continue without thumbnail
+                print(f"Warning: Could not add thumbnail image: {str(e)}")
+
+        # Add music if provided
+        if music_path and os.path.exists(music_path):
+            try:
+                audio_clip = AudioFileClip(music_path)
+                video_duration = final_video.duration
+
+                # Trim or loop music to match video duration
+                if audio_clip.duration > video_duration:
+                    audio_clip = audio_clip.subclipped(0, video_duration)
+                elif audio_clip.duration < video_duration:
+                    # Loop the music if it's shorter than video
+                    loops_needed = int(video_duration / audio_clip.duration) + 1
+                    audio_clips = [audio_clip] * loops_needed
+                    audio_clip = concatenate_audioclips(audio_clips).subclipped(
+                        0, video_duration
+                    )
+
+                # Set audio volume (can be adjusted based on script music settings)
+                audio_volume = script_data.get("music", {}).get("volume", 0.5)
+
+                # Apply volume adjustment using MoviePy 2.x API
+                # MoviePy 2.1.2+ uses with_volume_scaled instead of volumex
+                audio_clip = audio_clip.with_volume_scaled(audio_volume)
+
+                # Combine video with audio
+                # MoviePy 2.x uses with_audio instead of set_audio
+                final_video = final_video.with_audio(audio_clip)
+            except Exception as e:
+                # If music loading fails, continue without music
+                print(f"Warning: Could not add music: {str(e)}")
+
+        # Determine output path
+        if output_path is None:
+            video_ext = ".mp4"
+            temp_dir = tempfile.gettempdir()
+            output_path = os.path.join(
+                temp_dir, f"composed_video_{os.getpid()}{video_ext}"
+            )
+
+        # Ensure output directory exists
+        output_dir = os.path.dirname(output_path)
+        if output_dir and not os.path.exists(output_dir):
+            os.makedirs(output_dir, exist_ok=True)
+
+        # Write the final composed video
+        final_video.write_videofile(
+            output_path,
+            codec="libx264",
+            audio_codec="aac",
+            temp_audiofile=tempfile.mktemp(suffix=".m4a"),
+            remove_temp=True,
+            logger=None,
+        )
+
+        # Clean up
+        final_video.close()
+        for clip in video_clips_loaded:
+            clip.close()
+        if music_path and "audio_clip" in locals():
+            try:
+                audio_clip.close()
+            except:
+                pass
+
+        # Clean up temporary clipped files (always created from source videos)
+        for clip_path in clip_paths:
+            try:
+                if os.path.exists(clip_path) and "clipped_" in os.path.basename(
+                    clip_path
+                ):
+                    os.remove(clip_path)
+            except:
+                pass
+
+        # Return absolute path
+        return os.path.abspath(output_path)
+
+    except Exception as e:
+        # Clean up video objects if they exist
+        try:
+            if "video_clips_loaded" in locals():
+                for clip in video_clips_loaded:
+                    try:
+                        clip.close()
+                    except:
+                        pass
+            if "final_video" in locals():
+                try:
+                    final_video.close()
+                except:
+                    pass
+            if "audio_clip" in locals():
+                try:
+                    audio_clip.close()
+                except:
+                    pass
+        except:
+            pass
+        raise Exception(f"Error composing video: {str(e)}")

src/app/tools/video_script_generator.py

@@ -0,0 +1,430 @@
+import os
+import json
+import re
+from typing import Optional, List, Union
+import google.genai as genai
+
+
+def _extract_and_parse_json(text: str) -> Optional[Union[dict, list]]:
+    """
+    Extract and parse JSON from text that might contain extra content.
+    Handles cases where JSON is wrapped in markdown, has extra text, or multiple objects.
+    """
+    if not text or not isinstance(text, str):
+        return None
+
+    text = text.strip()
+
+    # Try direct parsing first
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    # Try to extract JSON array by finding balanced brackets
+    bracket_count = 0
+    array_start = -1
+    for i, char in enumerate(text):
+        if char == "[":
+            if bracket_count == 0:
+                array_start = i
+            bracket_count += 1
+        elif char == "]":
+            bracket_count -= 1
+            if bracket_count == 0 and array_start >= 0:
+                array_str = text[array_start : i + 1]
+                try:
+                    return json.loads(array_str)
+                except json.JSONDecodeError:
+                    pass
+                array_start = -1
+
+    # Try to find multiple JSON objects and combine them into an array
+    # This handles cases where objects are concatenated: {}{}
+    objects = []
+    brace_count = 0
+    start_idx = -1
+
+    for i, char in enumerate(text):
+        if char == "{":
+            if brace_count == 0:
+                start_idx = i
+            brace_count += 1
+        elif char == "}":
+            brace_count -= 1
+            if brace_count == 0 and start_idx >= 0:
+                obj_str = text[start_idx : i + 1]
+                try:
+                    obj = json.loads(obj_str)
+                    objects.append(obj)
+                except json.JSONDecodeError:
+                    pass
+                start_idx = -1
+
+    if objects:
+        # If we found multiple objects, return as list
+        # If only one, return it directly (will be wrapped in list by caller)
+        return objects if len(objects) > 1 else objects[0]
+
+    # Try to extract a single JSON object by finding balanced braces
+    brace_count = 0
+    obj_start = -1
+    for i, char in enumerate(text):
+        if char == "{":
+            if brace_count == 0:
+                obj_start = i
+            brace_count += 1
+        elif char == "}":
+            brace_count -= 1
+            if brace_count == 0 and obj_start >= 0:
+                obj_str = text[obj_start : i + 1]
+                try:
+                    return json.loads(obj_str)
+                except json.JSONDecodeError:
+                    pass
+                obj_start = -1
+
+    return None
+
+
+def video_script_generator(
+    video_summaries: Union[str, List[dict], List[str]],
+    user_description: Optional[str] = None,
+    target_duration: float = 30.0,
+) -> str:
+    """
+    Create a detailed script/storyboard for the final 30-second video.
+    Uses Google Gemini API to intelligently generate a script based on video summaries
+    and user requirements.
+
+    Args:
+        video_summaries: Video summaries from video_summarizer tool.
+                        Can be:
+                        - JSON string (single summary)
+                        - List of dict objects (multiple summaries)
+                        - List of JSON strings (multiple summaries)
+        user_description: Optional user description of desired mood/style/content
+        target_duration: Target duration in seconds (default: 30.0)
+
+    Returns:
+        str: JSON string containing detailed script with:
+            - Scene sequence with source video and timestamps
+            - Duration for each scene segment (must sum to ~target_duration seconds)
+            - Transition types between scenes (cut, fade, crossfade)
+            - Pacing and rhythm plan
+            - Music synchronization points (beat markers, mood changes)
+            - Overall narrative structure and flow
+            - Visual style recommendations
+
+    Example output format:
+    {
+        "total_duration": 30.0,
+        "scenes": [
+            {
+                "scene_id": 1,
+                "source_video": 0,
+                "start_time": 5.2,
+                "end_time": 8.5,
+                "duration": 3.3,
+                "description": "Opening shot of landscape",
+                "transition_in": "fade",
+                "transition_out": "crossfade"
+            },
+            ...
+        ],
+        "music": {
+            "mood": "energetic",
+            "bpm": 120,
+            "sync_points": [0.0, 7.5, 15.0, 22.5, 30.0],
+            "volume": 0.5
+        },
+        "pacing": "fast",
+        "narrative_structure": "hook -> build -> climax -> resolution",
+        "visual_style": "bright, colorful, dynamic"
+    }
+    """
+    try:
+        # Parse video summaries input
+        summaries_list = []
+        if isinstance(video_summaries, str):
+            # JSON string - could be a single object or an array
+            # Use robust parsing to handle malformed JSON
+            parsed = _extract_and_parse_json(video_summaries)
+
+            if parsed is None:
+                raise ValueError(
+                    f"Invalid JSON format for video_summaries. "
+                    f"Could not parse: {video_summaries[:200]}..."
+                )
+
+            if isinstance(parsed, list):
+                # It's a JSON array
+                summaries_list = parsed
+            else:
+                # It's a single JSON object
+                summaries_list = [parsed]
+        elif isinstance(video_summaries, list):
+            # List of summaries
+            for summary in video_summaries:
+                if isinstance(summary, str):
+                    # Use robust parsing for string summaries
+                    parsed = _extract_and_parse_json(summary)
+                    if parsed is None:
+                        raise ValueError(
+                            f"Invalid JSON format in video_summaries: {summary[:200]}..."
+                        )
+                    # If parsed is a list, extend; if it's a dict, append
+                    if isinstance(parsed, list):
+                        summaries_list.extend(parsed)
+                    else:
+                        summaries_list.append(parsed)
+                elif isinstance(summary, dict):
+                    summaries_list.append(summary)
+                else:
+                    raise ValueError(
+                        f"Invalid summary type: {type(summary).__name__}. "
+                        "Expected dict or JSON string."
+                    )
+        else:
+            raise ValueError(
+                f"Invalid video_summaries type: {type(video_summaries).__name__}. "
+                "Expected str, list of dicts, or list of JSON strings."
+            )
+
+        if not summaries_list:
+            raise ValueError("No video summaries provided")
+
+        # Validate target_duration
+        if target_duration <= 0:
+            raise ValueError("target_duration must be greater than 0")
+
+        # Get API key
+        api_key = os.getenv("GOOGLE_API_KEY")
+        if not api_key:
+            # Fallback: create a simple script using first video
+            summary = summaries_list[0]
+            duration = summary.get("duration", target_duration)
+            clip_duration = min(duration, target_duration)
+
+            # Extract mood from summary
+            mood_tags = summary.get("mood_tags", ["energetic"])
+            mood = mood_tags[0] if mood_tags else "energetic"
+
+            fallback_script = {
+                "total_duration": clip_duration,
+                "scenes": [
+                    {
+                        "scene_id": 1,
+                        "source_video": 0,
+                        "start_time": 0.0,
+                        "end_time": clip_duration,
+                        "duration": clip_duration,
+                        "description": summary.get("summary", "Video clip")[:100],
+                        "transition_in": "fade",
+                        "transition_out": "fade",
+                    }
+                ],
+                "music": {
+                    "mood": mood,
+                    "volume": 0.5,
+                },
+                "pacing": "moderate",
+                "narrative_structure": "single scene",
+            }
+            return json.dumps(fallback_script, indent=2)
+
+        # Initialize Gemini client
+        client = genai.Client(api_key=api_key)
+
+        # Build prompt for script generation
+        summaries_text = "\n\n".join(
+            [
+                f"Video {i+1}:\n{json.dumps(s, indent=2)}"
+                for i, s in enumerate(summaries_list)
+            ]
+        )
+
+        user_desc_text = (
+            f"\n\nUser Description: {user_description}" if user_description else ""
+        )
+
+        prompt = f"""You are a professional video editor creating a {target_duration}-second short-form video.
+
+Here are the video summaries:
+{summaries_text}
+{user_desc_text}
+
+Create a detailed video composition script that:
+1. Selects the most engaging and relevant scenes from the videos
+2. Creates a coherent narrative flow with a clear structure (hook -> build -> climax -> resolution)
+3. Uses appropriate transitions (cut, fade, or crossfade) between scenes
+4. Ensures the total duration is approximately {target_duration} seconds (within ±2 seconds)
+5. Distributes scenes evenly across the duration, considering pacing
+6. Identifies music mood, BPM, and sync points for rhythm matching
+7. Provides visual style recommendations based on the content
+
+Return ONLY a valid JSON object with this exact structure:
+{{
+    "total_duration": {target_duration},
+    "scenes": [
+        {{
+            "scene_id": 1,
+            "source_video": 0,
+            "start_time": 0.0,
+            "end_time": 5.0,
+            "duration": 5.0,
+            "description": "Brief description of what happens in this scene",
+            "transition_in": "fade",
+            "transition_out": "crossfade"
+        }},
+        {{
+            "scene_id": 2,
+            "source_video": 1,
+            "start_time": 10.0,
+            "end_time": 15.0,
+            "duration": 5.0,
+            "description": "Brief description of what happens in this scene",
+            "transition_in": "crossfade",
+            "transition_out": "fade"
+        }}
+    ],
+    "music": {{
+        "mood": "energetic",
+        "bpm": 120,
+        "sync_points": [0.0, 7.5, 15.0, 22.5, 30.0],
+        "volume": 0.5
+    }},
+    "pacing": "fast",
+    "narrative_structure": "hook -> build -> climax -> resolution",
+    "visual_style": "bright, colorful, dynamic"
+}}
+
+Rules:
+- source_video is 0-based index (0 for first video, 1 for second, etc.)
+- Each scene must have start_time, end_time, and duration
+- Total of all scene durations should be approximately {target_duration} seconds (±2 seconds tolerance)
+- Use transitions: "cut", "fade", or "crossfade"
+- Extract mood tags from the video summaries for the music section
+- sync_points should be evenly distributed or aligned to scene transitions
+- pacing should be one of: "slow", "moderate", "fast", "very-fast"
+- narrative_structure should describe the flow (e.g., "hook -> build -> climax -> resolution")
+- visual_style should describe the aesthetic (e.g., "bright, colorful, dynamic" or "dark, moody, cinematic")
+- Return ONLY the JSON, no other text or markdown formatting"""
+
+        # Generate script using Gemini
+        response = client.models.generate_content(
+            model="gemini-2.5-flash-lite",
+            contents=[prompt],
+        )
+
+        # Extract JSON from response
+        response_text = response.text.strip()
+
+        # Try to extract JSON if wrapped in markdown code blocks
+        if "```json" in response_text:
+            response_text = response_text.split("```json")[1].split("```")[0].strip()
+        elif "```" in response_text:
+            response_text = response_text.split("```")[1].split("```")[0].strip()
+
+        script = json.loads(response_text)
+
+        # Validate script structure
+        if not isinstance(script, dict):
+            raise ValueError("Generated script is not a valid dictionary")
+
+        # Ensure required fields exist
+        if "total_duration" not in script:
+            script["total_duration"] = target_duration
+
+        if "scenes" not in script:
+            raise ValueError("Generated script missing 'scenes' field")
+
+        if not isinstance(script["scenes"], list) or len(script["scenes"]) == 0:
+            raise ValueError("Generated script must contain at least one scene")
+
+        # Validate scene durations sum to approximately target_duration
+        total_scene_duration = sum(
+            scene.get("duration", 0) for scene in script["scenes"]
+        )
+        if abs(total_scene_duration - target_duration) > 5.0:
+            # Adjust durations proportionally if they're way off
+            if total_scene_duration > 0:
+                scale_factor = target_duration / total_scene_duration
+                for scene in script["scenes"]:
+                    if "duration" in scene:
+                        scene["duration"] = round(scene["duration"] * scale_factor, 2)
+                    if "start_time" in scene and "end_time" in scene:
+                        # Recalculate end_time based on scaled duration
+                        scene["end_time"] = round(
+                            scene["start_time"] + scene["duration"], 2
+                        )
+                script["total_duration"] = target_duration
+
+        # Ensure music section exists
+        if "music" not in script:
+            # Extract mood from summaries
+            mood_tags = []
+            for summary in summaries_list:
+                tags = summary.get("mood_tags", [])
+                if isinstance(tags, list):
+                    mood_tags.extend(tags)
+            mood = mood_tags[0] if mood_tags else "energetic"
+            script["music"] = {
+                "mood": mood,
+                "volume": 0.5,
+            }
+
+        # Add optional fields if missing
+        if "pacing" not in script:
+            script["pacing"] = "moderate"
+
+        if "narrative_structure" not in script:
+            script["narrative_structure"] = "linear"
+
+        if "visual_style" not in script:
+            script["visual_style"] = "standard"
+
+        return json.dumps(script, indent=2)
+
+    except json.JSONDecodeError as e:
+        # Fallback to simple script
+        if not summaries_list:
+            raise ValueError("No video summaries provided")
+
+        summary = summaries_list[0]
+        duration = summary.get("duration", target_duration)
+        clip_duration = min(duration, target_duration)
+
+        # Extract mood from summary
+        mood_tags = summary.get("mood_tags", ["energetic"])
+        mood = mood_tags[0] if mood_tags else "energetic"
+
+        fallback_script = {
+            "total_duration": clip_duration,
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": 0,
+                    "start_time": 0.0,
+                    "end_time": clip_duration,
+                    "duration": clip_duration,
+                    "description": (
+                        summary.get("summary", "Video clip")[:100]
+                        if isinstance(summary.get("summary"), str)
+                        else "Video clip"
+                    ),
+                    "transition_in": "fade",
+                    "transition_out": "fade",
+                }
+            ],
+            "music": {
+                "mood": mood,
+                "volume": 0.5,
+            },
+            "pacing": "moderate",
+            "narrative_structure": "single scene",
+        }
+        return json.dumps(fallback_script, indent=2)
+
+    except Exception as e:
+        raise Exception(f"Error generating video script: {str(e)}")

src/app/tools/video_summarizer.py

@@ -2,6 +2,7 @@ import cv2
 import json
 import os
 import mimetypes
+import re
 import google.genai as genai
 
 
@@ -15,7 +16,7 @@ def video_summarizer(video_input, fps: float = 2.0) -> str:
         fps (float): Frames per second for video processing by Gemini (default: 2.0, range: 0.1-24.0)
 
     Returns:
-        str: JSON string containing video summary with key scenes, detected objects/activities, and mood tags
+        str: JSON string containing video summary with key scenes, detected objects/activities, mood tags, and thumbnail_timeframe (in seconds)
     """
     try:
         # Handle Gradio video input format (can be tuple or string)
@@ -47,6 +48,8 @@ def video_summarizer(video_input, fps: float = 2.0) -> str:
         api_key = os.getenv("GOOGLE_API_KEY")
         if not api_key:
             # Fallback: return basic metadata without AI analysis
+            # Use middle of video as default thumbnail timeframe
+            thumbnail_timeframe = round(duration / 2, 2) if duration > 0 else 0
             return json.dumps(
                 {
                     "duration": round(duration, 2),
@@ -57,6 +60,7 @@ def video_summarizer(video_input, fps: float = 2.0) -> str:
                     "key_scenes": [],
                     "detected_objects": [],
                     "mood_tags": [],
+                    "thumbnail_timeframe": thumbnail_timeframe,
                 }
             )
 
@@ -81,6 +85,7 @@ def video_summarizer(video_input, fps: float = 2.0) -> str:
 3. Detected objects/activities - List the main objects, people, activities, or subjects visible in the video
 4. Mood and style tags - Identify the mood and style (e.g., energetic, calm, dramatic, fun, professional, casual, bright, dark, colorful, minimalist, fast-paced, slow-paced)
 5. Visual style description - Describe the visual aesthetics, color palette, lighting, and overall style
+6. Recommended thumbnail timestamp - Suggest the best timestamp (in seconds) to use as a thumbnail. This should be a visually representative moment that captures the essence of the video. Format your answer as: "THUMBNAIL_TIMESTAMP: X.XX seconds" where X.XX is the timestamp.
 
 Format your response as a structured, detailed summary that captures the essence of the video."""
 
@@ -120,6 +125,26 @@ Format your response as a structured, detailed summary that captures the essence
             mood for mood in mood_keywords if mood.lower() in summary_text.lower()
         ]
 
+        # Extract thumbnail timestamp from response
+        thumbnail_timeframe = None
+        # Try to find "THUMBNAIL_TIMESTAMP: X.XX seconds" pattern
+        timestamp_pattern = r"THUMBNAIL_TIMESTAMP:\s*([\d.]+)\s*seconds?"
+        match = re.search(timestamp_pattern, summary_text, re.IGNORECASE)
+        if match:
+            try:
+                thumbnail_timeframe = float(match.group(1))
+                # Ensure timestamp is within video duration
+                if thumbnail_timeframe > duration:
+                    thumbnail_timeframe = duration / 2
+                elif thumbnail_timeframe < 0:
+                    thumbnail_timeframe = 0
+            except ValueError:
+                thumbnail_timeframe = None
+
+        # Fallback: use middle of video if extraction failed
+        if thumbnail_timeframe is None:
+            thumbnail_timeframe = round(duration / 2, 2) if duration > 0 else 0
+
         # Structure the response
         result = {
             "duration": round(duration, 2),
@@ -128,6 +153,7 @@ Format your response as a structured, detailed summary that captures the essence
             "frame_count": frame_count,
             "summary": summary_text,
             "mood_tags": detected_moods if detected_moods else ["general"],
+            "thumbnail_timeframe": round(thumbnail_timeframe, 2),
         }
 
         return json.dumps(result, indent=2)

src/app/workflow.py

@@ -0,0 +1,355 @@
+"""
+Agent workflow for video creation using LangChain agent.
+
+This module implements the main workflow that orchestrates video processing
+tools to create polished videos from raw footage using a central agent.
+"""
+
+import os
+import json
+import re
+from typing import List, Optional, Generator, Tuple
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# LangChain v1.0 uses create_agent instead of create_react_agent
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain.agents import create_agent
+
+from tools.langchain_tools import ALL_TOOLS
+
+
+def _normalize_video_inputs(video_inputs) -> List[str]:
+    """
+    Normalize video inputs from Gradio format to list of absolute paths.
+
+    Args:
+        video_inputs: Can be:
+            - List of file paths
+            - List of tuples (from Gradio: (video_path, subtitle_path))
+            - Single file path
+            - Single tuple
+
+    Returns:
+        List of absolute file paths
+    """
+    if not video_inputs:
+        return []
+
+    # Handle single input
+    if not isinstance(video_inputs, list):
+        video_inputs = [video_inputs]
+
+    normalized = []
+    for item in video_inputs:
+        if isinstance(item, tuple):
+            # Gradio format: (video_path, subtitle_path)
+            video_path = item[0]
+        elif isinstance(item, str):
+            video_path = item
+        else:
+            continue
+
+        # Convert to absolute path
+        if video_path and os.path.exists(video_path):
+            normalized.append(os.path.abspath(video_path))
+
+    return normalized
+
+
+def _extract_json_from_text(text: str) -> Optional[str]:
+    """Extract JSON from text if present."""
+    if "{" in text and "}" in text:
+        start_idx = text.find("{")
+        end_idx = text.rfind("}") + 1
+        if start_idx >= 0 and end_idx > start_idx:
+            json_str = text[start_idx:end_idx]
+            try:
+                json.loads(json_str)
+                return json_str
+            except json.JSONDecodeError:
+                pass
+    return None
+
+
+def _extract_file_path_from_text(text: str, extensions: List[str]) -> Optional[str]:
+    """Extract file path from text if present."""
+    # First check if the text itself is a valid path
+    if os.path.exists(text.strip()):
+        return text.strip()
+
+    # Try to find path pattern in text
+    pattern = r"([/\\][^\s]+\.(" + "|".join(extensions) + "))"
+    match = re.search(pattern, text)
+    if match:
+        return match.group(1)
+    return None
+
+
+def agent_workflow(
+    video_inputs,
+    user_description: Optional[str] = None,
+    target_duration: float = 30.0,
+    generate_music: bool = True,
+) -> Generator[Tuple[Optional[str], str, str, str, str], None, None]:
+    """
+    Main agent workflow that orchestrates video creation using a central agent.
+
+    This is a generator function that yields progress updates as the workflow progresses.
+    Each yield contains: (final_path, summary_json, script_json, thumbnail_path, status)
+
+    Args:
+        video_inputs: Video file(s) from Gradio (can be list, tuple, or string)
+        user_description: Optional description of desired mood, style, or content
+        target_duration: Target duration in seconds for final video
+        generate_music: Whether to generate background music
+
+    Yields:
+        Tuple of (final_path, summary_json, script_json, thumbnail_path, status)
+        - final_path: Path to final video (None until complete)
+        - summary_json: JSON string of video summaries
+        - script_json: JSON string of generated script
+        - thumbnail_path: Path to thumbnail image (None until generated)
+        - status: Status message for UI
+    """
+    # Initialize outputs
+    final_path = None
+    summary_json = ""
+    script_json = ""
+    thumbnail_path = None
+    status = "Starting workflow...\n"
+
+    try:
+        # Normalize video inputs
+        status += "📥 Processing video inputs...\n"
+        yield final_path, summary_json, script_json, thumbnail_path, status
+
+        video_paths = _normalize_video_inputs(video_inputs)
+        if not video_paths:
+            status += "❌ No valid video files found.\n"
+            yield final_path, summary_json, script_json, thumbnail_path, status
+            return
+
+        status += f"✅ Found {len(video_paths)} video file(s).\n"
+        yield final_path, summary_json, script_json, thumbnail_path, status
+
+        # Get API key
+        api_key = os.getenv("GOOGLE_API_KEY")
+        if not api_key:
+            status += "❌ GOOGLE_API_KEY not found in environment.\n"
+            yield final_path, summary_json, script_json, thumbnail_path, status
+            return
+
+        # Create LLM
+        llm = ChatGoogleGenerativeAI(
+            model="gemini-2.5-flash-lite",
+            google_api_key=api_key,
+            temperature=0.7,
+        )
+
+        # Create central agent with all tools
+        status += "\n🤖 Initializing AI agent...\n"
+        yield final_path, summary_json, script_json, thumbnail_path, status
+
+        agent = create_agent(llm, tools=ALL_TOOLS)
+
+        # Build comprehensive workflow prompt
+        video_paths_str = "\n".join([f"- {path}" for path in video_paths])
+        user_desc_text = (
+            f"\nUser Description: {user_description}" if user_description else ""
+        )
+        music_instruction = (
+            "Generate background music matching the video's mood and style."
+            if generate_music
+            else "Do not generate background music."
+        )
+
+        workflow_prompt = f"""You are a professional video editor creating short-form videos. Your task is to transform raw video footage into a polished, engaging video.
+
+WORKFLOW TASKS (execute in order):
+
+Step 1. VIDEO ANALYSIS using the video_summarizer_tool
+   - Video files to analyze:
+{video_paths_str}
+   - Use fps=2.0 for analysis
+   - Collect all video summaries
+
+Step 2. SCRIPT GENERATION using the video_script_generator_tool
+   - Target duration: {target_duration} seconds
+   - The script should include:
+     * Scene sequences with source video references and timestamps
+     * Transitions (cut, fade, crossfade)
+     * Music configuration with mood and style
+     * Pacing and narrative structure
+{user_desc_text}
+
+Step 3. BACKGROUND MUSIC GENERATION (if enabled) using the music_selector_tool:
+   - {music_instruction}
+   - Extract mood from the script or video summaries
+   - Target duration: {target_duration} seconds
+
+Step 4. FRAME EXTRACTION using the frame_extractor_tool
+   - Extract a representative frame from the first video
+   - Use the thumbnail_timeframe from the first video's summary if available
+
+Step 5. THUMBNAIL GENERATION using thumbnail_generator_tool
+   - Use the extracted frame and video summary
+
+Step 6. VIDEO COMPOSITION using the video_composer_tool
+   - Provide the script JSON, video clips, music (if generated), and thumbnail
+   - The video_clips parameter should be a JSON array of video file paths
+
+IMPORTANT INSTRUCTIONS:
+- Execute all steps in sequence
+- Use the tools to accomplish each task
+- Extract and preserve JSON outputs (scripts, summaries) for the final result
+- Extract file paths from tool outputs (music, thumbnail, final video)
+- Think step by step and use the appropriate tools for each task
+- Do not skip any steps
+- Report progress as you complete each step
+
+Begin by analyzing the videos."""
+
+        status += "\n🎬 Starting video creation workflow...\n"
+        yield final_path, summary_json, script_json, thumbnail_path, status
+
+        # Stream agent execution for real-time updates
+        status += "🤖 Agent is working...\n"
+        yield final_path, summary_json, script_json, thumbnail_path, status
+
+        # Invoke agent and stream results
+        result = agent.invoke(
+            {"messages": [{"role": "user", "content": workflow_prompt}]}
+        )
+
+        print(result)
+
+        # Process agent result to extract outputs
+        if result and "messages" in result:
+            # Track tool outputs
+            summaries = []
+            music_path = None
+
+            # Extract information from all messages (including tool messages)
+            for message in result["messages"]:
+                # Check if this is a tool message (contains tool output)
+                message_type = (
+                    getattr(message, "type", None) if hasattr(message, "type") else None
+                )
+                content = (
+                    message.content if hasattr(message, "content") else str(message)
+                )
+
+                # Update status with agent's progress
+                if content:
+                    # Check for tool outputs - video_summarizer returns JSON
+                    if (
+                        "video_summarizer" in str(message).lower()
+                        or "summary" in content.lower()
+                    ):
+                        extracted_json = _extract_json_from_text(content)
+                        if extracted_json:
+                            try:
+                                parsed = json.loads(extracted_json)
+                                if isinstance(parsed, list):
+                                    summaries.extend(parsed)
+                                elif isinstance(parsed, dict) and "summary" in parsed:
+                                    summaries.append(parsed)
+                            except:
+                                pass
+
+                    # Check for script output
+                    if "script" in content.lower() or "scenes" in content:
+                        extracted_json = _extract_json_from_text(content)
+                        if extracted_json:
+                            try:
+                                parsed = json.loads(extracted_json)
+                                if "scenes" in parsed:
+                                    script_json = extracted_json
+                                    status += "✅ Script generated.\n"
+                                    yield final_path, summary_json, script_json, thumbnail_path, status
+                            except:
+                                pass
+
+                    # Check for music file path
+                    if "music" in content.lower() or "sound" in content.lower():
+                        music_path = _extract_file_path_from_text(
+                            content, ["mp3", "wav", "m4a"]
+                        )
+                        if music_path and os.path.exists(music_path):
+                            status += f"✅ Music generated.\n"
+                            yield final_path, summary_json, script_json, thumbnail_path, status
+
+                    # Check for thumbnail file path
+                    if "thumbnail" in content.lower() or "frame" in content.lower():
+                        thumb_path = _extract_file_path_from_text(
+                            content, ["png", "jpg", "jpeg"]
+                        )
+                        if thumb_path and os.path.exists(thumb_path):
+                            thumbnail_path = thumb_path
+                            status += f"✅ Thumbnail generated.\n"
+                            yield final_path, summary_json, script_json, thumbnail_path, status
+
+                    # Check for final video path
+                    if (
+                        "compose" in content.lower()
+                        or "final" in content.lower()
+                        or "video" in content.lower()
+                    ):
+                        video_path = _extract_file_path_from_text(
+                            content, ["mp4", "avi", "mov"]
+                        )
+                        if video_path and os.path.exists(video_path):
+                            final_path = video_path
+                            status += f"✅ Final video created.\n"
+                            yield final_path, summary_json, script_json, thumbnail_path, status
+
+            # Compile summaries if collected
+            if summaries:
+                summary_json = json.dumps(summaries, indent=2)
+                status += f"✅ Analyzed {len(summaries)} video(s).\n"
+                yield final_path, summary_json, script_json, thumbnail_path, status
+
+            # Final extraction from last message as fallback
+            if result["messages"]:
+                last_message = result["messages"][-1]
+                final_content = (
+                    last_message.content
+                    if hasattr(last_message, "content")
+                    else str(last_message)
+                )
+
+                # Final attempt to extract missing outputs
+                if not script_json:
+                    script_json = _extract_json_from_text(final_content) or ""
+
+                if not summary_json:
+                    summary_json = _extract_json_from_text(final_content) or ""
+
+                if not thumbnail_path:
+                    thumbnail_path = _extract_file_path_from_text(
+                        final_content, ["png", "jpg", "jpeg"]
+                    )
+
+                if not final_path:
+                    final_path = _extract_file_path_from_text(
+                        final_content, ["mp4", "avi", "mov"]
+                    )
+
+        # Final status update
+        if final_path:
+            status += "\n✅ Video creation complete! 🎉\n"
+        else:
+            status += "\n⚠️ Workflow completed, but final video path not found.\n"
+            status += "Check agent output for details.\n"
+
+        yield final_path, summary_json, script_json, thumbnail_path, status
+
+    except Exception as e:
+        status += f"\n❌ Workflow error: {str(e)}\n"
+        import traceback
+
+        status += f"\nDetails:\n{traceback.format_exc()}\n"
+        yield final_path, summary_json, script_json, thumbnail_path, status

src/app/workflow_ui.py

@@ -0,0 +1,153 @@
+import gradio as gr
+import traceback
+from workflow import agent_workflow
+
+
+def run_workflow(videos, description, duration, music):
+    """
+    Generator function that runs the workflow and yields progress updates in real-time.
+
+    According to Gradio's streaming outputs guide, generator functions yield values
+    that update the UI in real-time as they're produced.
+    """
+    # Handle empty or None input
+    if not videos or (isinstance(videos, list) and len(videos) == 0):
+        yield None, "❌ Please upload at least one video file.", "", "", None
+        return
+
+    try:
+        # Iterate through the generator from agent_workflow
+        # This will yield progress updates in real-time
+        for (
+            final_path,
+            summary_json,
+            script_json,
+            thumbnail_path,
+            status,
+        ) in agent_workflow(
+            video_inputs=videos,
+            user_description=description.strip() if description else None,
+            target_duration=float(duration),
+            generate_music=bool(music),
+        ):
+            # Yield each progress update to Gradio
+            # Gradio will automatically update the UI with each yield
+            yield final_path, status, summary_json, script_json, thumbnail_path
+
+    except Exception as e:
+        error_msg = f"❌ Error: {str(e)}\n\nDetails: {traceback.format_exc()}"
+        yield None, error_msg, "", "", None
+
+
+def workflow_ui():
+    """Create the full workflow UI interface."""
+    with gr.Column():
+        # Header
+        gr.Markdown(
+            """
+            # 🤖 Vidzly - AI Agent Workflow
+            
+            Transform your raw footage into a polished video with AI agent-powered editing.
+            Our intelligent agent uses MCP tools to analyze, plan, and create your video automatically.
+            Upload your videos, describe your vision, and let the AI agent handle the rest!
+            """
+        )
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                # Input section
+                gr.Markdown("### 📥 Input")
+
+                video_input = gr.File(
+                    label="Upload Video(s)",
+                    file_count="multiple",
+                    file_types=["video"],
+                    height=200,
+                )
+
+                user_description = gr.Textbox(
+                    label="Describe Your Vision (Optional)",
+                    placeholder="e.g., energetic and fast-paced, calm and cinematic, fun and colorful...",
+                    lines=3,
+                    info="Describe the mood, style, or vibe you want for your video",
+                )
+
+                with gr.Row():
+                    target_duration = gr.Slider(
+                        value=30.0,
+                        label="Target Duration (seconds)",
+                        minimum=5.0,
+                        maximum=60.0,
+                        step=1.0,
+                        info="Length of the final video",
+                    )
+
+                    generate_music = gr.Checkbox(
+                        value=True,
+                        label="Generate Background Music",
+                        info="Automatically generate music matching the video mood",
+                    )
+
+                create_btn = gr.Button(
+                    "🎬 Create Video",
+                    variant="primary",
+                    size="lg",
+                )
+
+                gr.Markdown("### 📝 Status")
+                progress_status = gr.Textbox(
+                    label="Status",
+                    value="Ready to create your video!",
+                    interactive=False,
+                    lines=10,
+                    max_lines=20,
+                )
+
+            with gr.Column(scale=2):
+                # Output section
+                gr.Markdown("### 🟢 Output")
+
+                thumbnail_image = gr.Image(
+                    label="Generated Thumbnail",
+                    type="filepath",
+                    height=400,
+                    visible=True,
+                )
+
+                final_video = gr.Video(
+                    label="Final Video",
+                    height=400,
+                )
+
+                with gr.Accordion("📋 Details", open=False):
+                    summary_display = gr.Textbox(
+                        label="Video Analysis Summary",
+                        lines=10,
+                        max_lines=20,
+                        interactive=False,
+                    )
+
+                    script_display = gr.Textbox(
+                        label="Generated Script",
+                        lines=10,
+                        max_lines=20,
+                        interactive=False,
+                    )
+
+        # Connect the button to the workflow
+        create_btn.click(
+            fn=run_workflow,
+            inputs=[
+                video_input,
+                user_description,
+                target_duration,
+                generate_music,
+            ],
+            outputs=[
+                final_video,
+                progress_status,
+                summary_display,
+                script_display,
+                thumbnail_image,
+            ],
+        )

tests/README.md

@@ -0,0 +1,70 @@
+# Tests
+
+This directory contains unit tests for the Vidzly tools.
+
+## Running Tests
+
+### Run all tests
+```bash
+poetry run pytest
+```
+
+### Run specific test file
+```bash
+poetry run pytest tests/test_video_clipper.py
+poetry run pytest tests/test_video_summarizer.py
+poetry run pytest tests/test_video_composer.py
+```
+
+### Run with coverage
+```bash
+poetry run pytest --cov=src/app/tools --cov-report=html
+```
+
+### Run with verbose output
+```bash
+poetry run pytest -v
+```
+
+### Run specific test
+```bash
+poetry run pytest tests/test_video_clipper.py::TestVideoClipper::test_video_clipper_with_string_path
+```
+
+## Test Structure
+
+- `conftest.py`: Shared pytest fixtures and configuration
+- `test_video_clipper.py`: Unit tests and integration tests for the video_clipper tool
+- `test_video_summarizer.py`: Unit tests and integration tests for the video_summarizer tool
+- `test_video_composer.py`: Unit tests and integration tests for the video_composer tool
+- `data/dodo.MOV`: Real video file used for integration tests
+- `data/dodo_2.mov`: Additional real video file used for integration tests
+
+## Test Coverage
+
+### Unit Tests (Mocked)
+The unit tests use mocking to avoid requiring actual video files or API keys:
+- **video_clipper**: Tests input validation, file handling, time range validation, and error handling
+- **video_summarizer**: Tests input validation, API integration (mocked), metadata extraction, and mood tag detection
+- **video_composer**: Tests script validation, source_video reference resolution (index/filename), error handling, and scene validation
+
+### Integration Tests (Real Video)
+The integration tests use the real video files from `tests/data/`:
+- **video_clipper**: Tests actual video clipping functionality with real video file
+- **video_summarizer**: Tests actual video analysis with real video file (works with or without API key)
+- **video_composer**: Tests actual video composition with real video files, including:
+  - Basic composition with multiple scenes from the same video
+  - Crossfade transitions
+  - Multiple source videos
+  - Three scenes from two different source videos
+  - Pre-clipped video composition
+
+## Notes
+
+- **Unit tests** use `unittest.mock` to mock external dependencies (MoviePy, OpenCV, Google Gemini API)
+- **Integration tests** use the real video files in `tests/data/` to test actual functionality
+- Temporary files are created and cleaned up automatically via pytest fixtures
+- Integration tests verify that the tools work correctly with real video files
+- The video_summarizer integration test with API key is skipped if `GOOGLE_API_KEY` is not set
+- **video_composer** requires `video_clips` parameter (list of source videos) and uses `source_video` in scenes to reference videos by index (0-based) or filename
+

tests/__init__.py

@@ -0,0 +1 @@
+# Tests package

tests/conftest.py

@@ -0,0 +1,104 @@
+"""
+Pytest configuration and shared fixtures for tests.
+"""
+
+import os
+import tempfile
+import pytest
+from pathlib import Path
+
+
+@pytest.fixture
+def temp_video_file():
+    """Create a temporary video file for testing."""
+    # Create a minimal test video file
+    # Note: In real tests, you might want to use an actual small video file
+    temp_dir = tempfile.mkdtemp()
+    video_path = os.path.join(temp_dir, "test_video.mp4")
+
+    # Create an empty file (in real scenario, this would be a valid video)
+    # For actual testing, you'd want to use a real small video file
+    Path(video_path).touch()
+
+    yield video_path
+
+    # Cleanup
+    if os.path.exists(video_path):
+        os.remove(video_path)
+    if os.path.exists(temp_dir):
+        os.rmdir(temp_dir)
+
+
+@pytest.fixture
+def temp_output_dir():
+    """Create a temporary directory for test outputs."""
+    temp_dir = tempfile.mkdtemp()
+    yield temp_dir
+
+    # Cleanup
+    import shutil
+
+    if os.path.exists(temp_dir):
+        shutil.rmtree(temp_dir)
+
+
+@pytest.fixture
+def mock_video_duration():
+    """Mock video duration in seconds."""
+    return 30.0
+
+
+@pytest.fixture
+def sample_video_metadata():
+    """Sample video metadata for testing."""
+    return {
+        "duration": 30.0,
+        "resolution": "1920x1080",
+        "fps": 30.0,
+        "frame_count": 900,
+    }
+
+
+@pytest.fixture
+def real_video_file():
+    """Get path to real video file in tests/data directory."""
+    test_dir = os.path.dirname(os.path.abspath(__file__))
+    video_path = os.path.join(test_dir, "data", "dodo.MOV")
+
+    if not os.path.exists(video_path):
+        pytest.skip(f"Test video file not found: {video_path}")
+
+    return video_path
+
+
+@pytest.fixture
+def real_video_file_2():
+    """Get path to second real video file in tests/data directory."""
+    test_dir = os.path.dirname(os.path.abspath(__file__))
+    video_path = os.path.join(test_dir, "data", "dodo_2.mov")
+
+    if not os.path.exists(video_path):
+        pytest.skip(f"Test video file not found: {video_path}")
+
+    return video_path
+
+
+@pytest.fixture
+def temp_image_file():
+    """Create a temporary image file for testing."""
+    from PIL import Image
+
+    temp_dir = tempfile.mkdtemp()
+    image_path = os.path.join(temp_dir, "test_image.png")
+
+    # Create a minimal test image
+    img = Image.new("RGB", (100, 100), color="red")
+    img.save(image_path)
+
+    yield image_path
+
+    # Cleanup
+    if os.path.exists(image_path):
+        os.remove(image_path)
+    if os.path.exists(temp_dir):
+        os.rmdir(temp_dir)

tests/test_adk_integration.py

@@ -0,0 +1,104 @@
+"""
+Test ADK integration with session manager.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from google.adk.agents import LlmAgent
+from google.adk.tools import FunctionTool
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src" / "app"))
+
+from adk_session_manager import ADKSessionManager
+from agent_helpers import invoke_agent_simple
+
+
+def test_session_manager():
+    """Test session manager creation."""
+    print("=== Testing Session Manager ===")
+    try:
+        manager = ADKSessionManager()
+        print("✅ Session manager created")
+
+        session_id = manager.create_session()
+        print(f"✅ Session created: {session_id}")
+
+        session = manager.get_session(session_id)
+        print(f"✅ Session retrieved: {type(session)}")
+
+        return manager
+    except Exception as e:
+        print(f"❌ Session manager test failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return None
+
+
+def test_simple_agent_invocation():
+    """Test simple agent invocation."""
+    print("\n=== Testing Simple Agent Invocation ===")
+    try:
+        # Create a simple tool
+        def add(a: int, b: int) -> int:
+            """Add two numbers."""
+            return a + b
+
+        tool = FunctionTool(func=add)
+
+        # Create agent
+        agent = LlmAgent(
+            model="gemini-2.5-flash-lite",
+            name="test_agent",
+            instruction="You are a helpful calculator. Use the add tool when asked to add numbers.",
+            tools=[tool],
+        )
+        print("✅ Agent created")
+
+        # Test invocation
+        try:
+            result = invoke_agent_simple(agent, "What is 5 + 3?")
+            print(f"✅ Agent invocation succeeded")
+            print(f"   Result: {result[:200]}")
+            return True
+        except Exception as e:
+            print(f"⚠️  Agent invocation failed: {e}")
+            print("   This is expected if ADK requires additional setup")
+            import traceback
+
+            traceback.print_exc()
+            return False
+
+    except Exception as e:
+        print(f"❌ Test failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return False
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("ADK Integration Test")
+    print("=" * 60)
+
+    manager = test_session_manager()
+    success = test_simple_agent_invocation()
+
+    print("\n" + "=" * 60)
+    print("Test Summary")
+    print("=" * 60)
+    print(f"Session Manager: {'✅' if manager else '❌'}")
+    print(f"Agent Invocation: {'✅' if success else '⚠️'}")
+    print("\nNote: Agent invocation may fail if ADK requires additional")
+    print("message handling or context setup. This is expected during development.")

tests/test_frame_extractor.py

@@ -0,0 +1,186 @@
+"""
+Unit tests for frame_extractor tool.
+"""
+
+import os
+import tempfile
+import pytest
+from unittest.mock import Mock, patch
+import numpy as np
+import sys
+
+# Add src to path to import modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from app.tools.frame_extractor import frame_extractor
+
+
+class TestFrameExtractor:
+    """Test cases for frame_extractor main function."""
+
+    def test_frame_extractor_with_api_key(self, temp_video_file, temp_output_dir):
+        """Test frame_extractor with API key."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.frame_extractor.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.frame_extractor.cv2.imwrite") as mock_imwrite,
+            patch("app.tools.frame_extractor.genai.Client") as mock_client,
+            patch("app.tools.frame_extractor.genai.types.Blob") as mock_blob,
+            patch(
+                "app.tools.frame_extractor.genai.types.VideoMetadata"
+            ) as mock_video_metadata,
+            patch("app.tools.frame_extractor.genai.types.Part") as mock_part,
+            patch("app.tools.frame_extractor.mimetypes.guess_type") as mock_guess_type,
+            patch("builtins.open", create=True) as mock_open,
+        ):
+
+            # Setup video capture mock (called twice: once for metadata, once for frame extraction)
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,  # FPS
+                7: 900,  # Frame count
+            }.get(prop, 0)
+            mock_cap.read.return_value = (
+                True,
+                np.ones((100, 100, 3), dtype=np.uint8) * 150,
+            )
+            mock_cap.set.return_value = True
+            mock_capture.return_value = mock_cap
+
+            # Setup file open mock for reading video file
+            mock_file = Mock()
+            mock_file.read.return_value = b"video file data"
+            mock_file.__enter__ = Mock(return_value=mock_file)
+            mock_file.__exit__ = Mock(return_value=None)
+            mock_open.return_value = mock_file
+
+            # Setup genai types mocks
+            mock_blob_instance = Mock()
+            mock_video_metadata_instance = Mock()
+            mock_part_instance = Mock()
+            mock_blob.return_value = mock_blob_instance
+            mock_video_metadata.return_value = mock_video_metadata_instance
+            mock_part.return_value = mock_part_instance
+
+            # Setup mimetypes mock
+            mock_guess_type.return_value = ("video/mp4", None)
+
+            # Setup Gemini API mock - returns timestamp
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = "15.5"  # Return timestamp in seconds
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            result = frame_extractor(temp_video_file)
+
+            assert isinstance(result, str)
+            # VideoCapture should be called twice: once for metadata, once for frame extraction
+            assert mock_capture.call_count == 2
+            # imwrite is called once for the final output frame
+            assert mock_imwrite.call_count == 1
+
+            # Cleanup frames directory if it was created
+            import shutil
+
+            frames_dir = os.path.join(os.path.dirname(temp_video_file), "frames")
+            if os.path.exists(frames_dir):
+                shutil.rmtree(frames_dir)
+
+    def test_frame_extractor_without_api_key(self, temp_video_file):
+        """Test frame_extractor raises error without API key."""
+        with (
+            patch.dict(os.environ, {}, clear=True),
+            patch("app.tools.frame_extractor.cv2.VideoCapture") as mock_capture,
+        ):
+
+            # Mock video capture to allow metadata extraction, so we reach the API key check
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,  # FPS
+                7: 900,  # Frame count
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            with pytest.raises(Exception) as exc_info:
+                frame_extractor(temp_video_file)
+
+            assert "GOOGLE_API_KEY" in str(exc_info.value)
+
+    def test_frame_extractor_invalid_input_format(self):
+        """Test frame_extractor with invalid input format."""
+        with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+            with pytest.raises(Exception) as exc_info:
+                frame_extractor(123)
+
+            assert "Invalid video input format" in str(exc_info.value)
+
+    def test_frame_extractor_file_not_found(self):
+        """Test frame_extractor with non-existent file."""
+        with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+            with pytest.raises(Exception) as exc_info:
+                frame_extractor("/nonexistent/video.mp4")
+
+            assert "Video file not found" in str(exc_info.value)
+
+    def test_frame_extractor_cannot_open_video(self, temp_video_file):
+        """Test frame_extractor when video cannot be opened."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.frame_extractor.cv2.VideoCapture") as mock_capture,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = False
+            mock_capture.return_value = mock_cap
+
+            with pytest.raises(Exception) as exc_info:
+                frame_extractor(temp_video_file)
+
+            assert "Could not open video file" in str(exc_info.value)
+
+    def test_frame_extractor_zero_duration(self, temp_video_file):
+        """Test frame_extractor with zero duration video."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.frame_extractor.cv2.VideoCapture") as mock_capture,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 0.0,  # Zero FPS
+                7: 0,  # Zero frames
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            with pytest.raises(Exception) as exc_info:
+                frame_extractor(temp_video_file)
+
+            assert "zero duration" in str(exc_info.value).lower()
+            mock_cap.release.assert_called_once()
+
+
+class TestFrameExtractorIntegration:
+    """Integration tests for frame_extractor using real video files."""
+
+    @pytest.mark.skipif(
+        not os.getenv("GOOGLE_API_KEY"),
+        reason="GOOGLE_API_KEY not set, skipping AI test",
+    )
+    def test_frame_extractor_real_video_ai(self, real_video_file):
+        """Test frame_extractor with real video file using AI."""
+        result = frame_extractor(real_video_file)
+
+        assert os.path.exists(result)
+        assert os.path.isabs(result)
+        assert result.endswith(".png")
+        assert os.path.getsize(result) > 0
+        # Cleanup
+        if os.path.exists(result):
+            os.remove(result)
+            frames_dir = os.path.dirname(result)
+            if os.path.exists(frames_dir) and not os.listdir(frames_dir):
+                os.rmdir(frames_dir)

tests/test_music_selector.py

@@ -0,0 +1,512 @@
+"""
+Unit tests for music_selector tool.
+"""
+
+import os
+import tempfile
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+import sys
+
+# Add src to path to import modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from app.tools.music_selector import music_selector
+
+
+class TestMusicSelector:
+    """Test cases for music_selector function."""
+
+    def test_music_selector_basic(self, temp_output_dir):
+        """Test music_selector with basic parameters."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            # Setup mock
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic", target_duration=10.0, output_path=output_path
+            )
+
+            # Assertions
+            assert os.path.isabs(result)
+            assert result == os.path.abspath(output_path)
+            assert os.path.exists(result)
+            mock_elevenlabs_class.assert_called_once_with(api_key="test_key")
+            mock_convert.assert_called_once()
+
+            # Check API was called with correct parameters
+            call_kwargs = mock_convert.call_args[1]
+            assert "text" in call_kwargs
+            assert "energetic" in call_kwargs["text"]
+            assert call_kwargs["duration_seconds"] == 10.0
+            assert call_kwargs["output_format"] == "mp3_44100_128"
+
+    @pytest.mark.parametrize(
+        "mood_input,expected_moods",
+        [
+            ("energetic, calm, dramatic", ["energetic", "calm", "dramatic"]),
+            (["fun", "professional"], ["fun", "professional"]),
+        ],
+    )
+    def test_music_selector_mood_formats(
+        self, temp_output_dir, mood_input, expected_moods
+    ):
+        """Test music_selector with different mood input formats."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood=mood_input,
+                target_duration=15.0,
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            for expected_mood in expected_moods:
+                assert expected_mood in call_kwargs["text"]
+
+    def test_music_selector_with_style(self, temp_output_dir):
+        """Test music_selector with style parameter."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic",
+                style="cinematic",
+                target_duration=25.0,
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            assert "cinematic" in call_kwargs["text"]
+            assert "style" in call_kwargs["text"]
+
+    def test_music_selector_with_bpm(self, temp_output_dir):
+        """Test music_selector with BPM parameter."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic", bpm=120, target_duration=15.0, output_path=output_path
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            assert "120" in call_kwargs["text"]
+            assert "BPM" in call_kwargs["text"]
+
+    def test_music_selector_with_looping(self, temp_output_dir):
+        """Test music_selector with looping enabled."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic",
+                looping=True,
+                target_duration=10.0,
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            assert call_kwargs["loop"] is True
+
+    def test_music_selector_with_prompt_influence(self, temp_output_dir):
+        """Test music_selector with prompt_influence parameter."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic",
+                prompt_influence=0.7,
+                target_duration=10.0,
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            assert call_kwargs["prompt_influence"] == 0.7
+
+    def test_music_selector_without_output_path(self, temp_output_dir):
+        """Test music_selector generates output path when not provided."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            result = music_selector(mood="energetic", target_duration=10.0)
+
+            assert os.path.isabs(result)
+            assert os.path.exists(result)
+            assert result.endswith(".mp3")
+            # Should contain mood in filename
+            assert "energetic" in os.path.basename(result).lower()
+
+    def test_music_selector_duration_clamping_max(self, temp_output_dir):
+        """Test music_selector clamps duration to maximum 30 seconds."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic",
+                target_duration=50.0,  # Exceeds max
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            assert call_kwargs["duration_seconds"] == 30.0
+
+    def test_music_selector_prompt_influence_clamping(self, temp_output_dir):
+        """Test music_selector clamps prompt_influence to 0-1 range."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+
+            # Test with value > 1
+            result = music_selector(
+                mood="energetic",
+                prompt_influence=2.0,
+                target_duration=10.0,
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            assert call_kwargs["prompt_influence"] == 1.0
+
+            # Test with value < 0
+            result = music_selector(
+                mood="energetic",
+                prompt_influence=-0.5,
+                target_duration=10.0,
+                output_path=output_path,
+            )
+
+            call_kwargs = mock_convert.call_args[1]
+            assert call_kwargs["prompt_influence"] == 0.0
+
+    def test_music_selector_empty_mood_defaults(self, temp_output_dir):
+        """Test music_selector uses default mood when empty."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="", target_duration=10.0, output_path=output_path
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            assert "energetic" in call_kwargs["text"]
+
+    def test_music_selector_with_sync_points(self, temp_output_dir):
+        """Test music_selector with sync_points parameter."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic",
+                sync_points=[0.0, 5.0, 10.0],
+                target_duration=10.0,
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            assert "beat markers" in call_kwargs["text"]
+
+    def test_music_selector_creates_output_directory(self, temp_output_dir):
+        """Test music_selector creates output directory if it doesn't exist."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_dir = os.path.join(temp_output_dir, "nested", "path")
+            output_path = os.path.join(output_dir, "test_sound.mp3")
+
+            result = music_selector(
+                mood="energetic", target_duration=10.0, output_path=output_path
+            )
+
+            assert os.path.exists(output_dir)
+            assert os.path.exists(result)
+
+    def test_music_selector_no_api_key(self):
+        """Test music_selector raises error when API key is missing."""
+        with patch.dict(os.environ, {}, clear=True):
+            with pytest.raises(Exception) as exc_info:
+                music_selector(mood="energetic", target_duration=10.0)
+
+            assert "ELEVENLABS_API_KEY" in str(exc_info.value)
+
+    def test_music_selector_elevenlabs_not_installed(self):
+        """Test music_selector raises error when elevenlabs is not installed."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs", None),
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            with pytest.raises(Exception) as exc_info:
+                music_selector(mood="energetic", target_duration=10.0)
+
+            assert "elevenlabs package is not installed" in str(exc_info.value)
+
+    def test_music_selector_api_error_handling(self, temp_output_dir):
+        """Test music_selector handles API errors gracefully."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(side_effect=Exception("API Error"))
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            with pytest.raises(Exception) as exc_info:
+                music_selector(
+                    mood="energetic", target_duration=10.0, output_path=output_path
+                )
+
+            assert "Error generating sound effect" in str(exc_info.value)
+
+    def test_music_selector_audio_data_bytes(self, temp_output_dir):
+        """Test music_selector handles bytes audio data."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_bytes_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic", target_duration=10.0, output_path=output_path
+            )
+
+            assert os.path.exists(result)
+            # Verify file was written
+            with open(result, "rb") as f:
+                assert f.read() == b"fake_audio_bytes_data"
+
+    def test_music_selector_audio_data_iterable(self, temp_output_dir):
+        """Test music_selector handles iterable audio data (generator/list)."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            # Return list of byte chunks
+            mock_convert = Mock(return_value=[b"chunk1", b"chunk2", b"chunk3"])
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic", target_duration=10.0, output_path=output_path
+            )
+
+            assert os.path.exists(result)
+            # Verify file contains all chunks
+            with open(result, "rb") as f:
+                content = f.read()
+                assert b"chunk1" in content
+                assert b"chunk2" in content
+                assert b"chunk3" in content
+
+    def test_music_selector_all_parameters(self, temp_output_dir):
+        """Test music_selector with all parameters provided."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic, calm",
+                style="cinematic",
+                target_duration=25.0,
+                bpm=120,
+                sync_points=[0.0, 5.0, 10.0],
+                looping=True,
+                prompt_influence=0.5,
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+
+            # Verify all parameters are in the prompt or API call
+            assert "energetic" in call_kwargs["text"]
+            assert "calm" in call_kwargs["text"]
+            assert "cinematic" in call_kwargs["text"]
+            assert "120" in call_kwargs["text"]
+            assert "beat markers" in call_kwargs["text"]
+            assert call_kwargs["duration_seconds"] == 25.0
+            assert call_kwargs["loop"] is True
+            assert call_kwargs["prompt_influence"] == 0.5
+            assert call_kwargs["output_format"] == "mp3_44100_128"
+
+    def test_music_selector_looping_false(self, temp_output_dir):
+        """Test music_selector with looping disabled."""
+        with (
+            patch("app.tools.music_selector.ElevenLabs") as mock_elevenlabs_class,
+            patch.dict(os.environ, {"ELEVENLABS_API_KEY": "test_key"}),
+        ):
+
+            mock_client = Mock()
+            mock_text_to_sound = Mock()
+            mock_convert = Mock(return_value=b"fake_audio_data")
+            mock_text_to_sound.convert = mock_convert
+            mock_client.text_to_sound_effects = mock_text_to_sound
+            mock_elevenlabs_class.return_value = mock_client
+
+            output_path = os.path.join(temp_output_dir, "test_sound.mp3")
+            result = music_selector(
+                mood="energetic",
+                looping=False,
+                target_duration=10.0,
+                output_path=output_path,
+            )
+
+            assert os.path.exists(result)
+            call_kwargs = mock_convert.call_args[1]
+            # When looping is False, loop parameter should not be in the call
+            # (or should be False if included)
+            if "loop" in call_kwargs:
+                assert call_kwargs["loop"] is False

tests/test_script_generator.py

@@ -0,0 +1,298 @@
+"""
+Unit tests for script_generator tool.
+"""
+
+import os
+import json
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+import sys
+
+# Add src to path to import modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from app.tools.script_generator import script_generator
+
+
+class TestScriptGenerator:
+    """Test cases for script_generator function."""
+
+    def test_script_generator_with_multiple_videos(self, temp_video_file):
+        """Test script_generator with multiple video inputs."""
+        with (
+            patch("app.tools.script_generator.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.script_generator.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = """Here's a comprehensive video script:
+
+```json
+{
+  "concept": "Energetic travel montage",
+  "target_duration": 30.0,
+  "total_duration": 30.0,
+  "scenes": [
+    {
+      "scene_id": 1,
+      "source_video": 0,
+      "start_time": 0.0,
+      "end_time": 10.0,
+      "duration": 10.0,
+      "description": "Opening scene",
+      "transition_in": "fade",
+      "transition_out": "crossfade"
+    }
+  ],
+  "audio": {
+    "mood": "energetic",
+    "style": "upbeat",
+    "bpm": 120,
+    "volume": 0.7
+  },
+  "text_overlays": [],
+  "visual_effects": ["color_grading"],
+  "call_to_action": "Subscribe for more"
+}
+```
+
+This is a narrative description of the script."""
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            video_inputs = [temp_video_file, temp_video_file]
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = script_generator(
+                    video_inputs, user_prompt="Create an energetic video"
+                )
+
+            result_json = json.loads(result)
+            assert "videos_analyzed" in result_json
+            assert "script_narrative" in result_json
+            assert len(result_json["videos_analyzed"]) == 2
+
+    def test_script_generator_without_prompt(self, temp_video_file):
+        """Test script_generator without user prompt."""
+        with (
+            patch("app.tools.script_generator.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.script_generator.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = "Auto-generated script based on video analysis."
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            video_inputs = [temp_video_file]
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = script_generator(video_inputs)
+
+            result_json = json.loads(result)
+            assert "videos_analyzed" in result_json
+            assert "script_narrative" in result_json
+            assert result_json["user_prompt"] == "Auto-generated based on materials"
+
+    def test_script_generator_with_string_input(self, temp_video_file):
+        """Test script_generator with single string video input."""
+        with (
+            patch("app.tools.script_generator.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.script_generator.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = "Generated script."
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = script_generator(temp_video_file)
+
+            result_json = json.loads(result)
+            assert "videos_analyzed" in result_json
+            assert len(result_json["videos_analyzed"]) == 1
+
+    def test_script_generator_with_tuple_input(self, temp_video_file):
+        """Test script_generator with tuple input (Gradio format)."""
+        with (
+            patch("app.tools.script_generator.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.script_generator.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = "Generated script."
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            video_input = (temp_video_file, "subtitle.srt")
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = script_generator(video_input)
+
+            result_json = json.loads(result)
+            assert "videos_analyzed" in result_json
+
+    def test_script_generator_with_empty_input(self):
+        """Test script_generator with no video input."""
+        result = script_generator([])
+        result_json = json.loads(result)
+        assert "error" in result_json
+        assert result_json["error"] == "No video files provided"
+
+    def test_script_generator_with_nonexistent_file(self):
+        """Test script_generator with nonexistent video file."""
+        result = script_generator(["/nonexistent/video.mp4"])
+        result_json = json.loads(result)
+        assert "error" in result_json
+        assert "not found" in result_json["error"]
+
+    def test_script_generator_without_api_key(self, temp_video_file):
+        """Test script_generator without GOOGLE_API_KEY."""
+        with patch("app.tools.script_generator.cv2.VideoCapture") as mock_capture:
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            with patch.dict(os.environ, {}, clear=True):
+                result = script_generator([temp_video_file])
+
+            result_json = json.loads(result)
+            assert "error" in result_json
+            assert "GOOGLE_API_KEY" in result_json["error"]
+            assert "videos_analyzed" in result_json
+
+    def test_script_generator_with_invalid_video(self, temp_video_file):
+        """Test script_generator with video that cannot be opened."""
+        with patch("app.tools.script_generator.cv2.VideoCapture") as mock_capture:
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = False
+            mock_capture.return_value = mock_cap
+
+            result = script_generator([temp_video_file])
+            result_json = json.loads(result)
+            assert "error" in result_json
+            assert "Could not open video file" in result_json["error"]
+
+    def test_script_generator_structured_script_parsing(self, temp_video_file):
+        """Test that structured JSON is properly extracted and parsed."""
+        with (
+            patch("app.tools.script_generator.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.script_generator.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = """Here's the script:
+
+```json
+{
+  "concept": "Test concept",
+  "target_duration": 30.0,
+  "scenes": []
+}
+```
+
+Narrative description."""
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = script_generator([temp_video_file])
+
+            result_json = json.loads(result)
+            assert "structured_script" in result_json
+            assert result_json["structured_script"]["concept"] == "Test concept"
+            assert result_json["structured_script"]["target_duration"] == 30.0
+
+    def test_script_generator_with_custom_prompt(self, temp_video_file):
+        """Test script_generator with custom user prompt."""
+        with (
+            patch("app.tools.script_generator.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.script_generator.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = "Custom prompt response."
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            custom_prompt = "Create a dramatic product reveal"
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = script_generator([temp_video_file], user_prompt=custom_prompt)
+
+            result_json = json.loads(result)
+            assert result_json["user_prompt"] == custom_prompt
+            assert "script_narrative" in result_json

tests/test_subtitle_creator.py

@@ -0,0 +1,435 @@
+"""
+Unit tests for subtitle_creator tool.
+"""
+
+import os
+import json
+import pytest
+from unittest.mock import Mock, patch, MagicMock, call
+import sys
+
+# Add src to path to import modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from app.tools.subtitle_creator import subtitle_creator
+
+
+class TestSubtitleCreator:
+    """Test cases for subtitle_creator function."""
+
+    @pytest.fixture
+    def simple_transcript(self):
+        """Simple transcript JSON for testing."""
+        return json.dumps(
+            {
+                "subtitles": [
+                    {
+                        "start": 0.0,
+                        "end": 2.5,
+                        "text": "Hello, welcome!",
+                        "position": "bottom",
+                        "fontsize": 48,
+                        "color": "white",
+                    },
+                    {
+                        "start": 2.5,
+                        "end": 5.0,
+                        "text": "This is a test.",
+                        "position": "top",
+                        "fontsize": 52,
+                        "color": "yellow",
+                    },
+                ],
+                "default_style": {
+                    "font": "Arial",
+                    "fontsize": 48,
+                    "color": "white",
+                    "bg_color": "black",
+                },
+            }
+        )
+
+    @pytest.fixture
+    def minimal_transcript(self):
+        """Minimal transcript with just required fields."""
+        return json.dumps(
+            {"subtitles": [{"start": 0.0, "end": 2.0, "text": "Test subtitle"}]}
+        )
+
+    def test_subtitle_creator_with_simple_transcript(
+        self, temp_video_file, simple_transcript
+    ):
+        """Test subtitle_creator with a simple transcript."""
+        with (
+            patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,
+            patch("app.tools.subtitle_creator.TextClip") as mock_text_clip,
+            patch("app.tools.subtitle_creator.CompositeVideoClip") as mock_composite,
+        ):
+            # Mock video
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video.fps = 30.0
+            mock_video_clip.return_value = mock_video
+
+            # Mock text clips
+            mock_text = Mock()
+            mock_text.with_start.return_value = mock_text
+            mock_text.with_end.return_value = mock_text
+            mock_text.with_position.return_value = mock_text
+            mock_text_clip.return_value = mock_text
+
+            # Mock composite
+            mock_final = Mock()
+            mock_composite.return_value = mock_final
+
+            result = subtitle_creator(temp_video_file, simple_transcript)
+
+            # Verify video was loaded
+            mock_video_clip.assert_called_once_with(temp_video_file)
+
+            # Verify text clips were created (2 subtitles)
+            assert mock_text_clip.call_count == 2
+
+            # Verify composite was created
+            mock_composite.assert_called_once()
+
+            # Verify video was written
+            mock_final.write_videofile.assert_called_once()
+
+            # Verify cleanup
+            mock_video.close.assert_called_once()
+            mock_final.close.assert_called_once()
+
+            assert result.endswith(".mp4")
+            assert os.path.exists(result) or result.startswith("/tmp/")
+
+    def test_subtitle_creator_with_minimal_transcript(
+        self, temp_video_file, minimal_transcript
+    ):
+        """Test subtitle_creator with minimal transcript (no styling)."""
+        with (
+            patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,
+            patch("app.tools.subtitle_creator.TextClip") as mock_text_clip,
+            patch("app.tools.subtitle_creator.CompositeVideoClip") as mock_composite,
+        ):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video.fps = 30.0
+            mock_video_clip.return_value = mock_video
+
+            mock_text = Mock()
+            mock_text.with_start.return_value = mock_text
+            mock_text.with_end.return_value = mock_text
+            mock_text.with_position.return_value = mock_text
+            mock_text_clip.return_value = mock_text
+
+            mock_final = Mock()
+            mock_composite.return_value = mock_final
+
+            result = subtitle_creator(temp_video_file, minimal_transcript)
+
+            # Verify text clip was created with defaults
+            mock_text_clip.assert_called_once()
+            call_kwargs = mock_text_clip.call_args[1]
+            assert call_kwargs["font"] == "Arial"
+            assert call_kwargs["font_size"] == 48
+            assert call_kwargs["color"] == "white"
+            assert call_kwargs["bg_color"] == "black"
+
+            assert result.endswith(".mp4")
+
+    def test_subtitle_creator_with_tuple_input(
+        self, temp_video_file, simple_transcript
+    ):
+        """Test subtitle_creator with tuple input (Gradio format)."""
+        with (
+            patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,
+            patch("app.tools.subtitle_creator.TextClip") as mock_text_clip,
+            patch("app.tools.subtitle_creator.CompositeVideoClip") as mock_composite,
+        ):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video.fps = 30.0
+            mock_video_clip.return_value = mock_video
+
+            mock_text = Mock()
+            mock_text.with_start.return_value = mock_text
+            mock_text.with_end.return_value = mock_text
+            mock_text.with_position.return_value = mock_text
+            mock_text_clip.return_value = mock_text
+
+            mock_final = Mock()
+            mock_composite.return_value = mock_final
+
+            video_input = (temp_video_file, "subtitle.srt")
+
+            result = subtitle_creator(video_input, simple_transcript)
+
+            mock_video_clip.assert_called_once_with(temp_video_file)
+            assert result.endswith(".mp4")
+
+    def test_subtitle_creator_with_custom_output_path(
+        self, temp_video_file, minimal_transcript, tmp_path
+    ):
+        """Test subtitle_creator with custom output path."""
+        with (
+            patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,
+            patch("app.tools.subtitle_creator.TextClip") as mock_text_clip,
+            patch("app.tools.subtitle_creator.CompositeVideoClip") as mock_composite,
+        ):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video.fps = 30.0
+            mock_video_clip.return_value = mock_video
+
+            mock_text = Mock()
+            mock_text.with_start.return_value = mock_text
+            mock_text.with_end.return_value = mock_text
+            mock_text.with_position.return_value = mock_text
+            mock_text_clip.return_value = mock_text
+
+            mock_final = Mock()
+            mock_composite.return_value = mock_final
+
+            output_path = str(tmp_path / "custom_subtitled.mp4")
+
+            result = subtitle_creator(temp_video_file, minimal_transcript, output_path)
+
+            assert result == output_path
+            mock_final.write_videofile.assert_called_once()
+
+    def test_subtitle_creator_with_nonexistent_file(self, simple_transcript):
+        """Test subtitle_creator with nonexistent video file."""
+        with pytest.raises(FileNotFoundError) as exc_info:
+            subtitle_creator("/nonexistent/video.mp4", simple_transcript)
+        assert "not found" in str(exc_info.value)
+
+    def test_subtitle_creator_with_invalid_json(self, temp_video_file):
+        """Test subtitle_creator with invalid JSON transcript."""
+        invalid_json = "{ this is not valid json }"
+
+        with pytest.raises(ValueError) as exc_info:
+            subtitle_creator(temp_video_file, invalid_json)
+        assert "Invalid JSON format" in str(exc_info.value)
+
+    def test_subtitle_creator_with_missing_subtitles_array(self, temp_video_file):
+        """Test subtitle_creator with missing subtitles array."""
+        transcript = json.dumps({"default_style": {"font": "Arial"}})
+
+        with (patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video_clip.return_value = mock_video
+
+            with pytest.raises(ValueError) as exc_info:
+                subtitle_creator(temp_video_file, transcript)
+            assert "must contain 'subtitles' array" in str(exc_info.value)
+
+    def test_subtitle_creator_with_empty_subtitles(self, temp_video_file):
+        """Test subtitle_creator with empty subtitles array."""
+        transcript = json.dumps({"subtitles": []})
+
+        with (patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video_clip.return_value = mock_video
+
+            with pytest.raises(ValueError) as exc_info:
+                subtitle_creator(temp_video_file, transcript)
+            assert "must contain 'subtitles' array" in str(exc_info.value)
+
+    def test_subtitle_creator_with_missing_required_fields(self, temp_video_file):
+        """Test subtitle_creator with subtitle missing required fields."""
+        transcript = json.dumps(
+            {"subtitles": [{"start": 0.0, "text": "Missing end time"}]}
+        )
+
+        with (patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video_clip.return_value = mock_video
+
+            with pytest.raises(ValueError) as exc_info:
+                subtitle_creator(temp_video_file, transcript)
+            assert "must have 'start', 'end', and 'text' fields" in str(exc_info.value)
+
+    def test_subtitle_creator_with_negative_times(self, temp_video_file):
+        """Test subtitle_creator with negative start/end times."""
+        transcript = json.dumps(
+            {"subtitles": [{"start": -1.0, "end": 2.0, "text": "Negative start"}]}
+        )
+
+        with (patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video_clip.return_value = mock_video
+
+            with pytest.raises(ValueError) as exc_info:
+                subtitle_creator(temp_video_file, transcript)
+            assert "must be >= 0" in str(exc_info.value)
+
+    def test_subtitle_creator_with_invalid_time_range(self, temp_video_file):
+        """Test subtitle_creator with end time before start time."""
+        transcript = json.dumps(
+            {"subtitles": [{"start": 5.0, "end": 2.0, "text": "Invalid range"}]}
+        )
+
+        with (patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video_clip.return_value = mock_video
+
+            with pytest.raises(ValueError) as exc_info:
+                subtitle_creator(temp_video_file, transcript)
+            assert "end time must be greater than start time" in str(exc_info.value)
+
+    def test_subtitle_creator_with_time_exceeding_duration(self, temp_video_file):
+        """Test subtitle_creator with start time exceeding video duration."""
+        transcript = json.dumps(
+            {"subtitles": [{"start": 15.0, "end": 20.0, "text": "Beyond video"}]}
+        )
+
+        with (patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video_clip.return_value = mock_video
+
+            with pytest.raises(ValueError) as exc_info:
+                subtitle_creator(temp_video_file, transcript)
+            assert "exceeds video duration" in str(exc_info.value)
+
+    def test_subtitle_creator_clamps_end_time(self, temp_video_file):
+        """Test that end time is clamped to video duration."""
+        transcript = json.dumps(
+            {"subtitles": [{"start": 8.0, "end": 15.0, "text": "End beyond duration"}]}
+        )
+
+        with (
+            patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,
+            patch("app.tools.subtitle_creator.TextClip") as mock_text_clip,
+            patch("app.tools.subtitle_creator.CompositeVideoClip") as mock_composite,
+        ):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video.fps = 30.0
+            mock_video_clip.return_value = mock_video
+
+            mock_text = Mock()
+            mock_text.with_start.return_value = mock_text
+            mock_text.with_end.return_value = mock_text
+            mock_text.with_position.return_value = mock_text
+            mock_text_clip.return_value = mock_text
+
+            mock_final = Mock()
+            mock_composite.return_value = mock_final
+
+            result = subtitle_creator(temp_video_file, transcript)
+
+            # Verify end time was clamped by checking with_end was called with video duration
+            mock_text.with_end.assert_called_with(10.0)
+
+    def test_subtitle_creator_with_different_positions(self, temp_video_file):
+        """Test subtitle_creator with different position options."""
+        transcript = json.dumps(
+            {
+                "subtitles": [
+                    {"start": 0.0, "end": 1.0, "text": "Bottom", "position": "bottom"},
+                    {"start": 1.0, "end": 2.0, "text": "Top", "position": "top"},
+                    {"start": 2.0, "end": 3.0, "text": "Center", "position": "center"},
+                    {
+                        "start": 3.0,
+                        "end": 4.0,
+                        "text": "Custom",
+                        "position": [100, 200],
+                    },
+                ]
+            }
+        )
+
+        with (
+            patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,
+            patch("app.tools.subtitle_creator.TextClip") as mock_text_clip,
+            patch("app.tools.subtitle_creator.CompositeVideoClip") as mock_composite,
+        ):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video.fps = 30.0
+            mock_video_clip.return_value = mock_video
+
+            mock_text = Mock()
+            mock_text.with_start.return_value = mock_text
+            mock_text.with_end.return_value = mock_text
+            mock_text.with_position.return_value = mock_text
+            mock_text_clip.return_value = mock_text
+
+            mock_final = Mock()
+            mock_composite.return_value = mock_final
+
+            result = subtitle_creator(temp_video_file, transcript)
+
+            # Verify 4 text clips were created
+            assert mock_text_clip.call_count == 4
+
+            # Verify with_position was called 4 times with different positions
+            assert mock_text.with_position.call_count == 4
+
+    def test_subtitle_creator_with_stroke_styling(self, temp_video_file):
+        """Test subtitle_creator with stroke/outline styling."""
+        transcript = json.dumps(
+            {
+                "subtitles": [
+                    {
+                        "start": 0.0,
+                        "end": 2.0,
+                        "text": "Outlined text",
+                        "stroke_color": "black",
+                        "stroke_width": 3,
+                    }
+                ]
+            }
+        )
+
+        with (
+            patch("app.tools.subtitle_creator.VideoFileClip") as mock_video_clip,
+            patch("app.tools.subtitle_creator.TextClip") as mock_text_clip,
+            patch("app.tools.subtitle_creator.CompositeVideoClip") as mock_composite,
+        ):
+            mock_video = Mock()
+            mock_video.duration = 10.0
+            mock_video.size = (1920, 1080)
+            mock_video.fps = 30.0
+            mock_video_clip.return_value = mock_video
+
+            mock_text = Mock()
+            mock_text.with_start.return_value = mock_text
+            mock_text.with_end.return_value = mock_text
+            mock_text.with_position.return_value = mock_text
+            mock_text_clip.return_value = mock_text
+
+            mock_final = Mock()
+            mock_composite.return_value = mock_final
+
+            result = subtitle_creator(temp_video_file, transcript)
+
+            # Verify stroke parameters were passed
+            call_kwargs = mock_text_clip.call_args[1]
+            assert call_kwargs["stroke_color"] == "black"
+            assert call_kwargs["stroke_width"] == 3
+
+    def test_subtitle_creator_with_invalid_video_input(self, simple_transcript):
+        """Test subtitle_creator with invalid video input type."""
+        with pytest.raises(ValueError) as exc_info:
+            subtitle_creator(12345, simple_transcript)  # type: ignore
+        assert "Invalid video input format" in str(exc_info.value)

tests/test_text_to_speech.py

@@ -0,0 +1,638 @@
+"""
+Tests for the Text-to-Speech converter.
+"""
+
+import os
+import json
+import pytest
+from pathlib import Path
+from unittest.mock import Mock, patch, MagicMock
+from src.app.tools.text_to_speech import text_to_speech_simple
+
+
+class TestTextToSpeechSimple:
+    """Test suite for the simple text-to-speech function using gTTS."""
+
+    def test_basic_text_to_speech(self, tmp_path, monkeypatch):
+        """Test basic text-to-speech conversion."""
+        # Mock gTTS
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            # Change output directory to tmp_path
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple("Hello, world!")
+
+            # Verify gTTS was called correctly with default parameters
+            mock_gtts_class.assert_called_once_with(
+                text="Hello, world!", lang="en", slow=False, tld="com"
+            )
+            mock_tts.save.assert_called_once()
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_srt_subtitle_conversion(self, tmp_path, monkeypatch):
+        """Test conversion of SRT subtitle format."""
+        srt_content = """1
+00:00:00,000 --> 00:00:03,500
+Welcome to our video.
+
+2
+00:00:03,500 --> 00:00:07,000
+Today we will learn something new."""
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(srt_content, format_type="srt")
+
+            # Check that dialogues were combined
+            call_args = mock_gtts_class.call_args
+            combined_text = call_args[1]["text"]
+            assert "Welcome to our video" in combined_text
+            assert "Today we will learn" in combined_text
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_vtt_subtitle_conversion(self, tmp_path, monkeypatch):
+        """Test conversion of VTT subtitle format."""
+        vtt_content = """WEBVTT
+
+00:00:00.000 --> 00:00:03.500
+Hello world.
+
+00:00:03.500 --> 00:00:07.000
+Welcome to the tutorial."""
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(vtt_content, format_type="vtt")
+
+            call_args = mock_gtts_class.call_args
+            combined_text = call_args[1]["text"]
+            assert "Hello world" in combined_text
+            assert "Welcome to the tutorial" in combined_text
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_json_subtitle_conversion(self, tmp_path, monkeypatch):
+        """Test conversion of JSON scenario format."""
+        json_content = (
+            '{"scenes": [{"dialogue": "First line"}, {"dialogue": "Second line"}]}'
+        )
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(json_content, format_type="json")
+
+            call_args = mock_gtts_class.call_args
+            combined_text = call_args[1]["text"]
+            assert "First line" in combined_text
+            assert "Second line" in combined_text
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_auto_detect_srt(self, tmp_path, monkeypatch):
+        """Test auto-detection of SRT format."""
+        srt_content = """1
+00:00:00,000 --> 00:00:03,500
+Auto-detected SRT."""
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(srt_content, format_type="auto")
+
+            mock_gtts_class.assert_called_once()
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_auto_detect_vtt(self, tmp_path, monkeypatch):
+        """Test auto-detection of VTT format."""
+        vtt_content = """WEBVTT
+
+00:00:00.000 --> 00:00:03.500
+Auto-detected VTT."""
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(vtt_content, format_type="auto")
+
+            mock_gtts_class.assert_called_once()
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_empty_text_raises_error(self):
+        """Test that empty text raises ValueError."""
+        with pytest.raises(ValueError, match="Text cannot be empty"):
+            text_to_speech_simple("")
+
+    def test_whitespace_only_text_raises_error(self):
+        """Test that whitespace-only text raises ValueError."""
+        with pytest.raises(ValueError, match="Text cannot be empty"):
+            text_to_speech_simple("   ")
+
+    def test_long_text_conversion(self, tmp_path, monkeypatch):
+        """Test conversion of longer text."""
+        long_text = "This is a longer piece of text. " * 10
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(long_text)
+
+            mock_gtts_class.assert_called_once()
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_gtts_not_installed(self):
+        """Test behavior when gTTS is not installed."""
+        # Mock the entire import to fail
+        with patch.dict("sys.modules", {"gtts": None}):
+            with patch(
+                "builtins.__import__", side_effect=ImportError("No module named 'gtts'")
+            ):
+                result = text_to_speech_simple("test")
+                assert "Please install gTTS" in result
+
+    def test_gtts_save_error(self):
+        """Test handling of gTTS save errors."""
+        mock_tts = Mock()
+        mock_tts.save.side_effect = Exception("Save failed")
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            with pytest.raises(RuntimeError, match="Failed to generate audio"):
+                text_to_speech_simple("test")
+
+    def test_special_characters_in_text(self, tmp_path, monkeypatch):
+        """Test text with special characters."""
+        text_with_special = "Hello! How are you? I'm fine, thanks. 😊"
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(text_with_special)
+
+            mock_gtts_class.assert_called_once_with(
+                text=text_with_special, lang="en", slow=False, tld="com"
+            )
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_multiline_text(self, tmp_path, monkeypatch):
+        """Test text with multiple lines."""
+        multiline_text = """Line one.
+Line two.
+Line three."""
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(multiline_text)
+
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_output_directory_creation(self, tmp_path, monkeypatch):
+        """Test that output directory is created if it doesn't exist."""
+        output_dir = tmp_path / "outputs" / "audio"
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        def mock_path(path_str):
+            if "outputs/audio" in str(path_str):
+                return output_dir
+            return Path(path_str)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            with patch("src.app.tools.text_to_speech.Path", side_effect=mock_path):
+                text_to_speech_simple("test")
+
+                # Verify directory would be created
+                assert mock_tts.save.called
+
+    def test_numbers_and_punctuation(self, tmp_path, monkeypatch):
+        """Test text with numbers and various punctuation."""
+        text = "The year is 2024! Count: 1, 2, 3... Ready? Let's go!"
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(text)
+
+            mock_gtts_class.assert_called_once_with(
+                text=text, lang="en", slow=False, tld="com"
+            )
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_male_voice_selection(self, tmp_path, monkeypatch):
+        """Test male voice selection uses correct TLD."""
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple("Hello", voice="male")
+
+            mock_gtts_class.assert_called_once_with(
+                text="Hello",
+                lang="en",
+                slow=False,
+                tld="co.uk",  # British English for male voice
+            )
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_female_voice_selection(self, tmp_path, monkeypatch):
+        """Test female voice selection uses correct TLD."""
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple("Hello", voice="female")
+
+            mock_gtts_class.assert_called_once_with(
+                text="Hello",
+                lang="en",
+                slow=False,
+                tld="com.au",  # Australian English for female voice
+            )
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_neutral_voice_selection(self, tmp_path, monkeypatch):
+        """Test neutral voice selection uses correct TLD."""
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple("Hello", voice="neutral")
+
+            mock_gtts_class.assert_called_once_with(
+                text="Hello",
+                lang="en",
+                slow=False,
+                tld="com",  # US English for neutral voice
+            )
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_language_selection(self, tmp_path, monkeypatch):
+        """Test different language selection."""
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple("Hola", language="es")
+
+            mock_gtts_class.assert_called_once_with(
+                text="Hola", lang="es", slow=False, tld="com"
+            )
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_slow_speed_selection(self, tmp_path, monkeypatch):
+        """Test slow speed selection."""
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple("Hello", speed="slow")
+
+            mock_gtts_class.assert_called_once_with(
+                text="Hello", lang="en", slow=True, tld="com"  # Slow speed enabled
+            )
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+    def test_combined_options(self, tmp_path, monkeypatch):
+        """Test combining voice, language, and speed options."""
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(
+                "Bonjour", voice="female", language="fr", speed="slow"
+            )
+
+            mock_gtts_class.assert_called_once_with(
+                text="Bonjour", lang="fr", slow=True, tld="com.au"
+            )
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+
+
+class TestTimedAudioSegments:
+    """Test suite for timed audio segment generation."""
+
+    def test_srt_timed_segments(self, tmp_path, monkeypatch):
+        """Test generating timed audio segments from SRT format."""
+        srt_content = """1
+00:00:00,000 --> 00:00:03,500
+Welcome to our video.
+
+2
+00:00:03,500 --> 00:00:07,000
+Today we will learn something new."""
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(
+                srt_content, format_type="srt", generate_segments=True
+            )
+
+            # Parse JSON result
+            result_data = json.loads(result)
+
+            # Verify structure
+            assert "segments" in result_data
+            assert len(result_data["segments"]) == 2
+
+            # Check first segment
+            segment1 = result_data["segments"][0]
+            assert segment1["segment_id"] == 1
+            assert segment1["start_time"] == 0.0
+            assert segment1["end_time"] == 3.5
+            assert segment1["duration"] == 3.5
+            assert segment1["dialogue"] == "Welcome to our video."
+            assert "segment_1.mp3" in segment1["audio_file"]
+
+            # Check second segment
+            segment2 = result_data["segments"][1]
+            assert segment2["segment_id"] == 2
+            assert segment2["start_time"] == 3.5
+            assert segment2["end_time"] == 7.0
+            assert segment2["duration"] == 3.5
+            assert segment2["dialogue"] == "Today we will learn something new."
+            assert "segment_2.mp3" in segment2["audio_file"]
+
+            # Verify gTTS was called twice (once per segment)
+            assert mock_gtts_class.call_count == 2
+
+    def test_vtt_timed_segments(self, tmp_path, monkeypatch):
+        """Test generating timed audio segments from VTT format."""
+        vtt_content = """WEBVTT
+
+1
+00:00:00.000 --> 00:00:02.500
+First subtitle here.
+
+2
+00:00:02.500 --> 00:00:05.000
+Second subtitle here."""
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(
+                vtt_content, format_type="vtt", generate_segments=True
+            )
+
+            # Parse JSON result
+            result_data = json.loads(result)
+
+            # Verify structure
+            assert "segments" in result_data
+            assert len(result_data["segments"]) == 2
+
+            # Check timing
+            segment1 = result_data["segments"][0]
+            assert segment1["start_time"] == 0.0
+            assert segment1["end_time"] == 2.5
+            assert segment1["dialogue"] == "First subtitle here."
+
+            segment2 = result_data["segments"][1]
+            assert segment2["start_time"] == 2.5
+            assert segment2["end_time"] == 5.0
+            assert segment2["dialogue"] == "Second subtitle here."
+
+    def test_json_timed_segments(self, tmp_path, monkeypatch):
+        """Test generating timed audio segments from JSON format."""
+        json_content = json.dumps(
+            {
+                "scenes": [
+                    {
+                        "scene_id": 1,
+                        "start_time": 0.0,
+                        "end_time": 4.0,
+                        "dialogue": "Scene one dialogue.",
+                    },
+                    {
+                        "scene_id": 2,
+                        "start_time": 4.0,
+                        "duration": 3.0,
+                        "dialogue": "Scene two dialogue.",
+                    },
+                ]
+            }
+        )
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(
+                json_content, format_type="json", generate_segments=True
+            )
+
+            # Parse JSON result
+            result_data = json.loads(result)
+
+            # Verify structure
+            assert "segments" in result_data
+            assert len(result_data["segments"]) == 2
+
+            # Check first segment
+            segment1 = result_data["segments"][0]
+            assert segment1["start_time"] == 0.0
+            assert segment1["end_time"] == 4.0
+            assert segment1["duration"] == 4.0
+            assert segment1["dialogue"] == "Scene one dialogue."
+
+            # Check second segment (end_time calculated from duration)
+            segment2 = result_data["segments"][1]
+            assert segment2["start_time"] == 4.0
+            assert segment2["end_time"] == 7.0
+            assert segment2["duration"] == 3.0
+            assert segment2["dialogue"] == "Scene two dialogue."
+
+    def test_auto_detect_srt_with_segments(self, tmp_path, monkeypatch):
+        """Test auto-detection of SRT format with segment generation."""
+        srt_content = """1
+00:00:00,000 --> 00:00:02,000
+Auto-detected SRT."""
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(
+                srt_content, format_type="auto", generate_segments=True
+            )
+
+            # Parse JSON result
+            result_data = json.loads(result)
+
+            # Verify auto-detection worked
+            assert "segments" in result_data
+            assert len(result_data["segments"]) == 1
+            assert result_data["segments"][0]["dialogue"] == "Auto-detected SRT."
+
+    def test_plain_text_with_segments_returns_single_file(self, tmp_path, monkeypatch):
+        """Test that plain text with generate_segments=True returns single file path."""
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(
+                "Plain text", format_type="text", generate_segments=True
+            )
+
+            # Plain text should return file path, not JSON
+            assert "generated_speech.mp3" in result or result.endswith(".mp3")
+            assert not result.startswith("{")
+
+    def test_empty_subtitle_segments(self, tmp_path, monkeypatch):
+        """Test handling of empty dialogue in timed segments (uses placeholder)."""
+        json_content = json.dumps(
+            {
+                "scenes": [
+                    {"scene_id": 1, "start_time": 0.0, "end_time": 2.0, "dialogue": ""},
+                    {
+                        "scene_id": 2,
+                        "start_time": 2.0,
+                        "end_time": 4.0,
+                        "dialogue": "Valid dialogue",
+                    },
+                ]
+            }
+        )
+
+        mock_tts = Mock()
+        mock_gtts_class = Mock(return_value=mock_tts)
+
+        with patch("gtts.gTTS", mock_gtts_class):
+            monkeypatch.setattr(
+                "src.app.tools.text_to_speech.Path",
+                lambda x: tmp_path / x if "outputs/audio" in x else Path(x),
+            )
+
+            result = text_to_speech_simple(
+                json_content, format_type="json", generate_segments=True
+            )
+
+            # Parse JSON result
+            result_data = json.loads(result)
+
+            # Both segments should be generated (empty dialogue gets placeholder)
+            assert len(result_data["segments"]) == 2
+            assert (
+                result_data["segments"][0]["dialogue"] == "Scene 1"
+            )  # Placeholder for empty dialogue
+            assert result_data["segments"][1]["dialogue"] == "Valid dialogue"

tests/test_thumbnail_generator.py

@@ -0,0 +1,341 @@
+"""
+Unit tests for thumbnail_generator tool.
+"""
+
+import os
+import tempfile
+import pytest
+from unittest.mock import Mock, patch, MagicMock, mock_open
+import sys
+from io import BytesIO
+
+# Add src to path to import modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from app.tools.thumbnail_generator import thumbnail_generator
+
+
+class TestThumbnailGenerator:
+    """Test cases for thumbnail_generator function."""
+
+    def test_thumbnail_generator_with_tuple_input(self, temp_image_file):
+        """Test thumbnail_generator with tuple input (Gradio format)."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.thumbnail_generator.genai.Client") as mock_client,
+            patch("app.tools.thumbnail_generator.Image.open") as mock_image_open,
+            patch(
+                "app.tools.thumbnail_generator.mimetypes.guess_type"
+            ) as mock_guess_type,
+            patch("builtins.open", mock_open(read_data=b"fake image data")),
+        ):
+
+            mock_guess_type.return_value = ("image/png", None)
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_candidate = Mock()
+            mock_content = Mock()
+            mock_part = Mock()
+            mock_inline_data = Mock()
+            mock_inline_data.data = b"fake generated image data"
+            mock_part.inline_data = mock_inline_data
+            mock_content.parts = [mock_part]
+            mock_candidate.content = mock_content
+            mock_response.candidates = [mock_candidate]
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            mock_image = Mock()
+            mock_image.convert.return_value = mock_image
+            mock_image_open.return_value = mock_image
+
+            image_input = (temp_image_file, "subtitle.srt")
+            summary = "An exciting adventure"
+
+            result = thumbnail_generator(image_input, summary)
+
+            assert os.path.isabs(result)
+            assert "thumbnail_" in result
+            assert result.endswith(".png")
+
+    def test_thumbnail_generator_without_output_path(self, temp_image_file):
+        """Test thumbnail_generator generates output path when not provided."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.thumbnail_generator.genai.Client") as mock_client,
+            patch("app.tools.thumbnail_generator.Image.open") as mock_image_open,
+            patch(
+                "app.tools.thumbnail_generator.mimetypes.guess_type"
+            ) as mock_guess_type,
+            patch("builtins.open", mock_open(read_data=b"fake image data")),
+        ):
+
+            mock_guess_type.return_value = ("image/png", None)
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_candidate = Mock()
+            mock_content = Mock()
+            mock_part = Mock()
+            mock_inline_data = Mock()
+            mock_inline_data.data = b"fake generated image data"
+            mock_part.inline_data = mock_inline_data
+            mock_content.parts = [mock_part]
+            mock_candidate.content = mock_content
+            mock_response.candidates = [mock_candidate]
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            mock_image = Mock()
+            mock_image.convert.return_value = mock_image
+            mock_image_open.return_value = mock_image
+
+            summary = "A dramatic moment"
+
+            result = thumbnail_generator(temp_image_file, summary)
+
+            assert os.path.isabs(result)
+            assert "thumbnail_" in result
+            assert result.endswith(".png")
+
+    def test_thumbnail_generator_invalid_input_format(self):
+        """Test thumbnail_generator with invalid input format."""
+        with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+            with pytest.raises(Exception) as exc_info:
+                thumbnail_generator(123, "summary")  # Invalid input type
+
+            assert "Invalid image input format" in str(exc_info.value)
+
+    def test_thumbnail_generator_file_not_found(self):
+        """Test thumbnail_generator with non-existent file."""
+        with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+            with pytest.raises(Exception) as exc_info:
+                thumbnail_generator("/nonexistent/image.png", "summary")
+
+            assert "Image file not found" in str(exc_info.value)
+
+    def test_thumbnail_generator_without_api_key(self, temp_image_file):
+        """Test thumbnail_generator raises error without API key."""
+        with patch.dict(os.environ, {}, clear=True):
+            with pytest.raises(Exception) as exc_info:
+                thumbnail_generator(temp_image_file, "summary")
+
+            assert "GOOGLE_API_KEY" in str(exc_info.value)
+
+    def test_thumbnail_generator_api_failure(self, temp_image_file):
+        """Test thumbnail_generator handles API failures."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.thumbnail_generator.genai.Client") as mock_client,
+            patch(
+                "app.tools.thumbnail_generator.mimetypes.guess_type"
+            ) as mock_guess_type,
+            patch("builtins.open", mock_open(read_data=b"fake image data")),
+        ):
+
+            mock_guess_type.return_value = ("image/png", None)
+
+            mock_genai_client = Mock()
+            mock_genai_client.models.generate_content.side_effect = Exception(
+                "API Error"
+            )
+            mock_client.return_value = mock_genai_client
+
+            with pytest.raises(Exception) as exc_info:
+                thumbnail_generator(temp_image_file, "summary")
+
+            assert "Error generating thumbnail" in str(
+                exc_info.value
+            ) or "API Error" in str(exc_info.value)
+
+    def test_thumbnail_generator_no_image_in_response(self, temp_image_file):
+        """Test thumbnail_generator when API doesn't return image data."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.thumbnail_generator.genai.Client") as mock_client,
+            patch(
+                "app.tools.thumbnail_generator.mimetypes.guess_type"
+            ) as mock_guess_type,
+            patch("builtins.open", mock_open(read_data=b"fake image data")),
+        ):
+
+            mock_guess_type.return_value = ("image/png", None)
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.candidates = []  # No candidates
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            with pytest.raises(Exception) as exc_info:
+                thumbnail_generator(temp_image_file, "summary")
+
+            assert "Failed to extract generated image" in str(
+                exc_info.value
+            ) or "Error generating thumbnail" in str(exc_info.value)
+
+    def test_thumbnail_generator_creates_output_directory(
+        self, temp_image_file, temp_output_dir
+    ):
+        """Test thumbnail_generator creates output directory if it doesn't exist."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.thumbnail_generator.genai.Client") as mock_client,
+            patch("app.tools.thumbnail_generator.Image.open") as mock_image_open,
+            patch(
+                "app.tools.thumbnail_generator.mimetypes.guess_type"
+            ) as mock_guess_type,
+            patch("builtins.open", mock_open(read_data=b"fake image data")),
+        ):
+
+            mock_guess_type.return_value = ("image/png", None)
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_candidate = Mock()
+            mock_content = Mock()
+            mock_part = Mock()
+            mock_inline_data = Mock()
+            mock_inline_data.data = b"fake generated image data"
+            mock_part.inline_data = mock_inline_data
+            mock_content.parts = [mock_part]
+            mock_candidate.content = mock_content
+            mock_response.candidates = [mock_candidate]
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            mock_image = Mock()
+            mock_image.convert.return_value = mock_image
+            mock_image_open.return_value = mock_image
+
+            output_dir = os.path.join(temp_output_dir, "nested", "path")
+            output_path = os.path.join(output_dir, "thumbnail.png")
+
+            result = thumbnail_generator(temp_image_file, "summary", output_path)
+
+            assert os.path.exists(output_dir)
+            assert os.path.isabs(result)
+
+    def test_thumbnail_generator_with_blob_format(self, temp_image_file):
+        """Test thumbnail_generator handles blob format in response."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.thumbnail_generator.genai.Client") as mock_client,
+            patch("app.tools.thumbnail_generator.Image.open") as mock_image_open,
+            patch(
+                "app.tools.thumbnail_generator.mimetypes.guess_type"
+            ) as mock_guess_type,
+            patch("builtins.open", mock_open(read_data=b"fake image data")),
+        ):
+
+            mock_guess_type.return_value = ("image/png", None)
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_candidate = Mock()
+            mock_content = Mock()
+            mock_part = Mock()
+            # Test blob format instead of inline_data
+            mock_blob = Mock()
+            mock_blob.data = b"fake generated image data"
+            mock_part.blob = mock_blob
+            mock_part.inline_data = None
+            mock_content.parts = [mock_part]
+            mock_candidate.content = mock_content
+            mock_response.candidates = [mock_candidate]
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            mock_image = Mock()
+            mock_image.convert.return_value = mock_image
+            mock_image_open.return_value = mock_image
+
+            result = thumbnail_generator(temp_image_file, "summary")
+
+            assert os.path.isabs(result)
+            assert result.endswith(".png")
+
+    def test_thumbnail_generator_api_fallback_without_response_modalities(
+        self, temp_image_file
+    ):
+        """Test thumbnail_generator falls back when response_modalities fails."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.thumbnail_generator.genai.Client") as mock_client,
+            patch("app.tools.thumbnail_generator.Image.open") as mock_image_open,
+            patch(
+                "app.tools.thumbnail_generator.mimetypes.guess_type"
+            ) as mock_guess_type,
+            patch("builtins.open", mock_open(read_data=b"fake image data")),
+        ):
+
+            mock_guess_type.return_value = ("image/png", None)
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_candidate = Mock()
+            mock_content = Mock()
+            mock_part = Mock()
+            mock_inline_data = Mock()
+            mock_inline_data.data = b"fake generated image data"
+            mock_part.inline_data = mock_inline_data
+            mock_content.parts = [mock_part]
+            mock_candidate.content = mock_content
+            mock_response.candidates = [mock_candidate]
+
+            # First call fails, second succeeds
+            mock_genai_client.models.generate_content.side_effect = [
+                Exception("response_modalities not supported"),
+                mock_response,
+            ]
+            mock_client.return_value = mock_genai_client
+
+            mock_image = Mock()
+            mock_image.convert.return_value = mock_image
+            mock_image_open.return_value = mock_image
+
+            result = thumbnail_generator(temp_image_file, "summary")
+
+            assert os.path.isabs(result)
+            # Should have been called twice (first with response_modalities, second without)
+            assert mock_genai_client.models.generate_content.call_count == 2
+
+    def test_thumbnail_generator_mime_type_detection(self, temp_image_file):
+        """Test thumbnail_generator handles different image MIME types."""
+        with (
+            patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}),
+            patch("app.tools.thumbnail_generator.genai.Client") as mock_client,
+            patch("app.tools.thumbnail_generator.Image.open") as mock_image_open,
+            patch(
+                "app.tools.thumbnail_generator.mimetypes.guess_type"
+            ) as mock_guess_type,
+            patch("builtins.open", mock_open(read_data=b"fake image data")),
+        ):
+
+            # Test with JPEG MIME type
+            mock_guess_type.return_value = ("image/jpeg", None)
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_candidate = Mock()
+            mock_content = Mock()
+            mock_part = Mock()
+            mock_inline_data = Mock()
+            mock_inline_data.data = b"fake generated image data"
+            mock_part.inline_data = mock_inline_data
+            mock_content.parts = [mock_part]
+            mock_candidate.content = mock_content
+            mock_response.candidates = [mock_candidate]
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            mock_image = Mock()
+            mock_image.convert.return_value = mock_image
+            mock_image_open.return_value = mock_image
+
+            result = thumbnail_generator(temp_image_file, "summary")
+
+            assert os.path.isabs(result)
+            # Verify MIME type was used
+            mock_guess_type.assert_called_once()

tests/test_video_clipper.py

@@ -0,0 +1,235 @@
+"""
+Unit tests for video_clipper tool.
+"""
+
+import os
+import tempfile
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+import sys
+
+# Add src to path to import modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from app.tools.video_clipper import video_clipper
+
+
+class TestVideoClipper:
+    """Test cases for video_clipper function."""
+
+    def test_video_clipper_with_tuple_input(self, temp_video_file, mock_video_duration):
+        """Test video_clipper with tuple input (Gradio format)."""
+        with patch("app.tools.video_clipper.VideoFileClip") as mock_video_clip:
+            mock_video = Mock()
+            mock_video.duration = mock_video_duration
+            mock_clipped = Mock()
+            mock_video.subclipped.return_value = mock_clipped
+            mock_video_clip.return_value = mock_video
+
+            video_input = (temp_video_file, "subtitle.srt")
+            start_time = 0.0
+            end_time = 10.0
+            output_path = tempfile.mktemp(suffix=".mp4")
+
+            result = video_clipper(video_input, start_time, end_time, output_path)
+
+            assert os.path.isabs(result)
+            assert result == os.path.abspath(output_path)
+            mock_video_clip.assert_called_once_with(temp_video_file)
+
+    def test_video_clipper_without_output_path(
+        self, temp_video_file, mock_video_duration
+    ):
+        """Test video_clipper generates output path when not provided."""
+        with patch("app.tools.video_clipper.VideoFileClip") as mock_video_clip:
+            mock_video = Mock()
+            mock_video.duration = mock_video_duration
+            mock_clipped = Mock()
+            mock_video.subclipped.return_value = mock_clipped
+            mock_video_clip.return_value = mock_video
+
+            start_time = 2.5
+            end_time = 7.5
+
+            result = video_clipper(temp_video_file, start_time, end_time)
+
+            assert os.path.isabs(result)
+            assert result.endswith(".mp4")  # Verify extension preserved
+            assert "clipped" in result.lower() or os.path.basename(result).startswith(
+                "clipped_"
+            )
+            mock_clipped.write_videofile.assert_called_once()
+
+    def test_video_clipper_invalid_input_format(self):
+        """Test video_clipper with invalid input format."""
+        with pytest.raises(Exception) as exc_info:
+            video_clipper(123, 0.0, 10.0)  # Invalid input type
+
+        assert "Invalid video input format" in str(exc_info.value)
+
+    def test_video_clipper_file_not_found(self):
+        """Test video_clipper with non-existent file."""
+        with pytest.raises(Exception) as exc_info:
+            video_clipper("/nonexistent/video.mp4", 0.0, 10.0)
+
+        assert "Video file not found" in str(exc_info.value)
+
+    def test_video_clipper_negative_start_time(self, temp_video_file):
+        """Test video_clipper with negative start time."""
+        with pytest.raises(Exception) as exc_info:
+            video_clipper(temp_video_file, -1.0, 10.0)
+
+        assert "Start time must be >= 0" in str(exc_info.value)
+
+    def test_video_clipper_end_time_less_than_start(self, temp_video_file):
+        """Test video_clipper with end time less than start time."""
+        with pytest.raises(Exception) as exc_info:
+            video_clipper(temp_video_file, 10.0, 5.0)
+
+        assert "End time must be greater than start time" in str(exc_info.value)
+
+    def test_video_clipper_start_time_exceeds_duration(
+        self, temp_video_file, mock_video_duration
+    ):
+        """Test video_clipper when start time exceeds video duration."""
+        with patch("app.tools.video_clipper.VideoFileClip") as mock_video_clip:
+            mock_video = Mock()
+            mock_video.duration = mock_video_duration
+            mock_video_clip.return_value = mock_video
+
+            start_time = mock_video_duration + 10.0
+            end_time = mock_video_duration + 20.0
+
+            with pytest.raises(Exception) as exc_info:
+                video_clipper(temp_video_file, start_time, end_time)
+
+            assert "exceeds video duration" in str(exc_info.value)
+            # close() may be called multiple times in error handling, so just check it was called
+            assert mock_video.close.call_count >= 1
+
+    def test_video_clipper_end_time_clamped_to_duration(
+        self, temp_video_file, mock_video_duration
+    ):
+        """Test video_clipper clamps end_time to video duration."""
+        with patch("app.tools.video_clipper.VideoFileClip") as mock_video_clip:
+            mock_video = Mock()
+            mock_video.duration = mock_video_duration
+            mock_clipped = Mock()
+            mock_video.subclipped.return_value = mock_clipped
+            mock_video_clip.return_value = mock_video
+
+            start_time = 5.0
+            end_time = mock_video_duration + 10.0  # Exceeds duration
+            output_path = tempfile.mktemp(suffix=".mp4")
+
+            result = video_clipper(temp_video_file, start_time, end_time, output_path)
+
+            # Should clamp end_time to duration
+            mock_video.subclipped.assert_called_once_with(
+                start_time, mock_video_duration
+            )
+            assert os.path.isabs(result)
+
+    def test_video_clipper_creates_output_directory(
+        self, temp_video_file, temp_output_dir, mock_video_duration
+    ):
+        """Test video_clipper creates output directory if it doesn't exist."""
+        with patch("app.tools.video_clipper.VideoFileClip") as mock_video_clip:
+            mock_video = Mock()
+            mock_video.duration = mock_video_duration
+            mock_clipped = Mock()
+            mock_video.subclipped.return_value = mock_clipped
+            mock_video_clip.return_value = mock_video
+
+            output_dir = os.path.join(temp_output_dir, "nested", "path")
+            output_path = os.path.join(output_dir, "output.mp4")
+
+            result = video_clipper(temp_video_file, 0.0, 10.0, output_path)
+
+            assert os.path.exists(output_dir)
+            assert os.path.isabs(result)
+
+    def test_video_clipper_cleanup_on_error(self, temp_video_file, mock_video_duration):
+        """Test video_clipper properly cleans up resources on error."""
+        with patch("app.tools.video_clipper.VideoFileClip") as mock_video_clip:
+            mock_video = Mock()
+            mock_video.duration = mock_video_duration
+            mock_clipped = Mock()
+            mock_clipped.write_videofile.side_effect = Exception("Write error")
+            mock_video.subclipped.return_value = mock_clipped
+            mock_video_clip.return_value = mock_video
+
+            with pytest.raises(Exception) as exc_info:
+                video_clipper(temp_video_file, 0.0, 10.0)
+
+            assert "Error clipping video" in str(exc_info.value)
+            # Verify cleanup was attempted
+            mock_clipped.close.assert_called_once()
+            mock_video.close.assert_called_once()
+
+
+class TestVideoClipperIntegration:
+    """Integration tests for video_clipper using real video files."""
+
+    def test_video_clipper_real_video_basic_clip(
+        self, real_video_file, temp_output_dir
+    ):
+        """Test video_clipper with real video file - basic clipping."""
+        output_path = os.path.join(temp_output_dir, "clipped_output.mp4")
+        start_time = 1.0
+        end_time = 3.0
+
+        result = video_clipper(real_video_file, start_time, end_time, output_path)
+
+        # Assertions
+        assert os.path.exists(result), f"Clipped video file should exist at {result}"
+        assert os.path.isabs(result)
+        assert result == os.path.abspath(output_path)
+        assert os.path.getsize(result) > 0, "Clipped video should have content"
+
+    def test_video_clipper_real_video_short_clip(
+        self, real_video_file, temp_output_dir
+    ):
+        """Test video_clipper with real video file - very short clip."""
+        output_path = os.path.join(temp_output_dir, "short_clip.mp4")
+        start_time = 0.0
+        end_time = 0.5  # Half second clip
+
+        result = video_clipper(real_video_file, start_time, end_time, output_path)
+
+        assert os.path.exists(result)
+        assert os.path.getsize(result) > 0
+
+    def test_video_clipper_real_video_validation(self, real_video_file):
+        """Test video_clipper validation with real video file."""
+        from moviepy import VideoFileClip
+
+        # Get actual video duration
+        with VideoFileClip(real_video_file) as video:
+            actual_duration = video.duration
+
+        # Test with invalid start time (exceeds duration)
+        with pytest.raises(Exception) as exc_info:
+            video_clipper(real_video_file, actual_duration + 1.0, actual_duration + 2.0)
+
+        assert "exceeds video duration" in str(exc_info.value)
+
+    def test_video_clipper_real_video_end_time_clamping(
+        self, real_video_file, temp_output_dir
+    ):
+        """Test video_clipper clamps end_time to video duration with real video."""
+        from moviepy import VideoFileClip
+
+        # Get actual video duration
+        with VideoFileClip(real_video_file) as video:
+            actual_duration = video.duration
+
+        output_path = os.path.join(temp_output_dir, "clamped_output.mp4")
+        start_time = max(0.0, actual_duration - 2.0)  # Start 2 seconds before end
+        end_time = actual_duration + 10.0  # End time exceeds duration
+
+        # Should not raise error, should clamp end_time
+        result = video_clipper(real_video_file, start_time, end_time, output_path)
+
+        assert os.path.exists(result)
+        assert os.path.getsize(result) > 0

tests/test_video_composer.py

@@ -0,0 +1,393 @@
+"""
+Unit tests for video_composer tool.
+"""
+
+import os
+import json
+import tempfile
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+from pathlib import Path
+import sys
+
+# Add src to path to import modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from app.tools.video_composer import video_composer
+
+
+class TestVideoComposer:
+    """Test cases for video_composer function."""
+
+    @pytest.fixture
+    def sample_script(self):
+        """Sample script JSON for testing."""
+        return {
+            "total_duration": 30.0,
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": 0,  # Reference first video by index
+                    "start_time": 0.0,
+                    "end_time": 5.0,
+                    "duration": 5.0,
+                    "transition_in": "fade",
+                    "transition_out": "crossfade",
+                },
+                {
+                    "scene_id": 2,
+                    "source_video": 1,  # Reference second video by index
+                    "start_time": 10.0,
+                    "end_time": 15.0,
+                    "duration": 5.0,
+                    "transition_in": "crossfade",
+                    "transition_out": "cut",
+                },
+            ],
+            "music": {"mood": "energetic", "bpm": 120, "volume": 0.5},
+        }
+
+    @pytest.fixture
+    def sample_script_json(self, sample_script):
+        """Sample script as JSON string."""
+        return json.dumps(sample_script)
+
+    def test_video_composer_missing_scenes_key(self, temp_output_dir):
+        """Test video_composer with script missing 'scenes' key."""
+        invalid_script = {"total_duration": 30.0}
+        clip1_path = os.path.join(temp_output_dir, "clip1.mp4")
+        Path(clip1_path).touch()
+
+        with pytest.raises(Exception) as exc_info:
+            video_composer(invalid_script, video_clips=[clip1_path])
+
+        assert "Script must contain a 'scenes' key" in str(exc_info.value)
+
+    def test_video_composer_empty_scenes(self, temp_output_dir):
+        """Test video_composer with empty scenes list."""
+        invalid_script = {"scenes": []}
+        clip1_path = os.path.join(temp_output_dir, "clip1.mp4")
+        Path(clip1_path).touch()
+
+        with pytest.raises(Exception) as exc_info:
+            video_composer(invalid_script, video_clips=[clip1_path])
+
+        assert "Script must contain at least one scene" in str(exc_info.value)
+
+    def test_video_composer_invalid_source_video_index(
+        self, sample_script, temp_output_dir
+    ):
+        """Test video_composer with invalid source_video index."""
+        clip1_path = os.path.join(temp_output_dir, "clip1.mp4")
+        Path(clip1_path).touch()
+
+        # Update script to use index 2 (out of range for single video)
+        sample_script["scenes"][0]["source_video"] = 2
+
+        with pytest.raises(Exception) as exc_info:
+            video_composer(sample_script, video_clips=[clip1_path])
+
+        assert "source_video index" in str(exc_info.value)
+        assert "out of range" in str(exc_info.value)
+
+    def test_video_composer_missing_source_video(self, temp_output_dir):
+        """Test video_composer with scene missing source_video."""
+        script = {
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "start_time": 0.0,
+                    "end_time": 5.0,
+                }
+            ]
+        }
+        clip1_path = os.path.join(temp_output_dir, "clip1.mp4")
+        Path(clip1_path).touch()
+
+        with pytest.raises(Exception) as exc_info:
+            video_composer(script, video_clips=[clip1_path])
+
+        assert "missing 'source_video'" in str(exc_info.value)
+
+    def test_video_composer_source_video_not_found(self, temp_output_dir):
+        """Test video_composer with source_video filename not found in video_clips."""
+        script = {
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": "nonexistent.mp4",
+                    "start_time": 0.0,
+                    "end_time": 5.0,
+                }
+            ]
+        }
+        clip1_path = os.path.join(temp_output_dir, "clip1.mp4")
+        Path(clip1_path).touch()
+
+        with pytest.raises(Exception) as exc_info:
+            video_composer(script, video_clips=[clip1_path])
+
+        assert "source_video" in str(exc_info.value)
+        assert "not found in video_clips" in str(exc_info.value)
+
+    def test_video_composer_clip_not_found(self, sample_script, temp_output_dir):
+        """Test video_composer with non-existent clip file in video_clips."""
+        nonexistent_clip = os.path.join(temp_output_dir, "nonexistent.mp4")
+        clip1_path = os.path.join(temp_output_dir, "clip1.mp4")
+        Path(clip1_path).touch()
+
+        with pytest.raises(Exception) as exc_info:
+            video_composer(sample_script, video_clips=[clip1_path, nonexistent_clip])
+
+        assert "Video clip not found" in str(exc_info.value)
+
+
+class TestVideoComposerIntegration:
+    """Integration tests for video_composer using real video files."""
+
+    def test_video_composer_real_video_basic_composition(
+        self, real_video_file, temp_output_dir
+    ):
+        """Test video_composer with real video file - basic composition."""
+        script = {
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": 0,  # Reference first video by index
+                    "start_time": 0.0,
+                    "end_time": 2.0,
+                    "duration": 2.0,
+                    "transition_in": "cut",
+                    "transition_out": "fade",
+                },
+                {
+                    "scene_id": 2,
+                    "source_video": 0,  # Same video, different time range
+                    "start_time": 2.0,
+                    "end_time": 4.0,
+                    "duration": 2.0,
+                    "transition_in": "fade",
+                    "transition_out": "cut",
+                },
+            ]
+        }
+
+        output_path = os.path.join(temp_output_dir, "composed_output.mp4")
+
+        result = video_composer(
+            script, video_clips=[real_video_file], output_path=output_path
+        )
+
+        # Assertions
+        assert os.path.exists(result), f"Composed video file should exist at {result}"
+        assert os.path.isabs(result)
+        assert result == os.path.abspath(output_path)
+        assert os.path.getsize(result) > 0, "Composed video should have content"
+
+    def test_video_composer_real_video_with_preclipped(
+        self, real_video_file, temp_output_dir
+    ):
+        """Test video_composer with real video using pre-clipped clips."""
+        from app.tools.video_clipper import video_clipper
+
+        # Create pre-clipped videos
+        clip1_path = os.path.join(temp_output_dir, "clip1.mp4")
+        clip2_path = os.path.join(temp_output_dir, "clip2.mp4")
+
+        video_clipper(real_video_file, 0.0, 2.0, clip1_path)
+        video_clipper(real_video_file, 2.0, 4.0, clip2_path)
+
+        script = {
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": 0,  # Reference first video
+                    "start_time": 0.0,
+                    "end_time": 2.0,
+                    "transition_in": "cut",
+                    "transition_out": "fade",
+                },
+                {
+                    "scene_id": 2,
+                    "source_video": 1,  # Reference second video
+                    "start_time": 0.0,
+                    "end_time": 2.0,
+                    "transition_in": "fade",
+                    "transition_out": "cut",
+                },
+            ]
+        }
+
+        output_path = os.path.join(temp_output_dir, "composed_preclipped.mp4")
+
+        result = video_composer(
+            script,
+            video_clips=[clip1_path, clip2_path],
+            output_path=output_path,
+        )
+
+        assert os.path.exists(result)
+        assert os.path.getsize(result) > 0
+
+    def test_video_composer_real_video_crossfade(
+        self, real_video_file, temp_output_dir
+    ):
+        """Test video_composer with real video using crossfade transitions."""
+        script = {
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": 0,  # Reference first video by index
+                    "start_time": 0.0,
+                    "end_time": 1.5,
+                    "transition_in": "cut",
+                    "transition_out": "crossfade",
+                },
+                {
+                    "scene_id": 2,
+                    "source_video": 0,  # Same video, different time range
+                    "start_time": 1.5,
+                    "end_time": 3.0,
+                    "transition_in": "crossfade",
+                    "transition_out": "cut",
+                },
+            ]
+        }
+
+        output_path = os.path.join(temp_output_dir, "composed_crossfade.mp4")
+
+        result = video_composer(
+            script, video_clips=[real_video_file], output_path=output_path
+        )
+
+        assert os.path.exists(result)
+        assert os.path.getsize(result) > 0
+
+    def test_video_composer_multiple_source_videos(
+        self, real_video_file, real_video_file_2, temp_output_dir
+    ):
+        """Test video_composer composing from multiple different source videos."""
+        script = {
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": 0,  # Reference first video by index
+                    "start_time": 0.0,
+                    "end_time": 2.0,
+                    "duration": 2.0,
+                    "transition_in": "fade",
+                    "transition_out": "crossfade",
+                },
+                {
+                    "scene_id": 2,
+                    "source_video": 1,  # Reference second video by index
+                    "start_time": 0.0,
+                    "end_time": 2.0,
+                    "duration": 2.0,
+                    "transition_in": "crossfade",
+                    "transition_out": "fade",
+                },
+            ]
+        }
+
+        output_path = os.path.join(temp_output_dir, "composed_multiple_sources.mp4")
+
+        result = video_composer(
+            script,
+            video_clips=[real_video_file, real_video_file_2],
+            output_path=output_path,
+        )
+
+        assert os.path.exists(result)
+        assert os.path.isabs(result)
+        assert result == os.path.abspath(output_path)
+        assert os.path.getsize(result) > 0
+
+    def test_video_composer_real_video_with_second_file_preclipped(
+        self, real_video_file, real_video_file_2, temp_output_dir
+    ):
+        """Test video_composer with clips from both video files."""
+        from app.tools.video_clipper import video_clipper
+
+        # Create pre-clipped videos from both sources
+        clip1_path = os.path.join(temp_output_dir, "clip1_from_dodo1.mp4")
+        clip2_path = os.path.join(temp_output_dir, "clip2_from_dodo2.mp4")
+
+        video_clipper(real_video_file, 0.0, 2.0, clip1_path)
+        video_clipper(real_video_file_2, 0.0, 2.0, clip2_path)
+
+        script = {
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": 0,  # Reference first video
+                    "start_time": 0.0,
+                    "end_time": 2.0,
+                    "transition_in": "cut",
+                    "transition_out": "crossfade",
+                },
+                {
+                    "scene_id": 2,
+                    "source_video": 1,  # Reference second video
+                    "start_time": 0.0,
+                    "end_time": 2.0,
+                    "transition_in": "crossfade",
+                    "transition_out": "cut",
+                },
+            ]
+        }
+
+        output_path = os.path.join(temp_output_dir, "composed_two_sources.mp4")
+
+        result = video_composer(
+            script,
+            video_clips=[clip1_path, clip2_path],
+            output_path=output_path,
+        )
+
+        assert os.path.exists(result)
+        assert os.path.getsize(result) > 0
+
+    def test_video_composer_real_video_three_scenes_from_two_files(
+        self, real_video_file, real_video_file_2, temp_output_dir
+    ):
+        """Test video_composer with three scenes from two different source videos."""
+        script = {
+            "scenes": [
+                {
+                    "scene_id": 1,
+                    "source_video": 0,  # Reference first video by index
+                    "start_time": 0.0,
+                    "end_time": 1.5,
+                    "transition_in": "fade",
+                    "transition_out": "crossfade",
+                },
+                {
+                    "scene_id": 2,
+                    "source_video": 1,  # Reference second video by index
+                    "start_time": 0.0,
+                    "end_time": 1.5,
+                    "transition_in": "crossfade",
+                    "transition_out": "crossfade",
+                },
+                {
+                    "scene_id": 3,
+                    "source_video": 0,  # Reference first video again, different time range
+                    "start_time": 1.5,
+                    "end_time": 3.0,
+                    "transition_in": "crossfade",
+                    "transition_out": "fade",
+                },
+            ]
+        }
+
+        output_path = os.path.join(temp_output_dir, "composed_three_scenes.mp4")
+
+        result = video_composer(
+            script,
+            video_clips=[real_video_file, real_video_file_2],
+            output_path=output_path,
+        )
+
+        assert os.path.exists(result)
+        assert os.path.getsize(result) > 0

tests/test_video_summarizer.py

@@ -0,0 +1,295 @@
+"""
+Unit tests for video_summarizer tool.
+"""
+
+import os
+import json
+import pytest
+from unittest.mock import Mock, patch, MagicMock
+import sys
+
+# Add src to path to import modules
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from app.tools.video_summarizer import video_summarizer
+
+
+class TestVideoSummarizer:
+    """Test cases for video_summarizer function."""
+
+    def test_video_summarizer_with_tuple_input(self, temp_video_file):
+        """Test video_summarizer with tuple input (Gradio format)."""
+        with (
+            patch("app.tools.video_summarizer.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.video_summarizer.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = "Test summary"
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            video_input = (temp_video_file, "subtitle.srt")
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = video_summarizer(video_input, fps=2.0)
+
+            result_json = json.loads(result)
+            assert "summary" in result_json
+
+    def test_video_summarizer_invalid_input_format(self):
+        """Test video_summarizer with invalid input format."""
+        result = video_summarizer(123, fps=2.0)
+        result_json = json.loads(result)
+        assert "error" in result_json
+        assert "Invalid video input format" in result_json["error"]
+
+    def test_video_summarizer_file_not_found(self):
+        """Test video_summarizer with non-existent file."""
+        result = video_summarizer("/nonexistent/video.mp4", fps=2.0)
+        result_json = json.loads(result)
+        assert "error" in result_json
+        assert "Video file not found" in result_json["error"]
+
+    def test_video_summarizer_cannot_open_video(self, temp_video_file):
+        """Test video_summarizer when video cannot be opened."""
+        with patch("app.tools.video_summarizer.cv2.VideoCapture") as mock_capture:
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = False
+            mock_capture.return_value = mock_cap
+
+            result = video_summarizer(temp_video_file, fps=2.0)
+            result_json = json.loads(result)
+
+            assert "error" in result_json
+            assert "Could not open video file" in result_json["error"]
+
+    def test_video_summarizer_no_api_key(self, temp_video_file):
+        """Test video_summarizer without API key (fallback mode)."""
+        with patch("app.tools.video_summarizer.cv2.VideoCapture") as mock_capture:
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            with patch.dict(os.environ, {}, clear=True):
+                result = video_summarizer(temp_video_file, fps=2.0)
+
+            result_json = json.loads(result)
+
+            assert "duration" in result_json
+            assert "summary" in result_json
+            assert "Video analysis requires GOOGLE_API_KEY" in result_json["summary"]
+            assert result_json["mood_tags"] == []
+
+    def test_video_summarizer_extracts_mood_tags(self, temp_video_file):
+        """Test video_summarizer extracts mood tags from summary."""
+        with (
+            patch("app.tools.video_summarizer.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.video_summarizer.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            # Include mood keywords in summary
+            mock_response.text = "This is an energetic and fast-paced video with bright colors and fun activities."
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = video_summarizer(temp_video_file, fps=2.0)
+
+            result_json = json.loads(result)
+
+            assert "mood_tags" in result_json
+            assert isinstance(result_json["mood_tags"], list)
+            # Should detect some mood tags
+            assert len(result_json["mood_tags"]) > 0
+
+    def test_video_summarizer_default_mood_tags(self, temp_video_file):
+        """Test video_summarizer uses default mood tag when none detected."""
+        with (
+            patch("app.tools.video_summarizer.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.video_summarizer.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            # Summary without mood keywords
+            mock_response.text = (
+                "This is a regular video without specific mood indicators."
+            )
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = video_summarizer(temp_video_file, fps=2.0)
+
+            result_json = json.loads(result)
+
+            assert "mood_tags" in result_json
+            assert result_json["mood_tags"] == ["general"]
+
+    def test_video_summarizer_custom_fps(self, temp_video_file):
+        """Test video_summarizer with custom fps parameter."""
+        with (
+            patch("app.tools.video_summarizer.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.video_summarizer.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 30.0,
+                7: 900,
+                3: 1920,
+                4: 1080,
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = "Test summary"
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = video_summarizer(temp_video_file, fps=5.0)
+
+            result_json = json.loads(result)
+            assert "summary" in result_json
+
+            # Verify fps was passed to VideoMetadata
+            call_args = mock_genai_client.models.generate_content.call_args
+            assert call_args is not None
+
+    def test_video_summarizer_error_handling(self, temp_video_file):
+        """Test video_summarizer handles exceptions gracefully."""
+        with patch("app.tools.video_summarizer.cv2.VideoCapture") as mock_capture:
+            mock_cap = Mock()
+            mock_cap.isOpened.side_effect = Exception("Unexpected error")
+            mock_capture.return_value = mock_cap
+
+            result = video_summarizer(temp_video_file, fps=2.0)
+            result_json = json.loads(result)
+
+            assert "error" in result_json
+            assert "Error processing video" in result_json["error"]
+
+    def test_video_summarizer_metadata_extraction(self, temp_video_file):
+        """Test video_summarizer extracts correct metadata."""
+        with (
+            patch("app.tools.video_summarizer.cv2.VideoCapture") as mock_capture,
+            patch("app.tools.video_summarizer.genai.Client") as mock_client,
+        ):
+
+            mock_cap = Mock()
+            mock_cap.isOpened.return_value = True
+            mock_cap.get.side_effect = lambda prop: {
+                5: 24.0,  # FPS
+                7: 720,  # Frame count
+                3: 1280,  # Width
+                4: 720,  # Height
+            }.get(prop, 0)
+            mock_capture.return_value = mock_cap
+
+            mock_genai_client = Mock()
+            mock_response = Mock()
+            mock_response.text = "Test summary"
+            mock_genai_client.models.generate_content.return_value = mock_response
+            mock_client.return_value = mock_genai_client
+
+            with patch.dict(os.environ, {"GOOGLE_API_KEY": "test_key"}):
+                result = video_summarizer(temp_video_file, fps=2.0)
+
+            result_json = json.loads(result)
+
+            assert result_json["fps"] == 24.0
+            assert result_json["frame_count"] == 720
+            assert result_json["resolution"] == "1280x720"
+            assert result_json["duration"] == pytest.approx(
+                30.0, rel=0.1
+            )  # 720/24 = 30
+
+
+class TestVideoSummarizerIntegration:
+    """Integration tests for video_summarizer using real video files."""
+
+    def test_video_summarizer_real_video_basic(self, real_video_file):
+        """Test video_summarizer with real video file - basic functionality."""
+        result = video_summarizer(real_video_file, fps=2.0)
+        result_json = json.loads(result)
+
+        # Should return valid JSON with metadata
+        assert "duration" in result_json
+        assert "resolution" in result_json
+        assert "fps" in result_json
+        assert "frame_count" in result_json
+        assert isinstance(result_json["duration"], (int, float))
+        assert result_json["duration"] > 0
+
+    def test_video_summarizer_real_video_no_api_key(self, real_video_file):
+        """Test video_summarizer with real video file without API key (fallback mode)."""
+        with patch.dict(os.environ, {}, clear=True):
+            result = video_summarizer(real_video_file, fps=2.0)
+
+        result_json = json.loads(result)
+
+        # Should still return metadata even without API key
+        assert "duration" in result_json
+        assert "resolution" in result_json
+        assert "summary" in result_json
+        assert "Video analysis requires GOOGLE_API_KEY" in result_json["summary"]
+        assert result_json["mood_tags"] == []
+
+    @pytest.mark.skipif(
+        not os.getenv("GOOGLE_API_KEY"),
+        reason="GOOGLE_API_KEY not set, skipping API test",
+    )
+    def test_video_summarizer_real_video_with_api(self, real_video_file):
+        """Test video_summarizer with real video file and API key (if available)."""
+        result = video_summarizer(real_video_file, fps=2.0)
+        result_json = json.loads(result)
+
+        # If API key is available, should get actual summary
+        if "error" not in result_json:
+            assert "summary" in result_json
+            assert len(result_json["summary"]) > 0
+            assert "mood_tags" in result_json
+            assert isinstance(result_json["mood_tags"], list)