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)

```bash
# 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)
```bash
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**
```bash
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)
```bash
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:
```bash
# 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:
```bash
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:
```bash
# 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:
```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)

```bash
# 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.