Processing: External encoder support

External encoder support allows VirtualDub to interface to encoding programs that don't support a full-fledged encoding API, but instead use a simple pipe interface called stdin.

Requirements

The external encoding mode uses three types of applications:

• Video encoders
• Audio encoders
• Multiplexers

Video encoders and audio encoders take video and audio streams and compress them, respectively. The multiplexer then takes the output files from the encoders and combines them to form a single combined audio/video file. For AVI files, VirtualDub uses codecs installed in Windows to do the encoding, and then handles the multiplexing internally; these are all separate programs when using external encoding.

Operation

Rendering through a set of external encoders works similarly to a normal render operation. During the main portion of the render, both the video and audio encoders are active in parallel, so they can benefit from multiple CPU cores in the system. For instance, the video encoder could use two cores, and the audio encoder could use another cores. This is in addition to the threading done within VirtualDub itself, so audio/video decompression and filtering can use even more cores to make the most use of multi-core systems.

Configuring an external encoder set

An external encoder set is a collection of external encoders that can be used to render a video. An external encoder set includes one or more of:

• Video encoder
• Audio encoder
• Multiplexer

All three of these are chosen from encoder profiles to allow encoder settings to be reused. For instance, the same multiplexer settings could be reused whenever an AVI or MPEG-4 file is being produced, even if the encoders use different settings.

Options

• File description: The name of the output format, as shown in the file dialog UI. This is used as descriptive text for the file format produced by the encoding set.
• File extension: The default filename extension to use in the file dialog UI. The leading period is optional but not necessary.
• Process partial output when render is aborted: Causes the multiplexer is run at the end of a process even if an error occurs during encoding or the Abort button is pressed.
• Replace temp audio/video paths with output path: If set, then the temporary output path setting for the audio or video encoder is ignored, and the primary output path is substituted instead. Use this setting if the encoder set only includes an audio or video encoder to have the encoder write directly to the output path.

Configuring an external encoder

In order to use an encoding program, an encoder profile has to be created for it. The encoder profile tells VirtualDub how to run the encoder.

Command-line tokens

The command line specifies the location of the encoder program and the arguments passed to it from VirtualDub. Tokens are special strings placed in the command line to specify that values from the encoding process should be passed to the encoder. All tokens are of the form %(name). The available tokens are:

• %(width): The width of a video frame, in pixels.
• %(height): The height of a video frame, in pixels.
• %(fps): The frame rate of the video stream, as a real number. This number includes the fractional portion, i.e. 29.97. The decimal separator is always a period regardless of locale.
• %(fpsnum): The numerator of the video stream frame rate, when represented as a fraction, in decimal. The valid range is 1-4294967295.
• %(fpsden): The denominator of the video stream frame rate, when represented as a fraction. The valid range is 1-4294967295.
• %(outputname): The filename and extension of the final output file. This does not include the drive specifier or directory.
• %(outputfile): The path to the final output file, including possible drive specifiers and directories.
• %(tempvideofile): The path and filename of a temporary file produced by the video encoder. This file does not exist unless produced by the video encoder; it is used as a temporary file to hold compressed video data that is eventually processed by the multiplexer.
• %(tempaudiofile): Same as %(tempvideofile), but for the audio encoder.
• %(samplingrate): The sampling rate of the audio stream, in Hz. For compressed streams, this refers to the decoded sampling rate, e.g. 48000 Hz. The sampling rate is always an integer.
• %(samplingratekhz): The sampling rate of the audio stream, in KHz. This value is always an integer; any fractional values are rounded.
• %(channels): The number of channels in the audio stream: 1 for mono, 2 for stereo, 6 for 5.1.
• %(audioprecision): The number of bits per sample in the audio stream, e.g. 8 or 16.
• %(hostdir): The path to the VirtualDub program directory. The path does not end in a slash.
• %(programdir): The path to the encoder program directory. The path does not end in a slash.
• %(systemdir): The path to the Windows system directory. In 64-bit versions of Windows, this refers to the system32 directory for 32-bit versions of VirtualDub, and the SysWOW64 directory for 64-bit versions. The path does not end in a slash.

Options

