archy-demo/neode-ui/VIDEO_COMPRESSION_GUIDE.md

Video Compression Guide for Web

Current Video Status

• File: public/assets/video/video-intro.mp4
• Size: ~1MB (optimized - 95%+ reduction from original 36MB)
• Usage: Background video for Welcome Noderunner screen and onboarding/login
• Format: MP4 (H.264 compatible)
• Last Updated: December 26, 2025 (16:35)
• Optimization: CRF 32, 1280x720, 30fps (web-optimized for fast loading)

Recommended Compression

Target File Size

• Ideal: 2-5MB for web
• Maximum: 8MB (still acceptable but slower loading)
• Current: 16MB (too large, needs compression)

Recommended Settings

Using FFmpeg (Recommended)

# Install FFmpeg (if not installed)
# macOS: brew install ffmpeg
# Linux: sudo apt install ffmpeg
# Windows: Download from https://ffmpeg.org/download.html

# Compress video with H.264 codec (best browser compatibility)
ffmpeg -i video-intro.mp4 \
  -c:v libx264 \
  -preset slow \
  -crf 28 \
  -c:a aac \
  -b:a 128k \
  -movflags +faststart \
  -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" \
  video-intro-compressed.mp4

# For even smaller file (more aggressive compression)
ffmpeg -i video-intro.mp4 \
  -c:v libx264 \
  -preset slow \
  -crf 32 \
  -c:a aac \
  -b:a 96k \
  -movflags +faststart \
  -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2" \
  video-intro-compressed-small.mp4

Using HandBrake (GUI Tool)

1. Download HandBrake: https://handbrake.fr/
2. Open your video file
3. Preset: Web/Google Gmail Large 3 Minutes 720p30
4. Adjust settings:
   • Video Codec: H.264 (x264)
   • Framerate: Same as source (or 30fps)
   • Quality: RF 28-32 (higher = smaller file, lower quality)
   • Resolution: 1920x1080 or 1280x720
   • Audio: AAC, 128kbps or 96kbps
5. Check "Web Optimized" checkbox
6. Start encoding

Using Online Tools

• CloudConvert: https://cloudconvert.com/mp4-compressor
• FreeConvert: https://www.freeconvert.com/video-compressor
• Clideo: https://clideo.com/compress-video

FFmpeg Parameter Explanation

• -c:v libx264: Use H.264 video codec (best browser support)
• -preset slow: Better compression (slower encoding, smaller file)
• -crf 28: Quality setting (18-28 = high quality, 28-32 = medium, 32+ = lower)
• -c:a aac: Audio codec
• -b:a 128k: Audio bitrate (96k-128k is fine for background music)
• -movflags +faststart: Enables progressive download (starts playing before fully downloaded)
• -vf scale=...: Resize video (1920x1080 or 1280x720 recommended)
• pad=...: Add black bars if aspect ratio doesn't match

Recommended Settings by Use Case

High Quality (5-8MB)

ffmpeg -i video-intro.mp4 \
  -c:v libx264 -preset slow -crf 24 \
  -c:a aac -b:a 128k \
  -movflags +faststart \
  -vf "scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2" \
  video-intro-hq.mp4

Balanced (2-4MB) - RECOMMENDED

ffmpeg -i video-intro.mp4 \
  -c:v libx264 -preset slow -crf 28 \
  -c:a aac -b:a 96k \
  -movflags +faststart \
  -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2" \
  video-intro-balanced.mp4

Small File (1-2MB)

ffmpeg -i video-intro.mp4 \
  -c:v libx264 -preset slow -crf 32 \
  -c:a aac -b:a 64k \
  -movflags +faststart \
  -vf "scale=854:480:force_original_aspect_ratio=decrease,pad=854:480:(ow-iw)/2:(oh-ih)/2" \
  video-intro-small.mp4

Additional Optimizations

1. Trim Video Length

If the video is longer than needed, trim it:

# Trim to first 30 seconds
ffmpeg -i video-intro.mp4 -t 30 -c copy video-intro-trimmed.mp4

2. Reduce Frame Rate

If original is 60fps, reduce to 30fps:

ffmpeg -i video-intro.mp4 -r 30 -c:v libx264 -crf 28 video-intro-30fps.mp4

3. Create Multiple Formats (Optional)

For better browser support, create WebM version:

# WebM version (often smaller, but less browser support)
ffmpeg -i video-intro.mp4 \
  -c:v libvpx-vp9 -crf 30 -b:v 0 \
  -c:a libopus -b:a 96k \
  video-intro.webm

Then update HTML:

<video>
  <source src="/assets/video/video-intro.webm" type="video/webm">
  <source src="/assets/video/video-intro.mp4" type="video/mp4">
</video>

Testing Compression

After compression, test:

1. File size: Should be 2-5MB
2. Visual quality: Check on different screen sizes
3. Loading speed: Test on slow connections
4. Playback: Ensure smooth playback and looping

Quick Command (Copy-Paste Ready)

# Navigate to video directory
cd neode-ui/public/assets/video

# Backup original
cp video-intro.mp4 video-intro-original.mp4

# Compress (balanced quality, ~2-4MB)
ffmpeg -i video-intro.mp4 \
  -c:v libx264 -preset slow -crf 28 \
  -c:a aac -b:a 96k \
  -movflags +faststart \
  -vf "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2" \
  video-intro-compressed.mp4

# Replace original (after testing)
mv video-intro-compressed.mp4 video-intro.mp4

Browser Compatibility

• MP4 (H.264): Works in all modern browsers
• WebM (VP9): Works in Chrome, Firefox, Edge (not Safari)
• Recommendation: Use MP4 for maximum compatibility

Performance Tips

1. Preload: Add preload="metadata" to video tag (loads only metadata, not full video)
2. Poster Image: Add poster="/assets/img/bg-intro.jpg" for instant display while loading
3. Lazy Load: Consider loading video only when user reaches that screen
4. CDN: Host video on CDN for faster delivery

Current Implementation

The video is currently set to:

• autoplay: Starts automatically
• loop: Repeats continuously
• muted: Required for autoplay in most browsers
• playsinline: Prevents fullscreen on mobile

These settings are optimal for background video use.