ffmpeg-stabilization-360

What this skill does

## CRITICAL GUIDELINES

### Windows File Path Requirements

**MANDATORY: Always Use Backslashes on Windows for File Paths**

When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).

---

## Quick Reference

| Task | Filter | Command Pattern |
|------|--------|-----------------|
| Basic stabilization | `deshake` | `-vf deshake` |
| VidStab (2-pass) | `vidstab` | See two-pass workflow |
| OpenCL stabilization | `deshake_opencl` | `-vf deshake_opencl` |
| 360 projection | `v360` | `-vf v360=e:c3x2` |
| Ken Burns effect | `zoompan` | `-vf zoompan=z='...'` |
| Lens correction | `lenscorrection` | `-vf lenscorrection=k1=...` |

## When to Use This Skill

Use for **motion correction and VR workflows**:
- Stabilizing shaky handheld footage
- Action camera (GoPro, DJI) processing
- Drone video smoothing
- 360/VR video format conversion
- Creating zoom/pan effects
- Correcting lens distortion

---

# FFmpeg Stabilization & 360 Video (2025)

Comprehensive guide to video stabilization, VR processing, and motion effects.

## Video Stabilization

### deshake - Basic Stabilization

Built-in single-pass stabilization filter.

```bash
# Basic stabilization
ffmpeg -i shaky.mp4 -vf "deshake" stable.mp4

# With custom parameters
ffmpeg -i shaky.mp4 -vf "deshake=x=-1:y=-1:w=-1:h=-1:rx=16:ry=16" stable.mp4

# Strong stabilization
ffmpeg -i shaky.mp4 -vf "deshake=rx=64:ry=64:edge=mirror" stable.mp4
```

**Parameters:**
| Parameter | Description | Default | Range |
|-----------|-------------|---------|-------|
| `x`, `y` | Motion search start | -1 (auto) | 0-width/height |
| `w`, `h` | Motion search size | -1 (auto) | 0-width/height |
| `rx`, `ry` | Maximum shift | 16 | 0-64 |
| `edge` | Edge handling | mirror | blank, original, clamp, mirror |
| `blocksize` | Block size for motion search | 8 | 4-128 |
| `contrast` | Contrast threshold | 125 | 1-255 |
| `search` | Search method | exhaustive | exhaustive, less |

**Edge modes:**
- `blank` - Fill edges with black
- `original` - Keep original edge pixels
- `clamp` - Clamp to edge values
- `mirror` - Mirror edge pixels (usually best)

### deshake_opencl - GPU-Accelerated Stabilization

Faster stabilization using OpenCL.

```bash
# OpenCL stabilization
ffmpeg -i shaky.mp4 \
  -vf "hwupload,deshake_opencl,hwdownload,format=yuv420p" \
  stable.mp4

# With custom parameters
ffmpeg -i shaky.mp4 \
  -vf "hwupload,deshake_opencl=tripod=0:smooth=9:adaptive_crop=1,hwdownload,format=yuv420p" \
  stable.mp4
```

### VidStab - Professional Two-Pass Stabilization

VidStab provides the highest quality stabilization using a two-pass approach.

**Pass 1: Analyze motion**
```bash
# Analyze video and save transform data
ffmpeg -i shaky.mp4 \
  -vf "vidstabdetect=stepsize=6:shakiness=8:accuracy=9:result=transforms.trf" \
  -f null -
```

**Pass 2: Apply transforms**
```bash
# Apply stabilization with transforms
ffmpeg -i shaky.mp4 \
  -vf "vidstabtransform=input=transforms.trf:zoom=1:smoothing=30" \
  stable.mp4
```

**vidstabdetect Parameters:**
| Parameter | Description | Default | Range |
|-----------|-------------|---------|-------|
| `stepsize` | Step size for motion estimation | 6 | 1-32 |
| `shakiness` | Shakiness amount (higher = more analysis) | 5 | 1-10 |
| `accuracy` | Detection accuracy | 15 | 1-15 |
| `result` | Output transform file | transforms.trf | filename |
| `show` | Visualize detection | 0 | 0-2 |

**vidstabtransform Parameters:**
| Parameter | Description | Default | Range |
|-----------|-------------|---------|-------|
| `input` | Transform file | transforms.trf | filename |
| `smoothing` | Smoothing frames (higher = smoother) | 10 | 0-100 |
| `zoom` | Zoom percentage | 0 | -100 to 100 |
| `optzoom` | Optimal zoom calculation | 1 | 0-2 |
| `zoomspeed` | Max zoom change per frame | 0.25 | 0-5 |
| `crop` | Cropping mode | keep | keep, black |
| `relative` | Transform type | 1 | 0-1 |
| `tripod` | Tripod mode (fixed position) | 0 | 0-1 |

