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):

CODEBLOCK0

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 INLINECODE0
• "Delete all non-video files" — permanently delete them
• "Leave them as-is" — do nothing

If user chooses to move:
CODEBLOCK1

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:

CODEBLOCK3

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

CODEBLOCK4

Step 4: Extract Frames and Analyze Videos with AI Vision

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

CODEBLOCK5

Also detect bad footage quality:

CODEBLOCK6

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. 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:

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. 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):
CODEBLOCK8

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:
CODEBLOCK9

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: INLINECODE12

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