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.