1. Parse user request → Extract video path and parameters
2. Validate prerequisites → Check FFmpeg, video file exists
3. Analyze video metadata → Get duration, fps, resolution using ffprobe
4. Calculate frame extraction strategy → Based on mode (quick/standard/detailed/custom)
5. Extract frames → Use FFmpeg to save frames as PNG images
6. Analyze frames sequentially → Use Read tool with vision for each frame
7. Aggregate results → Compile all analyses into comprehensive report
8. Output report → Structured markdown with scores and recommendations
9. Cleanup → Remove temporary frames (unless --keep-frames)

# Standard analysis (10 frames)
/video-analysis examples/my-video/out/video.mp4

# Quick overview (5 frames)
/video-analysis examples/my-video/out/video.mp4 --mode quick

# Detailed analysis (20 frames)
/video-analysis examples/my-video/out/video.mp4 --mode detailed

# Custom timestamps
/video-analysis examples/my-video/out/video.mp4 --frames 0,5,10,15,20,25,30

# Focus on UI/UX only
/video-analysis examples/my-video/out/video.mp4 --focus ui

# Keep frames for manual review
/video-analysis examples/my-video/out/video.mp4 --keep-frames --output analysis-output/

# Check if video file exists
if [ ! -f "$video_path" ]; then
  echo "Error: Video file not found: $video_path"
  exit 1
fi

# Check if FFmpeg is installed
if ! command -v ffmpeg &> /dev/null; then
  echo "Error: FFmpeg is required but not found."
  echo "Install from: https://ffmpeg.org/download.html"
  exit 1
fi

# Check if ffprobe is installed
if ! command -v ffprobe &> /dev/null; then
  echo "Error: ffprobe is required but not found."
  echo "ffprobe is part of FFmpeg. Install from: https://ffmpeg.org/download.html"
  exit 1
fi

# Check if file has a video stream
video_stream=$(ffprobe -v error -select_streams v:0 \
  -show_entries stream=codec_type \
  -of default=noprint_wrappers=1:nokey=1 "$video_path" 2>/dev/null)

if [ "$video_stream" != "video" ]; then
  echo "Error: File does not contain a video stream."
  echo "This appears to be an audio-only file or invalid video."
  echo "Supported formats: MP4, MOV, AVI, WebM, MKV"
  exit 1
fi

# Get duration in seconds
duration=$(ffprobe -v error -show_entries format=duration \
  -of default=noprint_wrappers=1:nokey=1 "$video_path")

if [ -z "$duration" ] || [ "$(echo "$duration <= 0" | bc -l)" -eq 1 ]; then
  echo "Error: Unable to read video duration."
  echo "The file may be corrupted or in an unsupported format."
  exit 1
fi

# Get fps (convert fraction to decimal)
fps_fraction=$(ffprobe -v error -select_streams v:0 \
  -show_entries stream=r_frame_rate \
  -of default=noprint_wrappers=1:nokey=1 "$video_path")

# Convert fraction (e.g., "30/1") to decimal using bc
fps=$(echo "scale=6; $fps_fraction" | bc -l)

if [ -z "$fps" ] || [ "$(echo "$fps <= 0" | bc -l)" -eq 1 ]; then
  echo "Error: Unable to read video frame rate."
  exit 1
fi

# Get resolution
resolution=$(ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height \
  -of csv=s=x:p=0 "$video_path")

# Get total frame count (use scale=0 for integer result)
total_frames=$(echo "scale=0; ($duration * $fps) / 1" | bc)

# Calculate timestamps using bc with proper scale
timestamps=(
  "0"
  "$(echo "scale=3; $duration * 0.25" | bc)"
  "$(echo "scale=3; $duration * 0.5" | bc)"
  "$(echo "scale=3; $duration * 0.75" | bc)"
  "$(echo "scale=3; $duration * 0.99" | bc)"
)

# Calculate interval (9 intervals = 10 frames)
interval=$(echo "scale=3; $duration / 9" | bc)

# Build array of timestamps
timestamps=()
for i in {0..9}; do
  timestamp=$(echo "scale=3; $i * $interval" | bc)
  timestamps+=("$timestamp")
done

# Calculate interval (19 intervals = 20 frames)
interval=$(echo "scale=3; $duration / 19" | bc)

# Build array of timestamps
timestamps=()
for i in {0..19}; do
  timestamp=$(echo "scale=3; $i * $interval" | bc)
  timestamps+=("$timestamp")
done

