Frame Tweaker
plugin for VirtualDub 1.2+

Frame Tweaker is a plugin filter for VirtualDub version 1.2 and later. It is designed to make adjustments to single frames of video. It's primary purpose is to correct defects in video tape or film tranfers that last for only a single frame, or a sequence of a few frames. It can also be used for fading scenes in and out.


Download Frame Tweaker to your hard disk, and unzip the contents to your VirtualDub\plugins directory. Then run VirtualDub. You will see a new filter named "frame tweaker" in the filter list.

You should download the current version from the list below. The previous version is also available in case you have any problems. If you do encounter any problems with the current version, please send me a note describing the problem.


The input to the Frame Tweaker plug-in consists of a script file which contains a list of frame numbers and commands. The script is a standard text file. Each line specifies a frame range and a command, in the following format:
   first[-last] command [parameters]
    first  =   The first (or only) frame number in a range of frames.
    last  =   The last frame number in a range of frames (inclusive). If this is not specified, then the range will consist of a single frame (specified by "first").
    command  =   A command which specifies the operation to be performed on the frame or frames. Commands are case-insensitive.
    parameters  =   The command parameters (depends on the individual command).
    [ ]  =   Optional. Everything in square brackets is optional, but may be required for the individual command.

The lines in the script file must appear in frame number order. This means that lower frame numbers must preceed higher frame numbers in the file. A frame number may appear more than once in the script file, and frame ranges may overlap. If two or more commands operate on the same frame number, the commands are executed in the order in which they appear in the script file.

All frame numbers are source frame numbers, which specify the frame number in the source file (starting at 0). To determine the source frame number for a given frame, you can look at the frame number displayed at the bottom of the main VirtualDub window before any segments are deleted.


The configuration dialog box allows you to specify and edit the Frame Tweaker script file.


The following commands are currently supported:


Blacks out the specified frames. This is sometimes useful immediately before a FADEIN or after a FADEOUT. Remember, you can't add new frames -- you can only black out existing frames.

Syntax:  first[-last] BLACK


Copies the current frame to the Frame Tweaker clipboard. (see also: PASTE, SHIFT)

Syntax:  frame COPY


Fades from black to full intensity during the specified range of frames. The frame range must consist of three or more frames. The first frame is always black, and the last frame is always full intensity.

Syntax:  first-last FADEIN


Fades from full intensity to black during the specified range of frames. The frame range must consist of three or more frames. The first frame is always full intensity, and the last frame is always black.

Syntax:  first-last FADEOUT


Replaces the contents of the source frame or frames with the contents of the Frame Tweaker clipboard. This is useful for masking frame glitches which can occasionally occur in film or video, by pasting the contents of the previous frame over the current frame. (see also: COPY)

Syntax:  first[-last] PASTE


Shifts the contents of the source frame up or down by the specified number of lines. This is useful for correcting frame jumps which can occasionally occur in film or video. (see also: COPY)

Syntax:  first[-last] SHIFT [EVEN | ODD] lines [PASTE]

The lines parameter can be positive or negative. If lines is positive, the frame will be shifted down by the specified number of lines. If lines is negative, the frame will be shifted up by the specified number of lines. If the "EVEN" or "ODD" parameter is used, only the even or odd field in an interlaced frame will be shifted. If the "PASTE" parameter is used, the new lines will contain the lines at the same position on the Frame Tweaker clipboard. Otherwise, the new lines will be black.

Sample Script

Here is an example of a Frame Tweaker Script:
31-47 FADEIN
546 COPY
1335 COPY
1336-1337 PASTE
1978 COPY
2647-2655 FADEOUT
2656-2665 BLACK
Frames 0 thru 30 will be deleted from this clip, so FADEIN starts at source frame 31. Frames 547 and 1336-1337 contained bright flashes (from video defects), so they are replaced by the previous frame (the resulting motion pause is much less objectionable than the bright flash). Frame 1979 was shifted up 17 lines due to a video sync glitch, so it is shifted back down 17 lines and the resulting new lines are replaced by lines from the previous frame.


The Frame Tweaker clipboard is not the same as the Windows clipboard. It is a local clipboard used only by the Frame Tweaker filter. Each instance of the filter has its own clipboard.

Because a COPY command must preceed a PASTE (or SHIFT) command, you cannot copy backwards.

You can include comment lines in the Frame Tweaker script file by beginning each comment line with pound sign (#). (Actually, any line that begins with a non-numeric is ignored by the current script parser, but let's standardize on the pound sign to allow for future enhancements).

You must not include spaces in a frame range (first-last).

Frame Tweaker has been tested with VirtualDub versions 1.2a, 1.3, and 1.3a.

When you save your configuration, a registry entry is created under the following key:

If you want to completely uninstall this filter, just delete the "tweaker.vcf" file in the plugins directory, and delete this registry entry.

Error Messages

There are several error messages that can be displayed by this plugin. When an error message box is displayed, the dialog box will have an OK and a Cancel button. These buttons affect the way the error is reported to VirtualDub. If the OK button is pressed, an error will not be reported to VirtualDub, but the Frame Tweaker filter will be disabled. If the Cancel button is pressed, an error will be reported to VirtualDub, which will display the message "Error readying filters" and abort the operation.

WARNING: Due to a bug in VirtualDub 1.2a/1.3/1.3a, you should NEVER press the Cancel button when using the single frame forward and back buttons. VirtualDub will crash if it receives an error from the plugin filter. It's safest to always press the OK button in an error dialog box.

Revision History

Version 1.1 (3/28/00) Version 1.0a (3/7/00) Version 1.0 (3/6/00)

Author:  Christopher P. LaRosa
Last Update:  March 28, 2000