vorbisenc.h File Reference

#include "codec.h"

Go to the source code of this file.

Classes
struct	ovectl_ratemanage2_arg
struct	ovectl_ratemanage_arg

Macros
vorbis_encode_ctl() codes
These values are passed as the number parameter of vorbis_encode_ctl(). The type of the referent of that function's arg pointer depends on these codes.
#define	OV_ECTL_RATEMANAGE2_GET   0x14
#define	OV_ECTL_RATEMANAGE2_SET   0x15
#define	OV_ECTL_LOWPASS_GET   0x20
#define	OV_ECTL_LOWPASS_SET   0x21
#define	OV_ECTL_IBLOCK_GET   0x30
#define	OV_ECTL_IBLOCK_SET   0x31
#define	OV_ECTL_COUPLING_GET   0x40
#define	OV_ECTL_COUPLING_SET   0x41
#define	OV_ECTL_RATEMANAGE_GET   0x10
#define	OV_ECTL_RATEMANAGE_SET   0x11
#define	OV_ECTL_RATEMANAGE_AVG   0x12
#define	OV_ECTL_RATEMANAGE_HARD   0x13

Functions
int	vorbis_encode_ctl (vorbis_info *vi, int number, void *arg)
int	vorbis_encode_init (vorbis_info *vi, long channels, long rate, long max_bitrate, long nominal_bitrate, long min_bitrate)
int	vorbis_encode_init_vbr (vorbis_info *vi, long channels, long rate, float base_quality)
int	vorbis_encode_setup_init (vorbis_info *vi)
int	vorbis_encode_setup_managed (vorbis_info *vi, long channels, long rate, long max_bitrate, long nominal_bitrate, long min_bitrate)
int	vorbis_encode_setup_vbr (vorbis_info *vi, long channels, long rate, float quality)

Detailed Description

Libvorbisenc is a convenient API for setting up an encoding environment using libvorbis. Libvorbisenc encapsulates the actions needed to set up the encoder properly.

Definition in file vorbisenc.h.

Macro Definition Documentation

#define OV_ECTL_COUPLING_GET   0x40

Returns the current encoder coupling setting in the int pointed to by arg.

Argument: int *

Definition at line 367 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_COUPLING_SET   0x41

Enables/disables channel coupling in multichannel encoding according to arg.

Argument: int *

Zero disables channel coupling for multichannel inputs, nonzer enables channel coupling. Setting has no effect on monophonic encoding or multichannel counts that do not offer coupling. At present, coupling is available for stereo and 5.1 encoding.

Definition at line 379 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_IBLOCK_GET   0x30

Returns the current encoder impulse block setting in the double pointed to by arg.

Argument: double *

Definition at line 348 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_IBLOCK_SET   0x31

Sets the impulse block bias to the the value pointed to by arg.

Argument: double *

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.

Definition at line 359 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_LOWPASS_GET   0x20

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

Argument: double *

Definition at line 332 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_LOWPASS_SET   0x21

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

Argument: double *

Definition at line 340 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_RATEMANAGE2_GET   0x14

Query the current encoder bitrate management setting.

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.

Definition at line 313 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_RATEMANAGE2_SET   0x15

Set the current encoder bitrate management settings.

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.

Definition at line 324 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_RATEMANAGE_AVG   0x12

Old interface to setting average-bitrate encoding mode.

Deprecated after move to bit-reservoir style management in 1.1 rendered this interface partially obsolete.

Argument: struct ovectl_ratemanage_arg *

Definition at line 415 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_RATEMANAGE_GET   0x10

Old interface to querying bitrate management settings.

Deprecated after move to bit-reservoir style management in 1.1 rendered this interface partially obsolete.

Argument: struct ovectl_ratemanage_arg *

Definition at line 393 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_RATEMANAGE_HARD   0x13

Old interface to setting bounded-bitrate encoding modes.

deprecated after move to bit-reservoir style management in 1.1 rendered this interface partially obsolete.

Argument: struct ovectl_ratemanage_arg *

Definition at line 426 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

#define OV_ECTL_RATEMANAGE_SET   0x11

Old interface to modifying bitrate management settings.

