From 49c877eec6169d7074791851912891f95a6046c7 Mon Sep 17 00:00:00 2001 From: Karl Kroening Date: Mon, 3 Jun 2019 02:42:29 -0500 Subject: [PATCH 1/6] Update README.md --- README.md | 49 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8d716cd..c146c7e 100644 --- a/README.md +++ b/README.md @@ -32,8 +32,10 @@ import ffmpeg ) ``` +## [[API reference]](https://kkroening.github.io/ffmpeg-python/) + ## Complex filter graphs -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. +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. Take for example a signal graph that looks like this: @@ -111,17 +113,6 @@ Here are a few: See the [Examples README](https://github.com/kkroening/ffmpeg-python/tree/master/examples) for additional examples. -## [API Reference](https://kkroening.github.io/ffmpeg-python/) - -API documentation is automatically generated from python docstrings and hosted on github pages: https://kkroening.github.io/ffmpeg-python/ - -Alternatively, standard python help is available, such as at the python REPL prompt as follows: - -```python ->>> import ffmpeg ->>> help(ffmpeg) -``` - ## Custom Filters 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: @@ -155,15 +146,39 @@ Arguments with special names such as `-qscale:v` can be specified as a keyword-a 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). +## Frequently asked questions + +**Why do I get an import/attribute/etc error from `import ffmpeg`?* + +Make sure you ran `pip install ffmpeg-python` and not `pip install ffmpeg` or `pip install python-ffmpeg`. + +**How do I do XYZ?** + +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. + +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. + +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. + +**Why did my audio stream get dropped?** + +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. + +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. + +As usual, take a look at the [Examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples#audiovideo-pipeline) (the "Audio/video pipeline" example in particular). + ## Contributing ffmpeg-python logo -Feel free to report any bugs or submit feature requests. +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 eventually incorporated into the documentation, examples, and other learning resources. -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). +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. -Pull requests are welcome as well. +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. + +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.
@@ -177,9 +192,11 @@ Pull requests are welcome as well. ## Additional Resources - [API Reference](https://kkroening.github.io/ffmpeg-python/) +- [Examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples) - [Filters](https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/_filters.py) -- [Tests](https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/tests/test_ffmpeg.py) - [FFmpeg Homepage](https://ffmpeg.org/) - [FFmpeg Documentation](https://ffmpeg.org/ffmpeg.html) - [FFmpeg Filters Documentation](https://ffmpeg.org/ffmpeg-filters.html) +- [Test cases](https://github.com/kkroening/ffmpeg-python/blob/master/ffmpeg/tests/test_ffmpeg.py) +- [Issue tracker](https://github.com/kkroening/ffmpeg-python/issues) - Matrix Chat: [#ffmpeg-python:matrix.org](https://riot.im/app/#/room/#ffmpeg-python:matrix.org) From 411b0a14ffdd7999e1984bfa53de966e3a2ac81a Mon Sep 17 00:00:00 2001 From: Karl Kroening Date: Mon, 3 Jun 2019 02:43:04 -0500 Subject: [PATCH 2/6] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c146c7e..9f28f40 100644 --- a/README.md +++ b/README.md @@ -148,7 +148,7 @@ When in doubt, refer to the [existing filters](https://github.com/kkroening/ffmp ## Frequently asked questions -**Why do I get an import/attribute/etc error from `import ffmpeg`?* +**Why do I get an import/attribute/etc error from `import ffmpeg`?** Make sure you ran `pip install ffmpeg-python` and not `pip install ffmpeg` or `pip install python-ffmpeg`. From bde72f4124af50a82d8c6d1609d54beb722748ff Mon Sep 17 00:00:00 2001 From: Karl Kroening Date: Mon, 3 Jun 2019 03:09:27 -0500 Subject: [PATCH 3/6] Update README.md --- README.md | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 9f28f40..7cf367b 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ import ffmpeg ) ``` -## [[API reference]](https://kkroening.github.io/ffmpeg-python/) +## [API reference](https://kkroening.github.io/ffmpeg-python/) ## Complex filter graphs 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. @@ -51,7 +51,7 @@ ffmpeg -i input.mp4 -i overlay.png -filter_complex "[0]trim=start_frame=10:end_f Maybe this looks great to you, but if you're not an FFmpeg command-line expert, it probably looks alien. -If you're like me and find Python to be powerful and readable, it's easy with `ffmpeg-python`: +If you're like me and find Python to be powerful and readable, it's easier with `ffmpeg-python`: ```python import ffmpeg @@ -70,28 +70,24 @@ overlay_file = ffmpeg.input('overlay.png') ) ``` -`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. +`ffmpeg-python` takes care of running `ffmpeg` with the command-line arguments that correspond to the above filter diagram, in familiar Python terms. Screenshot -Real-world signal graphs can get a heck of a lot more complex, but `ffmpeg-python` handles them with ease. - +Real-world signal graphs can get a heck of a lot more complex, but `ffmpeg-python` handles arbitrarily large (directed-acyclic) signal graphs. ## Installation -The latest version of `ffmpeg-python` can be acquired via pip: +The latest version of `ffmpeg-python` can be acquired via a typical pip install: ``` pip install ffmpeg-python ``` -It's also possible to clone the source and put it on your python path (`$PYTHONPATH`, `sys.path`, etc.): - +Or clone the source and install locally: ```bash -$ git clone git@github.com:kkroening/ffmpeg-python.git -$ export PYTHONPATH=${PYTHONPATH}:ffmpeg-python -$ python ->>> import ffmpeg +git clone git@github.com:kkroening/ffmpeg-python.git +pip install -e ./ffmpeg-python ``` ## [Examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples) @@ -166,7 +162,7 @@ Some ffmpeg filters drop audio streams, and care must be taken to preserve the a 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. -As usual, take a look at the [Examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples#audiovideo-pipeline) (the "Audio/video pipeline" example in particular). +As usual, take a look at the [examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples#audiovideo-pipeline) (*Audio/video pipeline* in particular). ## Contributing @@ -180,6 +176,18 @@ Pull requests are welcome as well, but it wouldn't hurt to touch base in the iss 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. +### Running tests + +```bash +git clone git@github.com:kkroening/ffmpeg-python.git +cd ffmpeg-python +virtualenv venv +. venv/bin/activate # (OS X / Linux) +venv\bin\activate # (Windows) +pip install -e .[dev] +pytest +``` +
### Special thanks From 2db3c4a3ce18151bb6c86db4f0b45ad30387dd60 Mon Sep 17 00:00:00 2001 From: Karl Kroening Date: Mon, 3 Jun 2019 03:30:04 -0500 Subject: [PATCH 4/6] Update README.md --- README.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7cf367b..7d5de40 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ The latest version of `ffmpeg-python` can be acquired via a typical pip install: pip install ffmpeg-python ``` -Or clone the source and install locally: +Or the source can be cloned and installed from locally: ```bash git clone git@github.com:kkroening/ffmpeg-python.git pip install -e ./ffmpeg-python @@ -111,7 +111,7 @@ See the [Examples README](https://github.com/kkroening/ffmpeg-python/tree/master ## Custom Filters -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: +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: ```python stream = ffmpeg.input('dummy.mp4') stream = ffmpeg.filter(stream, 'fps', fps=25, round='up') @@ -140,11 +140,23 @@ Arguments with special names such as `-qscale:v` can be specified as a keyword-a ) ``` +Filters that take multiple input streams can be specified by passing the input streams as an array to `ffmpeg.filter`: +```python +main = ffmpeg.input('main.mp4') +logo = ffmpeg.input('logo.png') +stream = ( + ffmpeg + .filter([main, logo], 'overlay', 10, 10) + .output('out.mp4') + .run() +) +``` + 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). ## Frequently asked questions -**Why do I get an import/attribute/etc error from `import ffmpeg`?** +**Why do I get an import/attribute/etc. error from `import ffmpeg`?** Make sure you ran `pip install ffmpeg-python` and not `pip install ffmpeg` or `pip install python-ffmpeg`. @@ -168,7 +180,7 @@ As usual, take a look at the [examples](https://github.com/kkroening/ffmpeg-pyth ffmpeg-python logo -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 eventually incorporated into the documentation, examples, and other learning resources. +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. 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. From a1e1f30a9933212f29f0333a6a6e6ba107e99707 Mon Sep 17 00:00:00 2001 From: Karl Kroening Date: Mon, 3 Jun 2019 03:52:07 -0500 Subject: [PATCH 5/6] Update README.md --- README.md | 62 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 49 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 7d5de40..d6efba4 100644 --- a/README.md +++ b/README.md @@ -130,21 +130,25 @@ Or fluently: ) ``` -Arguments with special names such as `-qscale:v` can be specified as a keyword-args dictionary as follows: +**Special option names:** + +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: ```python ( ffmpeg - .input('dummy.mp4') - .output('dummy2.mp4', **{'qscale:v': 3}) + .input('in.mp4') + .output('out.mp4', **{'qscale:v': 3}) .run() ) ``` -Filters that take multiple input streams can be specified by passing the input streams as an array to `ffmpeg.filter`: +**Multiple inputs:** + +Filters that take multiple input streams can be used by passing the input streams as an array to `ffmpeg.filter`: ```python main = ffmpeg.input('main.mp4') logo = ffmpeg.input('logo.png') -stream = ( +( ffmpeg .filter([main, logo], 'overlay', 10, 10) .output('out.mp4') @@ -152,6 +156,38 @@ stream = ( ) ``` +**Multiple outputs:** + +Filters that produce multiple outputs can be used with `.filter_multi_output`: +```python +split = ( + ffmpeg + .input('in.mp4') + .filter_multi_output('split') # or `.split()` +) +( + ffmpeg + .concat(split[0], split[1].reverse()) + .output('out.mp4') + .run() +) +``` +(In this particular case, `.split()` is the equivalent shorthand, but the general approach works for other multi-output filters) + +**String expressions:** + +Expressions to be interpreted by ffmpeg can be included as string parameters and reference any special ffmpeg variable names: +```python +( + ffmpeg + .input('in.mp4') + .filter('crop', 'in_w-2*10', 'in_h-2*20') + .input('out.mp4') +) +``` + +
+ 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). ## Frequently asked questions @@ -160,14 +196,6 @@ When in doubt, refer to the [existing filters](https://github.com/kkroening/ffmp Make sure you ran `pip install ffmpeg-python` and not `pip install ffmpeg` or `pip install python-ffmpeg`. -**How do I do XYZ?** - -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. - -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. - -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. - **Why did my audio stream get dropped?** 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. @@ -176,6 +204,14 @@ This dilemma is intrinsic to ffmpeg, and ffmpeg-python tries to stay out of the As usual, take a look at the [examples](https://github.com/kkroening/ffmpeg-python/tree/master/examples#audiovideo-pipeline) (*Audio/video pipeline* in particular). +**How do I do XYZ?** + +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. + +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. + +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. + ## Contributing ffmpeg-python logo From 1b2634291d9694ed5b8acb4f6567e43123a2f637 Mon Sep 17 00:00:00 2001 From: Karl Kroening Date: Mon, 3 Jun 2019 04:06:26 -0500 Subject: [PATCH 6/6] Release 0.1.18 --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 8d54b9d..e57a63c 100644 --- a/setup.py +++ b/setup.py @@ -1,7 +1,7 @@ from setuptools import setup from textwrap import dedent -version = '0.1.17' +version = '0.1.18' download_url = 'https://github.com/kkroening/ffmpeg-python/archive/v{}.zip'.format(version) long_description = dedent("""\