libvorbisenc documentation | libvorbisenc release 1.1 - 20040709

# vorbis_encode_ctl

declared in "vorbis/vorbisenc.h";

This function implements a generic interface to miscellaneous encoder settings similar to the clasasic UNIX 'ioctl()' system call. Applications may use vorbis_encode_ctl() to query or set bitrate management or quality mode details by using one of several request arguments detailed below. Vorbis_encode_ctl() must be called after one of vorbis_encode_setup_managed() or vorbis_encode_setup_vbr(). When used to modify settings, vorbis_encode_ctl() must be called before vorbis_encode_setup_init().

    extern int vorbis_encode_ctl(vorbis_info *vi,int request,void *arg);

### Parameters

vi
  Pointer to an initialized vorbis_info struct.

request
  Specifies the desired action; possible request fields are detailed below.

arg
  void * pointing to a data structure matching the request argument.

### Requests

OV_ECTL_RATEMANAGE2_GET
  Argument: struct ovectl_ratemanage2_arg *
  Used to query the current encoder bitrate management setting. Also used to initialize fields of an ovectl_ratemanage2_arg structure for use with OV_ECTL_RATEMANAGE2_SET.

OV_ECTL_RATEMANAGE2_SET
  Argument: struct ovectl_ratemanage2_arg *
  Used to set the current encoder bitrate management settings to the values listed in the ovectl_ratemanage2_arg. Passing a NULL pointer will disable bitrate management.

OV_ECTL_LOWPASS_GET
  Argument: double *
  Returns the current encoder hard-lowpass setting (kHz) in the double pointed to by arg.

OV_ECTL_LOWPASS_SET
  Argument: double *
  Sets the encoder hard-lowpass to the value (kHz) pointed to by arg. Valid lowpass settings range from 2 to 99.

OV_ECTL_IBLOCK_GET
  Argument: double *
  Returns the current encoder impulse block setting in the double pointed to by arg.

OV_ECTL_IBLOCK_SET
  Argument: double *
  Sets the impulse block bias to the the value pointed to by arg; valid range is -15.0 to 0.0 [default]. A negative impulse block bias will direct to encoder to use more bits when incoding short blocks that contain strong impulses, thus improving the accuracy of impulse encoding.

OV_ECTL_COUPLING_GET
  Argument: int *
  Returns the current encoder coupling enabled/disabled setting in the int pointed to by arg.

OV_ECTL_COUPLING_SET
  Argument: int *
  Enables/disables channel coupling in multichannel encoding according to arg. *arg of zero disables all channel coupling, nonzero allows the encoder to use coupling if a coupled mode is available for the input. At present, coupling is available for stereo and 5.1 input modes.

OV_ECTL_RATEMANAGE_GET [deprecated]
  Argument: struct ovectl_ratemanage_arg *
  Old interface to querying bitrate management settings; deprecated after move to bit-reservoir style management in 1.1 rendered this interface partially obsolete. Please use OV_ECTL_RATEMANGE2_GET instead.

OV_ECTL_RATEMANAGE_SET [deprecated]
  Argument: struct ovectl_ratemanage_arg *
  Old interface to modifying bitrate management settings; deprecated after move to bit-reservoir style management in 1.1 rendered this interface partially obsolete. Please use OV_ECTL_RATEMANGE2_SET instead.

OV_ECTL_RATEMANAGE_AVG [deprecated]
  Argument: struct ovectl_ratemanage_arg *
  Old interface to setting average-bitrate encoding mode; deprecated after move to bit-reservoir style management in 1.1 rendered this interface partially obsolete. Please use OV_ECTL_RATEMANGE2_SET instead.

OV_ECTL_RATEMANAGE_HARD [deprecated]
  Argument: struct ovectl_ratemanage_arg *
  Old interface to setting bounded-bitrate encoding modes; deprecated after move to bit-reservoir style management in 1.1 rendered this interface partially obsolete. Please use OV_ECTL_RATEMANGE2_SET instead.

### Return Values

vorbis_encode_ctl() returns zero on success, placing any further return information (such as the result of a query) into the storage pointed to by *arg. On error, vorbis_encode_ctl() may return one of the following error codes:

OV_EINVAL
  Invalid argument, or an attempt to modify a setting after calling vorbis_encode_setup_init().

OV_EIMPL
  Unimplemented or unknown request

copyright © 2004 xiph.org | Ogg Vorbis team@vorbis.org
libvorbisenc documentation | libvorbisenc release 1.1 - 20040709