deprecated after move to bit-reservoir style management in 1.1 rendered this interface partially obsolete.

Argument: struct ovectl_ratemanage_arg *

Definition at line 404 of file vorbisenc.h.

Referenced by vorbis_encode_ctl().

Function Documentation

int vorbis_encode_ctl	(	vorbis_info *	vi,
		int	number,
		void *	arg
	)

This function implements a generic interface to miscellaneous encoder settings similar to the classic 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().

Parameters

vi	Pointer to an initialized vorbis_info struct.
number	Specifies the desired action; See the listof available requests".
arg	void * pointing to a data structure matching the request argument.

Return values

0	Success. Any further return information (such as the result of a query) is placed into the storage pointed to by *arg.
OV_EINVAL	Invalid argument, or an attempt to modify a setting after calling vorbis_encode_setup_init().
OV_EIMPL	Unimplemented or unknown request

Definition at line 1013 of file vorbisenc.c.

References highlevel_encode_setup::base_setting, highlevel_encode_setup::bitrate_av, highlevel_encode_setup::bitrate_av_damp, ovectl_ratemanage_arg::bitrate_av_hi, ovectl_ratemanage_arg::bitrate_av_lo, ovectl_ratemanage_arg::bitrate_av_window, ovectl_ratemanage_arg::bitrate_av_window_center, ovectl_ratemanage2_arg::bitrate_average_damping, ovectl_ratemanage2_arg::bitrate_average_kbps, ovectl_ratemanage_arg::bitrate_hard_max, ovectl_ratemanage_arg::bitrate_hard_min, ovectl_ratemanage_arg::bitrate_hard_window, ovectl_ratemanage2_arg::bitrate_limit_max_kbps, ovectl_ratemanage2_arg::bitrate_limit_min_kbps, ovectl_ratemanage2_arg::bitrate_limit_reservoir_bias, ovectl_ratemanage2_arg::bitrate_limit_reservoir_bits, highlevel_encode_setup::bitrate_max, highlevel_encode_setup::bitrate_min, highlevel_encode_setup::bitrate_reservoir, highlevel_encode_setup::bitrate_reservoir_bias, vorbis_info::channels, vorbis_info::codec_setup, highlevel_encode_setup::coupling_p, get_setup_template(), cordic::hi, codec_setup_info::hi, highlevel_encode_setup::impulse_noisetune, highlevel_encode_setup::lowpass_altered, highlevel_encode_setup::lowpass_kHz, highlevel_encode_setup::managed, ovectl_ratemanage_arg::management_active, ovectl_ratemanage2_arg::management_active, NULL, OV_ECTL_COUPLING_GET, OV_ECTL_COUPLING_SET, OV_ECTL_IBLOCK_GET, OV_ECTL_IBLOCK_SET, OV_ECTL_LOWPASS_GET, OV_ECTL_LOWPASS_SET, OV_ECTL_RATEMANAGE2_GET, OV_ECTL_RATEMANAGE2_SET, OV_ECTL_RATEMANAGE_AVG, OV_ECTL_RATEMANAGE_GET, OV_ECTL_RATEMANAGE_HARD, OV_ECTL_RATEMANAGE_SET, OV_EIMPL, OV_EINVAL, vorbis_info::rate, highlevel_encode_setup::req, highlevel_encode_setup::set_in_stone, highlevel_encode_setup::setup, vorbis_encode_ctl(), and vorbis_encode_setup_setting().

Referenced by vorbis_encode_ctl().

int vorbis_encode_init	(	vorbis_info *	vi,
		long	channels,
		long	rate,
		long	max_bitrate,
		long	nominal_bitrate,
		long	min_bitrate
	)

This is the primary function within libvorbisenc for setting up managed bitrate modes.

Before this function is called, the vorbis_info struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear() should be called.

The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set constraints for the encoded file. This function uses these settings to select the appropriate encoding mode and set it up.

Parameters

vi	Pointer to an initialized vorbis_info struct.
channels	The number of channels to be encoded.
rate	The sampling rate of the source audio.
max_bitrate	Desired maximum bitrate (limit). -1 indicates unset.
nominal_bitrate	Desired average, or central, bitrate. -1 indicates unset.
min_bitrate	Desired minimum bitrate. -1 indicates unset.

