Filtergraph Builder Reference

One of the great feature of FFmpeg is the plethora of filters to manipulate video and audio data. See the official FFmpeg Filters Documentation and FFmpeg Wiki articles on Filtering.

All the media I/O operations in ffmpegio support FFmpeg filtering via per-stream filter, vf, af, and filter_script output options as well as the filter_complex and filter_complex_script global option. These options are typically specified by filtergraph expression strings. For example, 'scale=iw/2:-1' to reduce the video frame size by half. Multiple operations can be performed in sequence by chaining the filters, e.g., 'afade=t=in:d=1,afade=t=out:st=9:d=1' adds fade-in and fade-out effect to an audio stream. More complex filtergraph with multiple chains can also be specified, but as the complexity increases the expression length also increases. The ffmpegio.filtergraph submodule is designed to assist building complex filtergraphs. The module serves 3 primary functions:

Accessing filter information on FFmpeg
Constructing filtergraphs
Generating filtergraph script for extremely long filtergraph

These functions are served by three classes:

`ffmpegio.filtergraph.Filter`	FFmpeg filter definition immutable class
`ffmpegio.filtergraph.Chain`	List of FFmpeg filters, connected in series
`ffmpegio.filtergraph.Graph`	List of FFmpeg filterchains in parallel with interchain link specifications

See Filtergraph API Reference section below for the full documentation of these classes and other helper functions.

All filtergraph classes can be instantiated with a valid filtergraph description string and yield filtergraph descriptions when converted to str.

>>> import ffmpegio.filtergraph as fgb
>>> 
>>> # for a simple chain, use either Chain or Graph
>>> fgb.Chain('afade=t=in:d=1,afade=t=out:st=9:d=1')
<ffmpegio.filtergraph.Chain.Chain object at 0x7f95df033110>
    FFmpeg expression: "[UNC0]afade=t=in:d=1[UNC2];[UNC1]afade=t=out:st=9:d=1[UNC3]"
    Number of filters: 2
    Input pads (1): (0, 0)
    Output pads: (1): (1, 0)

>>> fgb.Graph('afade=t=in:d=1,afade=t=out:st=9:d=1')
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95df031970>
    FFmpeg expression: "afade=t=in:d=1,afade=t=out:st=9:d=1"
    Number of chains: 1
      chain[0]: [UNC0]afade=t=in:d=1,afade=t=out:st=9:d=1[UNC1]      
    Available input pads (1): (0, 0, 0)
    Available output pads: (1): (0, 1, 0)

>>> 
>>> # construct the chain from filters
>>> fgb.Filter('afade=t=in:d=1') + fgb.Filter('afade=t=out:st=9:d=1')
<ffmpegio.filtergraph.Chain.Chain object at 0x7f95cfe9e3f0>
    FFmpeg expression: "[UNC0]afade=t=in:d=1[UNC2];[UNC1]afade=t=out:st=9:d=1[UNC3]"
    Number of filters: 2
    Input pads (1): (0, 0)
    Output pads: (1): (1, 0)

All ffmpegio functions that take filter options accept these objects as input arguments and convert to str internally:

>>> fs, x = ffmpegio.audio.read('input.mp3', af=fg)
>>> # x contains the audio samples with the fading effects

Note

The simplified examples on this pages are for illustration purpose only. If a filtergraph is simple and does not require programmatic construction, use plain :py:class`str` expressions to improve the runtime speed.

Accessing filter information on FFmpeg

Filters can be instantiated in a several different ways:

fgb.Filter constructor with option values as arguments
fgb.Filter constructor with a single-filter filtergraph description
fgb.<filter_name> dynamic function (where <filter_name>> is the name of a FFmpeg filter)

For example, a crop filter crop=in_w-100:in_h-100:x=100:y=100 can be created by any of the following 3 lines:

