8000 #1: update docs · Powercoder64/ffmpeg-python@8d142c5 · GitHub
[go: up one dir, main page]
Skip to content

Commit 8d142c5

Browse files
kkroeningkkroening
committed
kkroening#1: update docs
1 parent 8abe60f commit 8d142c5

File tree

9 files changed

+438
-68
lines changed

9 files changed

+438
-68
lines changed

‎doc/Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ help:
1717
# Catch-all target: route all unknown targets to Sphinx using the new
1818
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
1919
%: Makefile
20+
@rm -rf html doctrees
2021
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
2122

2223

‎doc/html/genindex.html

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ <h1 id="index">Index</h1>
5151
| <a href="#F"><strong>F</strong></a>
5252
| <a href="#G"><strong>G</strong></a>
5353
| <a href="#H"><strong>H</strong></a>
54+
| <a href="#I"><strong>I</strong></a>
5455
| <a href="#M"><strong>M</strong></a>
5556
| <a href="#O"><strong>O</strong></a>
5657
| <a href="#R"><strong>R</strong></a>
@@ -114,6 +115,14 @@ <h2 id="H">H</h2>
114115
</ul></td>
115116
</tr></table>
116117

118+
<h2 id="I">I</h2>
119+
<table style="width: 100%" class="indextable genindextable"><tr>
120+
<td style="width: 33%; vertical-align: top;"><ul>
121+
<li><a href="index.html#ffmpeg.input">input() (in module ffmpeg)</a>
122+
</li>
123+
</ul></td>
124+
</tr></table>
125+
117126
<h2 id="M">M</h2>
118127
<table style="width: 100%" class="indextable genindextable"><tr>
119128
<td style="width: 33%; vertical-align: top;"><ul>
@@ -125,10 +134,12 @@ <h2 id="M">M</h2>
125134
<h2 id="O">O</h2>
126135
<table style="width: 100%" class="indextable genindextable"><tr>
127136
<td style="width: 33%; vertical-align: top;"><ul>
128-
<li><a href="index.html#ffmpeg.overlay">overlay() (in module ffmpeg)</a>
137+
<li><a href="index.html#ffmpeg.output">output() (in module ffmpeg)</a>
129138
</li>
130139
</ul></td>
131140
<td style="width: 33%; vertical-align: top;"><ul>
141+
<li><a href="index.html#ffmpeg.overlay">overlay() (in module ffmpeg)</a>
142+
</li>
132143
<li><a href="index.html#ffmpeg.overwrite_output">overwrite_output() (in module ffmpeg)</a>
133144
</li>
134145
</ul></td>

‎doc/html/index.html

Lines changed: 223 additions & 30 deletions
Large diffs are not rendered by default.

‎doc/html/objects.inv

6 Bytes
Binary file not shown.

‎doc/html/searchindex.js

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎doc/src/conf.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
# Add any Sphinx extension module names here, as strings. They can be
3131
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3232
# ones.
33-
extensions = ['sphinx.ext.autodoc']
33+
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
3434

3535
# Add any paths that contain templates here, relative to this directory.
3636
templates_path = ['_templates']

‎ffmpeg/_ffmpeg.py

Lines changed: 32 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,53 @@
88

99

1010
def file_input(filename):
11+
"""Input file URL (ffmpeg ``-i`` option)
12+
13+
Official documentation: `Main options <https://ffmpeg.org/ffmpeg.html#Main-options>`__
14+
"""
1115
return InputNode(file_input.__name__, filename=filename)
1216

1317

18+
def input(filename):
19+
"""Shorthand for ``file_input``"""
20+
return file_input(filename)
21+
22+
1423
@operator(node_classes={OutputNode, GlobalNode})
15-
def overwrite_output(parent):
16-
return GlobalNode(parent, overwrite_output.__name__)
24+
def overwrite_output(parent_node):
25+
"""Overwrite output files without asking (ffmpeg ``-y`` option)
26+
27+
Official documentation: `Main options <https://ffmpeg.org/ffmpeg.html#Main-options>`__
28+
"""
29+
return GlobalNode(parent_node, overwrite_output.__name__)
1730

1831

1932
@operator(node_classes={OutputNode})
20-
def merge_outputs(*parents):
21-
return OutputNode(parents, merge_outputs.__name__)
33+
def merge_outputs(*parent_nodes):
34+
return OutputNode(parent_nodes, merge_outputs.__name__)
2235