# Parse comma-separated timestamps from --frames argument
IFS=',' read -ra custom_timestamps <<< "$frames_arg"

# Validate each timestamp
timestamps=()
for ts in "${custom_timestamps[@]}"; do
  # Remove whitespace
  ts=$(echo "$ts" | xargs)

  # Validate timestamp is numeric
  if ! [[ "$ts" =~ ^[0-9]+\.?[0-9]*$ ]]; then
    echo "Error: Invalid timestamp '$ts' - must be numeric"
    exit 1
  fi

  # Check timestamp is within video duration
  if [ "$(echo "$ts > $duration" | bc -l)" -eq 1 ]; then
    echo "Error: Timestamp ${ts}s exceeds video duration of ${duration}s"
    exit 1
  fi

  timestamps+=("$ts")
done

# Check max frame limit (100 frames)
if [ "${#timestamps[@]}" -gt 100 ]; then
  echo "Error: Too many frames requested (${#timestamps[@]})"
  echo "Maximum: 100 frames. Consider using standard or detailed mode."
  exit 1
fi

# Check minimum frame count
if [ "${#timestamps[@]}" -eq 0 ]; then
  echo "Error: No valid timestamps provided"
  echo "Example: --frames 0,5,10,15,20"
  exit 1
fi

# Create temp directory with error checking
temp_dir=$(mktemp -d) || {
  echo "Error: Failed to create temporary directory"
  exit 1
}

# Set up cleanup trap for interrupts
cleanup() {
  if [ "$keep_frames" = false ] && [ -d "$temp_dir" ]; then
    rm -rf "$temp_dir"
  fi
}
trap cleanup EXIT INT TERM

# Extract each frame
for i in "${!timestamps[@]}"; do
  timestamp=${timestamps[$i]}

  # Convert timestamp to HH:MM:SS.MS format using bc for all calculations
  hours=$(echo "scale=0; $timestamp / 3600" | bc)
  minutes=$(echo "scale=0; ($timestamp % 3600) / 60" | bc)
  seconds=$(echo "scale=3; $timestamp - ($hours * 3600) - ($minutes * 60)" | bc)

  time_formatted=$(printf '%02d:%02d:%06.3f' "$hours" "$minutes" "$seconds")

  # Extract frame
  ffmpeg -ss "$time_formatted" -i "$video_path" \
    -vframes 1 -q:v 2 \
    "$temp_dir/frame_$(printf '%03d' $i).png" \
    -loglevel error

  # Check if extraction succeeded
  if [ ! -f "$temp_dir/frame_$(printf '%03d' $i).png" ]; then
    echo "Error: Failed to extract frame at timestamp $timestamp"
    exit 1
  fi
done

echo "Successfully extracted ${#timestamps[@]} frames"

# Video Analysis Report

**Video:** [file path]
**Duration:** X seconds (Y frames @ Z fps)
**Resolution:** WxH
**Analyzed:** YYYY-MM-DD HH:MM:SS
**Frames Analyzed:** N (mode: standard/quick/detailed/custom)
**Analysis Focus:** all/ui/aesthetics/technical/storytelling

---

## Overall Assessment: X.X/10

[2-3 sentence high-level summary of video quality, noting key strengths and primary areas for improvement]

---

## Detailed Scene Analysis

