ILMTheoraEncoder Interface

This is the interface for the LEAD Theora Encoder.

Interface Properties:

Type

Name

Description

eTHEORARATECONTROL

RateControlMethod

Set to THEORA_CONSTANT_BITRATE to use bitrate-based compression (CBR = constant bitrate). In this case, the bitrate is given by the AverageBitrate and MaxQFactor properties.

Set to THEORA_CONSTANT_QUALITY to use quality-based compression (VBR = variable bitrate). In this case, the quality is given by the QFactor property.

The default value is THEORA_CONSTANT_QUALITY.

long

AverageBitrate

(Used only if RateControlMethod is THEORA_CONSTANT_BITRATE). Use this value to set the desired compressed video rate in bits per second. Note: this is not the same value as in the property page, since the property page value is in kilo bits per second.

The default value is 400000.

long

MaxQFactor

(Used only if RateControlMethod is THEORA_CONSTANT_BITRATE). Indicate the maximum quality factor that should be used to achieve the desired bitrate. The value ranges from 1 (best quality, lowest compression ratio) to 64 (worst quality, highest compression). The compressor will not use a quality factor higher than this value. If you set this property to a low value, the compressor might not be able to achieve the desired bitrate. The recommended value is 64, which gives the compressor the freedom to use any quality factor in order to achieve the desired compression rate.

The default value is 64.

long

QFactor

(Used only if RateControlMethod is THEORA_CONSTANT_QUALITY). Use a custom quality factor. The value ranges from 1 (best quality, lowest compression) to 64 (worst quality, highest compression).

The default value is 32.

long

I_FrameDistance

Set the maximum distance between I frames. The compressor will smartly decide when it is time to generate a new key (I) frame, but this setting guarantees a maximum distance between I frames. The I frame distance must be a power of two. The allowed values are: 1, 2, 4, 8, 16, 32, 64 (default), 128, 256, 512, 1024, 2048, 4096, 8192, 16384 and 32768.

The distance between I frames becomes important especially when you use the compressor for videoconferencing applications. The decoder can start decoding only when it encounters an I frame. If the distance between I frames is too great, the decoder will take a long time to start playing. Seeking will also take longer when you have a big distance between I frames. On the other hand, I frames are larger and a big distance between I frames reduces the size of the compressed video.

The default value is 64.

double

OutputFrameRate

Use this property to control the output frame rate. You can set the output frame rate to be the same as the input frame rate (0) or you can set it to particular output frame rate (if > 0). Note that you should set the output frame rate to be less than the input frame rate (to get better compression). It is not very useful to set the output frame rate to more than the input frame rate.

The default value is 0 (use input frame rate).

VARIANT_BOOL

FastCompression

Set to TRUE to increase the compression speed by a factor of 3x.

Set to FALSE to use the slower compression – this will produce slightly better compression.

The default value is TRUE.

long

Sharpness

Use this to control the sharpness of the generated video. Allowed values are 0 (Sharpest), 1 and 2 (Least sharp). Sharper video looks better but will greatly reduce the compression ratio.

The default value is 2.

 Interface Methods:

HRESULT WriteToRegistry()

Description

Writes the values of all of the properties listed above to the system registry, so that the encoder will remember these settings the next time it is used. This method is automatically called by the encoder property page when you make changes and click on Apply or OK buttons.

Return

S_OK if successful, S_FALSE otherwise.

HRESULT ReadFromRegistry()

Description

Reads all the values of all of the properties listed above from the system registry, so that the encoder will use the last defaults saved through WriteToRegistry.

Return

S_OK if successful, HRESULT error code otherwise.

HRESULT ResetToDefaults()

Description

Resets the encoder to its defaults.

Return

S_OK if successful, HRESULT error code otherwise.

eTHEORARATECONTROL enumeration

Value

Description

THEORA_CONSTANT_BITRATE

[0] The compressor will try to achieve bitrate indicated by AverageBitrate property and with quality factors ranging from 1 to MaxQFactor.

THEORA_CONSTANT_QUALITY

[1] The compressor will generate output of constant quality, as indicated by the QFactor property.