2336

2437
@operator(node_classes={InputNode, FilterNode})
25-
def file_output(parent, filename):
26-
return OutputNode([parent], file_output.__name__, filename=filename)
38+
def file_output(parent_node, filename):
39+
"""Output file URL
40+
41+
Official documentation: `Synopsis <https://ffmpeg.org/ffmpeg.html#Synopsis>`__
42+
"""
43+
return OutputNode([parent_node], file_output.__name__, filename=filename)
44+
45+
46+
@operator(node_classes={InputNode, FilterNode})
47+
def output(parent_node, filename):
48+
"""Shorthand for ``file_output``"""
49+
return file_output(parent_node, filename)
50+
2751

2852

2953
__all__ = [
3054
'file_input',
3155
'file_output',
56+
'input',
3257
'merge_outputs',
58+
'output',
3359
'overwrite_output',
3460
]

‎ffmpeg/_filters.py

Lines changed: 162 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,64 +5,201 @@
55

66

77
@operator()
8-
def setpts(parent, expr):
9-
return FilterNode([parent], setpts.__name__, expr)
8+
def setpts(parent_node, expr):
9+
"""Change the PTS (presentation timestamp) of the input frames.
10+
11+
Args:
12+
expr: The expression which is evaluated for each frame to construct its timestamp.
13+
14+
Official documentation: `setpts, asetpts <https://ffmpeg.org/ffmpeg-filters.html#setpts_002c-asetpts>`__
15+
"""
16+
return FilterNode([parent_node], setpts.__name__, expr)
1017

1118

1219
@operator()
13-
def trim(parent, **kwargs):
14-
return FilterNode([parent], trim.__name__, **kwargs)
20+
def trim(parent_node, **kwargs):
21+
"""Trim the input so that the output contains one continuous subpart of the input.
22+
23+
Args:
24+
start: Specify the time of the start of the kept section, i.e. the frame with the timestamp start will be the
25+
first frame in the output.
26+
end: Specify the time of the first frame that will be dropped, i.e. the frame immediately preceding the one
27+
with the timestamp end will be the last frame in the output.
28+
start_pts: This is the same as start, except this option sets the start timestamp in timebase units instead of
29+
seconds.
30+
end_pts: This is the same as end, except this option sets the end timestamp in timebase units instead of
31+
seconds.
32+
duration: The maximum duration of the output in seconds.
33+
start_frame: The number of the first frame that should be passed to the output.
34+
end_frame: The number of the first frame that should be dropped.
35+
36+
Official documentation: `trim <https://ffmpeg.org/ffmpeg-filters.html#trim>`__
37+
"""
38+
return FilterNode([parent_node], trim.__name__, **kwargs)
1539

1640

1741
@operator()
18-
def overlay(main_parent, overlay_parent, eof_action='repeat', **kwargs):
42+
def overlay(main_parent_node, overlay_parent_node, eof_action='repeat', **kwargs):
43+
"""Overlay one video on top of another.
44+
45+
Args:
46+
x: Set the expression for the x coordinates of the overlaid video on the main video. Default value is 0. In
47+
case the expression is invalid, it is set to a huge value (meaning that the overlay will not be displayed
48+
within the output visible area).
49+
y: Set the expression for the y coordinates of the overlaid video on the main video. Default value is 0. In
50+
case the expression is invalid, it is set to a huge value (meaning that the overlay will not be displayed
51+
within the output visible area).
52+
eof_action: The action to take when EOF is encountered on the secondary input; it accepts one of the following
53+
values:
54+
55+
* ``repeat``: Repeat the last frame (the default).
56+
* ``endall``: End both streams.
57+
* ``pass``: Pass the main input through.
58+
59+
eval: Set when the expressions for x, and y are evaluated.
60+
It accepts the following values:
61+
62+
* ``init``: only evaluate expressions once during the filter initialization or when a command is
63+
processed
64+
* ``frame``: evaluate expressions for each incoming frame
65+
66+
Default value is ``frame``.
67+
shortest: If set to 1, force the output to terminate when the shortest input terminates. Default value is 0.
68+
format: Set the format for the output video.
69+
It accepts the following values:
70+
71+
* ``yuv420``: force YUV420 output
72+
* ``yuv422``: force YUV422 output
73+
* ``yuv444``: force YUV444 output
74+
* ``rgb``: force packed RGB output
75+
* ``gbrp``: force planar RGB output
76+
77+
Default value is ``yuv420``.
78+
rgb (deprecated): If set to 1, force the filter to accept inputs in the RGB color space. Default value is 0.
79+
This option is deprecated, use format instead.
80+
repeatlast: If set to 1, force the filter to draw the last overlay frame over the main input until the end of
81+
the stream. A value of 0 disables this behavior. Default value is 1.
82+
83+
Official documentation: `overlay <https://ffmpeg.org/ffmpeg-filters.html#overlay-1>`__
84+
"""
1985
kwargs['eof_action'] = eof_action
20-
return FilterNode([main_parent, overlay_parent], overlay.__name__, **kwargs)
86+
return FilterNode([main_parent_node, overlay_parent_node], overlay.__name__, **kwargs)
2187

