Video Folder Organizer

Intelligently organize a video folder: clean up non-video files, remove bad footage, analyze content with AI, and sort into categorized subfolders.

Usage

User wants to organize a video folder: $ARGUMENTS

If the user has not provided a folder path, ask them to provide one.

Language note: Detect the language the user is writing in and respond in that language throughout the entire session. Category folder names should also be in the user's language.

Step 1: Scan the Folder

Scan the folder for all files (non-recursive at root level first):

# List all files with sizes
ls -la "$FOLDER"

# Find video files (common extensions)
find "$FOLDER" -maxdepth 1 -type f \( \
  -iname "*.mp4" -o -iname "*.mov" -o -iname "*.avi" -o -iname "*.mkv" \
  -o -iname "*.m4v" -o -iname "*.wmv" -o -iname "*.flv" -o -iname "*.webm" \
  -o -iname "*.mts" -o -iname "*.m2ts" -o -iname "*.mpg" -o -iname "*.mpeg" \
  -o -iname "*.3gp" -o -iname "*.hevc" -o -iname "*.ts" \
\)

# Find non-video files
find "$FOLDER" -maxdepth 1 -type f ! \( \
  -iname "*.mp4" -o -iname "*.mov" -o -iname "*.avi" -o -iname "*.mkv" \
  -o -iname "*.m4v" -o -iname "*.wmv" -o -iname "*.flv" -o -iname "*.webm" \
  -o -iname "*.mts" -o -iname "*.m2ts" -o -iname "*.mpg" -o -iname "*.mpeg" \
  -o -iname "*.3gp" -o -iname "*.hevc" -o -iname "*.ts" \
\)

Report to user:

• Total files found
• Number of video files
• Number of non-video files (list them)

Step 2: Handle Non-Video Files

Use AskUserQuestion to ask what to do with non-video files (only if any exist):

Question: "Found N non-video file(s). How would you like to handle them?" Options:

• "Move to _misc subfolder (Recommended)" — move non-video files into $FOLDER/_misc/
• "Delete all non-video files" — permanently delete them
• "Leave them as-is" — do nothing

If user chooses to move:

mkdir -p "$FOLDER/_misc"
mv [non-video files] "$FOLDER/_misc/"

If user chooses to delete:

rm [non-video files]

Step 3: Remove Short Videos

Use AskUserQuestion to ask about short video threshold:

Question: "Would you like to remove very short videos?" Options:

• "Yes, remove videos shorter than 1 second (default)"
• "Yes, let me specify a duration"
• "No, keep all videos"

If user wants to specify duration, ask them to type the threshold in seconds.

Use ffprobe to check each video's duration:

ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$VIDEO_FILE"

List all videos shorter than the threshold, show their filenames and durations, then confirm deletion:

rm "$SHORT_VIDEO"

Step 4: Extract Frames and Analyze Videos with AI Vision

For each remaining video file, extract representative frames using ffmpeg:

# Create temp directory for frames
mkdir -p /tmp/video_frames

# Extract 4 evenly-spaced frames from each video
# (at 10%, 30%, 60%, 90% of duration)
DURATION=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$VIDEO")
ffmpeg -ss $(echo "$DURATION * 0.10" | bc) -i "$VIDEO" -frames:v 1 /tmp/video_frames/"${BASENAME}_01.jpg" -y -loglevel quiet
ffmpeg -ss $(echo "$DURATION * 0.30" | bc) -i "$VIDEO" -frames:v 1 /tmp/video_frames/"${BASENAME}_02.jpg" -y -loglevel quiet
ffmpeg -ss $(echo "$DURATION * 0.60" | bc) -i "$VIDEO" -frames:v 1 /tmp/video_frames/"${BASENAME}_03.jpg" -y -loglevel quiet
ffmpeg -ss $(echo "$DURATION * 0.90" | bc) -i "$VIDEO" -frames:v 1 /tmp/video_frames/"${BASENAME}_04.jpg" -y -loglevel quiet

Also detect bad footage quality:

