0
# FFmpeg Python
1
2
Python bindings for FFmpeg with complex filtering support. FFmpeg-python provides a fluent, Pythonic interface for constructing FFmpeg command lines, enabling sophisticated video and audio processing workflows without dealing with complex command-line arguments directly.
3
4
## Package Information
5
6
- **Package Name**: ffmpeg-python
7
- **Language**: Python
8
- **Installation**: `pip install ffmpeg-python`
9
- **Dependencies**: `future` (built-in), `graphviz` (optional, for visualization)
10
11
## Core Imports
12
13
```python
14
import ffmpeg
15
```
16
17
## Basic Usage
18
19
```python
20
import ffmpeg
21
22
# Simple horizontal flip
23
(
24
ffmpeg
25
.input('input.mp4')
26
.hflip()
27
.output('output.mp4')
28
.run()
29
)
30
31
# Complex filter chain with overlay
32
in_file = ffmpeg.input('input.mp4')
33
overlay_file = ffmpeg.input('overlay.png')
34
(
35
ffmpeg
36
.concat(
37
in_file.trim(start_frame=10, end_frame=20),
38
in_file.trim(start_frame=30, end_frame=40),
39
)
40
.overlay(overlay_file.hflip())
41
.drawbox(50, 50, 120, 120, color='red', thickness=5)
42
.output('out.mp4')
43
.run()
44
)
45
46
# Get media information
47
probe_data = ffmpeg.probe('input.mp4')
48
```
49
50
## Architecture
51
52
FFmpeg-python uses a node-based architecture to represent FFmpeg command graphs:
53
54
- **Stream Objects**: Represent data flow between processing nodes
55
- **Input Nodes**: Media input sources (files, pipes, etc.)
56
- **Filter Nodes**: Video/audio processing operations
57
- **Output Nodes**: Media output destinations
58
- **DAG Structure**: Directed acyclic graph for complex filter chains
59
60
This design enables arbitrarily complex signal graphs while maintaining a readable, fluent Python interface that mirrors FFmpeg's filter graph concepts.
61
62
## Capabilities
63
64
### Input and Output Operations
65
66
Core functionality for creating input streams from media files, URLs, or pipes, and defining output destinations with format specifications and encoding parameters.
67
68
```python { .api }
69
def input(filename: str, **kwargs) -> Stream
70
def output(*streams_and_filename, **kwargs) -> Stream
71
def merge_outputs(*streams) -> Stream
72
def overwrite_output(stream) -> Stream
73
def global_args(stream, *args) -> Stream
74
```
75
76
[Input and Output Operations](./input-output.md)
77
78
### Video Filters
79
80
Essential video processing filters including geometric transformations, visual effects, overlays, cropping, and drawing operations for comprehensive video manipulation.
81
82
```python { .api }
83
def hflip(stream) -> Stream
84
def vflip(stream) -> Stream
85
def crop(stream, x: int, y: int, width: int, height: int, **kwargs) -> Stream
86
def overlay(main_stream, overlay_stream, eof_action: str = 'repeat', **kwargs) -> Stream
87
def drawbox(stream, x: int, y: int, width: int, height: int, color: str, thickness: int = None, **kwargs) -> Stream
88
def drawtext(stream, text: str = None, x: int = 0, y: int = 0, escape_text: bool = True, **kwargs) -> Stream
89
```
90
91
[Video Filters](./video-filters.md)
92
93
### Stream Processing
94
95
Advanced stream manipulation including concatenation, splitting, trimming, timestamp adjustment, and custom filter application for complex multimedia workflows.
96
97
```python { .api }
98
def concat(*streams, **kwargs) -> Stream
99
def split(stream) -> FilterNode
100
def asplit(stream) -> FilterNode
101
def trim(stream, **kwargs) -> Stream
102
def setpts(stream, expr: str) -> Stream
103
def filter(stream_spec, filter_name: str, *args, **kwargs) -> Stream
104
def filter_multi_output(stream_spec, filter_name: str, *args, **kwargs) -> FilterNode
105
```
106
107
[Stream Processing](./stream-processing.md)
108
109
### Execution and Control
110
111
Functions for executing FFmpeg commands synchronously or asynchronously, building command-line arguments, and handling process control with comprehensive error management.
112
113
```python { .api }
114
def run(stream_spec, cmd: str = 'ffmpeg', capture_stdout: bool = False, capture_stderr: bool = False, input=None, quiet: bool = False, overwrite_output: bool = False) -> tuple
115
def run_async(stream_spec, cmd: str = 'ffmpeg', pipe_stdin: bool = False, pipe_stdout: bool = False, pipe_stderr: bool = False, quiet: bool = False, overwrite_output: bool = False)
116
def compile(stream_spec, cmd: str = 'ffmpeg', overwrite_output: bool = False) -> list
117
def get_args(stream_spec, overwrite_output: bool = False) -> list
118
```
119
120
[Execution and Control](./execution.md)
121
122
### Media Analysis and Visualization
123
124
Tools for analyzing media file properties, extracting metadata, and visualizing complex filter graphs for debugging and development purposes.
125
126
```python { .api }
127
def probe(filename: str, cmd: str = 'ffprobe', **kwargs) -> dict
128
def view(stream_spec, detail: bool = False, filename: str = None, pipe: bool = False, **kwargs)
129
```
130
131
[Media Analysis and Visualization](./analysis-visualization.md)
132
133
## Exception Handling
134
135
```python { .api }
136
class Error(Exception):
137
"""Exception raised when ffmpeg/ffprobe returns non-zero exit code."""
138
stdout: bytes
139
stderr: bytes
140
```
141
142
FFmpeg-python raises `ffmpeg.Error` exceptions when FFmpeg commands fail. The exception includes both stdout and stderr output for debugging failed operations.
143
144
## Stream Object API
145
146
```python { .api }
147
class Stream:
148
"""Represents the outgoing edge of an upstream node."""
149
150
@property
151
def audio(self) -> Stream
152
"""Select audio portion of stream (shorthand for ['a'])."""
153
154
@property
155
def video(self) -> Stream
156
"""Select video portion of stream (shorthand for ['v'])."""
157
158
def __getitem__(self, index: str) -> Stream
159
"""Select stream component ('a' for audio, 'v' for video, etc.)."""
160
```
161
162
All filter functions return Stream objects that support method chaining and component selection for building complex processing pipelines.