ClipForge - Desktop Video Editor

A professional desktop video editor built with Electron, React, and FFmpeg. Import videos, edit on a timeline, trim, split, and export to MP4.

🎯 Project Overview

ClipForge is a professional desktop video editor inspired by CapCut, built for the Gauntlet AI cohort challenge. It features industry-standard video and audio editing capabilities:

🎬 Core Video Features

• ✅ Video Import - Drag & drop or file picker (MP4, MOV, WebM)
• ✅ Image/Photo Import - Import images (JPG, PNG, WebP, GIF, BMP) and convert to video clips
• ✅ CapCut-style Timeline - Interactive timeline with adaptive zoom
• ✅ Clip Trimming - Drag white bars to trim in/out points
• ✅ Clip Splitting - Press S to split at playhead
• ✅ Clip Duplication - Ctrl/Cmd+D to duplicate clips
• ✅ Undo/Redo - Cmd+Z / Cmd+Shift+Z
• ✅ Video Preview - Playback with play/pause controls
• ✅ Screen Recording - Record screen with audio, auto-minimize to dock
• ✅ Webcam Recording - Record webcam with microphone
• ✅ Export to MP4 - Export your timeline composition
• ✅ Keyboard Shortcuts - Space (play/pause), Arrows (seek), S (split), Del (delete)

🎵 Advanced Audio Features

• ✅ Multi-track Audio - Separate audio tracks with independent controls
• ✅ Audio Waveform - Visual waveform representation for audio clips
• ✅ Audio Effects - Reverb, Echo, Distortion, EQ processing
• ✅ Volume Automation - Keyframes and curve editing for dynamic volume
• ✅ Audio Crossfade - Smooth transitions between overlapping clips
• ✅ Audio Normalization - Consistent volume levels across clips
• ✅ Audio Sync Tools - Manual offset adjustment for lip-sync
• ✅ Multi-track Mixing - Track-level volume, pan, mute, solo controls
• ✅ Master Controls - Global volume and mute for entire project

🎯 Professional Tools

• ✅ Project Save/Load - Save and reopen projects (.clipforge format)
• ✅ Auto-Save - Automatic project backup every 5 minutes with crash recovery
• ✅ Batch Operations - Apply effects to multiple clips simultaneously
• ✅ Multi-select - Ctrl/Cmd+click to select multiple clips
• ✅ Timeline Navigation - Frame-perfect navigation and zoom presets
• ✅ Mini Timeline - Overview of entire project with viewport indicator
• ✅ Text Overlays - Add customizable text with drag-to-position
• ✅ Video Effects - Brightness, contrast, saturation, blur, sharpen, grayscale, sepia, vintage filters
• ✅ Transitions - Fade, slide, zoom, blur effects between clips
• ✅ Clip Grouping - Group multiple clips to move them together as one unit
• ✅ Timeline Markers - Add bookmarks at important points for quick navigation
• ✅ Speed Control - Variable playback speed (0.25x to 4x)
• ✅ AI-Powered Tools - Smart video enhancement with OpenAI integration
  • Auto Captions generation
  • Content analysis and scene detection
  • AI color correction suggestions
  • Audio cleanup and enhancement
  • Workflow automation
  • Export settings optimization
• ✅ Smart Video Selection - Choose from media library or upload new videos for AI processing

🆕 Latest Updates

Image/Photo Support

• Image Import: Import photos and images (JPG, PNG, WebP, GIF, BMP) into your project
• Custom Duration: Set how long each image should display (default 3 seconds)
• Image-to-Video Conversion: Images are automatically converted to video clips using FFmpeg
• Drag & Drop: Drop images directly into the media library
• Seamless Integration: Imported images work exactly like video clips on the timeline

Project Management & Auto-Save System

• Save Projects: Save your work as .clipforge project files for later editing
• Open Projects: Reopen saved projects and continue where you left off
• Auto-Save: Automatic backup every 5 minutes to protect your work
• Crash Recovery: Restore your project automatically if the app crashes
• Unsaved Changes Indicator: Visual indicator when your project has unsaved changes
• Recent Projects: Quick access to recently opened projects

Enter AI-Powered Tools with Smart Video Selection

• Intelligent Video Selection: When using AI tools, choose from existing media library videos or upload new ones
• Media Library Integration: AI tools automatically detect videos in your library and offer quick selection
• Auto Captions: Generate subtitles automatically using OpenAI Whisper
• Smart Analysis: AI-powered content analysis and scene detection
• Color Correction: AI-suggested color enhancements based on video content
• Audio Enhancement: Professional audio cleanup with noise reduction and normalization
• Workflow Automation: AI-driven editing workflow suggestions
• Export Optimization: AI-recommended export settings for best quality and file size

