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 object at 0x7fa7c599baa0>
    FFmpeg expression: "afade=t=in:d=1,afade=t=out:st=9:d=1"
    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 object at 0x7fa7b7ca8410>
    FFmpeg expression: "afade=t=in:d=1,afade=t=out:st=9:d=1"
    Number of chains: 1
      chain[0]: afade=t=in:d=1,afade=t=out:st=9:d=1      
    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 object at 0x7fa7c599baa0>
    FFmpeg expression: "afade=t=in:d=1,afade=t=out:st=9:d=1"
    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)
<ffmpegio.filtergraph.Filter object at 0x7fa7b7b38f50>
    FFmpeg expression: "crop=in_w-100:in_h-100:x=100:y=100"
    Number of inputs: 1
    Number of outputs: 1

>>> fgb.Filter('crop=in_w-100:in_h-100:x=100:y=100')
<ffmpegio.filtergraph.Filter object at 0x7fa7b7b39610>
    FFmpeg expression: "crop=in_w-100:in_h-100:x=100:y=100"
    Number of inputs: 1
    Number of outputs: 1

>>> fgb.crop('in_w-100', 'in_h-100', x=100, y=100)
<ffmpegio.filtergraph.Filter object at 0x7fa7b7b38f50>
    FFmpeg expression: "crop=in_w-100:in_h-100:x=100:y=100"
    Number of inputs: 1
    Number of outputs: 1

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:

`ffmpegio.filtergraph.Filter.apply`	apply new filter options
`ffmpegio.filtergraph.Chain.append`	S.append(value) -- append value to the end of the sequence
`ffmpegio.filtergraph.Chain.extend`	S.extend(iterable) -- extend sequence by appending elements from the iterable
`ffmpegio.filtergraph.Graph.link`	set a filtergraph link
`ffmpegio.filtergraph.Graph.add_label`	label a filter pad
`ffmpegio.filtergraph.Graph.stack`	stack another Graph to this Graph
`ffmpegio.filtergraph.Graph.connect`	stack another Graph and make connection from left to right
`ffmpegio.filtergraph.Graph.join`	append another Graph object and connect all inputs to the outputs of this filtergraph
`ffmpegio.filtergraph.Graph.attach`	attach an output pad to right's input pad
`ffmpegio.filtergraph.Graph.rattach`	prepend an input filterchain to an existing filter chain of the filtergraph

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 object at 0x7fa7b7ca8500>
    FFmpeg expression: "trim=30:60;trim=90:120"
    Number of chains: 2
      chain[0]: trim=30:60;
      chain[1]: trim=90:120      
    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 object at 0x7fa7b7d2bc80>
    FFmpeg expression: "trim=30:60,scale=200:-1;atrim=30:60,afade=t=in"
    Number of chains: 2
      chain[0]: trim=30:60,scale=200:-1;
      chain[1]: atrim=30:60,afade=t=in      
    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]')
<ffmpegio.filtergraph.Graph object at 0x7fa7b7b97b90>
    FFmpeg expression: "[0:v]trim=30:60,scale=200:-1[out1];[0:a]atrim=30:60,afade=t=in[out2]"
    Number of chains: 2
      chain[0]: [0:v]trim=30:60,scale=200:-1[out1];
      chain[1]: [0:a]atrim=30:60,afade=t=in[out2]      
    Available input pads (0): 
    Available output pads: (2): (0, 1, 0), (1, 1, 0)

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 object at 0x7fa7b7b73770>
    FFmpeg expression: "crop=100:100;crop=100:100;crop=100:100"
    Number of chains: 3
      chain[0]: crop=100:100;
      chain[1]: crop=100:100;
      chain[2]: crop=100:100      
    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 object at 0x7fa7b7b976e0>
    FFmpeg expression: "fps=30,format=yuv420p;fps=30,format=yuv420p"
    Number of chains: 2
      chain[0]: fps=30,format=yuv420p;
      chain[1]: fps=30,format=yuv420p      
    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
