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.

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")
)
%3 6ee75bf8c2cf393b input.mp4 7a8e1d77a3630e14 custom_filter 6ee75bf8c2cf393b->7a8e1d77a3630e14 * => 0 7655b3392ecb235a output.mp4 7a8e1d77a3630e14->7655b3392ecb235a 0 => 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 6ee75bf8c2cf393b input.mp4 6b1a08fca6d34bd7 custom_video_filter 6ee75bf8c2cf393b->6b1a08fca6d34bd7 * => 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 7d40c273a7b8f96c input1.mp4 5878e744793c8b3e custom_video_filter 7d40c273a7b8f96c->5878e744793c8b3e * => 0 3cd1760fc481ee83 input2.mp4 3cd1760fc481ee83->5878e744793c8b3e * => 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 7d40c273a7b8f96c input1.mp4 5878e744793c8b3e custom_video_filter 7d40c273a7b8f96c->5878e744793c8b3e * => 0 3cd1760fc481ee83 input2.mp4 3cd1760fc481ee83->5878e744793c8b3e * => 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 7d40c273a7b8f96c input1.mp4 4a9c0e8254f4d3ff custom_split 7d40c273a7b8f96c->4a9c0e8254f4d3ff * => 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.