Professional Audio Editing Suite

• Multi-track Audio System: Complete audio editing with separate tracks
• Advanced Audio Effects: Professional-grade reverb, echo, distortion, and EQ
• Volume Automation: Keyframe-based volume curves for dynamic audio
• Audio Crossfade: Smooth transitions between overlapping audio clips
• Audio Normalization: Automatic volume leveling across all clips
• Lip-sync Tools: Manual offset adjustment for perfect audio-video sync

Enhanced Timeline & Navigation

• Professional Timeline: Frame-perfect navigation with zoom presets
• Mini Timeline Overview: Bird's-eye view of entire project
• Batch Operations: Multi-select and apply effects to multiple clips
• Enhanced Visual Feedback: Color-coded selection states and professional styling

Industry-Standard Features

• Master Audio Controls: Global volume and mute for entire project
• Track-level Mixing: Individual volume, pan, mute, and solo per track
• Professional UI/UX: Optimized layout with better space utilization
• Advanced Keyboard Shortcuts: Comprehensive hotkey support

🚀 Quick Start

Prerequisites

• Node.js 18+
• FFmpeg installed (brew install ffmpeg)
• macOS (for .app package)

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

Build

# Build for production
npm run build

# Package as macOS .app
npm run package

The packaged app will be in dist/ directory:

• ClipForge.app - macOS application (x64 & ARM64)
• ClipForge-1.0.0.dmg - Installer for Intel Macs
• ClipForge-1.0.0-arm64.dmg - Installer for Apple Silicon

📖 Usage Guide

Project Management

1. New Project: Click "New" button in header to start a fresh project
2. Save Project: Click "Save" (or "Save *" if you have unsaved changes) to save your project as a .clipforge file
3. Open Project: Click "Open" button to load a previously saved project
4. Auto-Save: Projects are automatically saved every 5 minutes in the background
5. Crash Recovery: If the app crashes, you'll be prompted to restore your auto-saved project on next launch

Import Media Files

1. Videos: Click "Import Video" or drag & drop video files (MP4, MOV, WebM)

   • Videos appear in Media Library with thumbnails
   • Clips automatically appear on Timeline Track 1

2. Images: Click "Import Image" or drag & drop image files (JPG, PNG, WebP, GIF, BMP)

   • Dialog prompts for display duration (default 3 seconds)
   • Images are converted to video clips automatically
   • Appear in Media Library and can be added to timeline like videos

3. Audio: Click "Import Audio" or drag & drop audio files

   • Audio clips appear in Media Library
   • Can be dragged to audio tracks on the timeline

Edit Timeline

• Trim: Select a clip, drag the thin white bars at the left/right edges to trim
• Move: Drag clips by clicking and dragging the center area to reposition
• Split: Position playhead and press S
• Delete: Select clip and press Del or click × button
• Group Clips: Select multiple clips (Cmd/Ctrl+click), then press Cmd/Ctrl+G or use Batch Operations panel to group them - grouped clips move together
• Add Markers: Click the marker button in timeline header to add a bookmark at playhead position
• Video Filters: Use the Video Effects section in RightSidebar to apply blur, sharpen, grayscale, sepia, or vintage effects

Playback

• Play/Pause: Space bar or click play button
• Seek: Left/Right arrows (1 second), or drag the red playhead
• Jump: Click anywhere on timeline

Zoom

• Mouse wheel: Ctrl+wheel to zoom in/out
• Buttons: +/- buttons in timeline header
• Adaptive: Timeline auto-fits to viewport

Recording

1. Click "Screen", "Webcam", or "Screen + Webcam" button
2. Screen recording: Select screen or window from picker
3. Audio: Toggle "Record Audio" checkbox for microphone
4. Click "Stop Recording" when done
5. Recording automatically appears in timeline

Note: App automatically minimizes to dock during screen recording to avoid capturing itself.

Export

1. Click "Export Video" in header
2. Choose save location
3. Wait for export to complete
4. Your video is ready!

AI-Powered Tools

1. Click "AI Tools" button in header
2. Select an AI feature (Captions, Analysis, Color Correction, etc.)
3. If you have videos in your media library:
   • A dialog appears showing available videos
   • Choose a video from your library OR click "Upload New Video"
4. If no videos in library, file picker opens directly
5. AI processes your video and displays results
6. Apply suggestions or use generated content in your project

⌨️ Keyboard Shortcuts

Key	Action
Space	Play/Pause
Left/Right	Seek 1 second
Home	Go to start
S	Split clip at playhead
Cmd+Z	Undo
Cmd+Shift+Z	Redo
Delete	Delete selected clip
Cmd+G	Group/Ungroup selected clips
Cmd+S	Save Project (via Save button)
Cmd+O	Open Project (via Open button)
Cmd+N	New Project (via New button)

