ffmpeg-deinterlacing-telecine

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 deinterlace | `yadif` | `-vf yadif` |
| High quality deinterlace | `bwdif` | `-vf bwdif` |
| CUDA deinterlace | `yadif_cuda` | `-vf yadif_cuda` |
| Inverse telecine | `pullup` | `-vf pullup` |
| Field order | `fieldorder` | `-vf fieldorder=tff` |
| Detect interlace | `idet` | `-vf idet` |

## When to Use This Skill

Use for **interlaced and telecined content**:
- Converting broadcast/TV content to progressive
- DVD and Blu-ray processing
- Legacy video digitization
- Professional video production
- Field order correction
- Telecine removal (3:2 pulldown)

---

# FFmpeg Deinterlacing & Telecine (2025)

Comprehensive guide to deinterlacing, field processing, and telecine removal.

## Understanding Interlaced Video

### What is Interlacing?

Interlaced video stores two half-resolution fields per frame:
- **Top Field (TFF)**: Odd lines (1, 3, 5, ...)
- **Bottom Field (BFF)**: Even lines (2, 4, 6, ...)

Common interlaced formats:
- 1080i (1920x1080, 50i or 60i)
- 576i (720x576, 50i - PAL)
- 480i (720x480, 60i - NTSC)

### Detecting Interlaced Content

```bash
# Use idet filter to detect interlacing
ffmpeg -i input.mp4 -vf "idet" -frames:v 500 -f null -

# Output shows field types:
# TFF = Top Field First
# BFF = Bottom Field First
# Progressive = Not interlaced
# Undetermined = Mixed or uncertain
```

---

## Deinterlacing Filters

### yadif - Yet Another DeInterlacing Filter

The most widely used deinterlacing filter. Good balance of speed and quality.

```bash
# Basic deinterlacing (output same frame rate)
ffmpeg -i interlaced.mp4 -vf "yadif" output.mp4

# Double frame rate (output both fields as frames)
ffmpeg -i interlaced.mp4 -vf "yadif=1" output.mp4

# Specify field parity (auto-detect by default)
ffmpeg -i interlaced.mp4 -vf "yadif=0:0:0" output.mp4  # TFF
ffmpeg -i interlaced.mp4 -vf "yadif=0:1:0" output.mp4  # BFF

# Only deinterlace if detected as interlaced
ffmpeg -i input.mp4 -vf "yadif=deint=interlaced" output.mp4
```

**Parameters:**
| Parameter | Description | Values |
|-----------|-------------|--------|
| `mode` | Output mode | 0=same fps, 1=double fps |
| `parity` | Field parity | -1=auto, 0=TFF, 1=BFF |
| `deint` | Frames to deinterlace | 0=all, 1=interlaced only |

**Mode options:**
- `0` / `send_frame` - Output one frame per input frame
- `1` / `send_field` - Output one frame per field (double fps)
- `2` / `send_frame_nospatial` - Like 0, without spatial interlacing check
- `3` / `send_field_nospatial` - Like 1, without spatial interlacing check

### bwdif - Bob Weaver Deinterlacing Filter

Higher quality than yadif, uses more frames for interpolation.

```bash
# Basic bwdif
ffmpeg -i interlaced.mp4 -vf "bwdif" output.mp4

# Double frame rate
ffmpeg -i interlaced.mp4 -vf "bwdif=1" output.mp4

# Specify parity
ffmpeg -i interlaced.mp4 -vf "bwdif=0:-1:1" output.mp4
```

**Parameters:** Same as yadif

### w3fdif - Martin Weston 3-Field Deinterlacing

Uses three fields for even higher quality interpolation.

```bash
# Simple filter (faster)
ffmpeg -i interlaced.mp4 -vf "w3fdif=filter=simple" output.mp4

# Complex filter (better quality)
ffmpeg -i interlaced.mp4 -vf "w3fdif=filter=complex" output.mp4
```

**Parameters:**
| Parameter | Description | Values |
|-----------|-------------|--------|
| `filter` | Filter coefficients | simple, complex |
| `deint` | Frames to deinterlace | all, interlaced |

### kerndeint - Kernel Deinterlacing

Adaptive kernel-based deinterlacing.

```bash
# Basic kerndeint
ffmpeg -i interlaced.mp4 -vf "kerndeint" output.mp4

# With threshold adjustment
ffmpeg -i interlaced.mp4 -vf "kerndeint=thresh=10:map=0:order=0:sharp=0:twoway=0" output.mp4
```

---

## Hardware-Accelerated Deinterlacing

### yadif_cuda - NVIDIA CUDA

```bash
# Full GPU pipeline with CUDA deinterlacing
ffmpeg -hwaccel cuda -hwaccel_output_format cuda \
  -i interlaced.mp4 \
  -vf "yadif_cuda=0:-1:0" \
  -c:v h264_nvenc output.mp4

# Double framerate with CUDA
ffmpeg -hwaccel cuda -hwaccel_output_format cuda \
  -i interlaced.mp4 \
  -vf "yadif_cuda=1" \
  -c:v h264_nvenc output.mp4
```