2288

2389
@operator()
24-
def hflip(parent):
25-
return FilterNode([parent], hflip.__name__)
90+
def hflip(parent_node):
91+
"""Flip the input video horizontally.
92+
93+
Official documentation: `hflip <https://ffmpeg.org/ffmpeg-filters.html#hflip>`__
94+
"""
95+
return FilterNode([parent_node], hflip.__name__)
2696

2797

2898
@operator()
29-
def vflip(parent):
30-
return FilterNode([parent], vflip.__name__)
99+
def vflip(parent_node):
100+
"""Flip the input video vertically.
101+
102+
Official documentation: `vflip <https://ffmpeg.org/ffmpeg-filters.html#vflip>`__
103+
"""
104+
return FilterNode([parent_node], vflip.__name__)
31105

32106

33107
@operator()
34-
def drawbox(parent, x, y, width, height, color, thickness=None, **kwargs):
108+
def drawbox(parent_node, x, y, width, height, color, thickness=None, **kwargs):
109+
"""Draw a colored box on the input image.
110+
111+
Args:
112+
x: The expression which specifies the top left corner x coordinate of the box. It defaults to 0.
113+
y: The expression which specifies the top left corner y coordinate of the box. It defaults to 0.
114+
width: Specify the width of the box; if 0 interpreted as the input width. It defaults to 0.
115+
heigth: Specify the height of the box; if 0 interpreted as the input height. It defaults to 0.
116+
color: Specify the color of the box to write. For the general syntax of this option, check the "Color" section
117+
in the ffmpeg-utils manual. If the special value invert is used, the box edge color is the same as the
118+
video with inverted luma.
119+
thickness: The expression which sets the thickness of the box edge. Default value is 3.
120+
w: Alias for ``width``.
121+
h: Alias for ``height``.
122+
c: Alias for ``color``.
123+
t: Alias for ``thickness``.
124+
125+
Official documentation: `drawbox <https://ffmpeg.org/ffmpeg-filters.html#drawbox>`__
126+
"""
35127
if thickness:
36128
kwargs['t'] = thickness
37-
return FilterNode([parent], drawbox.__name__, x, y, width, height, color, **kwargs)
129+
return FilterNode([parent_node], drawbox.__name__, x, y, width, height, color, **kwargs)
38130

39131

40132
@operator()
41-
def concat(*parents, **kwargs):
42-
kwargs['n'] = len(parents)
43-
return FilterNode(parents, concat.__name__, **kwargs)
133+
def concat(*parent_nodes, **kwargs):
134+
"""Concatenate audio and video streams, joining them together one after the other.
135+
136+
The filter works on segments of synchronized video and audio streams. All segments must have the same number of
137+
streams of each type, and that will also be the number of streams at output.
138+
139+
Args:
140+
unsafe: Activate unsafe mode: do not fail if segments have a different format.
141+
142+
Related streams do not always have exactly the same duration, for various reasons including codec frame size or
143+
sloppy authoring. For that reason, related synchronized streams (e.g. a video and its audio track) should be
144+
concatenated at once. The concat filter will use the duration of the longest stream in each segment (except the
145+
last one), and if necessary pad shorter audio streams with silence.
146+
147+
For this filter to work correctly, all segments must start at timestamp 0.
148+
149+
All corresponding streams must have the same parameters in all segments; the filtering system will automatically
150+
select a common pixel format for video streams, and a common sample format, sample rate and channel layout for
151+
audio streams, but other settings, such as resolution, must be converted explicitly by the user.
152+
153+
Different frame rates are acceptable but will result in variable frame rate at output; be sure to configure the
154+
output file to handle it.
155+
156+
Official documentation: `concat <https://ffmpeg.org/ffmpeg-filters.html#concat>`__
157+
"""
158+
kwargs['n'] = len(parent_nodes)
159+
return FilterNode(parent_nodes, concat.__name__, **kwargs)
44160

