Ryan Malloy
d635bbc3e5
Features: - Professional video recording with session management - Multi-clip concatenation with transitions - Video trimming, speed control, and overlay support - Audio mixing and video-audio synchronization - Branding and logo overlay capabilities - Multi-resolution export optimization - Format conversion with quality presets - Startup script for easy MCP client integration Built with FastMCP 2.0, MoviePy, and modern Python tooling
288 lines
12 KiB
Markdown
288 lines
12 KiB
Markdown
# MCP Video Editor Project
|
|
|
|
This project defines the MCP (Model Context Protocol) tools needed for professional video production and editing, specifically designed to create marketing demo videos like the InterNACHI expert agent demonstration.
|
|
|
|
## Project Overview
|
|
|
|
The goal is to create a comprehensive set of MCP tools that enable Claude to:
|
|
1. Record high-quality demo videos using browser interactions
|
|
2. Edit and enhance recorded clips with professional effects
|
|
3. Produce polished marketing videos suitable for website use
|
|
4. Work seamlessly with existing Playwright MCP recording capabilities
|
|
|
|
## Current Challenge
|
|
|
|
While developing a marketing demo for the InterNACHI expert agent system (https://l.inspect.pics), we encountered limitations with the existing Playwright MCP video recording tools:
|
|
|
|
- Recording sessions don't persist between browser actions
|
|
- Video files are not being generated despite successful recording setup
|
|
- Limited control over video quality and post-production enhancements
|
|
|
|
## Required MCP Tools for Professional Video Production
|
|
|
|
### 📹 **Core Video Recording & Capture**
|
|
|
|
#### `mcp_video_recorder_start`
|
|
- **Purpose**: Reliable video capture with persistent recording sessions
|
|
- **Parameters**:
|
|
- `filename`: Video output filename
|
|
- `resolution`: Recording resolution (1920x1080, 1280x720, etc.)
|
|
- `framerate`: Recording framerate (30fps, 60fps)
|
|
- `region`: Optional screen region to capture
|
|
- **Returns**: Recording session ID for tracking
|
|
|
|
#### `mcp_video_recorder_stop`
|
|
- **Purpose**: Stop recording and ensure file is saved
|
|
- **Parameters**: `session_id`
|
|
- **Returns**: File path and recording statistics
|
|
|
|
#### `mcp_video_screen_capture`
|
|
- **Purpose**: Capture specific UI regions or full screen
|
|
- **Parameters**: Region coordinates, output format
|
|
- **Use Case**: Record focused sections (chat interface only)
|
|
|
|
#### `mcp_video_multi_clip_recorder`
|
|
- **Purpose**: Record multiple separate segments for later editing
|
|
- **Parameters**: Clip naming scheme, auto-segmentation rules
|
|
- **Use Case**: Record different demo sections separately
|
|
|
|
### 🎞️ **Video Editing & Post-Production**
|
|
|
|
#### `mcp_video_concatenate`
|
|
- **Purpose**: Join multiple video clips into single file
|
|
- **Parameters**:
|
|
- `input_clips`: Array of video file paths
|
|
- `transition_type`: Cut, fade, dissolve, etc.
|
|
- `output_path`: Combined video output location
|
|
- **Use Case**: Combine demo segments into cohesive video
|
|
|
|
#### `mcp_video_trim`
|
|
- **Purpose**: Cut video segments to specific timeframes
|
|
- **Parameters**: Start time, end time, input/output paths
|
|
- **Use Case**: Remove unwanted sections, create precise timing
|
|
|
|
#### `mcp_video_add_transitions`
|
|
- **Purpose**: Add smooth transitions between video segments
|
|
- **Parameters**: Transition type, duration, between which clips
|
|
- **Use Case**: Professional flow between demo sections
|
|
|
|
#### `mcp_video_speed_control`
|
|
- **Purpose**: Adjust playback speed for specific segments
|
|
- **Parameters**: Speed multiplier, time range, input file
|
|
- **Use Case**: Slow down complex interactions, speed up navigation
|
|
|
|
### 🎨 **Visual Enhancement & Graphics**
|
|
|
|
#### `mcp_video_add_overlay`
|
|
- **Purpose**: Add graphics, text, shapes over video content
|
|
- **Parameters**:
|
|
- `overlay_type`: Text, image, shape, arrow
|
|
- `position`: Screen coordinates
|
|
- `duration`: How long overlay appears
|
|
- `style`: Font, color, animation properties
|
|
- **Use Case**: Add professional titles, callouts, feature highlights
|
|
|
|
#### `mcp_video_add_annotations`
|
|
- **Purpose**: Add explanatory text and labels during playback
|
|
- **Parameters**: Text content, timing, positioning, styling
|
|
- **Use Case**: Explain InterNACHI features, highlight AI responses
|
|
|
|
#### `mcp_video_zoom_pan`
|
|
- **Purpose**: Add zoom and pan effects to focus on specific areas
|
|
- **Parameters**: Target coordinates, zoom level, animation duration
|
|
- **Use Case**: Focus attention on chat responses, button clicks
|
|
|
|
#### `mcp_video_highlight_cursor`
|
|
- **Purpose**: Emphasize mouse movements and clicks
|
|
- **Parameters**: Highlight color, click animation, trail effects
|
|
- **Use Case**: Make user interactions clearly visible
|
|
|
|
#### `mcp_video_callout_system`
|
|
- **Purpose**: Add professional callout bubbles and arrows
|
|
- **Parameters**: Callout text, arrow direction, target element
|
|
- **Use Case**: Point out key InterNACHI expert features
|
|
|
|
### 🔊 **Audio Production & Enhancement**
|
|
|
|
#### `mcp_audio_record_narration`
|
|
- **Purpose**: Record professional voiceover track
|
|
- **Parameters**: Audio quality settings, noise reduction
|
|
- **Use Case**: Add explanatory narration to demo video
|
|
|
|
#### `mcp_audio_mix_tracks`
|
|
- **Purpose**: Combine multiple audio tracks (narration + system sounds)
|
|
- **Parameters**: Audio files, volume levels, sync timing
|
|
- **Use Case**: Layer narration over system interaction sounds
|
|
|
|
#### `mcp_audio_sync_video`
|
|
- **Purpose**: Synchronize audio track with video timeline
|
|
- **Parameters**: Audio file, video file, sync points
|
|
- **Use Case**: Align narration with specific demo actions
|
|
|
|
#### `mcp_audio_add_background`
|
|
- **Purpose**: Add subtle background music or ambient sound
|
|
- **Parameters**: Music file, volume level, fade in/out
|
|
- **Use Case**: Professional soundtrack for marketing video
|
|
|
|
### 📊 **Content Enhancement & Branding**
|
|
|
|
#### `mcp_video_add_branding`
|
|
- **Purpose**: Apply consistent branding elements (logos, colors)
|
|
- **Parameters**: Brand assets, positioning rules, opacity
|
|
- **Use Case**: Add InterNACHI/inspect.pics branding throughout
|
|
|
|
#### `mcp_video_intro_outro`
|
|
- **Purpose**: Add professional opening and closing sequences
|
|
- **Parameters**: Brand templates, duration, text content
|
|
- **Use Case**: Bookend marketing video with branded sequences
|
|
|
|
#### `mcp_video_progress_indicators`
|
|
- **Purpose**: Show demo progression visually
|
|
- **Parameters**: Progress style, positioning, milestone markers
|
|
- **Use Case**: Guide viewers through multi-part demo
|
|
|
|
#### `mcp_video_screenshot_integration`
|
|
- **Purpose**: Insert high-quality stills between video segments
|
|
- **Parameters**: Screenshot files, display duration, transition
|
|
- **Use Case**: Show detailed UI elements between interactions
|
|
|
|
### 💻 **Technical Production & Export**
|
|
|
|
#### `mcp_video_format_convert`
|
|
- **Purpose**: Export to different video formats and qualities
|
|
- **Parameters**:
|
|
- `output_format`: MP4, WebM, MOV, etc.
|
|
- `quality_preset`: Web-optimized, high-quality, mobile, etc.
|
|
- `compression_level`: Balance file size vs quality
|
|
- **Use Case**: Create multiple versions for different platforms
|
|
|
|
#### `mcp_video_resolution_optimizer`
|
|
- **Purpose**: Generate multiple resolutions from source
|
|
- **Parameters**: Target resolutions, quality settings
|
|
- **Use Case**: Create 1080p, 720p, 480p versions for web
|
|
|
|
#### `mcp_video_batch_process`
|
|
- **Purpose**: Apply consistent styling across multiple clips
|
|
- **Parameters**: Style templates, processing queue
|
|
- **Use Case**: Maintain brand consistency across video series
|
|
|
|
### 📝 **Production Management & Workflow**
|
|
|
|
#### `mcp_video_storyboard_create`
|
|
- **Purpose**: Plan demo flow and timing
|
|
- **Parameters**: Scene descriptions, duration estimates, assets needed
|
|
- **Use Case**: Pre-plan InterNACHI demo structure
|
|
|
|
#### `mcp_video_asset_manager`
|
|
- **Purpose**: Organize and track video clips, images, audio files
|
|
- **Parameters**: Asset categorization, tagging system
|
|
- **Use Case**: Manage all components of video production
|
|
|
|
#### `mcp_video_preview_generate`
|
|
- **Purpose**: Create quick preview of edits before final render
|
|
- **Parameters**: Preview quality, specific time ranges
|
|
- **Use Case**: Review video before time-consuming final export
|
|
|
|
## InterNACHI Expert Agent Demo Requirements
|
|
|
|
### Specific Marketing Video Needs
|
|
|
|
#### **Demo Structure (2-3 minutes total)**
|
|
1. **Opening Sequence** (10 seconds)
|
|
- Professional title card with InterNACHI branding
|
|
- Platform introduction: "inspect.pics - Professional Inspection Platform"
|
|
|
|
2. **Platform Navigation** (20 seconds)
|
|
- Show clean onboarding flow
|
|
- Demonstrate inspection → area → item hierarchy
|
|
- Highlight professional UI design
|
|
|
|
3. **Expert Agent Showcase** (90 seconds)
|
|
- **Electrical Expert** (20s): Show GFCI, arc flash, NEC compliance guidance
|
|
- **Appliance Expert** (20s): Demonstrate safety hierarchies, gas system protocols
|
|
- **Structural Expert** (20s): Show load analysis, foundation defect recognition
|
|
- **Real-time Responses** (30s): Highlight professional AI formatting and InterNACHI terminology
|
|
|
|
4. **Feature Highlights** (20 seconds)
|
|
- Quick action buttons working smoothly
|
|
- Professional chat interface design
|
|
- Photo integration capabilities
|
|
|
|
5. **Professional Compliance** (20 seconds)
|
|
- Emphasize InterNACHI Standards of Practice integration
|
|
- Show safety-first approach
|
|
- Highlight three-function narrative methodology
|
|
|
|
6. **Call to Action** (10 seconds)
|
|
- Contact information and website URL
|
|
- Professional closing with branding
|
|
|
|
### Technical Specifications
|
|
|
|
#### **Video Quality Standards**
|
|
- **Resolution**: 1920x1080 (Full HD) primary, 1280x720 web-optimized
|
|
- **Framerate**: 30fps for smooth interface interactions
|
|
- **Audio**: 48kHz stereo with clear narration and subtle background music
|
|
- **File Size**: Under 50MB for web delivery, high-quality version available
|
|
|
|
#### **Visual Style Guidelines**
|
|
- **Colors**: Match inspect.pics brand palette
|
|
- **Fonts**: Professional, readable typography for annotations
|
|
- **Animations**: Smooth, purposeful transitions that enhance understanding
|
|
- **Branding**: Consistent InterNACHI and inspect.pics logo placement
|
|
|
|
#### **Content Requirements**
|
|
- **Professional Tone**: Serious, competent, trustworthy for B2B audience
|
|
- **Technical Accuracy**: All demonstrated features must work exactly as shown
|
|
- **Clear Narrative**: Logical flow from problem → solution → benefits
|
|
- **Compelling CTA**: Clear next steps for interested professional inspectors
|
|
|
|
## Implementation Priority
|
|
|
|
### Phase 1: Core Recording & Basic Editing
|
|
- Fix existing Playwright recording reliability
|
|
- Implement basic concatenation and trimming tools
|
|
- Add simple overlay and annotation capabilities
|
|
|
|
### Phase 2: Professional Enhancement
|
|
- Audio mixing and narration tools
|
|
- Advanced visual effects and transitions
|
|
- Branding and style consistency tools
|
|
|
|
### Phase 3: Production Management
|
|
- Workflow and asset management tools
|
|
- Batch processing and export optimization
|
|
- Advanced storyboarding and planning tools
|
|
|
|
## Success Metrics
|
|
|
|
A successful MCP video editor implementation should enable:
|
|
|
|
1. **Reliable Recording**: 100% success rate for video capture
|
|
2. **Professional Quality**: Broadcast-ready output suitable for marketing
|
|
3. **Efficient Workflow**: Complete video production in under 2 hours
|
|
4. **Consistent Branding**: Automated brand compliance across all outputs
|
|
5. **Multi-Format Export**: Optimized versions for web, social media, presentations
|
|
|
|
## Technical Architecture Notes
|
|
|
|
### Integration with Existing Tools
|
|
- Must work seamlessly with current Playwright MCP tools
|
|
- Should leverage existing screenshot and browser interaction capabilities
|
|
- Maintain consistency with existing MCP tool patterns and interfaces
|
|
|
|
### Performance Considerations
|
|
- Video processing can be resource-intensive
|
|
- Consider async operations for large file processing
|
|
- Provide progress indicators for long-running operations
|
|
- Optimize for common web video formats and compression
|
|
|
|
### File Management
|
|
- Clear artifact organization and cleanup
|
|
- Consistent file naming conventions
|
|
- Proper handling of temporary files during processing
|
|
- Reliable error handling and recovery mechanisms
|
|
|
|
---
|
|
|
|
*This specification provides the foundation for developing professional video production capabilities within the MCP ecosystem, specifically designed to support marketing and demonstration needs for complex software platforms like the InterNACHI expert agent system.* |