How to Use FFmpeg fieldhint Filter for Deinterlacing

This article provides a practical guide on how to use the FFmpeg fieldhint filter to control and correct the deinterlacing process using an external hint file. You will learn the syntax of the hint file, how the filter interprets relative and absolute frame offsets, and the exact FFmpeg commands needed to execute this highly precise method of reconstruction for tricky telecine or interlaced video sources.

Understanding the fieldhint Filter

The fieldhint filter in FFmpeg is used to reconstruct progressive frames from interlaced content by manually specifying which fields from which source frames should be combined. While automatic tools like fieldmatch or yadif work well for standard patterns, they can fail on footage with broken cadences, irregular telecine, or edited interlaced video. By providing an external text file (a "hint file"), you tell FFmpeg exactly how to build each output frame, field-by-field.

Step 1: Create the Hint File

The hint file is a plain text file where each line corresponds to an output frame in sequential order. Each line contains four values separated by spaces:

[top_field_source_frame] [top_field_source] [bottom_field_source_frame] [bottom_field_source]

  • Source Frame: An integer representing the frame number. By default, this is a relative offset from the current frame (e.g., 0 is the current frame, -1 is the previous frame, 1 is the next frame).
  • Field Source: A character specifying which field to extract: t (top field) or b (bottom field).

Example of Relative Hint File (hints.txt)

If you want to reconstruct a sequence of progressive frames from a telecined source, your hints.txt file might look like this:

0 t 0 b
0 t 1 b
1 t 1 b
2 t 1 b
2 t 2 b
  • Line 1: Combine the top field of the current frame (0 t) with the bottom field of the current frame (0 b).
  • Line 2: Combine the top field of the current frame (0 t) with the bottom field of the next frame (1 b).
  • Line 3: Combine the top field of the next frame (1 t) with the bottom field of the next frame (1 b).

Step 2: Running the FFmpeg Command

Once your hint file is ready, use the -vf (video filter) flag to apply the fieldhint filter. You must specify the path to your hint file using the hint option.

ffmpeg -i input.mp4 -vf "fieldhint=hint=hints.txt" output.mp4

Using Absolute Mode

If you prefer to map fields using absolute frame numbers (e.g., Frame 0, Frame 1, Frame 2 of the input video) rather than relative offsets, you can change the filter's mode to absolute.

ffmpeg -i input.mp4 -vf "fieldhint=hint=hints.txt:mode=absolute" output.mp4

With mode=absolute, your hints.txt file would explicitly reference the actual input frame indices:

0 t 0 b
0 t 1 b
1 t 1 b

Important Considerations

  • Line Count Match: The hint file must contain at least as many lines as the number of frames you want to output. If the filter runs out of lines in the hint file, it will stop processing or reuse the last pattern, which may cause visual artifacts.
  • Performance: Because fieldhint reads from an external text file disk read speeds can occasionally impact rendering speed on very long videos, though the computational overhead of the filter itself is extremely low.