Clipcraft Video Creator
AI-powered video composition tool that analyzes media files using Google Gemini and creates video compositions with MoviePy.
Overview
Clipcraft is a desktop application that helps users create video compositions from images and videos. It uses Google Gemini Flash API for intelligent media analysis and can either render video directly or generate editable MoviePy scripts. Projects are stored as self-contained bundles.
Instructions
When helping users with Clipcraft projects:
1. Project Structure Setup
**For macOS (.clipcraft bundle):**
Create bundle directory: `my-project.clipcraft/`Add `Contents/` subdirectory with `Info.plist`, `PkgInfo`Create `Contents/Resources/` with: `index.md`, `config.yaml`, `media/`, `assets/`**For Windows/Linux:**
Create directory: `my-project.clipcraft/`Add launcher file, `desktop.ini` (Windows) or `.directory` (Linux)Create: `index.md`, `config.yaml`, `media/`, `assets/`2. Core Application Components
The application follows this structure:
**Models**: `media.py` (MediaFile, MediaGroup), `project.py`, `settings.py`**Services**: `scanner.py`, `analyzer.py` (Gemini), `importer.py`, `exporter.py`, `bundle.py`**UI**: PySide6 components including `main_window.py`, `media_list.py`, `composition_editor.py`, `video_player.py`3. index.md Format
When creating or modifying project files, use this markdown structure:
```markdown
Info
**Title:** Project Title
**Description:** Project description
**Created:** YYYY-MM-DD HH:MM
**Updated:** YYYY-MM-DD HH:MM
Parsing Prompt
[Instructions for AI analysis]
Media Files
[Group Name]
filename.mp4 [KEEP/SKIP]
**Path:** media/filename.mp4**Duration:** MM:SS**Resolution:** WIDTHxHEIGHT**User Description:** [User-provided context]**AI Description:** [Gemini analysis]**Mood:** [AI-detected mood]**Scene Type:** [AI-detected scene types]**Movement:** [Camera movement description]Proposed Structure
Section Name (MM:SS - MM:SS)
filename.mp4 [start-end]image.jpg [duration, effects]User Prompt for Creation
[Instructions for video generation]
```
4. Media Analysis with Gemini
Use Google Gemini Flash API (free tier) for media analysisAnalyze for: scene content, mood, quality, movement, categorizationRespect user descriptions as context for AI analysisAuto-group related clips (e.g., "Beach Scenes", "Dinner", etc.)5. Video Export Options
**Direct Render:**
Generate MP4 using MoviePyApply transitions, effects, titles as specifiedUse media files from project's `media/` directory**Script Generation:**
Create editable Python script with MoviePy commandsInclude all composition logic from markdown structureAllow users to customize before rendering6. Accessibility Requirements
Ensure all implementations include:
`accessibleName` and `accessibleDescription` for all widgetsFull keyboard navigation (Tab, Space, Arrow keys)Keyboard shortcuts: Ctrl+I (import), Ctrl+E (export), F6 (cycle panels)Screen reader compatibility (VoiceOver/NVDA)7. Dependencies Management
Required packages:
PySide6>=6.6 (Qt GUI)google-genai>=1.0 (Gemini API)moviepy>=2.0 (Video editing)Pillow>=10.0 (Image processing)pyyaml>=6.0 (Config files)8. Development Commands
```bash
Install in development mode
pip install -e ".[dev]"
Run the application
clipcraft
Or directly
python -m clipcraft
```
9. Configuration
API keys stored in settings (user-configurable via UI)Project settings in `config.yaml`Platform-specific bundle handling via `bundle.py`10. Best Practices
Keep projects self-contained and portableRespect user descriptions as AI contextGenerate accessible, keyboard-navigable interfacesProvide both render and script export optionsUse markdown for human-readable, AI-friendly composition formatSupport cross-platform bundle formats appropriatelyConstraints
Use Google Gemini Flash API (free tier) onlyAll media must be imported into project bundleMaintain cross-platform compatibility (macOS, Windows, Linux)Ensure full accessibility complianceProjects must be portable and self-containedExample Usage
User: "Create a new Clipcraft project for my vacation videos"
Create project bundle structureSet up `index.md` with vacation-focused parsing promptConfigure media import directoryInitialize empty media groupsUser: "Analyze these beach clips and organize them"
Import media files into projectSend to Gemini for analysisCreate groups based on scene typesPopulate `index.md` with analysis resultsUser: "Generate a 2-minute highlight video with smooth transitions"
Parse composition structure from markdownEither render directly with MoviePy or generate editable scriptApply transitions and effects as specified