# OneClip Pro: Video to Reels Processor **Production-Ready Video Segmentation Tool with AI-Powered Intelligence** Transform long-form videos into short 60-second reels with configurable overlap, preserving original quality using FFmpeg stream copy technology. --- ## 🌟 Features ### Core Functionality ✅ **Smart Video Segmentation** - Automatically cuts long videos into short reels with configurable duration and overlap ✅ **Quality Preservation** - Uses FFmpeg stream copy (`-c copy`) to maintain original quality without re-encoding ✅ **Multi-Format Support** - Supports MP4, MOV, AVI, MKV, WebM, and FLV formats ✅ **Intelligent Overlap** - Configurable 0-10 second overlap between clips for smooth transitions ✅ **Robust Queue System** - Concurrent processing with job queue (max 2 simultaneous jobs) ✅ **Real-Time Progress** - Live WebSocket updates with progress bars and status tracking ✅ **Batch Downloads** - Download individual clips or all clips as a single ZIP archive ✅ **AI Insights** - Mock AI-powered highlight detection and recommendations ✅ **Premium UI** - Modern dark theme with glassmorphism design and smooth animations ### Technical Highlights - **File Validation** - MIME type and extension checking with 5GB file size limit - **Error Handling** - Comprehensive error messages and user-friendly feedback - **Auto-Cleanup** - Automatic cleanup of old jobs and files (configurable) - **WebSocket Support** - Real-time bidirectional communication for progress updates - **Responsive Design** - Works seamlessly on desktop, tablet, and mobile devices - **Comprehensive Logging** - Detailed console logging for processing jobs, clips, and errors --- ## 🚀 Quick Start ### Prerequisites (CRITICAL) 1. **Node.js 18+** - Required to run the application - [Download Node.js](https://nodejs.org/) - Verify installation: `node --version` 2. **FFmpeg** - Required for video processing - [Download FFmpeg](https://ffmpeg.org/download.html) - **MUST be added to System PATH** - Verify installation: `ffmpeg -version` ### Installation & Setup 1. **Install Dependencies:** ```bash npm run install:all ``` This installs dependencies for root, client, and server. 2. **Run the Application:** - **Windows:** Double-click `start_app.bat` or `RUN_APPLICATION.bat` - **macOS/Linux:** ```bash npm run dev ``` 3. **Access the Application:** - Open your browser to `http://localhost:3000` - Backend API runs on `http://localhost:3001` --- ## 📖 User Guide ### Step 1: Upload Video 1. Click or drag-and-drop a video file into the upload zone 2. Supported formats: MP4, MOV, AVI, MKV, WebM, FLV 3. Maximum file size: 5GB 4. Click "Upload to Server" to begin analysis ### Step 2: Configure Settings 1. **Clip Duration** (10-300 seconds, default: 60s) - Slide to adjust the length of each reel segment 2. **Overlap** (0-10 seconds, default: 2s) - Adds overlap between clips for smooth transitions 3. Review AI recommendations for optimal settings ### Step 3: Generate Reels 1. Click "Generate Reels" to start processing 2. Watch real-time progress with live updates 3. Processing uses FFmpeg stream copy for maximum speed ### Step 4: Download Results 1. **Individual Downloads:** Click download icon on each clip 2. **Bulk Download:** Click "Download All" to get a ZIP archive 3. Files are named: `reel_001.mp4`, `reel_002.mp4`, etc. --- ## 🏗️ Project Structure ``` video-cutter/ ├── client/ # Next.js 14 Frontend │ ├── app/ │ │ ├── page.tsx # Main application UI │ │ ├── layout.tsx # Root layout │ │ └── globals.css # Global styles │ ├── components/ │ │ └── Toast.tsx # Toast notification system │ └── package.json ├── server/ # Node.js Express Backend │ ├── src/ │ │ ├── index.js # Main server with API routes │ │ └── queue.js # Job queue manager │ ├── uploads/ # Temporary upload storage │ ├── output/ # Processed video clips │ └── package.json ├── ffmpeg/ # FFmpeg binaries (optional) ├── package.json # Root workspace config ├── start_app.bat # Windows launcher └── README.md ``` --- ## 🔌 API Documentation ### Base URL `http://localhost:3001/api` ### Endpoints #### 1. Health Check ```http GET /api/health ``` **Response:** ```json { "status": "ok", "ffmpeg": "connected", "uploads": true, "output": true, "time": "2026-01-10T12:00:00.000Z" } ``` #### 2. Upload Video ```http POST /api/upload Content-Type: multipart/form-data Body: { video: File } ``` **Response:** ```json { "message": "Upload successful", "videoId": "uuid", "filename": "video-123456789.mp4", "originalName": "my-video.mp4", "path": "/path/to/uploaded/file", "size": 52428800 } ``` #### 3. Analyze Video ```http POST /api/video/analyze Content-Type: application/json Body: { "filePath": "/path/to/video.mp4" } ``` **Response:** ```json { "duration": 300.5, "size": 52428800, "format": "mov,mp4,m4a,3gp,3g2,mj2", "resolution": "1920x1080", "fps": "30/1", "codec": "h264", "aiInsights": { "highlights": [...], "bestClipLength": 60, "recommendedOverlap": 3 } } ``` #### 4. Process Video ```http POST /api/video/process Content-Type: application/json Body: { "filePath": "/path/to/video.mp4", "clipLength": 60, "overlap": 2 } ``` **Response:** ```json { "jobId": "uuid", "message": "Job queued" } ``` #### 5. Get Job Status ```http GET /api/job/:jobId/status ``` **Response:** ```json { "jobId": "uuid", "status": "processing", "progress": 45, "message": "Processing clip 3 of 6", "clips": ["reel_001.mp4", "reel_002.mp4"], "error": null, "createdAt": 1704902400000, "startTime": 1704902405000, "completedAt": null } ``` #### 6. Download Single Clip ```http GET /api/download/:jobId/:filename ``` **Response:** Binary video file stream #### 7. Download All Clips (ZIP) ```http GET /api/download-all/:jobId ``` **Response:** Binary ZIP file stream ### WebSocket Events Connect to: `ws://localhost:3001` **Event: `progress_update`** ```json { "jobId": "uuid", "status": "processing", "progress": 60, "message": "Processing clip 4 of 6", "clips": ["reel_001.mp4", "reel_002.mp4", "reel_003.mp4"], "error": null } ``` --- ## ⚙️ Configuration ### Server Configuration Edit `server/src/index.js`: ```javascript const PORT = process.env.PORT || 3001; const MAX_FILE_SIZE = 5 * 1024 * 1024 * 1024; // 5GB const CONCURRENCY = 2; // Simultaneous processing jobs ``` ### Client Configuration Edit `client/app/page.tsx`: ```javascript const DEFAULT_CLIP_LENGTH = 60; // seconds const DEFAULT_OVERLAP = 2; // seconds ``` ### Logging Configuration The application includes comprehensive console logging for debugging and monitoring: - **Job Processing Logs:** Track job start, completion, and failures - **Video Processing Logs:** Detailed logs for each clip processing step - **Error Logs:** FFmpeg errors and processing failures - **Performance Logs:** Processing times and clip generation stats Logs are output to the server console with prefixes: - `[QUEUE]` - Job queue operations - `[PROCESSING]` - Video processing steps - `[UPLOAD]` - File upload information --- ## 🛠️ Troubleshooting ### FFmpeg Not Detected **Error:** "FFmpeg is NOT installed or NOT in system PATH" **Solution:** 1. Download FFmpeg from [ffmpeg.org](https://ffmpeg.org/download.html) 2. Add FFmpeg to your System PATH 3. Restart terminal and verify: `ffmpeg -version` 4. Restart the server ### Upload Fails **Error:** "File is too large (Max 5GB)" **Solution:** Compress your video or split it into smaller files **Error:** "Invalid file format" **Solution:** Convert your video to MP4, MOV, AVI, MKV, WebM, or FLV ### Processing Fails **Error:** "Failed to probe video" **Solution:** - Ensure FFmpeg is properly installed - Check if the video file is corrupted - Try re-uploading the video - Check server logs for detailed error messages ### Server Won't Start **Error:** "Port 3001 already in use" **Solution:** Kill the process using port 3001 or change the PORT in server config --- ## 🧪 Testing ### Manual Testing 1. Test with a short video (30 seconds) 2. Test with a medium video (5 minutes) 3. Test with different formats (MP4, MOV, AVI) 4. Test with different clip lengths (10s, 60s, 120s) 5. Test with different overlaps (0s, 2s, 5s) 6. Test download individual and bulk downloads ### Verification Script ```bash npm run verify ``` --- ## 🔒 Security Considerations - **File Validation:** MIME type and extension checking - **Size Limits:** 5GB maximum file size - **Path Sanitization:** Prevents path traversal attacks - **Auto-Cleanup:** Old files deleted after 1 hour (configurable) - **CORS:** Configured for localhost (update for production) ### Production Recommendations 1. Add user authentication 2. Implement rate limiting 3. Use HTTPS for all connections 4. Store files in cloud storage (AWS S3, etc.) 5. Add malware scanning 6. Implement proper logging and monitoring --- ## 📊 Performance Metrics ### Target Benchmarks - **Upload Speed:** >10 MB/s - **Processing Speed:** 1x-2x real-time (no re-encoding) - **API Response:** <500ms - **Concurrent Users:** 50+ - **Max Queue Size:** 100 jobs ### Optimization Tips 1. Use SSD storage for faster I/O 2. Increase concurrent jobs for powerful servers 3. Use hardware acceleration: `-hwaccel cuda` (NVIDIA GPUs) 4. Implement Redis for queue persistence 5. Use CDN for serving processed files --- ## 🚀 Future Enhancements ### Phase 2 Features (Roadmap) - [ ] **Auto Captions** - AI-powered subtitle generation (Whisper AI) - [ ] **AI Best Moments** - ML-based highlight detection - [ ] **Vertical Crop** - Smart 9:16 cropping for TikTok/Reels - [ ] **Background Music** - Add royalty-free music tracks - [ ] **Batch Processing** - Multiple videos simultaneously - [ ] **User Accounts** - Authentication and history tracking - [ ] **Cloud Deployment** - AWS/GCP/Azure deployment guides - [ ] **API Access** - RESTful API for third-party integration --- ## 📄 License This project is licensed under the MIT License. --- ## 🤝 Contributing Contributions are welcome! Please follow these steps: 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request --- ## 💬 Support For issues, questions, or feature requests: - Open an issue on GitHub - Check the troubleshooting section above - Review FFmpeg documentation: [ffmpeg.org](https://ffmpeg.org/) --- ## 🙏 Acknowledgments - **FFmpeg** - The backbone of video processing - **Next.js** - Modern React framework - **Express** - Fast Node.js web framework - **Socket.io** - Real-time bidirectional communication - **Tailwind CSS** - Utility-first CSS framework --- **Built with ❤️ using FFmpeg, Next.js, and Express** Version: 1.1.0 | Last Updated: January 10, 2026 # video-clipper-