Skip to content

Video Compression Workflow for Fab Academy (macOS)

Overview

This guide documents the setup of an automated video compression system for Fab Academy documentation on macOS. Claude.ai was used to walk me through the steps, and to create this workflow with the options I chose. A custom Quick Action was created that allows me to right-click any video file in Finder, and compress it to a smaller size suitable for GitLab repositories.

Author: Dorian Fritze
Date: February 2, 2026
System: MacBook Pro running macOS
Tools Used: Automator, FFmpeg, Homebrew, Claude.ai

Table of Contents

  1. Prerequisites Installation
  2. Creating the Automator Quick Action
  3. Understanding the Compression Script
  4. Usage Instructions
  5. Expected Results
  6. Troubleshooting
  7. Customization Options
  8. Why This Matters for Fab Academy

Prerequisites Installation

Step 1: Install Homebrew

Homebrew is a package manager for macOS that simplifies software installation.

  1. Open Terminal (Applications → Utilities → Terminal)

  2. Run the installation command: 

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  3. Enter your Mac password when prompted (text won't appear as you type - this is normal security behavior)

  4. Wait 5-10 minutes for installation

  5. Critical Step: After installation, run the "Next steps" commands shown in the Terminal output: 

    echo '' >> ~/.bash_profile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile
source ~/.bash_profile

  6. Verify installation: 

    brew --version
    Expected output: Homebrew 4.x.x or similar

Step 2: Install FFmpeg

FFmpeg is a powerful video processing tool that handles the actual compression.

  1. Install via Homebrew: 

    brew install ffmpeg

  2. Wait 5-10 minutes for download and installation

  3. Verify installation: 

    ffmpeg -version
    Expected output: Version information (e.g., version 7.0.1 or 8.0.1)

Creating the Automator Quick Action

Step 1: Open Automator

  1. Press Cmd + Space (Spotlight Search)
  2. Type "Automator"
  3. Press Enter

Step 2: Create New Quick Action

  1. Click "New Document" (or File → New)
  2. Select "Quick Action" (gear icon)
  3. Click "Choose"

Step 3: Configure Workflow Settings

At the top of the Automator window: - "Workflow receives current" → "movie files" - "in" → "Finder" - Leave "Output replaces input" unchecked (preserves original files)

Step 4: Add Run Shell Script Action

  1. In the left sidebar, ensure you're viewing "Library" (not a specific category)
  2. Find "Run Shell Script" action:
  3. Option A: Search for it in the search box
  4. Option B: Look under the "Utilities" category
  5. Drag "Run Shell Script" into the workflow area on the right

Step 5: Configure the Shell Script

In the "Run Shell Script" action:

  1. Shell: /bin/bash
  2. Pass input: as arguments
  3. Delete the default code
  4. Paste this script:
export PATH=/usr/local/bin:/opt/homebrew/bin:$PATH

for f in "$@"
do
    filename="${f%.*}"
    output="${filename}_compressed.mp4"

    /opt/homebrew/bin/ffmpeg -i "$f" -vcodec h264 -crf 28 -preset medium -vf "scale=-2:720" -movflags +faststart "$output"
done

osascript -e 'display notification "Video compression complete!" with title "Fab Academy"'

Step 6: Save

  1. Press Cmd + S (or File → Save)
  2. Name: "Compress for Fab Academy"
  3. Saves automatically to ~/Library/Services/

Understanding the Compression Script

Script Breakdown

export PATH=/usr/local/bin:/opt/homebrew/bin:$PATH
Sets the system PATH so the script can locate FFmpeg.

for f in "$@"
do
    filename="${f%.*}"
    output="${filename}_compressed.mp4"
Loops through each selected file, strips the extension, and creates output filename.

/opt/homebrew/bin/ffmpeg -i "$f" -vcodec h264 -crf 28 -preset medium -vf "scale=-2:720" -movflags +faststart "$output"
The compression command with specific parameters (explained below).

osascript -e 'display notification "Video compression complete!" with title "Fab Academy"'
Shows a macOS notification when processing finishes.

FFmpeg Parameters Explained

Parameter Value Purpose
-i "$f" Input file Source video to compress
-vcodec h264 H.264 codec Universal video codec, plays everywhere
-crf 28 Quality level Constant Rate Factor: 18=high quality, 28=balanced, 32+=small files
-preset medium Encoding speed Balance between speed and compression efficiency
-vf "scale=-2:720" 720p height Resize to 720p, maintains aspect ratio
-movflags +faststart Streaming optimization Moves metadata to file beginning for faster web loading
"$output" Output filename Destination for compressed video

Why These Settings?

  • H.264 codec: Most compatible format, plays in all browsers
  • CRF 28: Good balance between quality and file size (70-90% reduction)
  • 720p: Sufficient resolution for documentation, significantly smaller than 1080p/4K
  • Medium preset: Reasonable compression time without excessive CPU usage
  • Fast start: Videos begin playing immediately on web pages

Usage Instructions

Single Video Compression

  1. Navigate to your video file in Finder
  2. Right-click the video (e.g., fabrication_process.MOV)
  3. Hover over "Quick Actions"
  4. Click "Compress for Fab Academy"
  5. Wait for processing (30 seconds to several minutes)
  6. Notification appears: "Video compression complete!"
  7. Compressed file appears: fabrication_process_compressed.mp4

Batch Processing Multiple Videos

  1. Select multiple video files in Finder (Cmd+Click each file)
  2. Right-click selection
  3. Quick Actions → "Compress for Fab Academy"
  4. All videos process sequentially
  5. Each compressed file appears as processing completes

Integration with Fab Academy Workflow

1. Record process on iPhone → video.MOV (450 MB)
2. Transfer to Mac via AirDrop/cable
3. Right-click → Compress for Fab Academy
4. Get video_compressed.mp4 (35 MB)
5. Add to Fab Academy repo
6. Commit and push to GitLab

Expected Results

Typical Compression Performance

Original Format Original Size Compressed Size Reduction Resolution
iPhone 4K MOV 450 MB 35 MB 92% 720p
iPhone 1080p MOV 180 MB 18 MB 90% 720p
Drone 4K MP4 800 MB 65 MB 92% 720p
Screen Recording 120 MB 12 MB 90% 720p

File Naming Convention

  • Original: milling_process.MOV
  • Compressed: milling_process_compressed.mp4
  • Both files coexist in the same folder
  • Original remains untouched as backup

Quality Assessment

Suitable for: - ✅ Fab Academy documentation pages - ✅ Process demonstrations - ✅ Machine operation videos - ✅ Web embedding - ✅ GitLab repository storage

Not ideal for: - ❌ Professional video production - ❌ Large screen presentations - ❌ Detailed close-up work requiring 4K - ❌ Archival purposes (use originals)

Troubleshooting

Quick Action Doesn't Appear in Context Menu

Solution: 1. Go to System Settings → Privacy & Security 2. Click Extensions → Finder 3. Ensure "Compress for Fab Academy" is enabled/checked 4. Restart Finder if needed (Option+Right-click Finder icon → Relaunch)

Video Compression Fails Silently

Diagnosis: Check FFmpeg installation 

ffmpeg -version

If command not found: 

brew install ffmpeg

Check Homebrew PATH: 

echo $PATH
Should include /opt/homebrew/bin

If PATH missing: 

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile
source ~/.bash_profile

Manual Test in Terminal

To diagnose issues, run compression manually:

cd ~/Desktop  # or wherever your video is
/opt/homebrew/bin/ffmpeg -i input_video.MOV -vcodec h264 -crf 28 -preset medium -vf "scale=-2:720" -movflags +faststart output_compressed.mp4

This shows error messages if something fails.

Common Error Messages

"Permission denied" - Check file isn't open in another application - Ensure you have write permissions in the folder

"Invalid codec" - FFmpeg might not be fully installed - Reinstall: brew reinstall ffmpeg

"No such file or directory" - File path contains special characters - Try moving video to Desktop and retry

Customization Options

Adjusting Video Quality

Edit the -crf value in the script:

CRF Value Quality File Size Use Case
-crf 18 Very High Larger High-quality presentations
-crf 23 High Large Important documentation
-crf 28 Good (default) Balanced General use
-crf 32 Acceptable Small Maximum compression
-crf 35 Lower Very small Quick previews

Changing Output Resolution

Edit the scale=-2:720 parameter:

-vf "scale=-2:1080"  # 1080p Full HD
-vf "scale=-2:720"   # 720p HD (default)
-vf "scale=-2:480"   # 480p SD (very small files)

Adjusting Encoding Speed

Edit the -preset value:

Preset Speed File Size CPU Usage
ultrafast Very fast Largest Low
fast Fast Large Medium
medium Balanced (default) Good Medium
slow Slower Smaller High
veryslow Very slow Smallest Very high

Recommendation: Keep medium for normal use, use slow for final documentation videos.

Example Custom Configuration

For maximum compression (smallest files): 

/opt/homebrew/bin/ffmpeg -i "$f" -vcodec h264 -crf 32 -preset slow -vf "scale=-2:480" -movflags +faststart "$output"

For higher quality documentation: 

/opt/homebrew/bin/ffmpeg -i "$f" -vcodec h264 -crf 23 -preset slow -vf "scale=-2:1080" -movflags +faststart "$output"

Why This Matters for Fab Academy

GitLab Repository Considerations

File Size Limits: - Most GitLab instances limit individual files to 100MB - Repository quotas often range from 500MB to 5GB - Uncompressed iPhone videos easily exceed these limits

Clone Performance: - Smaller repos download faster for instructors/peers - Reduces bandwidth usage on limited connections - Faster CI/CD pipeline execution

Example Impact: 

Week 1-16 documentation with 3 videos each:
- Uncompressed: 48 videos × 400MB = 19.2 GB ❌ (exceeds quota)
- Compressed: 48 videos × 30MB = 1.44 GB ✅ (well within limits)

Documentation Best Practices

Web Performance: - 720p loads quickly on documentation pages - H.264/MP4 plays natively in all browsers - Fast-start optimization enables immediate playback - Mobile-friendly file sizes

Archival Strategy: 

Keep originals on:
- External hard drive
- Cloud storage (Google Drive, iCloud)
- Personal backup

Commit to Git:
- Compressed versions only
- Optimized for web viewing
- Within size constraints

Workflow Efficiency

Time Savings: - Manual compression: ~5 minutes per video - Automated Quick Action: ~30 seconds interaction time - Batch processing: Set and forget

Consistency: - All videos use same settings - Predictable file sizes - Uniform quality across documentation

Professional Presentation: - Clean, consistent video formats - Fast-loading documentation pages - No broken/missing videos due to size issues

Real-World Fab Academy Scenario

Assignment: Document CNC milling process

Without compression workflow:
1. Record 10-minute process → 1.2 GB file
2. Try to commit → Git rejects (file too large)
3. Search for online converter
4. Upload to sketchy website
5. Wait for processing
6. Download result
7. Hope quality is acceptable
Total time: 20+ minutes, security concerns

With compression workflow:
1. Record 10-minute process → 1.2 GB file
2. Right-click → Compress for Fab Academy
3. Wait 2 minutes → 95 MB file
4. Commit and push successfully
Total time: 3 minutes, secure local processing

Advanced Tips

Creating Multiple Quality Profiles

You can create multiple Quick Actions with different settings:

  1. "Compress for Fab Academy (High Quality)"

  2. CRF 23, 1080p, slow preset

  3. "Compress for Fab Academy (Small)"

  4. CRF 32, 480p, fast preset

  5. "Compress for Fab Academy (Balanced)" (default)

  6. CRF 28, 720p, medium preset

Adding Progress Indication

For longer videos, modify the script to show progress:

/opt/homebrew/bin/ffmpeg -i "$f" -vcodec h264 -crf 28 -preset medium -vf "scale=-2:720" -movflags +faststart -progress pipe:1 "$output" 2>&1 | grep -oP 'frame=\K[0-9]+'

Automating Upload to GitLab

Extend the workflow to automatically stage compressed videos:

# After compression
cd /path/to/fab/academy/repo
git add "*_compressed.mp4"
osascript -e 'display notification "Ready to commit!" with title "Fab Academy"'

Summary

What You Built

A professional video compression pipeline that:

✅ Reduces video file sizes by 70-90%
✅ Maintains documentation-appropriate quality
✅ Integrates seamlessly into Finder workflow
✅ Preserves original files as backups
✅ Produces GitLab-compatible file sizes
✅ Uses industry-standard H.264/MP4 format

Setup Investment vs. Time Saved

One-time setup: ~20 minutes
Time saved per video: ~5 minutes
Break-even point: After 4 videos
Typical Fab Academy term: 40+ videos = 3+ hours saved

Key Takeaways

  1. Automation eliminates repetitive tasks - Right-click beats remembering commands
  2. Local processing is secure - No uploading to third-party services
  3. Consistency improves documentation - All videos follow same standards
  4. Preservation of originals - Non-destructive workflow maintains archives
  5. GitLab-friendly - Respects repository constraints from the start

Resources

Official Documentation

  • FFmpeg Documentation: https://ffmpeg.org/documentation.html
  • Homebrew Documentation: https://docs.brew.sh
  • Fab Academy Documentation: http://fabacademy.org

Further Learning

  • FFmpeg encoding guide: https://trac.ffmpeg.org/wiki/Encode/H.264
  • Video compression theory: Understanding codecs, bitrates, and quality metrics
  • Git LFS (Large File Storage): Alternative for managing large files in Git

Alternative Tools

If this workflow doesn't meet your needs:

  • HandBrake: GUI application for video compression
  • Compressor (Mac): Apple's professional video encoding tool
  • Adobe Media Encoder: Full-featured professional solution
  • Online tools: CloudConvert, FreeConvert (less secure, requires upload)

Changelog

Version 1.0 - February 2, 2026 - Initial documentation - Tested on MacBook Pro, macOS 14+ - FFmpeg 7.x/8.x - Homebrew 4.x

License & Attribution

This workflow and documentation created for Fab Academy 2026.

Feel free to: - Share with classmates and instructors - Adapt for your specific needs - Contribute improvements

Created by: Dorian Fritze
Fab Academy Year: 2026
Institution: [Your Fab Lab]

Questions or Issues?

If you encounter problems with this workflow:

  1. Check the Troubleshooting section
  2. Verify FFmpeg installation: ffmpeg -version
  3. Test manual compression in Terminal
  4. Contact your Fab Academy instructor
  5. Consult Fab Academy forum or Slack channel

Remember: Keep your original videos backed up separately from your Git repository!

Last updated: February 2, 2026