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.

Installation

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.

Input

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]
Where,
    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. Frame ranges must not overlap. A given frame number can only be specified once 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.

Configuration

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

Commands

The following commands are currently supported:

BLACK

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

COPY

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

Syntax:  frame COPY

FADEIN

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

FADEOUT

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

PASTE

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

SHIFT

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 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 "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
547 PASTE
1335 COPY
1336-1337 PASTE
1978 COPY
1979 SHIFT 17 PASTE
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.

Notes

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.

Do not edit the Frame Tweaker script file while you are using the Frame Tweaker filter (including frame stepping). This can cause unpredictable results, because the script file is already opened for reading by the filter. You should always edit the script by using the filter configuration dialog box.

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: 

   HKEY_CURRENT_USER\Software\Freeware\VirtualDub\plugins\FrameTweaker
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.0a (3/7/00) Version 1.0 (3/6/00)

Author: Christopher P. LaRosa
Last Update: March 7, 2000
Software Version: 1.0a