### bwdif_cuda - NVIDIA CUDA (FFmpeg 7.0+)

```bash
# Higher quality CUDA deinterlacing
ffmpeg -hwaccel cuda -hwaccel_output_format cuda \
  -i interlaced.mp4 \
  -vf "bwdif_cuda" \
  -c:v h264_nvenc output.mp4
```

### bwdif_vulkan - Vulkan (FFmpeg 8.0+)

Cross-platform GPU deinterlacing.

```bash
# Vulkan deinterlacing (works on AMD, Intel, NVIDIA)
ffmpeg -init_hw_device vulkan \
  -hwaccel vulkan -hwaccel_output_format vulkan \
  -i interlaced.mp4 \
  -vf "bwdif_vulkan" \
  -c:v h264_vulkan output.mp4
```

### deinterlace_vaapi - VAAPI (Linux)

```bash
# VAAPI deinterlacing
ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 \
  -hwaccel_output_format vaapi \
  -i interlaced.mp4 \
  -vf "deinterlace_vaapi" \
  -c:v h264_vaapi output.mp4

# Specify deinterlace mode
ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 \
  -hwaccel_output_format vaapi \
  -i interlaced.mp4 \
  -vf "deinterlace_vaapi=mode=motion_adaptive:rate=frame" \
  -c:v h264_vaapi output.mp4
```

**VAAPI deinterlace modes:**
- `default` - Use driver default
- `bob` - Simple bob (double rate)
- `weave` - Weave fields together
- `motion_adaptive` - Motion-adaptive (best quality)
- `motion_compensated` - Motion-compensated (highest quality)

### deinterlace_qsv - Intel QSV

```bash
# QSV deinterlacing
ffmpeg -hwaccel qsv -hwaccel_output_format qsv \
  -i interlaced.mp4 \
  -vf "vpp_qsv=deinterlace=2" \
  -c:v h264_qsv output.mp4
```

**VPP_QSV deinterlace modes:**
- `0` - Off
- `1` - Bob
- `2` - Advanced (motion adaptive)

---

## Inverse Telecine (IVTC)

### Understanding Telecine (3:2 Pulldown)

Telecine converts 24fps film to 30fps video by duplicating fields:
```yaml
Film:   A  B  C  D
Video:  AA AB BB BC CC CD DD DA
```

### pullup - Pullup Filter

Removes 3:2 telecine by detecting and removing duplicate fields.

```bash
# Basic IVTC
ffmpeg -i telecined.mp4 -vf "pullup" -r 24000/1001 output.mp4

# With metric output
ffmpeg -i telecined.mp4 -vf "pullup=mp=y" -r 24000/1001 output.mp4
```

**Parameters:**
| Parameter | Description | Values |
|-----------|-------------|--------|
| `jl`, `jr` | Left/right junk pixels | 1-width |
| `jt`, `jb` | Top/bottom junk pixels | 1-height |
| `sb` | Strict breaks | 0 or 1 |
| `mp` | Metric plane | y, u, v |

### fieldmatch - Field Matching

More advanced telecine removal with field matching.

```bash
# Basic field matching
ffmpeg -i telecined.mp4 -vf "fieldmatch" output.mp4

# Full IVTC pipeline with decimation
ffmpeg -i telecined.mp4 -vf "fieldmatch,decimate" output.mp4

# Specify field order
ffmpeg -i telecined.mp4 -vf "fieldmatch=order=tff,decimate" output.mp4
```

**Combined IVTC workflow:**
```bash
# Complete telecine removal pipeline
ffmpeg -i telecined.mp4 \
  -vf "fieldmatch=order=auto:combmatch=full,decimate" \
  -r 24000/1001 \
  output.mp4
```

### decimate - Frame Decimation

Removes duplicate frames (used after fieldmatch).

```bash
# Remove every 5th frame (30->24 fps)
ffmpeg -i input.mp4 -vf "decimate=cycle=5" output.mp4

# Detect duplicates
ffmpeg -i input.mp4 -vf "decimate=cycle=5:ppsrc=1" output.mp4
```

---

## Field Processing

### fieldorder - Change Field Order

Transforms field order between TFF and BFF.

```bash
# Convert BFF to TFF
ffmpeg -i bff_input.mp4 -vf "fieldorder=tff" output.mp4

# Convert TFF to BFF
ffmpeg -i tff_input.mp4 -vf "fieldorder=bff" output.mp4
```

### separatefields - Separate Fields

Splits each frame into two fields.

```bash
# Separate fields (doubles frame count, halves height)
ffmpeg -i interlaced.mp4 -vf "separatefields" output.mp4
```

### weave - W