claude-gif-optimize

claude-gif-optimize -- GIF Size Optimization

Multi-strategy GIF optimizer that iteratively reduces file size while preserving visual quality. Targets specific platform size limits or custom byte budgets.

Pipeline Overview

Analyze GIF --> Choose Strategy --> Apply --> Check Size --> Iterate if Needed --> Report

Step-by-Step Procedure

1. Read Reference

Before optimizing:

Read ~/.claude/skills/claude-gif/references/gif-optimization.md
Read ~/.claude/skills/claude-gif/references/platform-specs.md

2. Analyze Current GIF

# File size
stat -c%s INPUT.gif

# Frame count, dimensions, duration
ffprobe -v error -show_entries stream=width,height,nb_frames,r_frame_rate,duration \
  -show_entries format=duration,size -of json INPUT.gif

# Detailed frame info
gifsicle --info INPUT.gif | head -20

Record baseline: file size, dimensions (WxH), frame count, duration, FPS.

3. Determine Target

Platform auto-detection (from user's words):

| User Says | Target Size | Preset | |-----------|------------|--------| | "for Discord", "Discord" | 256 KB | discord | | "Discord Nitro" | 50 MB | (custom) | | "for Slack" | 500 KB | slack | | "for Twitter", "for X" | 15 MB | twitter | | "for Reddit" | 20 MB | (custom) | | "for GitHub", "README gif" | 10 MB | (custom) | | "for email" | 1 MB | (custom) | | "for web", "website" | 2 MB | web | | "small as possible" | minimize | aggressive | | Specific number (e.g., "under 1MB") | parse number | custom |

4. Optimization Chain

Apply strategies in order from least to most destructive. Stop when target size is reached.

Strategy 1: Gifsicle Lossless Optimization

gifsicle -O3 --no-comments --no-names INPUT.gif -o OPTIMIZED.gif

Typical savings: 5-15%. Always apply first.

Strategy 2: Gifsicle Lossy Compression

gifsicle -O3 --lossy=30 INPUT.gif -o OPTIMIZED.gif     # Light (barely visible)
gifsicle -O3 --lossy=80 INPUT.gif -o OPTIMIZED.gif     # Medium (some artifacts)
gifsicle -O3 --lossy=150 INPUT.gif -o OPTIMIZED.gif    # Heavy (visible artifacts)
gifsicle -O3 --lossy=200 INPUT.gif -o OPTIMIZED.gif    # Maximum (significant artifacts)

Start with --lossy=30, increase by 30 until target is met. Typical savings: 10-40% depending on level.

Strategy 3: Color Reduction

gifsicle --colors 192 -O3 INPUT.gif -o OPTIMIZED.gif   # Slight reduction
gifsicle --colors 128 -O3 INPUT.gif -o OPTIMIZED.gif   # Moderate
gifsicle --colors 64 -O3 INPUT.gif -o OPTIMIZED.gif    # Significant
gifsicle --colors 32 -O3 INPUT.gif -o OPTIMIZED.gif    # Heavy (posterization)

Typical savings: 10-30%. Works best on GIFs with many similar colors.

Strategy 4: Dimension Reduction

Re-encode at smaller dimensions via FFmpeg two-pass:

bash ~/.claude/skills/claude-gif/scripts/gif_convert.sh \
  --input INPUT.gif \
  --width NEW_WIDTH \
  --fps ORIGINAL_FPS \
  --output OPTIMIZED.gif \
  -y

Dimension scaling guide:

• Current 640px --> 480px (43% fewer pixels)
• Current 480px --> 320px (56% fewer pixels)
• Current 320px --> 240px (44% fewer pixels)
• Each step roughly halves file size.

Strategy 5: Frame Rate Reduction

Re-encode with lower FPS:

bash ~/.claude/skills/claude-gif/scripts/gif_convert.sh \
  --input INPUT.gif \
  --fps NEW_FPS \
  --width CURRENT_WIDTH \
  --output OPTIMIZED.gif \
  -y

Frame rate reduction guide:

• 20fps --> 15fps (25% fewer frames)
• 15fps --> 10fps (33% fewer frames)
• 10fps --> 8fps (20% fewer frames)
• Below 8fps looks noticeably choppy.

Strategy 6: Frame Dropping (gifsicle)

Remove every Nth frame:

# Keep only even-numbered frames (drops 50%)
gifsicle INPUT.gif --unoptimize $(seq -f '#%g' 0 2 $(gifsicle --info INPUT.gif | grep -oP '\d+ images' | grep -oP '\d+')) -O3 -o OPTIMIZED.gif

Use sparingly -- creates uneven timing.

Strategy 7: Dither Change (Re-encode)

Switch dithering algorithm for smaller output:

bash ~/.claude/skills/claude-gif/scripts/gif_convert.sh \
  --input INPUT.gif \
  --dither "bayer:bayer_scale=3" \
  --stats-mode diff \
  --width CURRENT_WIDTH \
  --fps CURRENT_FPS \
  --output OPTIMIZED.gif \
  -y

bayer + diff mode often produces smaller files than floyd_steinberg + full.

5. Automated Optimization Script

For automated multi-strategy optimization:

~/.video-skill/bin/python3 ~/.claude/skills/claude-gif/scripts/gif_optimize.py \
  --input INPUT.gif \
  --target-size 256 \
  --output ~/Documents/gif_output/optimized.gif

The script applies strategies in order, checking size after each step.

6. Before/After Report

Always report results:

Optimization Report
-------------------
Original:  1,245 KB  (640x360, 60 frames, 20fps, 3.0s)
Optimized:   248 KB  (320x180, 40 frames, 13fps, 3.0s)
Reduction: 80.1%

Applied strategies:
  1. Gifsicle -O3 --lossy=30    --> 1,058 KB (-15%)
  2. Colors 128                  --> 892 KB (-16%)
  3. Dimensions 640->320         --> 312 KB (-65%)
  4. Gifsicle --lossy=80         --> 248 KB (-21%)

Target: Discord (256 KB) -- PASS

Platform Auto-Fit Algorithm

When targeting a specific platform:

1. Apply gifsicle -O3 --lossy=30
2. If still over target:
   a. Reduce colors to 128
3. If still over target:
   b. Reduce width by one step (640->480->320->240)
4. If still over target:
   c. Increase lossy to 80
5. If still over target:
   d. Reduce FPS by one step (20->15->10->8)
6. If still over target:
   e. Increase lossy to 150, colors to 64
7. If still over target:
   f. Reduce width by another step
8. If still over target after all steps:
   Report failure, suggest shorter duration or different content

Quality Floor

Never go below these minimums (the GIF becomes unusable):

• Width: 160px
• FPS: 6
• Colors: 16
• Lossy: 200

If the target cannot be reached without going below quality floor, inform the user and suggest trimming the duration or splitting into multiple GIFs.

Error Handling

| Error | Cause | Fix | |-------|-------|-----| | gifsicle: no such file | gifsicle not installed | sudo apt install gifsicle | | Output larger than input | Re-encoding added overhead | Use gifsicle-only optimization (no FFmpeg) | | Visible banding | Too few colors | Increase colors, switch to floyd_steinberg dither | | Flickering frames | lossy too aggressive | Reduce lossy value | | Still too large | Content inherently complex | Suggest shorter duration, smaller dimensions, or video format instead |