archy-demo/neode-ui/VIDEO_OPTIMIZATION.md

Video Optimization Guide - Quality Preservation

Current Video

• File: public/assets/video/video-intro.mp4
• Size: ~36MB
• Goal: Optimize for web without losing quality

Quick Optimization

Run the optimization script:

cd neode-ui
./optimize-video.sh

This will:

1. Create a backup of the original video
2. Optimize using H.264 with CRF 18 (near-lossless)
3. Add faststart flag for web streaming
4. Replace the original with the optimized version

Manual Optimization

If you prefer to optimize manually:

Option 1: Near-Lossless (Recommended)

cd neode-ui/public/assets/video

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

# Optimize with CRF 18 (near-lossless, best quality)
ffmpeg -i video-intro.mp4 \
  -c:v libx264 \
  -preset slow \
  -crf 18 \
  -profile:v high \
  -level 4.0 \
  -pix_fmt yuv420p \
  -c:a aac \
  -b:a 128k \
  -ar 48000 \
  -movflags +faststart \
  -threads 0 \
  video-intro-optimized.mp4

# Replace original
mv video-intro-optimized.mp4 video-intro.mp4

Expected result: 15-25MB (40-60% reduction) with visually identical quality

Option 2: Lossless (Maximum Quality)

ffmpeg -i video-intro.mp4 \
  -c:v libx264 \
  -preset veryslow \
  -crf 15 \
  -profile:v high \
  -level 4.0 \
  -pix_fmt yuv420p \
  -c:a aac \
  -b:a 192k \
  -ar 48000 \
  -movflags +faststart \
  video-intro-lossless.mp4

Expected result: 20-30MB (20-40% reduction) with imperceptible quality loss

Option 3: H.265/HEVC (Better Compression, Modern Browsers)

ffmpeg -i video-intro.mp4 \
  -c:v libx265 \
  -preset slow \
  -crf 20 \
  -pix_fmt yuv420p \
  -c:a aac \
  -b:a 128k \
  -movflags +faststart \
  video-intro-hevc.mp4

Note: H.265 provides better compression but has limited browser support (Safari, Edge, Chrome on Android). Use H.264 for maximum compatibility.

Parameter Explanation

CRF (Constant Rate Factor)

• CRF 15: Visually lossless (largest file)
• CRF 18: Near-lossless (recommended, good balance)
• CRF 20: High quality (smaller file, still excellent)
• CRF 23: Good quality (noticeable but acceptable)
• Lower = Better Quality, Larger File

Preset

• veryslow: Best compression, slowest encoding
• slow: Best balance (recommended)
• medium: Faster encoding, larger file
• fast: Quick encoding, largest file

Faststart Flag

• -movflags +faststart: Moves metadata to beginning of file
• Enables progressive download (video starts playing before fully downloaded)
• Essential for web video

Profile & Level

• -profile:v high: Enables advanced H.264 features
• -level 4.0: Maximum compatibility with modern devices
• Ensures video plays on all browsers/devices

Quality Comparison

CRF	Quality	File Size	Use Case
15	Lossless	~30MB	Maximum quality needed
18	Near-lossless	~20MB	Recommended - Best balance
20	High	~15MB	Good quality, smaller file
23	Good	~10MB	Acceptable quality

Expected Results

With CRF 18 (recommended):

• Original: 36MB
• Optimized: ~18-22MB (40-50% reduction)
• Quality: Visually identical to original
• Loading: 2-3x faster on slower connections

Testing

After optimization:

1. Visual comparison: Compare original and optimized side-by-side
2. File size: Check reduction percentage
3. Loading speed: Test on slow connection (Chrome DevTools → Network → Throttling)
4. Playback: Verify smooth playback and looping

Browser Compatibility

• H.264 (MP4): Works in all modern browsers ✅
• H.265 (HEVC): Safari, Edge, Chrome Android ✅ (Chrome Desktop ❌)
• VP9 (WebM): Chrome, Firefox, Edge ✅ (Safari ❌)

Recommendation: Use H.264 for maximum compatibility.

Advanced: Two-Pass Encoding

For even better quality at same file size:

# First pass
ffmpeg -i video-intro.mp4 \
  -c:v libx264 \
  -preset slow \
  -crf 18 \
  -profile:v high \
  -level 4.0 \
  -pix_fmt yuv420p \
  -pass 1 \
  -an \
  -f null \
  /dev/null

# Second pass
ffmpeg -i video-intro.mp4 \
  -c:v libx264 \
  -preset slow \
  -crf 18 \
  -profile:v high \
  -level 4.0 \
  -pix_fmt yuv420p \
  -c:a aac \
  -b:a 128k \
  -ar 48000 \
  -movflags +faststart \
  -pass 2 \
  video-intro-optimized.mp4

Troubleshooting

"FFmpeg not found"

# macOS
brew install ffmpeg

# Linux
sudo apt install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

"Permission denied"

chmod +x optimize-video.sh

Video looks pixelated

• Use lower CRF (15-18 instead of 20+)
• Use slower preset (slow instead of medium)

File size still too large

• Use CRF 20-23 (slight quality trade-off)
• Reduce resolution if video is 4K (scale to 1920x1080)
• Reduce frame rate if 60fps (reduce to 30fps)

After Optimization

1. Update cache-busting version in code:

   • SplashScreen.vue: Change ?v=3 to ?v=4
   • OnboardingWrapper.vue: Change ?v=3 to ?v=4

2. Test the video:

   • Check playback smoothness
   • Verify looping works
   • Test on mobile devices

3. Update documentation:

   • Update VIDEO_COMPRESSION_GUIDE.md with new file size