# Check for all-black frames: compute mean brightness of frame
ffmpeg -i "$VIDEO" -ss $(echo "$DURATION * 0.5" | bc) -frames:v 1 -vf "blackdetect=d=0.1:pix_th=0.10" -f null - 2>&1

# Check for excessive shakiness using scene detection / motion vectors
ffmpeg -i "$VIDEO" -vf "select='gt(scene,0.4)',setpts=N/TB" -frames:v 5 /tmp/video_frames/"${BASENAME}_shake_%02d.jpg" -y -loglevel quiet 2>&1

Use the Read tool to load the extracted frame images, then analyze ALL videos together in one AI analysis pass:

Analyze each video's frames and produce for each video:

1. Category: A short label in the user's language describing the content (e.g., highway driving, city street, nature scenery, indoor footage, interview, sports, aerial, food, live event)
2. Quality issues:
   • all_black: frames are mostly black (>80% black pixels)
   • shaky: excessive camera movement/shake visible
   • blurry: extremely out of focus
   • none: no issues

After analyzing all videos, present a summary table to the user:

Filename            Duration  Category         Quality
video001.mp4        00:32     highway driving  none
video002.mp4        01:15     city street      shaky
video003.mp4        00:08     nature scenery   all black
...

Step 5: Handle Bad Quality Videos

If any videos were flagged with quality issues (all_black, shaky, blurry):

Use AskUserQuestion:

Question: "The following videos have quality issues: [list filenames and issue types]. How would you like to handle them?" Options:

• "Delete all problematic videos"
• "Move to _rejected subfolder"
• "Keep them, do nothing"
• "Decide one by one"

If "Decide one by one", for each bad video use AskUserQuestion with options: Delete / Move to _rejected / Keep

Execute the chosen action for each video.

Step 6: Classify Videos into Numbered Subfolders

Based on the AI analysis categories, propose a folder structure:

1. Collect all unique categories from the analysis
2. Sort categories by number of videos (most videos first)
3. Assign two-digit numbers: 01_, 02_, etc.

Show the proposed structure to the user (folder names in the user's language):

Proposed folder structure:
01_highway_driving  (12 videos)
02_city_street      (8 videos)
03_nature_scenery   (5 videos)
04_indoor           (3 videos)

Use AskUserQuestion:

Question: "Does the proposed folder structure look good?" Options:

• "Looks good, proceed"
• "I need to rename some categories"
• "I need to merge some categories"

If user wants adjustments, ask them to specify changes (use Other input), then update the plan.

Execute the file moves:

mkdir -p "$FOLDER/01_highway_driving"
mv "$VIDEO" "$FOLDER/01_highway_driving/"

After moving all files, confirm completion and show the final structure:

find "$FOLDER" -type d | sort

Step 7: Refine a Category (Optional)

Use AskUserQuestion:

Question: "Would you like to further organize any category folder?" Options:

• "No, all done"
• "Yes, let me choose a category"

If user wants to refine, ask which category folder they want to work on (list the created folders as options).

Then ask:

Question: "How would you like to organize this folder?" Options:

• "Group by time of day (morning / afternoon / evening)"
• "Group by quality (picks / normal)"
• "Group by length (short / long)"
• "Let me describe how"

Execute the requested sub-organization using the same AI analysis data already collected, or re-analyze if needed.

After completing, loop back to Step 7 to ask if any other category needs refinement.

Technical Notes

Prerequisites

• ffmpeg and ffprobe must be installed (brew install ffmpeg)
• Use which ffmpeg to verify before starting

Performance Tips

• Process frames extraction in batches to avoid overwhelming the system
• For large folders (>50 videos), inform the user this may take a few minutes
• Clean up temp frames after analysis: rm -rf /tmp/video_frames

Error Handling

• If a video file is corrupted and ffprobe fails, mark it as "unreadable" and ask user separately
• If ffmpeg frame extraction fails, skip that video's frames and note in analysis

Folder Safety

• Never delete files without explicit user confirmation
• Always show what will be deleted/moved before executing
• If unsure, prefer moving to a subfolder over permanent deletion