How to Parse VITC Timecode in FFmpeg

This guide explains how to use FFmpeg’s readvitc filter to extract and parse Vertical Interval Timecode (VITC) from analog video digitizations. You will learn the command-line syntax for reading this embedded metadata, how to customize the scanning parameters for analog captures, and how to output or burn the resulting timecode into your video.

Understanding VITC and the readvitc Filter

Vertical Interval Timecode (VITC) is a form of SMPTE timecode encoded into the vertical blanking interval (VBI) of analog video signals, typically located between lines 10 and 20. When analog videotapes (like VHS, Betacam, or U-matic) are digitized, this timecode is often preserved in the top lines of the active video area.

FFmpeg’s readvitc filter scans these specific lines of each video frame, decodes the timecode, and attaches it to the frame’s metadata as lavfi.readvitc.tc.

Basic Syntax

To simply read and test VITC extraction from an input file, use the following basic filter syntax:

ffmpeg -i input.mp4 -vf readvitc -f null -

This command runs the filter over the video, but since it only attaches metadata to the stream, you will not see the output unless you write it to a file or print the metadata.

Customizing Scan Lines

Analog captures can have head-switching noise, horizontal jitter, or vertical shifts that throw off default scanning. You can configure readvitc to target specific scan lines using two parameters:

• scan_max_line: Specifies the maximum line number to scan for VITC data (default is 45).
• thr_b: Sets the black threshold (default is 0.2).
• thr_w: Sets the white threshold (default is 0.6).

To limit the search to the first 20 lines of the video to increase accuracy and speed:

ffmpeg -i input.mp4 -vf readvitc=scan_max_line=20 -f null -

Burning VITC Timecode into the Video

To verify that the filter is reading the timecode correctly, you can overlay the extracted VITC onto the video using the drawtext filter. This is useful for creating reference or “window dub” copies.

ffmpeg -i input.mp4 -vf "readvitc,drawtext=text='%{metadata\:lavfi.readvitc.tc}':x=10:y=10:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.8" -c:a copy output.mp4

In this command: 1. readvitc extracts the timecode. 2. drawtext references the metadata key lavfi.readvitc.tc and prints it at coordinates x=10, y=10.

Exporting VITC to a Text File

If you need to extract the timecode metadata to a text file for archival purposes or NLE (Non-Linear Editor) integration, use ffprobe. This avoids re-encoding the video.

ffprobe -v error -f lavfi -i "movie=input.mp4,readvitc" -show_entries frame_tags=lavfi.readvitc.tc -of csv=p=0 > timecodes.txt

This command outputs a frame-by-frame list of decoded timecodes directly into a text file named timecodes.txt.