QCut Project Organization Skill

Organize files and folders according to QCut's standard project structure.

Standard QCut Project Structure

Documents/QCut/Projects/{project-name}/
├── project.qcut              # Project metadata file
├── media/                    # All media files
│   ├── imported/             # User-imported media (videos, images, audio)
│   ├── generated/            # AI-generated content (from skills)
│   └── temp/                 # Temporary processing files
├── skills/                   # Project-specific skills
│   ├── ai-content-pipeline/  # AI content generation skill
│   │   ├── Skill.md
│   │   ├── REFERENCE.md
│   │   └── EXAMPLES.md
│   └── ffmpeg-skill/         # FFmpeg processing skill
│       ├── Skill.md
│       └── REFERENCE.md
├── output/                   # Exported videos and renders
├── cache/                    # FFmpeg and processing cache
└── docs/                     # Project documentation (optional)

Organization Rules

Media Files

• Videos (.mp4, .mov, .webm, .avi): → media/imported/ or media/generated/
• Images (.jpg, .png, .webp, .gif): → media/imported/ or media/generated/
• Audio (.mp3, .wav, .aac, .m4a): → media/imported/ or media/generated/
• AI-generated content goes to media/generated/
• User-imported content goes to media/imported/

Hybrid Symlink Import System

QCut uses a hybrid symlink/copy system for imported media:

• Symlinks preferred: Creates symbolic links to original files (saves disk space)
• Copy fallback: Falls back to copying when symlinks unavailable (Windows without admin, network drives)
• Metadata tracking: Each import tracks importMethod, originalPath, and fileSize

Files in media/imported/ may be:

• Symlinks pointing to the original file location
• Copies of the original file (when symlink creation fails)

Skills

• Each skill is a folder with Skill.md as the entry point
• Additional reference files: REFERENCE.md, EXAMPLES.md, CONCEPTS.md
• Skills can have a scripts/ subfolder for helper scripts

Output

• Final rendered videos go to output/
• Use descriptive names: {project-name}_{date}_{resolution}.mp4

Temporary Files

• Processing intermediates go to media/temp/
• Cache files go to cache/
• Clean up temp files after export

Virtual Folder System

QCut uses a virtual folder system for organizing media in the UI:

• Virtual folders are metadata-only (files stay in original locations)
• Items can belong to multiple folders (like tags)
• Special "Skills" folder shows project skills
• Max folder depth: 3 levels

Virtual Folder Naming Conventions

• Use clear, descriptive names (max 50 characters)
• Examples: "Raw Footage", "B-Roll", "Music", "Sound Effects"
• Color-code folders for quick identification

When Organizing

1. Identify file types - Categorize by extension and source
2. Check existing structure - Don't duplicate folders
3. Move files safely - Use copy then delete, not direct move
4. Update references - Ensure project files still point to correct paths
5. Clean up empty folders - Remove unused directories

Commands to Help

# List all media files recursively
find . -type f \( -name "*.mp4" -o -name "*.mov" -o -name "*.jpg" -o -name "*.png" -o -name "*.mp3" \)

# Create standard structure
mkdir -p media/{imported,generated,temp} output cache skills docs

# Move videos to imported
mv *.mp4 *.mov *.webm media/imported/ 2>/dev/null

# Find large files (over 100MB)
find . -type f -size +100M

# Clean temp files
rm -rf media/temp/* cache/*

# === Symlink Commands ===

# List all symlinks in imported folder
find media/imported -type l

# Check if a file is a symlink
ls -la media/imported/

# Find broken symlinks
find media/imported -xtype l

# Show symlink target
readlink media/imported/video-id.mp4

# Create symlink manually (Unix/macOS)
ln -s /path/to/original.mp4 media/imported/video-id.mp4

# Create symlink manually (Windows - requires admin or dev mode)
mklink media\imported\video-id.mp4 C:\path\to\original.mp4

Example Organization Task

When asked to organize:

1. First, scan the current directory structure
2. Identify files that need to be moved
3. Create missing directories
4. Move files to appropriate locations
5. Report what was organized

Always confirm before moving files that might break project references.