• Interpret non-zero return code as error: This option causes VirtualDub to abort the rendering operation and report a failed render if an encoder or multiplexer program exits with a non-zero return value. This option should be enabled by default, and disabled only if the program does not follow standard return code conventions. The downside of disabling this option is that failed encodes will not be detected properly.
• Redirect standard output to log: Traps any output from the program to the standard output (stdout) channel and puts it into the log. This is useful for diagnostic purposes. Normally this should be enabled unless the program only outputs non-useful information to standard output, such as a startup banner.
• Redirect standard error to log: Traps any output from the program to the standard error (stderr) channel and puts it into the log. This is useful for catching error messages and should normally be enabled. However, sometimes programs output a lot of spammy status messages to stderr, and if those can't be disabled via a “quiet” option then stderr redirection should be disabled.
• Delete output file before starting: If set, the output file for the program is deleted if present prior to running the program. Enable this if the program refuses to overwrite an existing file.

Audio encoder specific options

• Raw audio data: Send audio data to the external encoder as raw audio data.
• WAV file: Send audio data to the external encoder as an open-ended Microsoft WAVE file.
• Bypass compression: Causes the audio compression setting in VirtualDub to be ignored, disabling any compression. If the source audio data is compressed, it is decompressed prior to being passed to the external encoder.

Importing and exporting profiles

External encoder profiles and sets are normally stored as part of VirtualDub's settings. You can also export them to a file to save them for another installation or to share them with other users.

Exporting profiles

To export profiles, click the Export button on the Configure External Encoders dialog and then specify a filename. All external encoders and encoding sets are written to the file.

Importing profiles

To import profiles, click the Import button on the Configure External Encoders dialog and then specify a profile file. All encoders and sets in the file are imported.

Note: The imported profiles are added to the ones already created. You cannot import from a file if there are name conflicts between the names in the file and the names of existing profiles or sets.

Customizing profiles

You can manually edit the .vdprof file to remove unwanted profiles and sets, making a tailored file for a specific encoding use. The .vdprof file uses JSON formatting and can be edited in a text editor.

If an encoder program name in a .vdprof file is a relative path, it is resolved during import as being relative to the .vdprof file itself. This allows .vdprof files to be deployed next to an encoder such that when imported, the external program path is automatically correct regardless of the install location of the encoder.

Writing your own external encoder

An external encoder must satisfy the following conditions:

• Must accept raw audio or video data through standard input.
• Must write output data to a file.
• Must not spawn blocking (modal) UI.
• Should exit with a zero return code for success or a non-zero return code for failure.
• Should accept filenames on the command line with spaces.

These are easy to satisfy with a simple C/C++ program.

Accepting video data

Video encoders receive video frames as a series of YCbCr encoded frames. The frames are encoded from in left-to-right and then top-to-bottom (reading) order; the plane order is Y, then Cb, then Cr. There is no padding within scanlines or between planes or frames. The width and height of the frame are always even to ensure that the chroma planes are an integral number of pixels.

The color space is 4:2:0 YCbCr using Rec. 601 limited-range, 8-bit per channel encoding. The normal excursions are 16-235 for luma and 16-240 for chroma, but values from 0-255 may be encoded. Chroma positioning is per MPEG-2 conventions, with chroma samples coaligned with luma samples horizontally and centered vertically. Frames are always encoded as progressive scan.

Accepting audio in .wav format

Audio encoders have the option of receiving data in the form of a Microsoft waveform (.wav) container file instead of raw data. The advantage is that the .wav file contains the format of the data, so the encoding application does not need to receive format information on the command line, allowing for easy and automatic configuration.

In order to accept data in .wav format in a single pass (streamed) scenario, some format parsing restrictions must be relaxed. When receiving .wav data, an external encoder should ignore the length fields on the outer RIFF container and the inner data chunk, and parse all data from the beginning of the data chunk to the end of the stream. Also, the fact chunk should not be expected and be ignored if present, even for a compressed stream.

Changing the stdin data mode (Visual C++ Specific)

For encoding programs written using Microsoft Visual C++, an additional step is required in order to receive data correctly. By default, the VC++ runtime library applies a text mode translation to standard input, which in particular will cause truncation of the input stream on a control-Z character (hex 1A). To avoid this problem, reset the handling mode for stdin to binary mode:

#include <io.h>
#include <fcntl.h>

_setmode(_fileno(stdin), _O_BINARY);