TimecodeFPS

Revision as of 03:06, 14 January 2022

Description

TimecodeFPS converts a clip from VFR to CFR. Timing information from clip is discarded, and matroska v2 timecodes from the timecodes file are used instead. Conversion is to any desired exact CFR framerate, as specified by fpsnum/fpsden. With report=true, an alternate debug/analysis display and info is used. Strictness of the conversion is controlled by the parameters threshone and threshmore.

Note: TimecodeFPS is a C-Plugin.

Requirements

• [x86] AviSynth+ or AviSynth 2.6.0
• [x64] AviSynth+
• Supported color formats: RGB24, RGB32, Y8, YV12, YV16, YV24

Syntax and Parameters

TimecodeFPS (clip, string "timecodes", int "fpsnum", int "fpsden", bool "report", float "threshone", float "threshmore", bool "start")

clip   =

Input clip. Can be any AviSynth supported colorspace. Must have exactly the same number of frames as lines in timecodes. Input FPS is discarded. Audio, if it exists, is passed through untouched.

string  timescodes = "timecodes.txt"

Path to a matroska v2 timecodes file. Only matroska v2 timecodes files are supported.

Exactly one timecode is expected per frame, and it gives the start point of the frame. (The end point of a frame is implicitly the same as the start point of the next frame, except for the last frame, where a guess is made.) The timecodes should be non-negative and non-decreasing. The first timecode need not be at time zero, but that will be used as the start point for the CFR stream, so a non-zero start time may cause the introduction of blank frame(s) before the first real frame.

int  fpsnum = 25

int  fpsden = 1

An exact CFR framerate to convert to. Any legal values are valid. Choosing the "right" framerate for a source should be done with report mode; there is no automatic detection.

bool  report = false

If false, TimecodeFPS simply does the conversion as expected. If true, an informative messagebox is shown on script load, and the returned frames are instead a timing track display.

The informative message box shows fpsnum, fpsden, number of dups of input frames, number of drops of input frames, average timing error in ms, and threshone and threshmore. Every drop is an input frame that is not sent to the output. Every dup is an input frame being displayed more than once to keep timing straight. The error value, in ms, is the average difference between original frame starts and the frame starts in the resulting stream. In some cases it can be used to detect jitter and drift, but don't bank too much on it.

The timing track display changes the video clip to 640x32 RGB32. Two rows of boxes are shown, which are visual representations of timing of this frame and nearby frames in the original VFR track and the resulting CFR track. The current frame in CFR is blue; the current frame in VFR is green.

float  threshone = 0.4

float  threshmore = 0.9

Controls the thresholds for the VFR->CFR algorithm. The algorithm is rather simple; it runs through the entire input track in sequence. For each input frame, it computes how much "space" there is for the frame: That is, the difference between the frame's VFR end time and the frame's CFR start time, the latter being determined by how many frames have been inserted into the output stream already.

This absolute time delta is converted to a unitless number relative to the CFR framerate, so that 1.0 = room for exactly one frame at the specified CFR rate. Then 0 or more copies of the input frame are inserted into the output track. The first copy is inserted if the available space is greater than threshone, and additional copies are inserted as long as the available space is greater than threshmore. (Available space decrements by 1.0 every time a frame is inserted).

With these parameters, the "strictness" of the conversion is defined. Threshone=0.5 and threshmore=0.5 will be the most accurate in preserving original timing. The default settings allow for "frame preserving" operation: A lower threshold for a first copy and a higher threshold for a second copy means timing can be sacrificed for the goal of getting each frame in the stream at least once. Experimentation with the report tool is advised.

bool  start = false

If set to true, the 0th timecode in the file is assumed to be at the 0 time. If set to false, the exact number t=0 is assumed to be the 0 time.

So for example, if the timecode for the 0th frame is at 6 seconds in, then if start=false, 6 seconds of pure black frames will be introduced into the output.

When start=true, things will just start with that 0th frame being the first frame in the output and the 6 seconds will be omitted.

Examples

Note: In order to get timing display along side output display, TimecodeFPS must be called twice with the same parameters, once with report on and once with report off. Here is an example:

clip1 = FFVideoSource ("foobar.mkv", timecodes="foobar.txt")

clipout = TimecodeFPS (clip1, "foobar.txt", 60000, 1001, false, 0.3, 0.9)
clippreview = TimecodeFPS (clip1, "foobar.txt", 60000, 1001, true, 0.3, 0.9)

#this requires reconciling colorspace and size differences first
StackVertical (clipout, clippreview)

Changelog

Version         Date            Changes

v1.1.4          2022-01-14      - Fixed regression when start=true. (Asd-g)

v1.1.3          2022-01-13      - Changes by Asd-g
                                                   - Set duration of the latest frame when specified.

v1.1.2          2021-09-28      - Changes by TomArrow
                                                   - Created Visual Studio 2019 solution and removed GCC .mak files.
                                                   - Changed to C++ and adapted a few lines of code that didn't work in C++.
                                                   - Can now pass multiple timecode files by separating them with a semicolon, for example if you are loading multiple videos with absolute timestamp values and concatenating them and you want to preserve a continuous FPS across multiple files.

v1.1.1          2021-06-04      - Changes by Asd-g
                                                   - Added support for timestamp files created from mkvtoolnix.

v1.1            2020-04-15      - Changes by Binjohn
                                                   - Add 64-bit binary.
                                                   - Update to AviSynth+ 3.5 library.

2018-02-17      2018-02-17      - Add "start" parameter

2012-04-16      2012-04-16      - Initial release - timecodefps.zip

External Links

• GitHub - Natt's plugin archive.
• GitHub - Source code repository (Binjohn).
• GitHub - Source code repository (Asd-g).

Back to External Filters ←