### Frame 1 (0:00 - 0.0s)
**Scene:** [Brief description of what's visible]

**What Works:**
- [Specific positive observation]
- [Another strength]

**Suggestions:**
- [Specific improvement recommendation]

**Score:** X/10

---

### Frame 2 (0:XX - X.Xs)
[Repeat structure]

---

[Continue for all frames...]

---

## Summary

### Strengths
1. [Recurring positive pattern or consistent strength]
2. [Another overall strength]
3. [Additional positive observation]

### Areas for Improvement
1. [Key issue or weakness observed across frames]
2. [Another improvement opportunity]
3. [Additional suggestion]

### Technical Quality Breakdown
- **Visual Consistency:** X/10 - [Brief note]
- **Readability:** X/10 - [Brief note]
- **Aesthetic Coherence:** X/10 - [Brief note]
- **Technical Execution:** X/10 - [Brief note]

---

## Recommendations

### High Priority
1. [Most impactful actionable suggestion]
2. [Second most important recommendation]

### Medium Priority
1. [Helpful but less critical suggestion]
2. [Another medium priority item]

### Nice to Have
1. [Polish or enhancement suggestion]
2. [Optional improvement]

---

## Appendix

**Extracted Frames:** [temp_dir path if --keep-frames, otherwise "Deleted after analysis"]
**Analysis Duration:** X minutes Y seconds
**Sampling Strategy:** [Description of frame selection approach]
**Focus Area:** [all/ui/aesthetics/technical/storytelling]

# Cleanup is handled by trap set in Step 4
# The trap ensures cleanup happens even on interrupt/error

# If --keep-frames IS set and --output specified, move frames before exit
if [ "$keep_frames" = true ] && [ -n "$output_dir" ]; then
  mkdir -p "$output_dir" || {
    echo "Error: Cannot create output directory: $output_dir"
    exit 1
  }

  mv "$temp_dir"/* "$output_dir/" || {
    echo "Warning: Some frames may not have been moved to $output_dir"
  }

  echo "Frames saved to: $output_dir"
else
  echo "Temporary frames cleaned up"
fi

Error: FFmpeg is required but not found.

FFmpeg is needed to extract frames from video files.
Install from: https://ffmpeg.org/download.html

Installation quick start:
- macOS: brew install ffmpeg
- Ubuntu/Debian: sudo apt-get install ffmpeg
- Windows: Download from ffmpeg.org

Error: Video file not found: [path]

Please check:
- File path is correct
- File exists at the specified location
- You have read permissions for the file

Tip: Use absolute paths or paths relative to current directory.

Error: File does not contain a video stream.

This appears to be an audio-only file or invalid video.
Supported formats: MP4, MOV, AVI, WebM, MKV

If this is an audio file, this tool only analyzes video content.
Try:
- Providing a video file instead
- Converting audio to video format with visualizations
- Using an audio analysis tool

Error: Unable to read video duration.
The file may be corrupted or in an unsupported format.

This usually indicates:
- Corrupted or incomplete video file
- Unsupported codec or container
- File is not actually a video file

Try:
- Playing the video in VLC or another media player to verify it works
- Re-encoding to a standard format: ffmpeg -i input.mov -c:v libx264 -c:a aac output.mp4
- Using a different video file

Error: Failed to create temporary directory

This usually indicates:
- Insufficient disk space
- Permission issues with /tmp directory
- System resource limitations

Try:
- Freeing up disk space
- Checking /tmp directory permissions
- Using --output to specify an alternative directory

Error: Failed to extract frame at timestamp X.XXs

Possible causes:
- Video file is corrupted at that timestamp
- Insufficient disk space during extraction
- Invalid timestamp (beyond video duration)
- FFmpeg encoding error

Try:
- Using different timestamps with --frames
- Checking video file integrity
- Freeing up disk space
- Re-encoding video: ffmpeg -i input.mp4 -c copy output.mp4

Error: Invalid timestamp 'abc' - must be numeric

Requirements for --frames parameter:
- Comma-separated numeric values: "0,10,20,30"
- Timestamps in seconds
- Can include decimals: "0,5.5,10,15.25,20"
- Must be within video duration

Example: --frames 0,5,10,15,20

Error: Timestamp 65s exceeds video duration of 45s

All timestamps must be within the video duration.

To fix:
- Use timestamps <= 45s
- Remove the invalid timestamp
- Use automatic modes (quick/standard/detailed) instead

Valid example for this video: --frames 0,10,20,30,40

Error: Too many frames requested (150)
Maximum: 100 frames. Consider using standard or detailed mode.

Why the limit?
- Processing 100+ frames takes hours
- Storage requirements become excessive
- Analysis quality plateaus beyond ~20 frames

Recommended:
- Quick mode (5 frames): Fast overview
- Standard mode (10 frames): Balanced analysis
- Detailed mode (20 frames): Thorough review
- Custom mode: Target specific moments (max 100)

Error: Cannot create output directory: [path]

Possible causes:
- Parent directory doesn't exist
- No write permissions
- Invalid path characters

Try:
- Creating parent directories first: mkdir -p /path/to/parent
- Using a different output path
- Checking directory permissions

/video-analysis path/to/video.mp4

# Quick check (5 frames)
/video-analysis video.mp4 --mode quick

# Standard analysis (10 frames)
/video-analysis video.mp4

# Detailed review (20 frames)
/video-analysis video.mp4 --mode detailed

# UI focus
/video-analysis video.mp4 --focus ui

/video-analysis examples/my-project/out/final-video.mp4 \
  --mode detailed \
  --focus all \
  --keep-frames \
  --output analysis-2026-02-06/