Skip to content

Customizing Filters

Customizing Filters in Typed-FFmpeg

Introduction to Custom Filters

While Typed-FFmpeg supports most of the FFmpeg filters out-of-the-box, there might be instances where you need to use filters that are not predefined in the library. For such cases, Typed-FFmpeg provides a flexible way to define and utilize custom filters.

Creating Single-input Custom Filters

Easily create your own single-input custom filters with the vfilter, afilter method. This allows for direct application of new or specialized video filters not standard in Typed-FFmpeg.

%xmode Minimal
import ffmpeg

# Apply a custom single-input video filter
(
    ffmpeg.input("input.mp4")
    .vfilter(
        name="custom_filter", option1="value1", option2="value2"
    )  # Apply "custom_filter" with specified options
    .output(filename="output.mp4")
)

Exception reporting mode: Minimal
%3 604ab03321d8ab8f -i input.mp4 4a9c5cba9739f997 [0] custom_filter= option1=value1:option2=value2 [s0] 604ab03321d8ab8f->4a9c5cba9739f997 0 -> 0 58a0a4c9beb05c96 -map [s0] output.mp4 4a9c5cba9739f997->58a0a4c9beb05c96 s0 -> 0

This code snippet will correspond to the following FFmpeg command line:

(
    ffmpeg.input("input.mp4")
    .vfilter(
        name="custom_filter", option1="value1", option2="value2"
    )  # Apply "custom_filter" with specified options
    .output(filename="output.mp4")
).compile_line()

"ffmpeg -i input.mp4 -filter_complex '[0]custom_filter=option1=value1:option2=value2[s0]' -map '[s0]' output.mp4"

Alternatively:

import ffmpeg

# Define a custom video filter for later use
ffmpeg.vfilter(
    ffmpeg.input("input.mp4"),
    name="custom_video_filter",
    option1="value1",
    option2="value2",
)
%3 604ab03321d8ab8f -i input.mp4 19a46f1d094c55d1 [0] custom_video_filter= option1=value1:option2=value2 604ab03321d8ab8f->19a46f1d094c55d1 0 -> 0

Implementing Multi-input Custom Filters

For filters that require multiple inputs, specify the type of each input using the input_typings parameter to ensure correct stream handling.

import ffmpeg
from ffmpeg.schema import StreamType

# Create a multi-input custom video filter
(
    ffmpeg.input("input1.mp4").vfilter(
        ffmpeg.input("input2.mp4"),
        name="custom_video_filter",
        input_typings=(StreamType.video, StreamType.video),
    )
)
%3 4365f434cb9d947c -i input1.mp4 2dec9b05adba945f [0][1] custom_video_filter 4365f434cb9d947c->2dec9b05adba945f 0 -> 0 1a9957d0ad34d0c6 -i input2.mp4 1a9957d0ad34d0c6->2dec9b05adba945f 1 -> 1

Alternatively, use the vfilter, afilter function directly for multi-input scenarios:

import ffmpeg
from ffmpeg.schema import StreamType

# Define and apply a multi-input custom video filter
ffmpeg.vfilter(
    ffmpeg.input("input1.mp4"),
    ffmpeg.input("input2.mp4"),
    name="custom_video_filter",
    input_typings=(StreamType.video, StreamType.video),
)
%3 4365f434cb9d947c -i input1.mp4 2dec9b05adba945f [0][1] custom_video_filter 4365f434cb9d947c->2dec9b05adba945f 0 -> 0 1a9957d0ad34d0c6 -i input2.mp4 1a9957d0ad34d0c6->2dec9b05adba945f 1 -> 1

Defining Multi-output Custom Filters

In cases where a filter generates multiple outputs, use ffmpeg.filter_multi_output function and specify the expected types of these outputs using the output_typings parameter. This feature is particularly useful for filters that split the input stream into several output streams.

import ffmpeg
from ffmpeg.schema import StreamType

# Create a custom filter that yields multiple outputs
ffmpeg.filter_multi_output(
    ffmpeg.input("input1.mp4"),
    name="custom_split",
    input_typings=(StreamType.video,),
    output_typings=(StreamType.video, StreamType.video),
)
%3 154ff34600e9d197 -i input1.mp4 55777e461d6738ad [0] custom_split 154ff34600e9d197->55777e461d6738ad 0 -> 0

By following these guidelines, you can extend the functionality of Typed-FFmpeg to accommodate any specific filtering needs, ensuring maximum flexibility and efficiency in your video processing tasks.

Define Source Filter

Source filter can also be defined in the same way

import ffmpeg
from ffmpeg.schema import StreamType

ffmpeg.vfilter(
    name="color",
    color="black",
    duration=1,
    input_typings=(),
    output_typings=(StreamType.video,),
)
%3 3064ec056e14e614 color= color=black:duration=1:output_typings=(<StreamType.video\: \'video\'>,)