Returns

Zero for success, and negative values for failure.

Return values

0	Success.
OV_EFAULT	Internal logic fault; indicates a bug or heap/stack corruption.
OV_EINVAL	Invalid setup request, eg, out of range argument.
OV_EIMPL	Unimplemented mode; unable to comply with bitrate request.

Definition at line 990 of file vorbisenc.c.

References ret, vorbis_encode_setup_init(), vorbis_encode_setup_managed(), and vorbis_info_clear().

int vorbis_encode_init_vbr	(	vorbis_info *	vi,
		long	channels,
		long	rate,
		float	base_quality
	)

This is the primary function within libvorbisenc for setting up variable bitrate ("quality" based) modes.

Before this function is called, the vorbis_info struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear() should be called.

Parameters

vi	Pointer to an initialized vorbis_info struct.
channels	The number of channels to be encoded.
rate	The sampling rate of the source audio.
base_quality	Desired quality level, currently from -0.1 to 1.0 (lo to hi).

Returns

Zero for success, or a negative number for failure.

Return values

0	Success
OV_EFAULT	Internal logic fault; indicates a bug or heap/stack corruption.
OV_EINVAL	Invalid setup request, eg, out of range argument.
OV_EIMPL	Unimplemented mode; unable to comply with quality level request.

Definition at line 923 of file vorbisenc.c.

References ret, vorbis_encode_setup_init(), vorbis_encode_setup_vbr(), and vorbis_info_clear().

int vorbis_encode_setup_init

(

vorbis_info *

vi

)

This function performs the last stage of three-step encoding setup, as described in the API overview under managed bitrate modes.

Before this function is called, the vorbis_info struct should be initialized by using vorbis_info_init() from the libvorbis API, one of vorbis_encode_setup_managed() or vorbis_encode_setup_vbr() called to initialize the high-level encoding setup, and vorbis_encode_ctl() called if necessary to make encoding setup changes. vorbis_encode_setup_init() finalizes the highlevel encoding structure into a complete encoding setup after which the application may make no further setup changes.

After encoding, vorbis_info_clear() should be called.

Parameters

vi	Pointer to an initialized vorbis_info struct.

Returns

Zero for success, and negative values for failure.

Return values

0	Success.
OV_EFAULT	Internal logic fault; indicates a bug or heap/stack corruption.
OV_EINVAL	Attempt to use vorbis_encode_setup_init() without first calling one of vorbis_encode_setup_managed() or vorbis_encode_setup_vbr() to initialize the high-level encoding setup

Definition at line 681 of file vorbisenc.c.

References highlevel_encode_setup::amplitude_track_dBpersec, highlevel_encode_setup::ath_floating_dB, bitrate_manager_info::avg_rate, highlevel_encode_setup::base_setting, codec_setup_info::bi, highlevel_encode_setup::bitrate_av, highlevel_encode_setup::bitrate_av_damp, vorbis_info::bitrate_lower, highlevel_encode_setup::bitrate_max, highlevel_encode_setup::bitrate_min, vorbis_info::bitrate_nominal, highlevel_encode_setup::bitrate_reservoir, highlevel_encode_setup::bitrate_reservoir_bias, vorbis_info::bitrate_upper, vorbis_info::bitrate_window, highlevel_encode_setup::block, codec_setup_info::blocksizes, vorbis_info::codec_setup, cordic::hi, codec_setup_info::hi, i, highlevel_encode_setup::impulse_block_p, highlevel_encode_setup::impulse_noisetune, highlevel_encode_setup::managed, bitrate_manager_info::max_rate, bitrate_manager_info::min_rate, highlevel_byblocktype::noise_bias_setting, highlevel_byblocktype::noise_compand_setting, NULL, OV_EINVAL, bitrate_manager_info::reservoir_bias, bitrate_manager_info::reservoir_bits, highlevel_encode_setup::set_in_stone, setting_to_approx_bitrate(), highlevel_encode_setup::setup, bitrate_manager_info::slew_damp, highlevel_byblocktype::tone_mask_setting, highlevel_byblocktype::tone_peaklimit_setting, highlevel_encode_setup::trigger_setting, vorbis_encode_ath_setup(), vorbis_encode_blocksize_setup(), vorbis_encode_compand_setup(), vorbis_encode_floor_setup(), vorbis_encode_global_psych_setup(), vorbis_encode_global_stereo(), vorbis_encode_map_n_res_setup(), vorbis_encode_noisebias_setup(), vorbis_encode_peak_setup(), vorbis_encode_psyset_setup(), and vorbis_encode_tonemask_setup().

