Using the FFmpeg Fieldhint Filter

The fieldhint filter in FFmpeg reconstructs progressive frames from interlaced or telecined video by matching specific top and bottom fields guided by an external text file. This approach is particularly useful for complex or broken telecine transfers where standard automated filters (like pullup or fieldmatch) fail to correctly pair fields, allowing you to manually define exact field pairings to eliminate combing artifacts.

Understanding the Hint File Format

The fieldhint filter relies on a plain text file that specifies which source frames supply the top and bottom fields for each output frame.

Each line in the hint file corresponds to one output frame. The format consists of two comma-separated integer values:

top_field_source_frame,bottom_field_source_frame
  • The first number specifies the source frame number from which to extract the top field.
  • The second number specifies the source frame number from which to extract the bottom field.

Example Hint File (hints.txt):

0,0
1,1
2,3
3,4
5,5

In this example:

  • Output frame 0 uses both fields from source frame 0.
  • Output frame 1 uses both fields from source frame 1.
  • Output frame 2 combines the top field from source frame 2 and the bottom field from source frame 3.
  • Output frame 3 combines the top field from source frame 3 and the bottom field from source frame 4.
  • Output frame 4 uses both fields from source frame 5.

Filter Options

The fieldhint filter accepts two primary parameters:

  • hint: The absolute or relative path to the text file containing the field mapping instructions.
  • mode: The operation mode used to interpret the hint entries.
    • direct: Uses exact, absolute frame numbers as written in the hint file. This is the most common mode for manual corrections.
    • pattern: Applies a repeating telecine pattern continuously.

Basic Command Syntax

To run FFmpeg using an external hint file in direct mode, use the following syntax:

ffmpeg -i input.mkv -vf "fieldhint=hint=hints.txt:mode=direct" -c:a copy output.mp4

Complete Inverse Telecine (IVTC) Workflow

When performing inverse telecine on standard 3:2 pull-down material (such as converting 29.97 fps NTSC back to 23.976 fps progressive), reconstructing fields often leaves duplicate frames that must be removed. You can chain fieldhint with the decimate filter to drop these duplicates:

ffmpeg -i telecined_input.ts -vf "fieldhint=hint=hints.txt:mode=direct,decimate" -c:v libx264 -crf 18 -c:a copy progressive_output.mp4

Tips for Generating Hint Files

  1. Step Through Frames: Use tools like AvsPmod, VirtualDub, or FFplay to inspect problematic scenes frame-by-frame and identify where field mismatches occur.
  2. Handle Scene Changes: Pay close attention to scene cuts. Telecined transfers often introduce orphaned fields at edit points, which can be cleanly resolved by pointing the mismatch to an adjacent matching field in the hint file.