**Complete VidStab workflow:**
```bash
#!/bin/bash
# Professional stabilization workflow

INPUT="$1"
OUTPUT="${1%.*}_stabilized.mp4"

echo "Pass 1: Analyzing motion..."
ffmpeg -i "$INPUT" \
  -vf "vidstabdetect=stepsize=6:shakiness=8:accuracy=15:result=transforms.trf" \
  -f null -

echo "Pass 2: Applying stabilization..."
ffmpeg -i "$INPUT" \
  -vf "vidstabtransform=input=transforms.trf:smoothing=30:zoom=2:optzoom=1" \
  -c:v libx264 -crf 18 -preset slow \
  -c:a copy \
  "$OUTPUT"

rm transforms.trf
echo "Stabilized: $OUTPUT"
```

### Stabilization Comparison

| Method | Quality | Speed | GPU | Use Case |
|--------|---------|-------|-----|----------|
| `deshake` | Good | Fast | No | Quick fixes |
| `deshake_opencl` | Good | Very Fast | Yes | Quick fixes with GPU |
| `vidstab` (2-pass) | Best | Slow | No | Professional work |

---

## 360/VR Video Processing

### v360 - 360 Video Projection Conversion

Converts between various 360 video projections.

```bash
# Equirectangular to Cubemap 3x2
ffmpeg -i equirect.mp4 -vf "v360=e:c3x2" cubemap.mp4

# Equirectangular to Cubemap 6x1
ffmpeg -i equirect.mp4 -vf "v360=e:c6x1" cubemap_6x1.mp4

# Cubemap to Equirectangular
ffmpeg -i cubemap.mp4 -vf "v360=c3x2:e" equirect.mp4

# Equirectangular to EAC (YouTube format)
ffmpeg -i equirect.mp4 -vf "v360=e:eac" youtube_360.mp4

# Dual fisheye to Equirectangular
ffmpeg -i dual_fisheye.mp4 -vf "v360=dfisheye:e:ih_fov=190:iv_fov=190" equirect.mp4
```

**Input/Output Projections:**
| Code | Projection | Description |
|------|------------|-------------|
| `e` | Equirectangular | Standard 360 format (2:1 ratio) |
| `c3x2` | Cubemap 3x2 | 3 faces wide, 2 high |
| `c6x1` | Cubemap 6x1 | 6 faces in a row |
| `c1x6` | Cubemap 1x6 | 6 faces in a column |
| `eac` | Equi-Angular Cubemap | YouTube 360 format |
| `dfisheye` | Dual Fisheye | Two circular fisheye images |
| `sg` | Stereographic | Low distortion projection |
| `flat` | Flat/Rectilinear | Normal perspective view |
| `barrel` | Barrel | Barrel split |
| `fb` | Facebook | Facebook 360 format |

**Parameters:**
| Parameter | Description | Example |
|-----------|-------------|---------|
| `id_fov` | Input diagonal FOV | `id_fov=195` |
| `ih_fov`, `iv_fov` | Input H/V FOV | `ih_fov=190:iv_fov=190` |
| `yaw`, `pitch`, `roll` | Rotation angles | `yaw=90:pitch=0` |
| `w`, `h` | Output size | `w=4096:h=2048` |
| `interp` | Interpolation | `nearest`, `linear`, `cubic`, `lanczos` |

### 360 Video Rotation and Reframing

```bash
# Rotate 360 video 90 degrees
ffmpeg -i input_360.mp4 -vf "v360=e:e:yaw=90" rotated.mp4

# Tilt view up
ffmpeg -i input_360.mp4 -vf "v360=e:e:pitch=-30" tilted.mp4

# Extract flat view from 360
ffmpeg -i 360_video.mp4 \
  -vf "v360=e:flat:h_fov=120:v_fov=90:yaw=45:pitch=-10:w=1920:h=1080" \
  flat_extract.mp4
```

### Stereoscopic 360 Processing

```bash
# Split top-bottom stereo to left eye only
ffmpeg -i stereo_tb.mp4 -vf "v360=e:e:in_stereo=tb:out_stereo=2d" left_eye.mp4

# Convert side-by-side to top-bottom
ffmpeg -i stereo_sbs.mp4 -vf "v360=e:e:in_stereo=sbs:out_stereo=tb" stereo_tb.mp4
```

---

## Ken Burns and Zoom Effects

### zoompan - Pan and Zoom Animation

Creates Ken Burns style effects on still images or video.

```bash
# Basic zoom in on center
ffmpeg -loop 1 -i image.jpg -t 5 \
  -vf "zoompan=z='min(zoom+0.001,1.5)':d=125" \
  -c:v libx264 zoom_in.mp4

# Zoom in from top-left to center
ffmpeg -loop 1 -i image.jpg -t 5 \
  -vf "zoompan=z='min(zoom+0.001,1.5)':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=125:s=1920x1080" \
  ken_burns.mp4

# Pan across image
ffmpeg -loop 1 -i image.jpg -t 10 \
  -vf "zoompan=z=1.3:x='if(gte(x,iw-iw/zoom),0,x+1)':y='ih/2-(ih/zoom/2)':d=1:s=1920x1080" \
  pan.mp4

# Zoom out
ffmpeg -loo