You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
FFmpeg is extremely powerful, but its command-line interface gets really complicated really quickly - especially when working with signal graphs and doing anything more than trivial.
38
+
FFmpeg is extremely powerful, but its command-line interface gets really complicated rather quickly - especially when working with signal graphs and doing anything more than trivial.
37
39
38
40
Take for example a signal graph that looks like this:
`ffmpeg-python` takes care of running `ffmpeg` with the command-line arguments that correspond to the above filter diagram, and it's easy to see what's going on and make changes as needed.
73
+
`ffmpeg-python` takes care of running `ffmpeg` with the command-line arguments that correspond to the above filter diagram, in familiar Python terms.
API documentation is automatically generated from python docstrings and hosted on github pages: https://kkroening.github.io/ffmpeg-python/
117
-
118
-
Alternatively, standard python help is available, such as at the python REPL prompt as follows:
119
-
120
-
```python
121
-
>>>import ffmpeg
122
-
>>>help(ffmpeg)
123
-
```
124
-
125
112
## Custom Filters
126
113
127
-
Don't see the filter you're looking for? `ffmpeg-python` includes shorthand notation for some of the most commonly used filters (such as `concat`), but it's easy to use any arbitrary ffmpeg filter:
114
+
Don't see the filter you're looking for? While `ffmpeg-python` includes shorthand notation for some of the most commonly used filters (such as `concat`), all filters can be referenced via the `.filter` operator:
Arguments with special names such as `-qscale:v` can be specified as a keyword-args dictionary as follows:
133
+
**Special option names:**
134
+
135
+
Arguments with special names such as `-qscale:v` (variable bitrate), `-b:v` (constant bitrate), etc. can be specified as a keyword-args dictionary as follows:
147
136
```python
148
137
(
149
138
ffmpeg
150
-
.input('dummy.mp4')
151
-
.output('dummy2.mp4', **{'qscale:v': 3})
139
+
.input('in.mp4')
140
+
.output('out.mp4', **{'qscale:v': 3})
141
+
.run()
142
+
)
143
+
```
144
+
145
+
**Multiple inputs:**
146
+
147
+
Filters that take multiple input streams can be used by passing the input streams as an array to `ffmpeg.filter`:
148
+
```python
149
+
main = ffmpeg.input('main.mp4')
150
+
logo = ffmpeg.input('logo.png')
151
+
(
152
+
ffmpeg
153
+
.filter([main, logo], 'overlay', 10, 10)
154
+
.output('out.mp4')
155
+
.run()
156
+
)
157
+
```
158
+
159
+
**Multiple outputs:**
160
+
161
+
Filters that produce multiple outputs can be used with `.filter_multi_output`:
162
+
```python
163
+
split = (
164
+
ffmpeg
165
+
.input('in.mp4')
166
+
.filter_multi_output('split') # or `.split()`
167
+
)
168
+
(
169
+
ffmpeg
170
+
.concat(split[0], split[1].reverse())
171
+
.output('out.mp4')
152
172
.run()
153
173
)
154
174
```
175
+
(In this particular case, `.split()` is the equivalent shorthand, but the general approach works for other multi-output filters)
176
+
177
+
**String expressions:**
178
+
179
+
Expressions to be interpreted by ffmpeg can be included as string parameters and reference any special ffmpeg variable names:
180
+
```python
181
+
(
182
+
ffmpeg
183
+
.input('in.mp4')
184
+
.filter('crop', 'in_w-2*10', 'in_h-2*20')
185
+
.input('out.mp4')
186
+
)
187
+
```
188
+
189
+
<br />
155
190
156
191
When in doubt, refer to the [existing filters](https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_filters.py), [examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples), and/or the [official ffmpeg documentation](https://ffmpeg.org/ffmpeg-filters.html).
157
192
193
+
## Frequently asked questions
194
+
195
+
**Why do I get an import/attribute/etc. error from `import ffmpeg`?**
196
+
197
+
Make sure you ran `pip install ffmpeg-python` and not `pip install ffmpeg` or `pip install python-ffmpeg`.
198
+
199
+
**Why did my audio stream get dropped?**
200
+
201
+
Some ffmpeg filters drop audio streams, and care must be taken to preserve the audio in the final output. The ``.audio`` and ``.video`` operators can be used to reference the audio/video portions of a stream so that they can be processed separately and then re-combined later in the pipeline.
202
+
203
+
This dilemma is intrinsic to ffmpeg, and ffmpeg-python tries to stay out of the way while users may refer to the official ffmpeg documentation as to why certain filters drop audio.
204
+
205
+
As usual, take a look at the [examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples#audiovideo-pipeline) (*Audio/video pipeline* in particular).
206
+
207
+
**How do I do XYZ?**
208
+
209
+
Take a look at each of the links in the [Additional Resources](https://kkroening.github.io/ffmpeg-python/) section at the end of this README. If you look everywhere and can't find what you're looking for and have a question that may be relevant to other users, you may open an issue asking how to do it, while providing a thorough explanation of what you're trying to do and what you've tried so far.
210
+
211
+
Issues not directly related to `ffmpeg-python` or issues asking others to write your code for you or how to do the work of solving a complex signal processing problem for you that's not relevant to other users will be closed.
212
+
213
+
That said, we hope to continue improving our documentation and provide a community of support for people using `ffmpeg-python` to do cool and exciting things.
Feel free to report any bugs or submit feature requests.
219
+
One of the best things you can do to help make `ffmpeg-python` better is to answer [open questions](https://github.com/kkroening/ffmpeg-python/labels/question) in the issue tracker. The questions that are answered will be tagged and incorporated into the documentation, examples, and other learning resources.
220
+
221
+
If you notice things that could be better in the documentation or overall development experience, please say so in the [issue tracker](https://github.com/kkroening/ffmpeg-python/issues). And of course, feel free to report any bugs or submit feature requests.
222
+
223
+
Pull requests are welcome as well, but it wouldn't hurt to touch base in the issue tracker or hop on the [Matrix chat channel](https://riot.im/app/#/room/#ffmpeg-python:matrix.org) first.
163
224
164
-
It's generally straightforward to use filters that aren't explicitly built into `ffmpeg-python` but if there's a feature you'd like to see included in the library, head over to the [issue tracker](https://github.com/kkroening/ffmpeg-python/issues).
225
+
Anyone who fixes any of the [open bugs](https://github.com/kkroening/ffmpeg-python/labels/bug) or implements [requested enhancements](https://github.com/kkroening/ffmpeg-python/labels/enhancement) is a hero, but changes should include passing tests.
0 commit comments