Referenced by vorbis_encode_init(), and vorbis_encode_init_vbr().

int vorbis_encode_setup_managed	(	vorbis_info *	vi,
		long	channels,
		long	rate,
		long	max_bitrate,
		long	nominal_bitrate,
		long	min_bitrate
	)

This function performs step-one of a three-step bitrate-managed encode setup. It functions similarly to the one-step setup performed by vorbis_encode_init but allows an application to make further encode setup tweaks using vorbis_encode_ctl before finally calling vorbis_encode_setup_init to complete the setup process.

Before this function is called, the vorbis_info struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear() should be called.

The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set constraints for the encoded file. This function uses these settings to select the appropriate encoding mode and set it up.

Parameters

vi	Pointer to an initialized vorbis_info struct.
channels	The number of channels to be encoded.
rate	The sampling rate of the source audio.
max_bitrate	Desired maximum bitrate (limit). -1 indicates unset.
nominal_bitrate	Desired average, or central, bitrate. -1 indicates unset.
min_bitrate	Desired minimum bitrate. -1 indicates unset.

Returns

Zero for success, and negative for failure.

Return values

0	Success
OV_EFAULT	Internal logic fault; indicates a bug or heap/stack corruption.
OV_EINVAL	Invalid setup request, eg, out of range argument.
OV_EIMPL	Unimplemented mode; unable to comply with bitrate request.

Definition at line 943 of file vorbisenc.c.

References highlevel_encode_setup::base_setting, highlevel_encode_setup::bitrate_av, highlevel_encode_setup::bitrate_av_damp, highlevel_encode_setup::bitrate_max, highlevel_encode_setup::bitrate_min, highlevel_encode_setup::bitrate_reservoir, highlevel_encode_setup::bitrate_reservoir_bias, vorbis_info::codec_setup, highlevel_encode_setup::coupling_p, get_setup_template(), cordic::hi, codec_setup_info::hi, highlevel_encode_setup::managed, OV_EIMPL, OV_EINVAL, highlevel_encode_setup::req, highlevel_encode_setup::setup, and vorbis_encode_setup_setting().

Referenced by vorbis_encode_init().

int vorbis_encode_setup_vbr	(	vorbis_info *	vi,
		long	channels,
		long	rate,
		float	quality
	)

This function performs step-one of a three-step variable bitrate (quality-based) encode setup. It functions similarly to the one-step setup performed by vorbis_encode_init_vbr() but allows an application to make further encode setup tweaks using vorbis_encode_ctl() before finally calling vorbis_encode_setup_init to complete the setup process.

Before this function is called, the vorbis_info struct should be initialized by using vorbis_info_init() from the libvorbis API. After encoding, vorbis_info_clear() should be called.

Parameters

vi	Pointer to an initialized vorbis_info struct.
channels	The number of channels to be encoded.
rate	The sampling rate of the source audio.
quality	Desired quality level, currently from -0.1 to 1.0 (lo to hi).

Returns

Zero for success, and negative values for failure.

Return values

0	Success
OV_EFAULT	Internal logic fault; indicates a bug or heap/stack corruption.
OV_EINVAL	Invalid setup request, eg, out of range argument.
OV_EIMPL	Unimplemented mode; unable to comply with quality level request.

Definition at line 902 of file vorbisenc.c.

References highlevel_encode_setup::base_setting, vorbis_info::codec_setup, highlevel_encode_setup::coupling_p, get_setup_template(), cordic::hi, codec_setup_info::hi, highlevel_encode_setup::managed, OV_EIMPL, highlevel_encode_setup::req, highlevel_encode_setup::setup, and vorbis_encode_setup_setting().

Referenced by vorbis_encode_init_vbr().