0
# Video Filters
1

2
Essential video processing filters including geometric transformations, visual effects, overlays, cropping, and drawing operations for comprehensive video manipulation.
3

4
## Capabilities
5

6
### Geometric Transformations
7

8
Basic video transformations for flipping and rotating video content.
9

10
```python { .api }
11
def hflip(stream) -> Stream:
12
    """
13
    Flip the input video horizontally.
14
    
15
    Parameters:
16
    - stream: Stream, input video stream
17
    
18
    Returns:
19
    Stream object with horizontal flip applied
20
    """
21

22
def vflip(stream) -> Stream:
23
    """
24
    Flip the input video vertically.
25
    
26
    Parameters:
27
    - stream: Stream, input video stream
28
    
29
    Returns:
30
    Stream object with vertical flip applied
31
    """
32
```
33

34
**Usage Example:**
35
```python
36
# Horizontal flip
37
flipped = ffmpeg.input('input.mp4').hflip()
38

39
# Vertical flip
40
vertically_flipped = ffmpeg.input('input.mp4').vflip()
41

42
# Both flips (180-degree rotation)
43
rotated = ffmpeg.input('input.mp4').hflip().vflip()
44
```
45

46
### Video Cropping
47

48
Extract specific rectangular regions from video frames.
49

50
```python { .api }
51
def crop(stream, x: int, y: int, width: int, height: int, **kwargs) -> Stream:
52
    """
53
    Crop the input video to a rectangular region.
54
    
55
    Parameters:
56
    - stream: Stream, input video stream
57
    - x: int, horizontal position of left edge in input video
58
    - y: int, vertical position of top edge in input video  
59
    - width: int, width of output video (must be > 0)
60
    - height: int, height of output video (must be > 0)
61
    - Additional FFmpeg crop filter options as keyword arguments
62
    
63
    Returns:
64
    Stream object with cropping applied
65
    """
66
```
67

68
**Usage Example:**
69
```python
70
# Crop to center 640x480 region of 1920x1080 video
71
cropped = ffmpeg.input('fullhd.mp4').crop(640, 300, 640, 480)
72

73
# Top-left corner crop
74
corner = ffmpeg.input('input.mp4').crop(0, 0, 320, 240)
75
```
76

77
### Video Overlays
78

79
Composite multiple video streams by overlaying one video on top of another.
80

81
```python { .api }
82
def overlay(main_stream, overlay_stream, eof_action: str = 'repeat', **kwargs) -> Stream:
83
    """
84
    Overlay one video on top of another.
85
    
86
    Parameters:
87
    - main_stream: Stream, main background video
88
    - overlay_stream: Stream, video to overlay on top
89
    - eof_action: str, action when overlay ends ('repeat', 'endall', 'pass')
90
    - x: int/str, x position expression for overlay (default: 0)
91
    - y: int/str, y position expression for overlay (default: 0)
92
    - eval: str, when to evaluate position expressions ('init', 'frame')
93
    - shortest: int, terminate when shortest input ends (0/1)
94
    - format: str, output pixel format ('yuv420', 'yuv422', 'yuv444', 'rgb', 'gbrp')
95
    - repeatlast: int, repeat last overlay frame (0/1, default: 1)
96
    
97
    Returns:
98
    Stream object with overlay applied
99
    """
100
```
101

102
**Usage Example:**
103
```python
104
main_video = ffmpeg.input('background.mp4')
105
watermark = ffmpeg.input('logo.png')
106

107
# Simple overlay at top-left
108
overlaid = main_video.overlay(watermark)
109

110
# Positioned overlay with transparency
111
positioned = main_video.overlay(
112
    watermark,
113
    x=10,
114
    y=10,
115
    eof_action='pass'
116
)
117

118
# Complex positioning using expressions
119
centered = main_video.overlay(
120
    watermark,
121
    x='(main_w-overlay_w)/2',
122
    y='(main_h-overlay_h)/2'
123
)
124
```
125

126
### Drawing Operations
127

128
Add graphical elements like boxes and text directly onto video frames.
129