>>> fgb.Filter('crop', 'in_w-100', 'in_h-100', x=100, y=100)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Filter.py", line 164, in __repr__
    FFmpeg expression: \"{self.compose(True,True)}\"
                          ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Filter.py", line 154, in compose
    fgb.Graph(self.data).compose(
              ^^^^^^^^^
AttributeError: 'Filter' object has no attribute 'data'
>>> fgb.Filter('crop=in_w-100:in_h-100:x=100:y=100')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Filter.py", line 164, in __repr__
    FFmpeg expression: \"{self.compose(True,True)}\"
                          ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Filter.py", line 154, in compose
    fgb.Graph(self.data).compose(
              ^^^^^^^^^
AttributeError: 'Filter' object has no attribute 'data'
>>> fgb.crop('in_w-100', 'in_h-100', x=100, y=100)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Filter.py", line 164, in __repr__
    FFmpeg expression: \"{self.compose(True,True)}\"
                          ^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Filter.py", line 154, in compose
    fgb.Graph(self.data).compose(
              ^^^^^^^^^
AttributeError: 'Filter' object has no attribute 'data'

The :py:func`fgb.crop` function is dynamically created when user call it for the first time. If the function name fails to resolve an FFmpeg filter, an AttributeError will be raised.

In addition, these dynamic functions get FFmpeg filter help text as their docstrings:

>>> help(fgb.crop)
Help on function crop in module ffmpegio.filtergraph:

crop(*args, filter_id=None, **kwargs)
    Filter crop
      Crop the input video.
        Inputs:
           #0: default (video)
        Outputs:
           #0: default (video)
    crop AVOptions:
       out_w             <string>     ..FV.....T. set the width crop area expression (default "iw")
       w                 <string>     ..FV.....T. set the width crop area expression (default "iw")
       out_h             <string>     ..FV.....T. set the height crop area expression (default "ih")
       h                 <string>     ..FV.....T. set the height crop area expression (default "ih")
       x                 <string>     ..FV.....T. set the x crop area expression (default "(in_w-out_w)/2")
       y                 <string>     ..FV.....T. set the y crop area expression (default "(in_h-out_h)/2")
       keep_aspect       <boolean>    ..FV....... keep aspect ratio (default false)
       exact             <boolean>    ..FV....... do exact cropping (default false)

Use ffmpegio.caps.filters() to get the full list of filters supported by the installed FFmpeg and ffmpegio.caps.filter_info() to get a parsed version of the filter help text.

Constructing filtergraphs

A complex filtergraph can be authored using a combination of Filter, Chain, and Graph. The following 4 operators are defined:

Operator	Description
`\|`	Stack sections (no linking)
`* n`	Create `n` copies of itself and stack them
`+`	Join filtergraph sections
`>>`	Point-to-point connection and pad labeling

Other useful filtergraph manipulation class methods are:

This section mainly describes the operators, leaving the details of the class methods to the API reference section later on this page.

`|`: filtegraph stacking

Stacking operation creates a new Graph object from two filtergraph objects, orienting them in parallel without making any connections. The left and right sides do not need to be of the same class, and they can be mixed and matched.

>>> # 1. given 2 filters
>>> fgb.trim(30, 60) | fgb.trim(90, 120)
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd2060>
    FFmpeg expression: "trim=30:60;trim=90:120"
    Number of chains: 2
      chain[0]: [UNC0]trim=30:60[UNC2];
      chain[1]: [UNC1]trim=90:120[UNC3]      
    Available input pads (2): (0, 0, 0), (1, 0, 0)
    Available output pads: (2): (0, 0, 0), (1, 0, 0)

>>> 
>>> # 2. given 2 chains
>>> fgb.Chain('trim=30:60,scale=200:-1') | fgb.Chain('atrim=30:60,afade=t=in')
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95df0319a0>
    FFmpeg expression: "trim=30:60,scale=200:-1;atrim=30:60,afade=t=in"
    Number of chains: 2
      chain[0]: [UNC0]trim=30:60,scale=200:-1[UNC2];
      chain[1]: [UNC1]atrim=30:60,afade=t=in[UNC3]      
    Available input pads (2): (0, 0, 0), (1, 0, 0)
    Available output pads: (2): (0, 1, 0), (1, 1, 0)

>>> 
>>> # 3. given 2 graphs
>>> fgb.Graph('[0:v]trim=30:60,scale=200:-1[out]') | fgb.Graph('[0:a]atrim=30:60,afade=t=in[out]')
Traceback (most recent call last):
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Graph.py", line 835, in _stack
    fg._links.update(
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 820, in update
    fglinks.create_label(l, i, o, force)
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 656, in create_label
    label = self._resolve_label(label, force=force, check_stream_spec=False)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 337, in _resolve_label
    raise GraphLinks.Error(f"{label=} is already in use.")
ffmpegio.filtergraph.GraphLinks.GraphLinks.Error: label='out' is already in use.

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 653, in __or__
    return fgb.stack(self, other)
           ^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/build.py", line 347, in stack
    fg = fg._stack(fgb.as_filtergraph_object(other), auto_link, replace_sws_flags)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Graph.py", line 842, in _stack
    raise Graph.Error(e) from e
ffmpegio.filtergraph.Graph.Graph.Error: label='out' is already in use.

Note

Duplicate link labels are automatically renamed with a trailing counter.

`* n`: filtergraph self-stacking

Like Python lists and tuples, multipling any filtergraph object by an integer creates a Graph object containing n copies of the object and stack them (i.e., create parallel chains).

>>> # multiplying filters
>>> fgb.crop(100,100) * 3
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd2360>
    FFmpeg expression: "crop=100:100;crop=100:100;crop=100:100"
    Number of chains: 3
      chain[0]: [UNC0]crop=100:100[UNC3];
      chain[1]: [UNC1]crop=100:100[UNC4];
      chain[2]: [UNC2]crop=100:100[UNC5]      
    Available input pads (3): (0, 0, 0), (1, 0, 0), (2, 0, 0)
    Available output pads: (3): (0, 0, 0), (1, 0, 0), (2, 0, 0)

>>> 
>>> # multiplying chains
>>> fgb.Chain('fps=30,format=yuv420p') * 2
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd25a0>
    FFmpeg expression: "fps=30,format=yuv420p;fps=30,format=yuv420p"
    Number of chains: 2
      chain[0]: [UNC0]fps=30,format=yuv420p[UNC2];
      chain[1]: [UNC1]fps=30,format=yuv420p[UNC3]      
    Available input pads (2): (0, 0, 0), (1, 0, 0)
    Available output pads: (2): (0, 1, 0), (1, 1, 0)

>>> 
>>> # multiplying graphs
>>> fgb.Graph('color,[0]overlay[vout]') * 2
Traceback (most recent call last):
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Graph.py", line 835, in _stack
    fg._links.update(
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 820, in update
    fglinks.create_label(l, i, o, force)
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 656, in create_label
    label = self._resolve_label(label, force=force, check_stream_spec=False)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 337, in _resolve_label
    raise GraphLinks.Error(f"{label=} is already in use.")
ffmpegio.filtergraph.GraphLinks.GraphLinks.Error: label='vout' is already in use.

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 643, in __mul__
    return fgb.stack(*((self,) * __n))
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/build.py", line 347, in stack
    fg = fg._stack(fgb.as_filtergraph_object(other), auto_link, replace_sws_flags)
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Graph.py", line 842, in _stack
    raise Graph.Error(e) from e
ffmpegio.filtergraph.Graph.Graph.Error: label='vout' is already in use.

Note

Multiplied link labels receive unique labels with trailing counter.

`+`: filtergraph joining

Join operation connects two filtergraph objects by auto-linking the available output pads of the left side and the available input pads of the right side. The output object type depends on the input types.

Joining a single-output object to a single-input object connection is trivial. If both are of either Filter or Chain classes, they are joined in series, resulting in Chain object. If Graph is involved, the joining chain is extended with the other object.

>>> # 1. joining 2 filters:
>>> fgb.trim(60,120) + fgb.Chain('crop=100:100:12:34,fps=30')
<ffmpegio.filtergraph.Chain.Chain object at 0x7f95cfcd20f0>
    FFmpeg expression: "[UNC0]trim=60:120[UNC3];[UNC1]crop=100:100:12:34[UNC4];[UNC2]fps=30[UNC5]"
    Number of filters: 3
    Input pads (1): (0, 0)
    Output pads: (1): (2, 0)

>>> 
>>> # 2. joining 2 graphs:
>>> fgb.Graph('[0]fps=30[v0];[v0]overlay') + fgb.Graph('split[v0][v1];[v1]hflip')
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd2270>
    FFmpeg expression: "[0]fps=30[v0];[v0]overlay[L0];[L0]split[v1];[v1]hflip"
    Number of chains: 4
      chain[0]: [0]fps=30[v0];
      chain[1]: [v0][UNC0]overlay[L0];
      chain[2]: [L0]split[UNC1][v1];
      chain[3]: [v1]hflip[UNC2]      
    Available input pads (1): (1, 0, 1)
    Available output pads: (2): (2, 0, 0), (3, 0, 0)

Joining multiple-output Graph object with multiple-input Graph object yields a Graph object. The number of exposed filter pads must match on both sides. The pad pairing is automatically performed in one of the two possible ways:

pairs the first unused output filter pad of each chain of the left filtergraph and the
first unused input filter pad of each chain of the right filtergraph (per-chain)
pairs all the unused filter pads of the left and right filtergraphs (all)

Both pairing types require the two sides to have the matching number of unused pads. If no match is attained per chain, then the all unused pads are paired. This mechanism allows the + operator to support two important usecases involving branching and merging filters such as overlay, concat, split, and asplit. The following examples demonstrate these cases:

>>> # case 1: attaching a chain of one side to one of the multiple pads of the other
>>> fgb.hflip() + fgb.hstack()
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd27b0>
    FFmpeg expression: "hflip[L0];[L0]hstack"
    Number of chains: 2
      chain[0]: [UNC0]hflip[L0];
      chain[1]: [L0][UNC1]hstack[UNC2]      
    Available input pads (2): (0, 0, 0), (1, 0, 1)
    Available output pads: (1): (1, 0, 0)

>>> 
>>> # case 2: connecting all the chains (one unused pad each) of one side to a filter with
>>> #         matching number of pads on the other side
>>> (fgb.hflip() | fgb.vflip()) + fgb.hstack()
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd2960>
    FFmpeg expression: "hflip[L0];vflip[L1];[L0][L1]hstack"
    Number of chains: 3
      chain[0]: [UNC0]hflip[L0];
      chain[1]: [UNC1]vflip[L1];
      chain[2]: [L0][L1]hstack[UNC2]      
    Available input pads (2): (0, 0, 0), (1, 0, 0)
    Available output pads: (1): (2, 0, 0)

Note

If joining results in a multi-chain filtergraph, inter-chain links are unnamed, and when converted to :py:class:str the unnamed links uses L# link names.

Note

Be aware of the operator precedence. That is, * precedes +, and + precedes |.

When joining filtergraph objects with multiple inputs and outputs, +

`>>` filtergraph labeling / filtergraph p2p linking

The >> is a multi-purpose operator to label a filter pad and to stack two filtergraphs with a single link between them. It also accepts optionally explicit filter pad id’s to override the default selection policty of the first unused filter pad.

Simple usecases are:

>>> # label input and output pads to a SISO filtergraph
>>> '[in]' >> fgb.scale(100,-2) >> '[out]'
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd23f0>
    FFmpeg expression: "[in]scale=100:-2[out]"
    Number of chains: 1
      chain[0]: [in]scale=100:-2[out]      
    Available input pads (1): (0, 0, 0)
    Available output pads: (1): (0, 0, 0)

>>> 
>>> # connect 2 filtergraphs with the first available filter pads
>>> fgb.hflip() >> fgb.concat()
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd21b0>
    FFmpeg expression: "hflip[L0];[L0]concat"
    Number of chains: 2
      chain[0]: [UNC0]hflip[L0];
      chain[1]: [L0][UNC1]concat[UNC2]      
    Available input pads (2): (0, 0, 0), (1, 0, 1)
    Available output pads: (1): (1, 0, 0)

Filter pad labeling

To label a filter pad, the label string must be fully specified with the square brackets:

# valid label strings
'[in]' >> fg   # valid FFmpeg link label (alphanumeric characters + '_' inside '[]')
'[0:v]' >> fg  # valid FFmpeg stream specifier (the first video stream of the first input url)

# incorrect label strings
'in' >> fg  # create an "in" Filter object (not a valid FFmpeg filter)
'0:v' >> fg # fails to parse the string as a filtergraph

To label multiple pads at once, provide a sequence of labels:

>>> ['[0:v]','[1:v]'] >> fgb.Chain('overlay,split') >> ['[vout1]','[vout2]']
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd2ea0>
    FFmpeg expression: "[0:v][1:v]overlay,split[vout1][vout2]"
    Number of chains: 1
      chain[0]: [0:v][1:v]overlay,split[vout1][vout2]      
    Available input pads (0): 
    Available output pads: (2): (0, 1, 0), (0, 1, 1)

The pads do not need to be of the same filter:

>>> ['[0:v]','[1:v]'] >> fgb.Graph('pad=640:480[v1];scale=100:100[v2];[v1][v2]overlay')
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd30b0>
    FFmpeg expression: "[0:v]pad=640:480[v1];[1:v]scale=100:100[v2];[v1][v2]overlay"
    Number of chains: 3
      chain[0]: [0:v]pad=640:480[v1];
      chain[1]: [1:v]scale=100:100[v2];
      chain[2]: [v1][v2]overlay[UNC0]      
    Available input pads (0): 
    Available output pads: (1): (2, 0, 0)

Filtergraph linking

Functionally, >> and + are the same if both sides of the operator expose only one pad. So, they can be used interchangeably.

>>> # following two operations produce the same filtergraph
>>> fgb.hflip() >> fgb.vflip()
<ffmpegio.filtergraph.Chain.Chain object at 0x7f95cfcd2fc0>
    FFmpeg expression: "[UNC0]hflip[UNC2];[UNC1]vflip[UNC3]"
    Number of filters: 2
    Input pads (1): (0, 0)
    Output pads: (1): (1, 0)

>>> fgb.hflip() + fgb.vflip()
<ffmpegio.filtergraph.Chain.Chain object at 0x7f95cfcd30b0>
    FFmpeg expression: "[UNC0]hflip[UNC2];[UNC1]vflip[UNC3]"
    Number of filters: 2
    Input pads (1): (0, 0)
    Output pads: (1): (1, 0)

The >> operator is primarily designed to attach a filter or a filterchain to a larger filtergraph with multiple pads.

>>> # a 4-input graph with the first one connected to an input stream
>>> fg = fgb.Graph('[0:v]hstack[h1];hstack[h2];[h1][h2]vstack')
>>> 
>>> # add the zoomed version as the second input
>>> fgb.Graph('[0:v]crop,scale') >> fg
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 708, in __rshift__
    return fgb.attach(self, right, left_on, right_on)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/build.py", line 252, in attach
    raise ValueError(
ValueError: Cannot determine which side is attaching. One of left or right argument must be a Filter or Chain object.
>>> # -> [0:v]crop,scale[L1];[0:v][L1]hstack[h1];hstack[h2];[h1][h2]vstack

Filter pad indexing

In some cases linking of the filter pads may not happen in a top-down order. It is also possible to specify which filter pad to label or to connect.

First, here is the the automatic pad selection rules:

Unused filter pad is searched on filterchains in sequence
On the selected filterchain on the left side of >>
- The first filter with an unused input pad is selected
- The first unused input pad on the selected filter is selected
On the selected filterchain on the right side of >>
- The last filter with an unused output pad is selected
- The first unused output pad on the selected filter is selected

These rules apply to both labeling and linking. Here are a couple examples to illustrate the order of pad selection:

>>> ["[in1]", "[in2]", "[in3]", "[in4]"] >> fgb.Graph("overlay,overlay;hflip")
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd3110>
    FFmpeg expression: "[in1][in2]overlay,[in3]overlay;[in4]hflip"
    Number of chains: 2
      chain[0]: [in1][in2]overlay,[in3]overlay[UNC0];
      chain[1]: [in4]hflip[UNC1]      
    Available input pads (4): (0, 0, 0), (0, 0, 1), (0, 1, 0), (1, 0, 0)
    Available output pads: (2): (0, 1, 0), (1, 0, 0)

>>> 
>>> fgb.Chain("split,split") >> "[label1]" >> "[label2]" >> "[label3]"
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 708, in __rshift__
    return fgb.attach(self, right, left_on, right_on)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/build.py", line 302, in attach
    return left_objs_labels._attach(right_objs_labels, left_on, right_on)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 1020, in _attach
    fg.add_label(r, outpad=l_idx)
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Graph.py", line 729, in add_label
    self._links.create_label(label, inpad, outpad, force)
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 699, in create_label
    raise GraphLinks.Error(
ffmpegio.filtergraph.GraphLinks.GraphLinks.Error: pad_in_use='label1' is already using the specified pad: (0, 0, 0)

To specify the connecting pads, accompany the label or attaching filtergraph with the filter pad index:

>>> ("[in]", (0,1,1)) >> fgb.Graph("overlay,overlay;hflip")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 758, in __rrshift__
    return fgb.attach(left, self, left_on, right_on)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/build.py", line 297, in attach
    right_on, left_on = resolve_indices(
                        ^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/build.py", line 271, in resolve_indices
    base_indices = base.resolve_pad_indices(base_indices, is_input=base_is_input)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 914, in resolve_pad_indices
    self.resolve_pad_index(
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Graph.py", line 200, in resolve_pad_index
    return super().resolve_pad_index(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 882, in resolve_pad_index
    raise FiltergraphPadNotFoundError(
ffmpegio.filtergraph.exceptions.FiltergraphPadNotFoundError: index_or_label=(0, 1, 1) is either already connected or invalid input pad.
>>> 
>>> fgb.Chain("split,split") >> ((0,-1,1), "[label]")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 708, in __rshift__
    return fgb.attach(self, right, left_on, right_on)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/build.py", line 293, in attach
    left_on, right_on = resolve_indices(
                        ^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/build.py", line 271, in resolve_indices
    base_indices = base.resolve_pad_indices(base_indices, is_input=base_is_input)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 914, in resolve_pad_indices
    self.resolve_pad_index(
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/abc.py", line 882, in resolve_pad_index
    raise FiltergraphPadNotFoundError(
ffmpegio.filtergraph.exceptions.FiltergraphPadNotFoundError: index_or_label=(0, -1, 1) is either already connected or invalid output pad.

The filter pad index is given by a three-element tuple:

# filter pad index (tuple of 3 ints)

(i, j, k)
# i -> chain index, selecting the (i+1)st chain
# j -> filter index on the (i+1)st chain
# k -> (input or output) pad index of the (j+1)st filter

So, the first example (0,1,1) selects the 1st chain’s 2nd filter (overlay) and label its 2nd input pad [in3]. Negative indices (as used for Python sequences) are supported. The second example (0,-1,1) selects the 1st chain’s last filter and labels its 2nd output as [label3].

Alternatively, an existing label could be used to specify the connecting pad:

>>> fg_overlay = fgb.Chain("scale=240:-2,format=gray")
>>> fg1 = fgb.Graph("[in1][in2]overlay,[in3]overlay;[in4]hflip")
>>> 
>>> (fg_overlay,'in2') >> fg1
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd33e0>
    FFmpeg expression: "scale=240:-2,format=gray[L0];[in1][L0]overlay,[in3]overlay;[in4]hflip"
    Number of chains: 3
      chain[0]: [UNC0]scale=240:-2,format=gray[L0];
      chain[1]: [in1][L0]overlay,[in3]overlay[UNC1];
      chain[2]: [in4]hflip[UNC2]      
    Available input pads (4): (0, 0, 0), (1, 0, 0), (1, 1, 0), (2, 0, 0)
    Available output pads: (2): (1, 1, 0), (2, 0, 0)

The label name for indexing may optionally omit the square brackets as done in this example.

`Graph.link()` - within-filtergraph linking

To create a link within a filtergraph, use :py:func`link`. An example in which an intra-graph linking is with scale2ref. Its 2 outputs (scaled and passthrough reference streams) may not be used in the output pad order. Suppose we want the output video to show the first input on top of the scaled version of the second input, the desired filtergraph expression is

[1:v][0:v]scale2ref[v1_scaled][v0];[v0][v1_scaled]vstack

Neither joining nor linking operation cannot produce the desired outcome:

>>> #INCORRECT: only one link which is incorrect
>>> fgb.Graph('[1:v][0:v]scale2ref[v1_scaled][v0]') + fgb.vstack()
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd3350>
    FFmpeg expression: "[1:v][0:v]scale2ref[L0][L1];[L0][L1]vstack"
    Number of chains: 2
      chain[0]: [1:v][0:v]scale2ref[L0][L1];
      chain[1]: [L0][L1]vstack[UNC0]      
    Available input pads (0): 
    Available output pads: (1): (1, 0, 0)

>>> 
>>> #INCORRECT: correct first link but only one link
>>> fgb.Graph('[1:v][0:v]scale2ref[v1_scaled][v0]') >> ('v0', fgb.vstack())
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd32f0>
    FFmpeg expression: "[1:v][0:v]scale2ref[v1_scaled][L0];[L0]vstack"
    Number of chains: 2
      chain[0]: [1:v][0:v]scale2ref[v1_scaled][L0];
      chain[1]: [L0][UNC0]vstack[UNC1]      
    Available input pads (1): (1, 0, 1)
    Available output pads: (2): (0, 0, 0), (1, 0, 0)

To make the explicit link. Use the Graph.link() method to create out-of-order links:

>>> # first stack 2 filters
>>> fg = fgb.Graph("[1:v][0:v]scale2ref[v1_scaled][v0]") | fgb.vstack()
>>> # then make the connections (returns the link label)
>>> fg.link((-1, 0, 0), "v0") # (-1, 0, 0) <- [v0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Graph.py", line 673, in link
    return self._links.link(inpad, outpad, label, preserve_label, force)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 228, in link
    self.validate_pad_idx(inpad, none_ok=False)
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 93, in validate_pad_idx
    raise GraphLinks.Error(
ffmpegio.filtergraph.GraphLinks.GraphLinks.Error: id=(-1, 0, 0) is not a valid filter pad ID. Filter pad ID must be a 3-element tuple: (chain id, filter id, pad id)
>>> fg.link((-1, 0, 1), "v1_scaled") # (-1, 0, 1) <- [v1_scaled]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/Graph.py", line 673, in link
    return self._links.link(inpad, outpad, label, preserve_label, force)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 228, in link
    self.validate_pad_idx(inpad, none_ok=False)
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph/GraphLinks.py", line 93, in validate_pad_idx
    raise GraphLinks.Error(
ffmpegio.filtergraph.GraphLinks.GraphLinks.Error: id=(-1, 0, 1) is not a valid filter pad ID. Filter pad ID must be a 3-element tuple: (chain id, filter id, pad id)
>>> fg
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd2ba0>
    FFmpeg expression: "[1:v][0:v]scale2ref[v1_scaled][v0];vstack"
    Number of chains: 2
      chain[0]: [1:v][0:v]scale2ref[v1_scaled][v0];
      chain[1]: [UNC0][UNC1]vstack[UNC2]      
    Available input pads (2): (1, 0, 0), (1, 0, 1)
    Available output pads: (3): (0, 0, 0), (0, 0, 1), (1, 0, 0)

This method modifies the filtergraph.

Examples

Simple example

Borrowing the example from ffmpeg-python package:

[0]trim=start_frame=10:end_frame=20[v0]; \
[0]trim=start_frame=30:end_frame=40[v1]; \
[1]hflip[v2]; \
[v0][v1]concat=n=2[v3]; \
[v3][v2]overlay=eof_action=repeat, drawbox=50:50:120:120:red:t=5[v5]

This filtergraph can be built in the following steps:

>>> v0 = "[0]" >> fgb.trim(start_frame=10, end_frame=20)
>>> v1 = "[0]" >> fgb.trim(start_frame=30, end_frame=40)
>>> v3 = "[1]" >> fgb.hflip()
>>> v2 = (v0 | v1) + fgb.concat(2)
>>> v5 = (v2|v3) + fgb.overlay(eof_action='repeat') + fgb.drawbox(50, 50, 120, 120, 'red', t=5)
>>> v5
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd3920>
    FFmpeg expression: "[0]trim=start_frame=10:end_frame=20[L0];[0]trim=start_frame=30:end_frame=40[L1];[L0][L1]concat=2[L2];[1]hflip[L3];[L2][L3]overlay=eof_action=repeat,drawbox=50:50:120:120:red:t=5"
    Number of chains: 5
      chain[0]: [0]trim=start_frame=10:end_frame=20[L0];
      chain[1]: [0]trim=start_frame=30:end_frame=40[L1];
      chain[2]: [L0][L1]concat=2[L2];
      chain[3]: [1]hflip[L3];
      chain[4]: [L2][L3]overlay=eof_action=repeat,drawbox=50:50:120:120:red:t=5[UNC0]      
    Available input pads (0): 
    Available output pads: (1): (4, 1, 0)

Concat with preprocessing stage

The concat filter can be finicky, requiring all the streams to have the same attributes. To combine mismatched streams, they need to be preprocessed by other filters. Video streams must have the same frame size, frame rate, and pixel format. Meanwhile, the audio streams need to have the same sampling rate, channel format, and sample format.

To build the filtergraph to concatenate mismatched video files, we start by defining the filters

>>> audio_filter = fgb.aformat(sample_fmts='flt',        # 32-bit floating point format
...                            sample_rates=48000,       # 48 kS/s sampling rate
...                            channel_layouts='stereo') # 2 channels in stereo layout
>>> video_filters = [
...    fgb.scale(1280, 720,
...              force_original_aspect_ratio='decrease'), # scale at least one dimension to 720p
...    fgb.pad(1280, 720, -1, -1),                        # if not 16:9, pad to fill the frame
...    fgb.setsar(1),                                     # make sure pixels are square
...    fgb.fps(30),                                       # set framerate to 30 (dupe or drop frames)
...    fgb.format('yuv420p')                              # use yuv420p pixel format
... ]

We need multiple video filters while the aformat filter takes care of the audio stream format. To combine the video filters, we can use the built-in sum() with an empty :py:class:Filter. as the initial value. Then, stack video and audio filters to finalize the preprocessor filtergraph for an input file.

>>> preproc = sum(video_filters, fgb.Chain()) | audio_filter
>>> preproc
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd3740>
    FFmpeg expression: "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p;aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo"
    Number of chains: 2
      chain[0]: [UNC0]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[UNC2];
      chain[1]: [UNC1]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[UNC3]      
    Available input pads (2): (0, 0, 0), (1, 0, 0)
    Available output pads: (2): (0, 4, 0), (1, 0, 0)

Suppose that we have 3 video files, we need 3 copies of the preprocessor filtergraph. The preprocessor filtergraph can be multiplied 3 times and assign the input stream specs:

>>> inputs = [f'[{file_id}:{media_type}]' for file_id in range(3) for media_type in ('v', 'a')]
>>> inputs
['[0:v]', '[0:a]', '[1:v]', '[1:a]', '[2:v]', '[2:a]']
>>> prestage = inputs >> (preproc * 3)
>>> prestage
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfcd3020>
    FFmpeg expression: "[0:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p;[0:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo;[1:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p;[1:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo;[2:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p;[2:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo"
    Number of chains: 6
      chain[0]: [0:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[UNC0];
      chain[1]: [0:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[UNC1];
      chain[2]: [1:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[UNC2];
      chain[3]: [1:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[UNC3];
      chain[4]: [2:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[UNC4];
      chain[5]: [2:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[UNC5]      
    Available input pads (0): 
    Available output pads: (6): (0, 4, 0), (1, 0, 0), (2, 4, 0), (3, 0, 0), (4, 4, 0), (5, 0, 0)

Finally, feed the outputs of the prestage filtergraph to the concat filter and assign the output labels:

>>> fg = prestage + fgb.concat(n=3, v=1, a=1) >> ['[vout]','[aout]']
>>> fg
<ffmpegio.filtergraph.Graph.Graph object at 0x7f95cfd04050>
    FFmpeg expression: "[0:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[L0];[0:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[L1];[1:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[L2];[1:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[L3];[2:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[L4];[2:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[L5];[L0][L1][L2][L3][L4][L5]concat=n=3:v=1:a=1[vout][aout]"
    Number of chains: 7
      chain[0]: [0:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[L0];
      chain[1]: [0:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[L1];
      chain[2]: [1:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[L2];
      chain[3]: [1:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[L3];
      chain[4]: [2:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p[L4];
      chain[5]: [2:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo[L5];
      chain[6]: [L0][L1][L2][L3][L4][L5]concat=n=3:v=1:a=1[vout][aout]      
    Available input pads (0): 
    Available output pads: (2): (6, 0, 0), (6, 0, 1)

Note that the output pads of the concat filter are listed as “available” because they are technically not (yet) connected to anything. You can use this filter graph with ffmpegio.transcode() to concatenate 3 input MP4 files:

>>> ffmpegio.transcode(['input1.mp4','input2.mp4','input3.mp4'], 'output.mp4',
...                    filter_complex=fg, map=['[vout]','[aout]'])

Generating filtergraph script for extremely long filtergraph

Extremely long filtergraph description may hit the limit of the subprocess argument length (~30 kB for Windows and ~100 kB for Posix). In such case, the filtergraph description needs to be passed to FFmpeg by the filter_script FFmpeg output option or the filter_complex_script global option with a filtergraph script file.

A preferred way to pass a long filtergraph description is to pipe it directly. If stdin is available, use the input argument of subprocess.Popen():

# assume `fg` is a SISO video Graph object

ffmpegio.ffmpegprocess.run(
   {
      'inputs':  [('input.mp4', None)]
      'outputs': [('output.mp4', {'filter_script:v': 'pipe:0'})]
   },
   input=str(fg))

Note that pipe:0 must be used and not the shorthand '-' unlike the input url.

If stdin is not available, Graph.as_script_file() provides a convenient way to create a temporary script file. The previous example can also run as follows:

with fg.as_script_file() as script_path:
   ffmpegio.ffmpegprocess.run(
      {
            'inputs':  [('input.mp4', None)]
            'outputs': [('output.mp4', {'filter_script:v': script_path})]
      })

Filtergraph API Reference

ffmpegio.filtergraph.as_filter(filter_spec, copy=False)

convert the input to a filter

Parameters:

filter_spec (str | FilterGraphObject) – filtergraph expression or object.
copy (bool) – True to copy even if the input is a Filter object.

Returns:

Filter object interpretation of filter_spec. No copy is performed if the input is already a Filter and copy=False.

Return type:

Filter

If the input is a Chain or Graph object with more than one filter element, this function will raise a FiltergraphConversionError exception.

If the input expression could not be parsed, FiltergraphInvalidExpression will be raised.

ffmpegio.filtergraph.as_filterchain(filter_specs, copy=False)

Convert the input to a filter chain

Parameters:

filter_spec – filtergraph expression or object.
copy (bool) – True to copy even if the input is a Filter object.
filter_specs (str | FilterGraphObject)

Returns:

Chain object interpretation of filter_spec. No copy is performed if the input is already a Chain and copy=False.

Return type:

Chain

If the input is a Graph object with more than one filter chain, this function will raise a FiltergraphConversionError exception.

If the input expression could not be parsed, FiltergraphInvalidExpression will be raised.

ffmpegio.filtergraph.as_filtergraph(filter_specs, copy=False)

Convert the input to a filter graph

Parameters:

filter_spec – filtergraph expression or object.
copy (bool) – True to copy even if the input is a Filter object.
filter_specs (str | FilterGraphObject)

Returns:

Graph object interpretation of filter_spec. No copy is performed if the input is already a Graph and copy=False.

Return type:

Graph

If the input expression could not be parsed, FiltergraphInvalidExpression will be raised.

ffmpegio.filtergraph.as_filtergraph_object(filter_specs, copy=False)

Convert the input to a filter graph object

Parameters:

filter_spec – filtergraph expression or object.
copy (bool) – True to copy even if the input is a Filter object.
filter_specs (str | FilterGraphObject)

Returns:

Depending on the complexity of the filter_spec, Filter, Chain, or Graph object interpretation of filter_spec. No copy is performed if the input is already a Graph and copy=False.

Return type:

FilterGraphObject

class ffmpegio.filtergraph.Filter(filter_spec, *args, filter_id=None, **kwargs)

FFmpeg filter definition immutable class

Parameters:

filter_spec (_type_) – _description_
filter_id (_type_, optional) – _description_, defaults to None
*opts (dict, optional) – filter option values assigned in the order options are declared
**kwopts (dict, optional) – filter options in key=value pairs

exception Error

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception InvalidName(name)

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception InvalidOption

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception Unsupported(name, feature)

Return type:: None

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

add_label(label, inpad=None, outpad=None, force=None)

label a filter pad

Parameters:

label (str) – name of the new label. Square brackets are optional.
inpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int]) – input filter pad index or a sequence of pads, defaults to None
outpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int) – output filter pad index, defaults to None
force (bool) – True to delete existing labels, defaults to None

Returns:

actual label name

Return type:

Graph

Only one of inpad and outpad argument must be given.

If given label already exists, no new label will be created.

If inpad indices are given, the label must be an input stream specifier.

If label has a trailing number, the number will be dropped and replaced with an internally assigned label number.

apply(options, filter_id=None)

apply new filter options

Parameters:

options (dict) – new option key-value pairs. For ordered option, use positional index (0 corresponds to the first option). Set value as None to drop the option. Ordered options can only be dropped in contiguous fashion, including the last ordered option.
filter_id (str, optional) – new filter id, defaults to None

Returns:

new filter with modified options

Return type:

Filter

Note

To add new ordered options, int-keyed options item must be presented in the increasing key order so the option can be expanded one at a time.

attach(right, left_on=None, right_on=None)

attach filter(s), chain(s), or label(s) to a filtergraph object

Parameters:

right (FilterGraphObject | str | list[FilterGraphObject | str]) – output filterchain, filtergraph expression, or label, or list thereof
left_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad_index, specify the pad on left, default to None (first available)
right_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad index, specifies which pad on the right graph, defaults to None (first available)

Returns:

new filtergraph object

Return type:

Graph

One and only one of left or right may be a list or a label.

If pad indices are not specified, only the first available output/input pad is linked. If the primary filtergraph object is Filter or Chain, the chainable pad (i.e., the last pad) will be chosen.

compose(show_unconnected_inputs=False, show_unconnected_outputs=False)

compose filtergraph

Parameters:

show_unconnected_inputs (bool) – display [UNC#] on all unconnected input pads, defaults to True
show_unconnected_outputs (bool) – display [UNC#] on all unconnected output pads, defaults to True

connect(right, from_left, to_right, from_right=None, to_left=None, chain_siso=True, replace_sws_flags=None)

append another filtergraph object and make downstream connections

Parameters:

right (FilterGraphObject | str) – receiving filtergraph object
from_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – output pad ids or labels of left fg
to_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – input pad ids or labels of the right fg
from_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – output pad ids or labels of the right fg
to_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – input pad ids or labels of this left fg
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool | None) – True to use right sws_flags if present, False to drop right sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph | Chain

link labels may be auto-renamed if there is a conflict

count(value, /): Return number of occurrences of value.

get_input_pad(index_or_label)

resolve (unconnected) input pad from pad index or label

Parameters:

index – pad index or link label
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str)

Returns:

filter input pad index and its link label (None if not assigned)

Return type:

Raises error if specified label does not resolve uniquely to an input pad

get_label(input=True, index=None, inpad=None, outpad=None)

get the label string of the specified filter input or output pad

Parameters:

input (bool) – True to get label of input pad, False to get label of output pad, defaults to True
index (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – 3-element tuple to specify the (chain, filter, pad) indices, defaults to None
inpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – alternate argument to specify an input pad index, defaults to None
outpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – alternate argument to specify an output pad index, defaults to None

Returns:

the label of the specified pad or None if no label is assigned.

Return type:

str | None

If the pad index is invalid, the method raises FiltergraphInvalidIndex.

get_num_chains()

get the number of chains

Return type:: int

get_num_filters(chain)

get the number of filters of the specfied chain

Parameters:: chain (int) – id of the chain
Return type:: int

get_num_inputs(): get the number of input pads of the filter :return: number of input pads :rtype: int

get_num_outputs(): get the number of output pads of the filter :return: number of output pads :rtype: int

get_num_pads(input)

get the number of available pads at input or output

Parameters:: input (bool) – True to get the input count, False for the output count.
Return type:: int

get_output_pad(index_or_label)

resolve (unconnected) output filter pad from pad index or labels

Parameters:

index (tuple(int,int,int) or str) – pad index or link label
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str)

Returns:

filter output pad index and its link labels

Return type:

tuple(int,int,int), list(str)

Raises error if specified index does not resolve uniquely to an output pad

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

iter_chains(skip_if_no_input=False, skip_if_no_output=False, chainable_only=False)

iterate over chains of the filtergraphobject

Parameters:

skip_if_no_input (bool) – True to skip chains without available input pads, defaults to False
skip_if_no_output (bool) – True to skip chains without available output pads, defaults to False
chainable_only (bool) – True to further restrict skip_if_no_input and skip_if_no_input arguments to require chainable input or output, defaults to False to allow any input/output

Yield:

chain id and chain object

Return type:

Generator[tuple[int, Chain]]

iter_input_labels(exclude_stream_specs=False)

iterate over the dangling labeled input pads of the filtergraph object

Parameters:: exclude_stream_specs (bool) – True to not include input streams
Yield:: a tuple of 3-tuple pad index and the pad index of the connected output pad if connected
Return type:: Generator[tuple[str, Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int]]

iter_input_pads(pad=None, filter=None, chain=None, *, exclude_chainable=False, chainable_first=False, include_connected=False, unlabeled_only=False, chainable_only=False, full_pad_index=False)

Iterate over input pads of the filter

Parameters:

pad (int | None) – pad id, defaults to None
filter (Literal[0] | None) – filter index, defaults to None
chain (Literal[0] | None) – chain index, defaults to None
exclude_chainable (bool) – True to leave out the last input pads, defaults to False (all avail pads)
chainable_first (bool) – True to yield the last input first then the rest, defaults to False
include_connected (bool) – True to include pads connected to input streams, defaults to False
unlabeled_only (bool) – True to leave out named inputs, defaults to False to return all inputs
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index

Yield:

filter pad index, link label, filter object, output pad index of connected filter if connected

Return type:

Generator[tuple[PAD_INDEX, Filter, None]]

iter_output_labels()

iterate over the dangling labeled output pads of the filtergraph object

Yield:: a tuple of 3-tuple pad index and the pad index of the connected input pad if connected
Return type:: Generator[tuple[str, Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int]]

iter_output_pads(pad=None, filter=None, chain=None, *, exclude_chainable=False, chainable_first=False, include_connected=False, unlabeled_only=False, chainable_only=False, full_pad_index=False)

Iterate over output pads of the filter

Parameters:

pad (int | None) – pad id, defaults to None
filter (Literal[0] | None) – filter index, defaults to None
chain (Literal[0] | None) – chain index, defaults to None
exclude_chainable (bool) – True to leave out the last output pads, defaults to False (all avail pads)
chainable_first (bool) – True to yield the last output first then the rest, defaults to False
include_connected (bool) – True to include pads connected to output streams, defaults to False
unlabeled_only (bool) – True to leave out named outputs, defaults to False to return only all outputs
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all outputs
full_pad_index (bool) – True to return 3-element index

Yield:

filter pad index, link label, filter object, output pad index of connected filter if connected

Return type:

Generator[tuple[PAD_INDEX, Filter, PAD_INDEX | None]]

join(right, how='per_chain', n_links='all', strict=False, unlabeled_only=False, chain_siso=True, replace_sws_flags=None)

filtergraph auto-connector

Parameters:

right (FilterGraphObject | str) – receiving filtergraph object
how (Literal['chainable', 'per_chain', 'all', 'auto']) –
method on how to mate input and output, defaults to "per_chain".
- 'chainable': joins only chainable input pads and output pads.
- 'per_chain': joins one pair of first available input pad and output pad of each
  mating chains. Source and sink chains are ignored.
- 'all': joins all input pads and output pads
- 'auto': tries 'per_chain' first, if fails, then tries 'all'.
n_links (int | Literal['all']) – number of left output pads to be connected to the right input pads, default: 0 (all matching links). If how=='per_chain', n_links connections are made per chain.
strict (bool) – True to raise exception if numbers of available pads do not match, default: False
unlabeled_only (bool) – True to ignore labeled unconnected pads, defaults to False
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

Graph with the appended filter chains or None if inplace=True.

Return type:

Graph | None

next_input_pad(pad=None, filter=None, chain=None, chainable_first=False, unlabeled_only=False, chainable_only=False, full_pad_index=False, exclude_indices=None)

get next available input pad

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (int | None) – chain index, defaults to None
chainable_first (bool) – True to retrieve the last pad first, then the rest sequentially, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index, defaults to False
exclude_indices (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int] | None) – List pad indices to skip, defaults to None to allow all

Returns:

The index of the pad or None if no pad found

Return type:

next_output_pad(pad=None, filter=None, chain=None, chainable_first=False, unlabeled_only=False, chainable_only=False, full_pad_index=False, exclude_indices=None)

get next available output pad

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (int | None) – chain index, defaults to None
chainable_first (bool) – True to retrieve the last pad first, then the rest sequentially, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index, defaults to False
exclude_indices (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int] | None) – List pad indices to skip, defaults to None to allow all

Returns:

The index of the pad or None if no pad found

Return type:

rattach(left, left_on=None, right_on=None)

attach filter(s), chain(s), or label(s) to a filtergraph object

Parameters:

left (FilterGraphObject | str | list[FilterGraphObject | str]) – input filtergraph object, filtergraph expression, or label, or list thereof
right – output filterchain, filtergraph expression, or label, or list thereof
left_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad_index, specify the pad on left, default to None (first available)
right_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad index, specifies which pad on the right graph, defaults to None (first available)

Returns:

new filtergraph object

Return type:

Graph

One and only one of left or right may be a list or a label.

If pad indices are not specified, only the first available output/input pad is linked. If the primary filtergraph object is Filter or Chain, the chainable pad (i.e., the last pad) will be chosen.

rconnect(left, from_left, to_right, from_right=None, to_left=None, chain_siso=True, replace_sws_flags=None)

append another filtergraph object and make upstream connections

Parameters:

left (FilterGraphObject | str) – transmitting filtergraph object
right – receiving filtergraph object
from_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – output pad ids or labels of left fg
to_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – input pad ids or labels of the right fg
from_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – output pad ids or labels of the right fg
to_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – input pad ids or labels of this left fg
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool | None) – True to use right sws_flags if present, False to drop right sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph | Chain

link labels may be auto-renamed if there is a conflict

resolve_pad_index(index_or_label, *, is_input=True, chain_id_omittable=False, filter_id_omittable=False, pad_id_omittable=False, resolve_omitted=True, chain_fill_value=None, filter_fill_value=None, pad_fill_value=None, chainable_first=False, chainable_only=False)

Resolve unconnected label or pad index to full 3-element pad index

Parameters:

index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None) – pad index set or pad label or None to auto-select
is_input (bool) – True to resolve an input pad, else an output pad, defaults to True
chain_id_omittable (bool) – True to allow None chain index, defaults to False
filter_id_omittable (bool) – True to allow None filter index, defaults to False
pad_id_omittable (bool) – True to allow None pad index, defaults to False
resolve_omitted (bool) – True to fill each omitted value with the prescribed fill value.
chain_fill_value (int | None) – if chain_id_omittable=True and chain index is either not given or None, this value will be returned, defaults to None, which returns the first available pad.
filter_fill_value (int | None)
pad_fill_value (int | None)
chainable_first (bool)
chainable_only (bool)

Return type:

:param filter_fill_value:if filter_id_omittable=True and filter index is either not: given or None, this value will be returned, defaults to None, which returns the first available pad.

Parameters:

pad_fill_value (int | None) – if pad_id_omittable=True and either index is None or pad index is None, this value will be returned, defaults to None, which returns the first available pad.
chainable_first (bool) – if True, chainable pad is selected first, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all pads
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None)
is_input (bool)
chain_id_omittable (bool)
filter_id_omittable (bool)
pad_id_omittable (bool)
resolve_omitted (bool)
chain_fill_value (int | None)
filter_fill_value (int | None)

Return type:

One and only one of index and label must be specified. If the given index or label is invalid, it raises FiltergraphPadNotFoundError.

resolve_pad_indices(indices_or_labels, *, is_input=True, resolve_omitted=True, chainable_first=False, unlabeled_only=False, chainable_only=False)

Resolve unconnected labels or pad indices to full 3-element pad indices

Parameters:

indices_or_labels (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None]) – a list of pad indices or pad labels or None to auto-select
is_input (bool) – True to resolve an input pad, else an output pad, defaults to True
chainable_first (bool) – if True, chainable pad is selected first, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all pads
resolve_omitted (bool)

Return type:

One and only one of index and label must be specified. If the given index or label is invalid, it raises FiltergraphPadNotFoundError.

Omitted pads

rjoin(left, how='per_chain', n_links='all', strict=False, unlabeled_only=False, chain_siso=True, replace_sws_flags=None)

filtergraph auto-connector

Parameters:

left (FilterGraphObject | str) – transmitting filtergraph object
how (Literal['chainable', 'per_chain', 'all', 'auto']) –
method on how to mate input and output, defaults to "per_chain".
- 'chainable': joins only chainable input pads and output pads.
- 'per_chain': joins one pair of first available input pad and output pad of each
  mating chains. Source and sink chains are ignored.
- 'all': joins all input pads and output pads
- 'auto': tries 'per_chain' first, if fails, then tries 'all'.
n_links (int | Literal['all']) – number of left output pads to be connected to the right input pads, default: 0 (all matching links). If how=='per_chain', n_links connections are made per chain.
strict (bool) – True to raise exception if numbers of available pads do not match, default: False
unlabeled_only (bool) – True to ignore labeled unconnected pads, defaults to False
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

Graph with the appended filter chains or None if inplace=True.

Return type:

Graph | None

stack(other, auto_link=False, replace_sws_flags=None)

stack another Graph to this Graph

Parameters:

other (FilterGraphObject | str) – other filtergraph
auto_link (bool) – True to connect matched I/O labels, defaults to None
replace_sws_flags (bool | None) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph

Remarks

extend() and import links
If auto-link=False, common labels may be renamed.
For more explicit linking rather than the auto-linking, use connect() instead.

TO-CHECK/TO-DO: what happens if common link labels are already linked

class ffmpegio.filtergraph.Chain(filter_specs=None)

List of FFmpeg filters, connected in series

Chain() to instantiate empty Graph object

Chain(obj) to copy-instantiate Graph object from another

Chain(’…’) to parse an FFmpeg filtergraph expression

Parameters:: filter_specs (str or seq(Filter), optional) – single-in-single-out filtergraph description without labels, defaults to None

exception Error

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

add_label(label, inpad=None, outpad=None, force=None)

label a filter pad

Parameters:

label (str) – name of the new label. Square brackets are optional.
inpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int) – input filter pad index or a sequence of pads, defaults to None
outpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int) – output filter pad index, defaults to None
force (bool) – True to delete existing labels, defaults to None

Returns:

actual label name

Return type:

Graph

Only one of inpad and outpad argument must be given.

If given label already exists, no new label will be created.

If label has a trailing number, the number will be dropped and replaced with an internally assigned label number.

append(item): S.append(value) – append value to the end of the sequence

attach(right, left_on=None, right_on=None)

attach filter(s), chain(s), or label(s) to a filtergraph object

Parameters:

right (FilterGraphObject | str | list[FilterGraphObject | str]) – output filterchain, filtergraph expression, or label, or list thereof
left_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad_index, specify the pad on left, default to None (first available)
right_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad index, specifies which pad on the right graph, defaults to None (first available)

Returns:

new filtergraph object

Return type:

Graph

One and only one of left or right may be a list or a label.

If pad indices are not specified, only the first available output/input pad is linked. If the primary filtergraph object is Filter or Chain, the chainable pad (i.e., the last pad) will be chosen.

clear() → None -- remove all items from S

compose(show_unconnected_inputs=False, show_unconnected_outputs=False)

compose filtergraph

Parameters:

show_unconnected_inputs (bool) – display [UNC#] on all unconnected input pads, defaults to True
show_unconnected_outputs (bool) – display [UNC#] on all unconnected output pads, defaults to True

connect(right, from_left, to_right, from_right=None, to_left=None, chain_siso=True, replace_sws_flags=None)

append another filtergraph object and make downstream connections

Parameters:

right (FilterGraphObject | str) – receiving filtergraph object
from_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – output pad ids or labels of left fg
to_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – input pad ids or labels of the right fg
from_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – output pad ids or labels of the right fg
to_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – input pad ids or labels of this left fg
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool | None) – True to use right sws_flags if present, False to drop right sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph | Chain

link labels may be auto-renamed if there is a conflict

count(value) → integer -- return number of occurrences of value

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

Parameters:: other (Chain | Sequence[Filter | str])

get_input_pad(index_or_label)

resolve (unconnected) input pad from pad index or label

Parameters:

index – pad index or link label
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str)

Returns:

filter input pad index and its link label (None if not assigned)

Return type:

Raises error if specified label does not resolve uniquely to an input pad

get_label(input=True, index=None, inpad=None, outpad=None)

get the label string of the specified filter input or output pad

Parameters:

input (bool) – True to get label of input pad, False to get label of output pad, defaults to True
index (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – 3-element tuple to specify the (chain, filter, pad) indices, defaults to None
inpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – alternate argument to specify an input pad index, defaults to None
outpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – alternate argument to specify an output pad index, defaults to None

Returns:

the label of the specified pad or None if no label is assigned.

Return type:

str | None

If the pad index is invalid, the method raises FiltergraphInvalidIndex.

get_num_chains()

get the number of chains

Return type:: int

get_num_filters(chain)

get the number of filters of the specfied chain

Parameters:: chain (int) – id of the chain
Return type:: int

get_num_inputs()

get the number of input pads of the filter :return: number of input pads

Return type:: int

get_num_outputs()

get the number of output pads of the filter :return: number of output pads

Return type:: int

get_num_pads(input)

get the number of available pads at input or output

Parameters:: input (bool) – True to get the input count, False for the output count.
Return type:: int

get_output_pad(index_or_label)

resolve (unconnected) output filter pad from pad index or labels

Parameters:

index (tuple(int,int,int) or str) – pad index or link label
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str)

Returns:

filter output pad index and its link labels

Return type:

tuple(int,int,int), list(str)

Raises error if specified index does not resolve uniquely to an output pad

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item): S.insert(index, value) – insert value before index

is_last_filter(filter_id)

Returns True if the given id is the last filter of the chain

Parameters:: filter_id (int)
Return type:: bool

iter_chains(skip_if_no_input=False, skip_if_no_output=False, chainable_only=False)

iterate over chains of the filtergraphobject

Parameters:

skip_if_no_input (bool) – True to skip chains without available input pads, defaults to False
skip_if_no_output (bool) – True to skip chains without available output pads, defaults to False
chainable_only (bool) – True to further restrict skip_if_no_input and skip_if_no_input arguments to require chainable input or output, defaults to False to allow any input/output

Yield:

chain id and chain object

Return type:

Generator[tuple[int, Chain]]

iter_input_labels(exclude_stream_specs=False)

iterate over the dangling labeled input pads of the filtergraph object

Parameters:: exclude_stream_specs (bool) – True to not include input streams
Yield:: a tuple of 3-tuple pad index and the pad index of the connected output pad if connected
Return type:: Generator[tuple[str, Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int]]

iter_input_pads(pad=None, filter=None, chain=None, *, exclude_chainable=False, chainable_first=False, include_connected=False, unlabeled_only=False, chainable_only=False, full_pad_index=False)

Iterate over input pads of the filters on the filterchain

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (Literal[0] | None) – chain index, defaults to None
exclude_chainable (bool) – True to leave out the last input pads, defaults to False (all avail pads)
chainable_first (bool) – True to yield the last input first then the rest, defaults to False
include_connected (bool) – True to include pads connected to input streams, defaults to False
unlabeled_only (bool) – True to leave out named inputs, defaults to False to return all inputs
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index

Yield:

filter pad index, link label, filter object, output pad index of connected filter if connected

Return type:

iter_output_labels()

iterate over the dangling labeled output pads of the filtergraph object

Yield:: a tuple of 3-tuple pad index and the pad index of the connected input pad if connected
Return type:: Generator[tuple[str, Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int]]

iter_output_pads(pad=None, filter=None, chain=None, *, exclude_chainable=False, chainable_first=False, include_connected=False, unlabeled_only=False, chainable_only=False, full_pad_index=False)

Iterate over output pads of the filters on the filterchain

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (int | None) – chain index, defaults to None
exclude_chainable (bool) – True to leave out the last output pads, defaults to False (all avail pads)
chainable_first (bool) – True to yield the last output first then the rest, defaults to False
include_connected (bool) – True to include pads connected to output streams, defaults to False
unlabeled_only (bool) – True to leave out named outputs, defaults to False to return all outputs
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all outputs
full_pad_index (bool) – True to return 3-element index

Yield:

filter pad index, link label, filter object, output pad index of connected filter if connected

Return type:

join(right, how='per_chain', n_links='all', strict=False, unlabeled_only=False, chain_siso=True, replace_sws_flags=None)

filtergraph auto-connector

Parameters:

right (FilterGraphObject | str) – receiving filtergraph object
how (Literal['chainable', 'per_chain', 'all', 'auto']) –
method on how to mate input and output, defaults to "per_chain".
- 'chainable': joins only chainable input pads and output pads.
- 'per_chain': joins one pair of first available input pad and output pad of each
  mating chains. Source and sink chains are ignored.
- 'all': joins all input pads and output pads
- 'auto': tries 'per_chain' first, if fails, then tries 'all'.
n_links (int | Literal['all']) – number of left output pads to be connected to the right input pads, default: 0 (all matching links). If how=='per_chain', n_links connections are made per chain.
strict (bool) – True to raise exception if numbers of available pads do not match, default: False
unlabeled_only (bool) – True to ignore labeled unconnected pads, defaults to False
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

Graph with the appended filter chains or None if inplace=True.

Return type:

Graph | None

next_input_pad(pad=None, filter=None, chain=None, chainable_first=False, unlabeled_only=False, chainable_only=False, full_pad_index=False, exclude_indices=None)

get next available input pad

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (int | None) – chain index, defaults to None
chainable_first (bool) – True to retrieve the last pad first, then the rest sequentially, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index, defaults to False
exclude_indices (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int] | None) – List pad indices to skip, defaults to None to allow all

Returns:

The index of the pad or None if no pad found

Return type:

next_output_pad(pad=None, filter=None, chain=None, chainable_first=False, unlabeled_only=False, chainable_only=False, full_pad_index=False, exclude_indices=None)

get next available output pad

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (int | None) – chain index, defaults to None
chainable_first (bool) – True to retrieve the last pad first, then the rest sequentially, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index, defaults to False
exclude_indices (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int] | None) – List pad indices to skip, defaults to None to allow all

Returns:

The index of the pad or None if no pad found

Return type:

pop([index]) → item -- remove and return item at index (default last).: Raise IndexError if list is empty or index is out of range.

rattach(left, left_on=None, right_on=None)

attach filter(s), chain(s), or label(s) to a filtergraph object

Parameters:

left (FilterGraphObject | str | list[FilterGraphObject | str]) – input filtergraph object, filtergraph expression, or label, or list thereof
right – output filterchain, filtergraph expression, or label, or list thereof
left_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad_index, specify the pad on left, default to None (first available)
right_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad index, specifies which pad on the right graph, defaults to None (first available)

Returns:

new filtergraph object

Return type:

Graph

One and only one of left or right may be a list or a label.

If pad indices are not specified, only the first available output/input pad is linked. If the primary filtergraph object is Filter or Chain, the chainable pad (i.e., the last pad) will be chosen.

rconnect(left, from_left, to_right, from_right=None, to_left=None, chain_siso=True, replace_sws_flags=None)

append another filtergraph object and make upstream connections

Parameters:

left (FilterGraphObject | str) – transmitting filtergraph object
right – receiving filtergraph object
from_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – output pad ids or labels of left fg
to_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – input pad ids or labels of the right fg
from_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – output pad ids or labels of the right fg
to_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – input pad ids or labels of this left fg
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool | None) – True to use right sws_flags if present, False to drop right sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph | Chain

link labels may be auto-renamed if there is a conflict

remove(item): S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

resolve_pad_index(index_or_label, *, is_input=True, chain_id_omittable=False, filter_id_omittable=False, pad_id_omittable=False, resolve_omitted=True, chain_fill_value=None, filter_fill_value=None, pad_fill_value=None, chainable_first=False, chainable_only=False)

Resolve unconnected label or pad index to full 3-element pad index

Parameters:

index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None) – pad index set or pad label or None to auto-select
is_input (bool) – True to resolve an input pad, else an output pad, defaults to True
chain_id_omittable (bool) – True to allow None chain index, defaults to False
filter_id_omittable (bool) – True to allow None filter index, defaults to False
pad_id_omittable (bool) – True to allow None pad index, defaults to False
resolve_omitted (bool) – True to fill each omitted value with the prescribed fill value.
chain_fill_value (int | None) – if chain_id_omittable=True and chain index is either not given or None, this value will be returned, defaults to None, which returns the first available pad.
filter_fill_value (int | None)
pad_fill_value (int | None)
chainable_first (bool)
chainable_only (bool)

Return type:

:param filter_fill_value:if filter_id_omittable=True and filter index is either not: given or None, this value will be returned, defaults to None, which returns the first available pad.

Parameters:

pad_fill_value (int | None) – if pad_id_omittable=True and either index is None or pad index is None, this value will be returned, defaults to None, which returns the first available pad.
chainable_first (bool) – if True, chainable pad is selected first, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all pads
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None)
is_input (bool)
chain_id_omittable (bool)
filter_id_omittable (bool)
pad_id_omittable (bool)
resolve_omitted (bool)
chain_fill_value (int | None)
filter_fill_value (int | None)

Return type:

One and only one of index and label must be specified. If the given index or label is invalid, it raises FiltergraphPadNotFoundError.

resolve_pad_indices(indices_or_labels, *, is_input=True, resolve_omitted=True, chainable_first=False, unlabeled_only=False, chainable_only=False)

Resolve unconnected labels or pad indices to full 3-element pad indices

Parameters:

indices_or_labels (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None]) – a list of pad indices or pad labels or None to auto-select
is_input (bool) – True to resolve an input pad, else an output pad, defaults to True
chainable_first (bool) – if True, chainable pad is selected first, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all pads
resolve_omitted (bool)

Return type:

One and only one of index and label must be specified. If the given index or label is invalid, it raises FiltergraphPadNotFoundError.

Omitted pads

reverse(): S.reverse() – reverse IN PLACE

rjoin(left, how='per_chain', n_links='all', strict=False, unlabeled_only=False, chain_siso=True, replace_sws_flags=None)

filtergraph auto-connector

Parameters:

left (FilterGraphObject | str) – transmitting filtergraph object
how (Literal['chainable', 'per_chain', 'all', 'auto']) –
method on how to mate input and output, defaults to "per_chain".
- 'chainable': joins only chainable input pads and output pads.
- 'per_chain': joins one pair of first available input pad and output pad of each
  mating chains. Source and sink chains are ignored.
- 'all': joins all input pads and output pads
- 'auto': tries 'per_chain' first, if fails, then tries 'all'.
n_links (int | Literal['all']) – number of left output pads to be connected to the right input pads, default: 0 (all matching links). If how=='per_chain', n_links connections are made per chain.
strict (bool) – True to raise exception if numbers of available pads do not match, default: False
unlabeled_only (bool) – True to ignore labeled unconnected pads, defaults to False
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

Graph with the appended filter chains or None if inplace=True.

Return type:

Graph | None

stack(other, auto_link=False, replace_sws_flags=None)

stack another Graph to this Graph

Parameters:

other (FilterGraphObject | str) – other filtergraph
auto_link (bool) – True to connect matched I/O labels, defaults to None
replace_sws_flags (bool | None) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph

Remarks

extend() and import links
If auto-link=False, common labels may be renamed.
For more explicit linking rather than the auto-linking, use connect() instead.

TO-CHECK/TO-DO: what happens if common link labels are already linked

class ffmpegio.filtergraph.Graph(filter_specs=None, links=None, sws_flags=None)

List of FFmpeg filterchains in parallel with interchain link specifications

Graph() to instantiate empty Graph object

Graph(obj) to copy-instantiate Graph object from another

Graph(’…’) to parse an FFmpeg filtergraph expression

Graph(filter_specs, links, sws_flags) to specify the compose_graph(…) arguments

Parameters:

filter_specs (Graph, str, or seq(seq(filter_args))) – either an existing Graph instance to copy, an FFmpeg filtergraph expression, or a nested sequence of argument sequences to compose_filter() to define a filtergraph. For the latter option, The last element of each filter argument sequence may be a dict, defining its keyword arguments, defaults to None
links (dict, optional) – specifies filter links
sws_flags (seq of stringifyable elements with optional dict as the last element for the keyword flags, optional) – specify swscale flags for those automatically inserted scalers, defaults to None

exception Error

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception FilterPadMediaTypeMismatch(in_name, in_pad, in_type, out_name, out_pad, out_type)

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception InvalidFilterPadId(type, index)

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

add_label(label, inpad=None, outpad=None, force=None)

label a filter pad

Parameters:

label (str) – name of the new label. Square brackets are optional.
inpad (tuple(int,int,int) | seq(tuple(int,int,int)), optional) – input filter pad index or a sequence of pads, defaults to None
outpad (tuple(int,int,int), optional) – output filter pad index, defaults to None
force (bool, optional) – True to delete existing labels, defaults to None

Returns:

actual label name

Return type:

str

Only one of inpad and outpad argument must be given.

If given label already exists, no new label will be created.

If label has a trailing number, the number will be dropped and replaced with an internally assigned label number.

append(item)

S.append(value) – append value to the end of the sequence

Parameters:: item (Chain | str)

are_linked(inpad, outpad, check_input_stream=False)

True if given pads are linked

Parameters:

inpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – input pad index, default to None to check if outpad is connected to any input pad.
outpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – output pad index, defaults to None to check if inpad is connected to any output pad or an input stream.
check_input_stream (bool | str) – True to check inpad is connected to an input stream, or a stream specifier string to check the connection to a specific stream, defaults to False.

Return type:

bool

ValueError will be raised if both inpad and outpad None or if include_input_stream!=False and outpad is None.

as_script_file()

return script file containing the filtergraph description

Yield:: path of a temporary text file with filtergraph description
Return type:: str

This method is intended to work with the filter_script and filter_complex_script FFmpeg options, by creating a temporary text file containing the filtergraph description.

Note

Only use this function when the filtergraph description is too long for OS to handle it. Presenting the filtergraph with a filter_complex or filter option to FFmpeg is always a faster solution.

Moreover, if stdin is available, i.e., not for a write or filter operation, it is more performant to pass the long filtergraph object to the subprocess’ input argument instead of using this method.

Use this method with a with statement. How to incorporate its output with ffmpegprocess depends on the as_file_obj argument.

Example:

The following example illustrates a usecase for a video SISO filtergraph:

# assume `fg` is a SISO video filter Graph object

with fg.as_script_file() as script_path:
    ffmpegio.ffmpegprocess.run(
        {
            'inputs':  [('input.mp4', None)]
            'outputs': [('output.mp4', {'filter_script:v': script_path})]
        })

As noted above, a performant alternative is to use an input pipe and feed the filtergraph description directly:

ffmpegio.ffmpegprocess.run(
    {
        'inputs':  [('input.mp4', None)]
        'outputs': [('output.mp4', {'filter_script:v': 'pipe:0'})]
    },
    input=str(fg))

Note that pipe:0 must be used and not the shorthand '-' unlike the input url.

attach(right, left_on=None, right_on=None)

attach filter(s), chain(s), or label(s) to a filtergraph object

Parameters:

right (FilterGraphObject | str | list[FilterGraphObject | str]) – output filterchain, filtergraph expression, or label, or list thereof
left_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad_index, specify the pad on left, default to None (first available)
right_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad index, specifies which pad on the right graph, defaults to None (first available)

Returns:

new filtergraph object

Return type:

Graph

One and only one of left or right may be a list or a label.

If pad indices are not specified, only the first available output/input pad is linked. If the primary filtergraph object is Filter or Chain, the chainable pad (i.e., the last pad) will be chosen.

clear() → None -- remove all items from S

compose(show_unconnected_inputs=True, show_unconnected_outputs=True)

compose filtergraph

Parameters:

show_unconnected_inputs (bool) – display [UNC#] on all unconnected input pads, defaults to True
show_unconnected_outputs (bool) – display [UNC#] on all unconnected output pads, defaults to True

connect(right, from_left, to_right, from_right=None, to_left=None, chain_siso=True, replace_sws_flags=None)

append another filtergraph object and make downstream connections

Parameters:

right (FilterGraphObject | str) – receiving filtergraph object
from_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – output pad ids or labels of left fg
to_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – input pad ids or labels of the right fg
from_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – output pad ids or labels of the right fg
to_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – input pad ids or labels of this left fg
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool | None) – True to use right sws_flags if present, False to drop right sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph | Chain

link labels may be auto-renamed if there is a conflict

count(value) → integer -- return number of occurrences of value

extend(other, auto_link=False, force_link=False)

S.extend(iterable) – extend sequence by appending elements from the iterable

Parameters:

other (Sequence[fgb.Chain | str] | fgb.FilterGraph)
auto_link (bool)
force_link (bool)

get_input_pad(index_or_label)

resolve (unconnected) input pad from pad index or label

Parameters:

index – pad index or link label
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str)

Returns:

filter input pad index and its link label (None if not assigned)

Return type:

Raises error if specified label does not resolve uniquely to an input pad

get_label(input=True, index=None, inpad=None, outpad=None)

get the label string of the specified filter input or output pad

Parameters:

input (bool) – True to get label of input pad, False to get label of output pad, defaults to True
index (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – 3-element tuple to specify the (chain, filter, pad) indices, defaults to None
inpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – alternate argument to specify an input pad index, defaults to None
outpad (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | None) – alternate argument to specify an output pad index, defaults to None

Returns:

the label of the specified pad or None if no label is assigned.

Return type:

str | None

If the pad index is invalid, the method raises FiltergraphInvalidIndex.

get_num_chains()

get the number of hains

Return type:: int

get_num_filters(chain)

get the number of filters of the specfied chain

Parameters:: chain (int) – id of the chain
Return type:: int

get_num_inputs(chainable_only=False): get the number of input pads of the filter :return: number of input pads

get_num_outputs(chainable_only=False): get the number of output pads of the filter :return: number of output pads

get_num_pads(input)

get the number of available pads at input or output

Parameters:: input (bool) – True to get the input count, False for the output count.
Return type:: int

get_output_pad(index_or_label)

resolve (unconnected) output filter pad from pad index or labels

Parameters:

index (tuple(int,int,int) or str) – pad index or link label
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str)

Returns:

filter output pad index and its link labels

Return type:

tuple(int,int,int), list(str)

Raises error if specified index does not resolve uniquely to an output pad

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

Parameters:

i (int)
item (Chain | str)

is_chain_siso(chain_id, check_input=True, check_output=True, check_link=False)

True if specified filter chain is single-input and single-output

Parameters:

chain_id (int) – chain id
check_input (bool) – False to check only for single-output, defaults to True
check_output (bool) – False to check only for single-input, defaults to True
check_link (bool) – True to return True if and only if the chain has no active connection, defaults to True

Return type:

bool

iter_chains(skip_if_no_input=False, skip_if_no_output=False, chainable_only=False)

iterate over chains of the filtergraphobject

Parameters:

skip_if_no_input (bool) – True to skip chains without available input pads, defaults to False
skip_if_no_output (bool) – True to skip chains without available output pads, defaults to False
chainable_only (bool) – True to further restrict skip_if_no_input and skip_if_no_input arguments to require chainable input or output, defaults to False to allow any input/output

Yield:

chain id and chain object

Return type:

Generator[tuple[int, Chain]]

iter_input_labels(exclude_stream_specs=False)

iterate over the dangling labeled input pads of the filtergraph object

Parameters:: exclude_stream_specs (bool) – True to not include input streams
Yield:: a tuple of 3-tuple pad index and the pad index of the connected output pad if connected
Return type:: Generator[tuple[str, Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int]]

iter_input_pads(pad=None, filter=None, chain=None, *, exclude_chainable=False, chainable_first=False, include_connected=False, unlabeled_only=False, chainable_only=False, full_pad_index=False)

Iterate over input pads of the filters on the filtergraph

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (int | None) – chain index, defaults to None
exclude_chainable (bool) – True to leave out the last input pads, defaults to False (all avail pads)
chainable_first (bool) – True to yield the last input first then the rest, defaults to False
include_connected (bool) – True to include pads connected to input streams, defaults to False
unlabeled_only (bool) – True to leave out named inputs, defaults to False to return all inputs
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index

Yield:

filter pad index, link label, filter object, output pad index of connected filter if connected

Return type:

iter_output_labels()

iterate over the dangling labeled output pads of the filtergraph object

Yield:: a tuple of 3-tuple pad index and the pad index of the connected input pad if connected
Return type:: Generator[tuple[str, Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int]]

iter_output_pads(pad=None, filter=None, chain=None, *, exclude_chainable=False, chainable_first=False, include_connected=False, unlabeled_only=False, chainable_only=False, full_pad_index=False)

Iterate over output pads of the filter

Parameters:

pad – pad id, defaults to None
filter – filter index, defaults to None
chain – chain index, defaults to None
exclude_chainable (bool) – True to leave out the last output pads, defaults to False (all avail pads)
chainable_first (bool) – True to yield the last output first then the rest, defaults to False
include_connected (bool) – True to include pads connected to output streams, defaults to False
unlabeled_only (bool) – True to leave out named outputs, defaults to False to return all outputs
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all outputs
full_pad_index (bool) – True to return 3-element index

Yield:

filter pad index, link label, filter object, output pad index of connected filter if connected

Return type:

join(right, how='per_chain', n_links='all', strict=False, unlabeled_only=False, chain_siso=True, replace_sws_flags=None)

filtergraph auto-connector

Parameters:

right (FilterGraphObject | str) – receiving filtergraph object
how (Literal['chainable', 'per_chain', 'all', 'auto']) –
method on how to mate input and output, defaults to "per_chain".
- 'chainable': joins only chainable input pads and output pads.
- 'per_chain': joins one pair of first available input pad and output pad of each
  mating chains. Source and sink chains are ignored.
- 'all': joins all input pads and output pads
- 'auto': tries 'per_chain' first, if fails, then tries 'all'.
n_links (int | Literal['all']) – number of left output pads to be connected to the right input pads, default: 0 (all matching links). If how=='per_chain', n_links connections are made per chain.
strict (bool) – True to raise exception if numbers of available pads do not match, default: False
unlabeled_only (bool) – True to ignore labeled unconnected pads, defaults to False
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

Graph with the appended filter chains or None if inplace=True.

Return type:

Graph | None

link(inpad, outpad, label=None, preserve_label=False, force=False)

set a filtergraph link

Parameters:

inpad (PAD_INDEX) – input pad ids
outpad (PAD_INDEX) – output pad index
label (str | None) – desired label name, defaults to None (=reuse inpad/outpad label or unnamed link)
preserve_label (Literal[False, 'input', 'output']) – False to remove the labels of the input and output pads (default) or ‘input’ to prefer the input label or ‘output’ to prefer the output label.
force (bool) – True to drop conflicting existing link, defaults to False

Returns:

assigned label of the created link. Unnamed links gets a unique integer value assigned to it.

Return type:

str | int

..notes:

Unless force=True, inpad pad must not be already connected

User-supplied label name is a suggested name, and the function could modify the name to maintain integrity.

If inpad or outpad were previously named, their names will be dropped unless one matches the user-supplied label.

No guarantee on consistency of the link label (both named and unnamed) during the life of the object

next_input_pad(pad=None, filter=None, chain=None, chainable_first=False, unlabeled_only=False, chainable_only=False, full_pad_index=False, exclude_indices=None)

get next available input pad

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (int | None) – chain index, defaults to None
chainable_first (bool) – True to retrieve the last pad first, then the rest sequentially, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index, defaults to False
exclude_indices (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int] | None) – List pad indices to skip, defaults to None to allow all

Returns:

The index of the pad or None if no pad found

Return type:

next_output_pad(pad=None, filter=None, chain=None, chainable_first=False, unlabeled_only=False, chainable_only=False, full_pad_index=False, exclude_indices=None)

get next available output pad

Parameters:

pad (int | None) – pad id, defaults to None
filter (int | None) – filter index, defaults to None
chain (int | None) – chain index, defaults to None
chainable_first (bool) – True to retrieve the last pad first, then the rest sequentially, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all inputs
full_pad_index (bool) – True to return 3-element index, defaults to False
exclude_indices (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int] | None) – List pad indices to skip, defaults to None to allow all

Returns:

The index of the pad or None if no pad found

Return type:

pop([index]) → item -- remove and return item at index (default last).: Raise IndexError if list is empty or index is out of range.

rattach(left, left_on=None, right_on=None)

attach filter(s), chain(s), or label(s) to a filtergraph object

Parameters:

left (FilterGraphObject | str | list[FilterGraphObject | str]) – input filtergraph object, filtergraph expression, or label, or list thereof
right – output filterchain, filtergraph expression, or label, or list thereof
left_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad_index, specify the pad on left, default to None (first available)
right_on (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None] | None) – pad index, specifies which pad on the right graph, defaults to None (first available)

Returns:

new filtergraph object

Return type:

Graph

One and only one of left or right may be a list or a label.

If pad indices are not specified, only the first available output/input pad is linked. If the primary filtergraph object is Filter or Chain, the chainable pad (i.e., the last pad) will be chosen.

rconnect(left, from_left, to_right, from_right=None, to_left=None, chain_siso=True, replace_sws_flags=None)

append another filtergraph object and make upstream connections

Parameters:

left (FilterGraphObject | str) – transmitting filtergraph object
right – receiving filtergraph object
from_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – output pad ids or labels of left fg
to_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str]) – input pad ids or labels of the right fg
from_right (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – output pad ids or labels of the right fg
to_left (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | list[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str] | None) – input pad ids or labels of this left fg
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool | None) – True to use right sws_flags if present, False to drop right sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph | Chain

link labels may be auto-renamed if there is a conflict

remove(item): S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

remove_label(label)

remove an input/output label

Parameters:: label (str) – linkn label

rename_label(old_label, new_label)

rename an existing link label

Parameters:

old_label (str) – existing label named
new_label (str) – new desired label name or None to make it unnamed label

Returns:

actual label name or None if unnamed

Return type:

str | None

Note:

new_label is not guaranteed, and actual label depends on existing labels

resolve_pad_index(index_or_label, *, is_input=True, chain_id_omittable=False, filter_id_omittable=False, pad_id_omittable=False, resolve_omitted=True, chain_fill_value=None, filter_fill_value=None, pad_fill_value=None, chainable_first=False)

Resolve unconnected label or pad index to full 3-element pad index

Parameters:

index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None) – pad index set or pad label or None to auto-select
is_input (bool) – True to resolve an input pad, else an output pad, defaults to True
chain_id_omittable (bool) – True to allow None chain index, defaults to False
filter_id_omittable (bool) – True to allow None filter index, defaults to False
pad_id_omittable (bool) – True to allow None pad index, defaults to False
resolve_omitted (bool) – True to fill each omitted value with the prescribed fill value.
chain_fill_value (int | None) – if chain_id_omittable=True and chain index is either not given or None, this value will be returned, defaults to None, which returns the first available pad.
filter_fill_value (int | None)
pad_fill_value (int | None)
chainable_first (bool)

Return type:

:param filter_fill_value:if filter_id_omittable=True and filter index is either not: given or None, this value will be returned, defaults to None, which returns the first available pad.

Parameters:

pad_fill_value (int | None) – if pad_id_omittable=True and either index is None or pad index is None, this value will be returned, defaults to None, which returns the first available pad.
chainable_first (bool) – if True, chainable pad is selected first, defaults to False
index_or_label (Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None)
is_input (bool)
chain_id_omittable (bool)
filter_id_omittable (bool)
pad_id_omittable (bool)
resolve_omitted (bool)
chain_fill_value (int | None)
filter_fill_value (int | None)

Return type:

One and only one of index and label must be specified. If the given index or label is invalid, it raises FiltergraphPadNotFoundError.

resolve_pad_indices(indices_or_labels, *, is_input=True, resolve_omitted=True, chainable_first=False, unlabeled_only=False, chainable_only=False)

Resolve unconnected labels or pad indices to full 3-element pad indices

Parameters:

indices_or_labels (Sequence[Tuple[int | None, int | None, int] | Tuple[int | None, int | None] | Tuple[int | None] | int | str | None]) – a list of pad indices or pad labels or None to auto-select
is_input (bool) – True to resolve an input pad, else an output pad, defaults to True
chainable_first (bool) – if True, chainable pad is selected first, defaults to False
unlabeled_only (bool) – True to retrieve only unlabeled pad, defaults to False
chainable_only (bool) – True to only iterate chainable pads, defaults to False to return all pads
resolve_omitted (bool)

Return type:

One and only one of index and label must be specified. If the given index or label is invalid, it raises FiltergraphPadNotFoundError.

Omitted pads

reverse(): S.reverse() – reverse IN PLACE

rjoin(left, how='per_chain', n_links='all', strict=False, unlabeled_only=False, chain_siso=True, replace_sws_flags=None)

filtergraph auto-connector

Parameters:

left (FilterGraphObject | str) – transmitting filtergraph object
how (Literal['chainable', 'per_chain', 'all', 'auto']) –
method on how to mate input and output, defaults to "per_chain".
- 'chainable': joins only chainable input pads and output pads.
- 'per_chain': joins one pair of first available input pad and output pad of each
  mating chains. Source and sink chains are ignored.
- 'all': joins all input pads and output pads
- 'auto': tries 'per_chain' first, if fails, then tries 'all'.
n_links (int | Literal['all']) – number of left output pads to be connected to the right input pads, default: 0 (all matching links). If how=='per_chain', n_links connections are made per chain.
strict (bool) – True to raise exception if numbers of available pads do not match, default: False
unlabeled_only (bool) – True to ignore labeled unconnected pads, defaults to False
chain_siso (bool) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

Graph with the appended filter chains or None if inplace=True.

Return type:

Graph | None

stack(other, auto_link=False, replace_sws_flags=None)

stack another Graph to this Graph

Parameters:

other (FilterGraphObject | str) – other filtergraph
auto_link (bool) – True to connect matched I/O labels, defaults to None
replace_sws_flags (bool | None) – True to use other’s sws_flags if present, False to ignore other’s sws_flags, None to throw an exception (default)

Returns:

new filtergraph object

Return type:

Graph

Remarks

extend() and import links
If auto-link=False, common labels may be renamed.
For more explicit linking rather than the auto-linking, use connect() instead.

TO-CHECK/TO-DO: what happens if common link labels are already linked

sws_flags

swscale flags for automatically inserted scalers

Type:: Filter|None

unlink(label=None, inpad=None, outpad=None)

unlink specified links

Parameters:

label (str|int, optional) – specify all the links with this label, defaults to None
inpad (tuple(int,int,int), optional) – specify the link with this inpad pad, defaults to None
outpad (tuple(int,int,int), optional) – specify all the links with this outpad pad, defaults to None

Filtergraph Builder Reference

Accessing filter information on FFmpeg

Constructing filtergraphs

|: filtegraph stacking

* n: filtergraph self-stacking

+: filtergraph joining

>> filtergraph labeling / filtergraph p2p linking

Filter pad labeling

Filtergraph linking

Filter pad indexing

Graph.link() - within-filtergraph linking

Examples

Simple example

Concat with preprocessing stage

Generating filtergraph script for extremely long filtergraph

Filtergraph API Reference

Remarks

Remarks

Remarks

`|`: filtegraph stacking

`* n`: filtergraph self-stacking

`+`: filtergraph joining

`>>` filtergraph labeling / filtergraph p2p linking

`Graph.link()` - within-filtergraph linking