🏗️ Architecture

src/
├── main/           # Electron main process
│   ├── index.ts    # Window management, IPC handlers
│   └── services/
│       └── FFmpegService.ts  # Video processing
├── renderer/       # React UI
│   ├── components/
│   │   ├── Header.tsx
│   │   ├── MediaLibrary.tsx
│   │   ├── VideoPreview.tsx
│   │   └── Timeline.tsx
│   ├── context/
│   │   └── ProjectContext.tsx  # State management
│   └── hooks/
│       └── useKeyboardShortcuts.ts
└── shared/         # Shared types
    └── types.ts

📦 Features Status

✅ MVP Requirements (Complete)

• Desktop app that launches
• Video import (drag & drop + file picker)
• Timeline view with clips
• Video preview player
• Trim functionality
• Export to MP4
• Packaged as native app

✅ Core Features (Complete)

• CapCut-style timeline design
• Adaptive zoom
• Drag clips on timeline
• Trim clips (in/out points)
• Split clips
• Undo/redo system
• Keyboard shortcuts
• Multi-track timeline (2 tracks)

✅ Recording Features (Complete)

• Screen recording with source selection
• Webcam recording
• Picture-in-picture recording mode
• Microphone audio capture
• Auto-minimize during recording
• Recording duration tracking

✅ Project Management (Complete)

• Save projects to .clipforge format
• Load saved projects
• Auto-save every 5 minutes
• Crash recovery with auto-restore
• Unsaved changes tracking
• Recent projects history

✅ Image/Photo Support (Complete)

• Import images (JPG, PNG, WebP, GIF, BMP)
• Custom duration dialog for image display time
• Image-to-video conversion using FFmpeg
• Drag & drop image support
• Thumbnail generation for imported images
• Images work as video clips on timeline

✅ Phase 2 Features (Complete)

• Export presets (YouTube, Instagram, TikTok) - Quick export with platform-optimized settings
• Timeline snapping - Magnetic snapping to playhead and clip edges with visual feedback
• Copy/paste clips - Ctrl/Cmd+C to copy, Ctrl/Cmd+V to paste at playhead

✅ Phase 3 Features (Complete)

• Video rotation (0°, 90°, 180°, 270°) - Rotate clips with UI controls in RightSidebar
• Horizontal flip - Mirror clips horizontally
• Vertical flip - Flip clips vertically
• Real-time preview - See rotation/flip instantly in video preview
• Export support - Rotation/flip applied during video export

✅ Phase 4 Features (Complete)

• Additional Video Filters - Blur, sharpen, sepia, grayscale, and vintage effects with real-time preview
• Timeline Markers/Bookmarks - Add markers at important points, jump to markers, label them, delete them
• Clip Grouping - Group multiple clips together so they move as one unit (Cmd/Ctrl+G or use Batch Operations)
• Enhanced Drag & Trim - Smooth drag-to-move and trim functionality for both video and audio clips
• Frame Numbers - Display frame numbers on timeline rulers (at 30fps intervals)

⏳ Future Enhancements

• Nested timelines - Create sequences within sequences
• Performance optimization for large projects
• Additional transition effects

🎨 UI/UX Highlights

• CapCut-inspired Design: Clean, modern interface
• Thumbnail Previews: Video clips show actual thumbnails
• Smart Zoom: Timeline scales intelligently to avoid label overlap
• Visual Feedback: Trim handles, selection rings, hover effects
• Professional Controls: Large buttons, clear typography, smooth animations

🛠️ Technical Stack

• Desktop: Electron 29
• Frontend: React 18 + TypeScript
• Styling: Tailwind CSS
• Video Processing: FFmpeg (fluent-ffmpeg)
• Build: electron-vite, electron-builder
• State: React Context + useReducer

📝 Development Notes

Duration Format

• Timeline: Milliseconds (precise editing)
• Video Element: Seconds (native HTML5)

Video Sync

Videos sync with timeline playhead position, allowing precise scrubbing and playback.

Export Pipeline

1. Trim each clip to selected in/out points
2. Concatenate clips in sequence
3. Render to MP4 with FFmpeg

🎯 Performance Targets

• ✅ Timeline remains responsive with 10+ clips
• ✅ Preview playback at 30+ fps
• ✅ Export completes without crashes
• ✅ App launch under 5 seconds
• ✅ No memory leaks during extended editing

📄 License

MIT

👥 Contributors

ClipForge Team - Gauntlet AI Cohort 2024

---

Note: FFmpeg must be installed for video processing to work. On macOS, install via brew install ffmpeg.