130
```python { .api }
131
def drawbox(stream, x: int, y: int, width: int, height: int, color: str, thickness: int = None, **kwargs) -> Stream:
132
    """
133
    Draw a colored box on the input video.
134
    
135
    Parameters:
136
    - stream: Stream, input video stream
137
    - x: int, x coordinate of box top-left corner
138
    - y: int, y coordinate of box top-left corner  
139
    - width: int, box width (0 = input width)
140
    - height: int, box height (0 = input height)
141
    - color: str, box color (color name, hex, or 'invert')
142
    - thickness: int, box edge thickness (default: 3)
143
    - w: int, alias for width
144
    - h: int, alias for height
145
    - c: str, alias for color
146
    - t: int, alias for thickness
147
    
148
    Returns:
149
    Stream object with box drawn
150
    """
151

152
def drawtext(stream, text: str = None, x: int = 0, y: int = 0, escape_text: bool = True, **kwargs) -> Stream:
153
    """
154
    Draw text string on top of video using libfreetype.
155
    
156
    Parameters:
157
    - stream: Stream, input video stream
158
    - text: str, text to draw (required if textfile not specified)
159
    - x: int, x position for text (default: 0)
160
    - y: int, y position for text (default: 0)
161
    - escape_text: bool, automatically escape special characters
162
    - textfile: str, file containing text to draw
163
    - fontfile: str, path to font file
164
    - font: str, font family name (default: Sans)
165
    - fontsize: int, font size in points (default: 16)
166
    - fontcolor: str, text color (default: black)
167
    - box: int, draw background box (0/1)
168
    - boxcolor: str, background box color (default: white)
169
    - boxborderw: int, box border width
170
    - shadowcolor: str, text shadow color (default: black)
171
    - shadowx: int, shadow x offset (default: 0)
172
    - shadowy: int, shadow y offset (default: 0)
173
    - alpha: float, text transparency (0.0-1.0, default: 1.0)
174
    
175
    Returns:
176
    Stream object with text drawn
177
    """
178
```
179

180
**Usage Example:**
181
```python
182
# Draw red box
183
boxed = ffmpeg.input('input.mp4').drawbox(50, 50, 200, 100, 'red', thickness=3)
184

185
# Draw text with custom styling
186
texted = ffmpeg.input('input.mp4').drawtext(
187
    'Hello World',
188
    x=10,
189
    y=10,
190
    fontsize=24,
191
    fontcolor='white',
192
    box=1,
193
    boxcolor='black@0.5'
194
)
195

196
# Dynamic text with expressions
197
dynamic_text = ffmpeg.input('input.mp4').drawtext(
198
    'Frame: %{n}',
199
    x='(w-text_w)/2',
200
    y='h-th-10',
201
    fontsize=20,
202
    fontcolor='yellow'
203
)
204
```
205

206
### Special Effects
207

208
Advanced video effects for creative processing.
209

210
```python { .api }
211
def zoompan(stream, **kwargs) -> Stream:
212
    """
213
    Apply zoom and pan effects to video.
214
    
215
    Parameters:
216
    - stream: Stream, input video stream
217
    - zoom: str, zoom expression (default: 1)
218
    - x: str, x position expression (default: 0)
219
    - y: str, y position expression (default: 0)
220
    - d: str, duration in frames for effect
221
    - s: str, output size (default: hd720)
222
    - fps: int, output frame rate (default: 25)
223
    - z: str, alias for zoom
224
    
225
    Returns:
226
    Stream object with zoom/pan applied
227
    """
228

229
def hue(stream, **kwargs) -> Stream:
230
    """
231
    Modify hue and saturation of input video.
232
    
233
    Parameters:
234
    - stream: Stream, input video stream
235
    - h: str, hue angle in degrees (default: 0)
236
    - s: str, saturation multiplier -10 to 10 (default: 1)
237
    - H: str, hue angle in radians (default: 0)  
238
    - b: str, brightness -10 to 10 (default: 0)
239
    
240
    Returns:
241
    Stream object with hue/saturation modified
242
    """
243

244
def colorchannelmixer(stream, *args, **kwargs) -> Stream:
245
    """
246
    Adjust video by re-mixing color channels.
247
    
248
    Parameters:
249
    - stream: Stream, input video stream
250
    - Color channel mixing parameters as keyword arguments
251
    
252
    Returns:
253
    Stream object with color channels adjusted
254
    """
255
```
256

257
**Usage Example:**
258
```python
259
# Zoom in slowly
260
zoomed = ffmpeg.input('input.mp4').zoompan(
261
    zoom='min(zoom+0.0015,1.5)',
262
    d=125
263
)
264

265
# Adjust hue and saturation
266
color_adjusted = ffmpeg.input('input.mp4').hue(h=30, s=1.2)
267

268
# Advanced color mixing
269
mixed = ffmpeg.input('input.mp4').colorchannelmixer(
270
    rr=0.393, rg=0.769, rb=0.189,
271
    gr=0.349, gg=0.686, gb=0.168,
272
    br=0.272, bg=0.534, bb=0.131
273
)
274
```
275

276
## Complex Filter Chains
277

278
Video filters can be chained together for sophisticated processing:
279

280
```python
281
# Complex video processing pipeline
282
result = (
283
    ffmpeg
284
    .input('input.mp4')
285
    .crop(100, 100, 800, 600)
286
    .hflip()
287
    .drawtext('Processed Video', x=10, y=10, fontsize=20, fontcolor='white')
288
    .hue(s=1.2)
289
    .output('processed.mp4')
290
)
291
```