<ffmpegio.filtergraph.Graph object at 0x7fa7b7b97920>
    FFmpeg expression: "color,[0]overlay[vout1];color,[0]overlay[vout2]"
    Number of chains: 2
      chain[0]: color,[0]overlay[vout1];
      chain[1]: color,[0]overlay[vout2]      
    Available input pads (0): 
    Available output pads: (2): (0, 1, 0), (1, 1, 0)

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 object at 0x7fa7b7b97ad0>
    FFmpeg expression: "trim=60:120,crop=100:100:12:34,fps=30"
    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 object at 0x7fa7c5ad78c0>
    FFmpeg expression: "[0]fps=30[v0];[v0]overlay,split[v1][v2];[v2]hflip"
    Number of chains: 3
      chain[0]: [0]fps=30[v0];
      chain[1]: [v0]overlay,split[v1][v2];
      chain[2]: [v2]hflip      
    Available input pads (1): (1, 0, 1)
    Available output pads: (2): (1, 1, 0), (2, 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 object at 0x7fa7b7b97da0>
    FFmpeg expression: "hflip[L0];[L0]hstack"
    Number of chains: 2
      chain[0]: hflip[L0];
      chain[1]: [L0]hstack      
    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 object at 0x7fa7b7bc4050>
    FFmpeg expression: "hflip[L0];vflip[L1];[L0][L1]hstack"
    Number of chains: 3
      chain[0]: hflip[L0];
      chain[1]: vflip[L1];
      chain[2]: [L0][L1]hstack      
    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 object at 0x7fa7b9537e00>
    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 object at 0x7fa7b7b97920>
    FFmpeg expression: "hflip[L0];[L0]concat"
    Number of chains: 2
      chain[0]: hflip[L0];
      chain[1]: [L0]concat      
    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 object at 0x7fa7b7bc45c0>
    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 object at 0x7fa7b7bc4350>
    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      
    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 object at 0x7fa7b7bc48c0>
    FFmpeg expression: "hflip,vflip"
    Number of filters: 2
    Input pads (1): (0, 0)
    Output pads: (1): (1, 0)

>>> fgb.hflip() + fgb.vflip()
<ffmpegio.filtergraph.Chain object at 0x7fa7b7b97680>
    FFmpeg expression: "hflip,vflip"
    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
<ffmpegio.filtergraph.Graph object at 0x7fa7b7bc50a0>
    FFmpeg expression: "[0:v]crop,scale[L0];[0:v][L0]hstack[h1];hstack[h2];[h1][h2]vstack"
    Number of chains: 4
      chain[0]: [0:v]crop,scale[L0];
      chain[1]: [0:v][L0]hstack[h1];
      chain[2]: hstack[h2];
      chain[3]: [h1][h2]vstack      
    Available input pads (2): (2, 0, 0), (2, 0, 1)
    Available output pads: (1): (3, 0, 0)

>>> # -> [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 object at 0x7fa7b7bc57f0>
    FFmpeg expression: "[in1][in2]overlay,[in3]overlay;[in4]hflip"
    Number of chains: 2
      chain[0]: [in1][in2]overlay,[in3]overlay;
      chain[1]: [in4]hflip      
    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.py", line 1480, in __repr__
    expr = str(self)
           ^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph.py", line 1473, in __str__
    fg = self.split_sources() if self.autosplit_output else self
         ^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph.py", line 2229, in split_sources
    fg._links.link((*new_src, pid), index, label=label, force=True)
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/utils/fglinks.py", line 504, in link
    raise GraphLinks.Error(f"both src and dst ids must not be Nones.")
ffmpegio.utils.fglinks.GraphLinks.Error: both src and dst ids must not be Nones.

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 "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph.py", line 1463, in _resolve_index
    return next(
           ^^^^^
StopIteration

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph.py", line 1676, in __rrshift__
    return _shift_labels(self, "dst", other)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph.py", line 233, in _shift_labels
    label_type, {obj._resolve_index(is_dst, args[is_dst]): args[not is_dst]}
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/work/python-ffmpegio/python-ffmpegio/src/ffmpegio/filtergraph.py", line 1469, in _resolve_index
    raise FiltergraphPadNotFoundError("input" if is_input else "output", index)
ffmpegio.filtergraph.FiltergraphPadNotFoundError: cannot find input pad at pad (0, 1, 1)
>>> 
>>> fgb.Chain("split,split") >> ((0,-1,1), "[label]")
<ffmpegio.filtergraph.Graph object at 0x7fa7b7bc5850>
    FFmpeg expression: "split,split[label]"
    Number of chains: 1
      chain[0]: split,split[label]      
    Available input pads (1): (0, 0, 0)
    Available output pads: (3): (0, 1, 0), (0, 1, 1), (0, 0, 0)

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 object at 0x7fa7b7bc5c40>
    FFmpeg expression: "scale=240:-2,format=gray[in2];[in1][in2]overlay,[in3]overlay;[in4]hflip"
    Number of chains: 3
      chain[0]: scale=240:-2,format=gray[in2];
      chain[1]: [in1][in2]overlay,[in3]overlay;
      chain[2]: [in4]hflip      
    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 object at 0x7fa7b7bc5df0>
    FFmpeg expression: "[1:v][0:v]scale2ref[v1_scaled][v0];[v1_scaled][v0]vstack"
    Number of chains: 2
      chain[0]: [1:v][0:v]scale2ref[v1_scaled][v0];
      chain[1]: [v1_scaled][v0]vstack      
    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 object at 0x7fa7b7bc5d90>
    FFmpeg expression: "[1:v][0:v]scale2ref[v1_scaled][v0];[v0]vstack"
    Number of chains: 2
      chain[0]: [1:v][0:v]scale2ref[v1_scaled][v0];
      chain[1]: [v0]vstack      
    Available input pads (1): (1, 0, 0)
    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]
'v0'
>>> fg.link((-1, 0, 1), "v1_scaled") # (-1, 0, 1) <- [v1_scaled]
'v1_scaled'
>>> fg
<ffmpegio.filtergraph.Graph object at 0x7fa7b7bc5a60>
    FFmpeg expression: "[1:v][0:v]scale2ref[v1_scaled][v0];[v0][v1_scaled]vstack"
    Number of chains: 2
      chain[0]: [1:v][0:v]scale2ref[v1_scaled][v0];
      chain[1]: [v0][v1_scaled]vstack      
    Available input pads (0): 
    Available output pads: (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 object at 0x7fa7b7bc6cf0>
    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      
    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 object at 0x7fa7b7bc5fa0>
    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]: scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p;
      chain[1]: aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo      
    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 object at 0x7fa7b7b977a0>
    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;
      chain[1]: [0:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo;
      chain[2]: [1:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p;
      chain[3]: [1:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo;
      chain[4]: [2:v]scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:-1:-1,setsar=1,fps=30,format=yuv420p;
      chain[5]: [2:a]aformat=sample_fmts=flt:sample_rates=48000:channel_layouts=stereo      
    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 object at 0x7fa7b7bc6a80>
    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)

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

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

ffmpegio.filtergraph.as_filtergraph_object(filter_specs)

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_labels(pad_type, labels)

turn into filtergraph and add labels

Parameters:

pad_type ('dst'|'src') – filter pad type
labels (str|seq(str)|dict(int:str), optional) – pad label(s) and optionally pad id

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.

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

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

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

Return first index of value.

Raises ValueError if the value is not present.

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_labels(pad_type, labels)

turn into filtergraph and add labels

Parameters:

input_labels (dict(int:str), optional) – input pad labels keyed by pad index, defaults to None
output_labels (dict(int:str), optional) – output pad labels keyed by pad index, defaults to None

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

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

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

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

get_chainable_input_pad()

get first filter’s input pad, which can be chained

Returns:: filter position, input pad poisition, and filter object. If the head filter is a source filter, returns None.
Return type:: tuple(int, int, Filter) | None

get_chainable_output_pad()

get last filter’s output pad, which can be chained

Returns:: filter position, output pad poisition, and filter object. If the tail filter is a sink filter, returns None.
Return type:: tuple(int, int, Filter) | None

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

iter_input_pads(filter=None, pad=None)

Iterate over input pads of the filters

Parameters:: pad (int, optional) – specify if only interested in pid-th pad of each filter, defaults to None
Yield:: filter index, pad index, and filter instance
Return type:: tuple(int, int, Filter)

iter_output_pads(filter=None, pad=None)

Iterate over output pads of the filters

Parameters:: pid (int, optional) – specify if only interested in pid-th pad of each filter, defaults to None
Yield:: filter index, pad index, and filter instance
Return type:: tuple(int, int, Filter)

Filters are scanned from the end to the front

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

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

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

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

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, dst=None, src=None, force=None)

label a filter pad

Parameters:

label (str) – name of the new label. Square brackets are optional.
dst (tuple(int,int,int) | seq(tuple(int,int,int)), optional) – input filter pad index or a sequence of pads, defaults to None
src (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 dst and src 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.

add_labels(pad_type, labels)

turn into filtergraph and add labels

Parameters:

input_labels (dict(int:str), optional) – input pad labels keyed by pad index, defaults to None
output_labels (dict(int:str), optional) – output pad labels keyed by pad index, defaults to None

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

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 an output pad to right’s input pad

Parameters:

right (Chain or Filter) – output filterchain to be attached
left_on (int or str, optional) – pad_index, specify the pad on self, default to None (first available)
right_on (int or str, optional) – pad index, specifies which pad on the right graph, defaults to None (first available)

Returns:

new filtergraph object

Return type:

Graph

autosplit_output

True

Type:: bool
Type:: True to insert a split filter when an output pad is linked multiple times. default

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

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

stack another Graph and make connection from left to right

Parameters:

right (Graph) – other filtergraph
from_left (seq(tuple(int,int,int)|str)) – output pad ids or labels of this fg
to_right (seq(tuple(int,int,int)|str)) – input pad ids or labels of the right fg
chain_siso (bool, optional) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool | None, optional) – 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

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

get_input_pad(index)

resolve (unconnected) input pad from pad index or label

Parameters:: index (tuple(int,int,int) or str) – pad index or link label
Returns:: filter input pad index and its link label (None if not assigned)
Return type:: tuple(int,int,int), str|None

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

get_output_pad(index)

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

Parameters:: index (tuple(int,int,int) or str) – pad index or link label
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

iter_chainable_input_pads(exclude_named=False, include_connected=False, chain=None)

Iterate over filtergraph’s chainable filter output pads

Parameters:

exclude_named (bool, optional) – True to leave out named input pads, defaults to False (all avail pads)
include_connected (bool, optional) – True to include input streams, which are already connected to input streams, defaults to False

Yield:

filter pad index, link label, & source filter object

Return type:

tuple(tuple(int,int,int), label, Filter)

iter_chainable_output_pads(exclude_named=False, chain=None)

Iterate over filtergraph’s chainable filter output pads

Parameters:: exclude_named (bool, optional) – True to leave out unnamed outputs, defaults to False
Yield:: filter pad index, link label (if any), & source filter object
Return type:: tuple(tuple(int,int,int), str, Filter)

iter_input_pads(exclude_named=False, include_connected=False, chain=None, filter=None, pad=None)

Iterate over filtergraph’s filter output pads

Parameters:

exclude_named (bool, optional) – True to leave out named inputs, defaults to False to return only all inputs
include_connected (bool, optional) – True to include pads connected to input streams, defaults to False

Yield:

filter pad index, link label, & source filter object

Return type:

tuple(tuple(int,int,int), label, Filter)

iter_output_pads(exclude_named=False, chain=None, filter=None, pad=None)

Iterate over filtergraph’s filter output pads

Parameters:: exclude_named (bool, optional) – True to leave out named outputs, defaults to False
Yield:: filter pad index, link label, and source filter object
Return type:: tuple(tuple(int,int,int), str, Filter)

join(right, how='per_chain', match_scalar=False, ignore_labels=False, chain_siso=True, replace_sws_flags=None)

append another Graph object and connect all inputs to the outputs of this filtergraph

Parameters:

right (Graph|Chain|Filter) – right filtergraph to be appended

how ("chainable"|"per_chain"|"all") –

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

match_scalar (bool) – True to multiply self if SO-MI connection or right if MO-SI connection to single-ended entity to the other, defaults to False
ignore_labels (bool, optional) – True to pair pads w/out checking pad labels, default: True
chain_siso (bool, optional) – True to chain the single-input single-output connection, default: True
replace_sws_flags (bool | None, optional) – 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 or None

link(dst, src, label=None, preserve_src_label=False, force=False)

set a filtergraph link

Parameters:

dst (tuple(int,int,int)) – input pad ids
src (tuple(int,int,int)) – output pad index
label (str, optional) – desired label name, defaults to None (=reuse dst/src label or unnamed link)
preserve_src_label (bool, optional) – True to keep existing output labels of src, defaults to False to remove one output label of the src
force (bool, optional) – 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, dst 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 dst or src 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

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, right_on=None, left_on=None)

prepend an input filterchain to an existing filter chain of the filtergraph

Parameters:

left (Chain or Filter) – filterchain to be attached
right_on (int or str, optional) – filterchain to accept the input chain, defaults to None (first available)

Returns:

new filtergraph object

Return type:

Graph

If the attached filter pad has an assigned label, the label will be automatically removed.

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|None) – 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

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

split_sources()

possibly create a new filtergraph with all duplicate sources: separated by split/asplit filter

Returns:: _description_
Return type:: _type_

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

stack another Graph to this Graph

Parameters:

other (Graph) – other filtergraph
auto_link (bool, optional) – True to connect matched I/O labels, defaults to None
replace_sws_flags (bool | None, optional) – 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

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, dst=None, src=None)

unlink specified links

Parameters:

label (str|int, optional) – specify all the links with this label, defaults to None
dst (tuple(int,int,int), optional) – specify the link with this dst pad, defaults to None
src (tuple(int,int,int), optional) – specify all the links with this src 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

`|`: filtegraph stacking

`* n`: filtergraph self-stacking

`+`: filtergraph joining

`>>` filtergraph labeling / filtergraph p2p linking

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