45161

46162
@operator()
47-
def zoompan(parent, **kwargs):
48-
return FilterNode([parent], zoompan.__name__, **kwargs)
163+
def zoompan(parent_node, **kwargs):
164+
"""Apply Zoom & Pan effect.
165+
166+
Args:
167+
zoom: Set the zoom expression. Default is 1.
168+
x: Set the x expression. Default is 0.
169+
y: Set the y expression. Default is 0.
170+
d: Set the duration expression in number of frames. This sets for how many number of frames effect will last
171+
for single input image.
172+
s: Set the output image size, default is ``hd720``.
173+
fps: Set the output frame rate, default is 25.
174+
z: Alias for ``zoom``.
175+
176+
Official documentation: `zoompan <https://ffmpeg.org/ffmpeg-filters.html#zoompan>`__
177+
"""
178+
return FilterNode([parent_node], zoompan.__name__, **kwargs)
49179

50180

51181
@operator()
52-
def hue(parent, **kwargs):
53-
return FilterNode([parent], hue.__name__, **kwargs)
182+
def hue(parent_node, **kwargs):
183+
"""Modify the hue and/or the saturation of the input.
184+
185+
Args:
186+
h: Specify the hue angle as a number of degrees. It accepts an expression, and defaults to "0".
187+
s: Specify the saturation in the [-10,10] range. It accepts an expression and defaults to "1".
188+
H: Specify the hue angle as a number of radians. It accepts an expression, and defaults to "0".
189+
b: Specify the brightness in the [-10,10] range. It accepts an expression and defaults to "0".
190+
191+
Official documentation: `hue <https://ffmpeg.org/ffmpeg-filters.html#hue>`__
192+
"""
193+
return FilterNode([parent_node], hue.__name__, **kwargs)
54194

55195

56196
@operator()
57-
def colorchannelmixer(parent, *args, **kwargs):
197+
def colorchannelmixer(parent_node, *args, **kwargs):
58198
"""Adjust video input frames by re-mixing color channels.
59199
60-
`FFmpeg colorchannelmixer filter`_
61-
62-
.. _FFmpeg colorchannelmixer filter:
63-
https://ffmpeg.org/ffmpeg-filters.html#toc-colorchannelmixer
200+
Official documentation: `colorchannelmixer <https://ffmpeg.org/ffmpeg-filters.html#colorchannelmixer>`__
64201
"""
65-
return FilterNode([parent], colorchannelmixer.__name__, **kwargs)
202+
return FilterNode([parent_node], colorchannelmixer.__name__, **kwargs)
66203

67204

68205
__all__ = [

‎ffmpeg/_run.py

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -81,10 +81,11 @@ def _get_output_args(node, stream_name_map):
8181

8282

8383
@operator(node_classes={OutputNode, GlobalNode})
84-
def get_args(parent):
84+
def get_args(node):
85+
"""Get command-line arguments for ffmpeg."""
8586
args = []
8687
# TODO: group nodes together, e.g. `-i somefile -r somerate`.
87-
sorted_nodes, child_map = _topo_sort(parent)
88+
sorted_nodes, child_map = _topo_sort(node)
8889
input_nodes = [node for node in sorted_nodes if isinstance(node, InputNode)]
8990
output_nodes = [node for node in sorted_nodes if isinstance(node, OutputNode) and not
9091
isinstance(node, GlobalNode)]
@@ -101,8 +102,9 @@ def get_args(parent):
101102

102103

103104
@operator(node_classes={OutputNode, GlobalNode})
104-
def run(parent, cmd='ffmpeg'):
105-
args = [cmd] + parent.get_args()
105+
def run(node, cmd='ffmpeg'):
106+
"""Run ffmpeg on node graph."""
107+
args = [cmd] + node.get_args()
106108
_subprocess.check_call(args)
107109

108110

0 commit comments

Comments
 (0)
0