8000 Merge remote-tracking branch 'origin/master' into black · Powercoder64/ffmpeg-python@fff79e6 · GitHub
[go: up one dir, main page]

Skip to content

Commit fff79e6

Browse files
committed
Merge remote-tracking branch 'origin/master' into black
Conflicts: setup.py
2 parents 46eeb41 + 1b26342 commit fff79e6

File tree

2 files changed

+105
-32
lines changed

2 files changed

+105
-32
lines changed

README.md

Lines changed: 104 additions & 31 deletions
72
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,10 @@ import ffmpeg
3232
)
3333
```
3434

35+
## [API reference](https://kkroening.github.io/ffmpeg-python/)
36+
3537
## Complex filter graphs
36-
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.
3739

3840
Take for example a signal graph that looks like this:
3941

@@ -49,7 +51,7 @@ ffmpeg -i input.mp4 -i overlay.png -filter_complex "[0]trim=start_frame=10:end_f
4951

5052
Maybe this looks great to you, but if you're not an FFmpeg command-line expert, it probably looks alien.
5153

52-
If you're like me and find Python to be powerful and readable, it's easy with `ffmpeg-python`:
54+
If you're like me and find Python to be powerful and readable, it's easier with `ffmpeg-python`:
5355
```python
5456
import ffmpeg
5557

@@ -68,28 +70,24 @@ overlay_file = ffmpeg.input('overlay.png')
6870
)
6971
```
70

71-
`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.
7274

7375
<img src="https://raw.githubusercontent.com/kkroening/ffmpeg-python/master/doc/screenshot.png" alt="Screenshot" align="middle" width="60%" />
7476

75-
Real-world signal graphs can get a heck of a lot more complex, but `ffmpeg-python` handles them with ease.
76-
77+
Real-world signal graphs can get a heck of a lot more complex, but `ffmpeg-python` handles arbitrarily large (directed-acyclic) signal graphs.
7778

7879
## Installation
7980

80-
The latest version of `ffmpeg-python` can be acquired via pip:
81+
The latest version of `ffmpeg-python` can be acquired via a typical pip install:
8182

8283
```
8384
pip install ffmpeg-python
8485
```
8586

86-
It's also possible to clone the source and put it on your python path (`$PYTHONPATH`, `sys.path`, etc.):
87-
87+
Or the source can be cloned and installed from locally:
8888
```bash
89-
$ git clone git@github.com:kkroening/ffmpeg-python.git
90-
$ export PYTHONPATH=${PYTHONPATH}:ffmpeg-python
91-
$ python
92-
>>> import ffmpeg
89+
git clone git@github.com:kkroening/ffmpeg-python.git
90+
pip install -e ./ffmpeg-python
9391
```
9492

9593
## [Examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples)
@@ -111,20 +109,9 @@ Here are a few:
111109

112110
See the [Examples README](https://github.com/kkroening/ffmpeg-python/tree/master/examples) for additional examples.
113111

114-
## [API Reference](https://kkroening.github.io/ffmpeg-python/)
115-
116-
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-
125112
## Custom Filters
126113

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:
128115
```python
129116
stream = ffmpeg.input('dummy.mp4')
130117
stream = ffmpeg.filter(stream, 'fps', fps=25, round='up')
@@ -143,27 +130,111 @@ Or fluently:
143130
)
144131
```
145132

146-
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:
147136
```python
148137
(
149138
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')
152172
.run()
153173
)
154174
```
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 />
155190

156191
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).
157192

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.
214+
158215
## Contributing
159216

160217
<img align="right" src="https://raw.githubusercontent.com/kkroening/ffmpeg-python/master/doc/logo.png" alt="ffmpeg-python logo" width="20%" />
161218

162-
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.
163224

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.
165226

166-
Pull requests are welcome as well.
227+
### Running tests
228+
229+
```bash
230+
git clone git@github.com:kkroening/ffmpeg-python.git
231+
cd ffmpeg-python
232+
virtualenv venv
233+
. venv/bin/activate # (OS X / Linux)
234+
venv\bin\activate # (Windows)
235+
pip install -e .[dev]
236+
pytest
237+
```
167238

168239
<br />
169240

@@ -177,9 +248,11 @@ Pull requests are welcome as well.
177248
## Additional Resources
178249

179250
- [API Reference](https://kkroening.github.io/ffmpeg-python/)
251+
- [Examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples)
180252
- [Filters](https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_filters.py)
181-
- [Tests](https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/tests/test_ffmpeg.py)
182253
- [FFmpeg Homepage](https://ffmpeg.org/)
183254
- [FFmpeg Documentation](https://ffmpeg.org/ffmpeg.html)
184255
- [FFmpeg Filters Documentation](https://ffmpeg.org/ffmpeg-filters.html)
256+
- [Test cases](https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/tests/test_ffmpeg.py)
257+
- [Issue tracker](https://github.com/kkroening/ffmpeg-python/issues)
185258
- Matrix Chat: [#ffmpeg-python:matrix.org](https://riot.im/app/#/room/#ffmpeg-python:matrix.org)

setup.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
from setuptools import setup
22
from textwrap import dedent
33

4-
version = '0.1.17'
4+
version = '0.1.18'
55
download_url = 'https://github.com/kkroening/ffmpeg-python/archive/v{}.zip'.format(
66
version
77
)

0 commit comments

Comments
 (0)
0