mcp-video-editor/README.md

# MCP Video Editor

Professional video production tools for the Model Context Protocol (MCP), designed to create high-quality marketing demo videos and enhance existing Playwright video recording capabilities.

## Overview

This MCP server provides comprehensive video editing and processing tools specifically designed for creating professional marketing videos, such as the InterNACHI expert agent demonstration videos. It addresses the limitations of existing Playwright MCP video recording tools by providing persistent recording sessions, reliable file generation, and advanced post-production capabilities.

## Features

### 📹 Core Video Recording & Capture
- **Persistent Recording Sessions**: Reliable video capture with session tracking
- **Multiple Format Support**: MP4, WebM, MOV, AVI output formats  
- **Quality Control**: Configurable resolution, framerate, and compression settings
- **Region Capture**: Record specific screen areas or full screen

### 🎞️ Video Editing & Post-Production
- **Concatenation**: Join multiple video clips with smooth transitions
- **Trimming**: Precise video segment cutting and timing control
- **Speed Control**: Adjust playback speed for specific segments or entire videos
- **Format Conversion**: Export to multiple formats with quality optimization

### 🎨 Visual Enhancement & Graphics
- **Text Overlays**: Add professional titles, callouts, and annotations
- **Logo Branding**: Consistent brand element application with positioning control
- **Resolution Optimization**: Generate multiple resolution versions for web delivery

### 🔊 Audio Production & Enhancement
- **Multi-track Mixing**: Combine multiple audio sources with volume control
- **Audio-Video Sync**: Synchronize narration and background audio with video timeline
- **Audio Replacement**: Replace or mix with existing video audio

## Installation

### Prerequisites
- Python 3.9+
- FFmpeg installed on system
- UV package manager (recommended)

### Install with UV
```bash
# Clone the repository
git clone <repository-url>
cd mcp-video-editor

# Install with UV
uv install

# Or install in development mode
uv install -e ".[dev]"
```

### Install with Pip
```bash
pip install -e .
```

## Usage

### Running the MCP Server

```bash
# Start the server
mcp-video-editor

# Or run directly
python -m mcp_video_editor
```

### Example MCP Tool Usage

#### Basic Video Recording
```python
# Start recording session
result = mcp_video_recorder_start(
    filename="demo.mp4",
    resolution="1920x1080", 
    framerate=30
)
session_id = result["session_id"]

# Stop recording
final_result = mcp_video_recorder_stop(session_id)
print(f"Video saved to: {final_result['output_path']}")
```

#### Video Editing Workflow
```python
# Concatenate multiple clips
mcp_video_concatenate(
    input_clips=["intro.mp4", "demo.mp4", "outro.mp4"],
    output_path="final_demo.mp4",
    transition_type="fade"
)

# Add text overlay
mcp_video_add_overlay(
    input_path="final_demo.mp4",
    output_path="branded_demo.mp4",
    overlay_type="text",
    text="InterNACHI Expert Agent Demo",
    position="center",
    style={"fontsize": 60, "color": "white"}
)

# Add branding
mcp_video_add_branding(
    input_path="branded_demo.mp4",
    output_path="final_output.mp4",
    logo_path="internachi_logo.png",
    position="bottom-right",
    opacity=0.8
)
```

#### Multi-Resolution Export
```python
# Generate web-optimized versions
mcp_video_resolution_optimizer(
    input_path="final_output.mp4",
    output_directory="./web_versions",
    target_resolutions=["1080p", "720p", "480p"]
)
```

## Available MCP Tools

### Recording Tools
- `mcp_video_recorder_start` - Start persistent recording session
- `mcp_video_recorder_stop` - Stop recording and save file

### Editing Tools  
- `mcp_video_concatenate` - Join multiple video clips
- `mcp_video_trim` - Cut video segments precisely
- `mcp_video_speed_control` - Adjust playback speed

### Enhancement Tools
- `mcp_video_add_overlay` - Add text, graphics, and annotations
- `mcp_video_add_branding` - Apply consistent brand elements
- `mcp_video_format_convert` - Export to different formats

### Audio Tools
- `mcp_audio_mix_tracks` - Combine multiple audio sources
- `mcp_audio_sync_video` - Sync audio with video timeline

### Optimization Tools
- `mcp_video_resolution_optimizer` - Generate multiple resolution versions

## Use Cases

### InterNACHI Expert Agent Demo Video
This tool was specifically designed to address the needs of creating professional marketing videos for the InterNACHI expert agent system:

1. **Record Demo Interactions** - Capture clean browser interactions with the expert agent system
2. **Edit and Enhance** - Add professional titles, callouts, and branding
3. **Multi-Format Export** - Generate web-optimized versions for different platforms
4. **Professional Polish** - Apply consistent branding and smooth transitions

### General Video Production
- Marketing demo videos
- Product walkthroughs  
- Training and educational content
- Social media video content
- Professional presentations

## Development

### Setup Development Environment
```bash
# Install with development dependencies
uv install -e ".[dev]"

# Run linting
ruff check mcp_video_editor/

# Run formatting
ruff format mcp_video_editor/
```

### Testing
```bash
# Run tests
pytest
```

## Configuration

The server can be configured through environment variables:

- `VIDEO_OUTPUT_DIR` - Default directory for video outputs (default: `./temp_videos`)
- `AUDIO_OUTPUT_DIR` - Default directory for audio outputs (default: `./temp_audio`)
- `MAX_VIDEO_DURATION` - Maximum video duration in seconds (default: 3600)

## Architecture

Built using:
- **FastMCP** - High-level MCP server framework
- **MoviePy** - Video editing and processing
- **OpenCV** - Video capture and computer vision
- **FFmpeg** - Video encoding and format conversion

## License

MIT License - See LICENSE file for details.

## Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

## Support

For issues and questions:
- Open an issue on GitHub
- Check the documentation at [FastMCP docs](https://gofastmcp.com)

---

*Built for professional video production in the Model Context Protocol ecosystem.*