1 /******************************************************************** 2 * * 3 * THIS FILE IS PART OF THE OggVorbis SOFTWARE CODEC SOURCE CODE. * 4 * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * 5 * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * 6 * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * 7 * * 8 * THE OggVorbis SOURCE CODE IS (C) COPYRIGHT 1994-2001 * 9 * by the Xiph.Org Foundation http://www.xiph.org/ * 10 * * 11 ******************************************************************** 12 13 function: vorbis encode-engine setup 14 15 ********************************************************************/ 16 17 /** \file 18 * Libvorbisenc is a convenient API for setting up an encoding 19 * environment using libvorbis. Libvorbisenc encapsulates the 20 * actions needed to set up the encoder properly. 21 */ 22 23 #ifndef _OV_ENC_H_ 24 #define _OV_ENC_H_ 25 26 #ifdef __cplusplus 27 extern "C" 28 { 29 #endif /* __cplusplus */ 30 31 #include "codec.h" 32 33 /** 34 * This is the primary function within libvorbisenc for setting up managed 35 * bitrate modes. 36 * 37 * Before this function is called, the \ref vorbis_info 38 * struct should be initialized by using vorbis_info_init() from the libvorbis 39 * API. After encoding, vorbis_info_clear() should be called. 40 * 41 * The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set 42 * constraints for the encoded file. This function uses these settings to 43 * select the appropriate encoding mode and set it up. 44 * 45 * \param vi Pointer to an initialized \ref vorbis_info struct. 46 * \param channels The number of channels to be encoded. 47 * \param rate The sampling rate of the source audio. 48 * \param max_bitrate Desired maximum bitrate (limit). -1 indicates unset. 49 * \param nominal_bitrate Desired average, or central, bitrate. -1 indicates unset. 50 * \param min_bitrate Desired minimum bitrate. -1 indicates unset. 51 * 52 * \return Zero for success, and negative values for failure. 53 * 54 * \retval 0 Success. 55 * \retval OV_EFAULT Internal logic fault; indicates a bug or heap/stack corruption. 56 * \retval OV_EINVAL Invalid setup request, eg, out of range argument. 57 * \retval OV_EIMPL Unimplemented mode; unable to comply with bitrate request. 58 */ 59 extern int vorbis_encode_init(vorbis_info *vi, 60 long channels, 61 long rate, 62 63 long max_bitrate, 64 long nominal_bitrate, 65 long min_bitrate); 66 67 /** 68 * This function performs step-one of a three-step bitrate-managed encode 69 * setup. It functions similarly to the one-step setup performed by \ref 70 * vorbis_encode_init but allows an application to make further encode setup 71 * tweaks using \ref vorbis_encode_ctl before finally calling \ref 72 * vorbis_encode_setup_init to complete the setup process. 73 * 74 * Before this function is called, the \ref vorbis_info struct should be 75 * initialized by using vorbis_info_init() from the libvorbis API. After 76 * encoding, vorbis_info_clear() should be called. 77 * 78 * The max_bitrate, nominal_bitrate, and min_bitrate settings are used to set 79 * constraints for the encoded file. This function uses these settings to 80 * select the appropriate encoding mode and set it up. 81 * 82 * \param vi Pointer to an initialized vorbis_info struct. 83 * \param channels The number of channels to be encoded. 84 * \param rate The sampling rate of the source audio. 85 * \param max_bitrate Desired maximum bitrate (limit). -1 indicates unset. 86 * \param nominal_bitrate Desired average, or central, bitrate. -1 indicates unset. 87 * \param min_bitrate Desired minimum bitrate. -1 indicates unset. 88 * 89 * \return Zero for success, and negative for failure. 90 * 91 * \retval 0 Success 92 * \retval OV_EFAULT Internal logic fault; indicates a bug or heap/stack corruption. 93 * \retval OV_EINVAL Invalid setup request, eg, out of range argument. 94 * \retval OV_EIMPL Unimplemented mode; unable to comply with bitrate request. 95 */ 96 extern int vorbis_encode_setup_managed(vorbis_info *vi, 97 long channels, 98 long rate, 99 100 long max_bitrate, 101 long nominal_bitrate, 102 long min_bitrate); 103 104 /** 105 * This function performs step-one of a three-step variable bitrate 106 * (quality-based) encode setup. It functions similarly to the one-step setup 107 * performed by \ref vorbis_encode_init_vbr() but allows an application to 108 * make further encode setup tweaks using \ref vorbis_encode_ctl() before 109 * finally calling \ref vorbis_encode_setup_init to complete the setup 110 * process. 111 * 112 * Before this function is called, the \ref vorbis_info struct should be 113 * initialized by using \ref vorbis_info_init() from the libvorbis API. After 114 * encoding, vorbis_info_clear() should be called. 115 * 116 * \param vi Pointer to an initialized vorbis_info struct. 117 * \param channels The number of channels to be encoded. 118 * \param rate The sampling rate of the source audio. 119 * \param quality Desired quality level, currently from -0.1 to 1.0 (lo to hi). 120 * 121 * \return Zero for success, and negative values for failure. 122 * 123 * \retval 0 Success 124 * \retval OV_EFAULT Internal logic fault; indicates a bug or heap/stack corruption. 125 * \retval OV_EINVAL Invalid setup request, eg, out of range argument. 126 * \retval OV_EIMPL Unimplemented mode; unable to comply with quality level request. 127 */ 128 extern int vorbis_encode_setup_vbr(vorbis_info *vi, 129 long channels, 130 long rate, 131 132 float quality 133 ); 134 135 /** 136 * This is the primary function within libvorbisenc for setting up variable 137 * bitrate ("quality" based) modes. 138 * 139 * 140 * Before this function is called, the vorbis_info struct should be 141 * initialized by using vorbis_info_init() from the libvorbis API. After 142 * encoding, vorbis_info_clear() should be called. 143 * 144 * \param vi Pointer to an initialized vorbis_info struct. 145 * \param channels The number of channels to be encoded. 146 * \param rate The sampling rate of the source audio. 147 * \param base_quality Desired quality level, currently from -0.1 to 1.0 (lo to hi). 148 * 149 * 150 * \return Zero for success, or a negative number for failure. 151 * 152 * \retval 0 Success 153 * \retval OV_EFAULT Internal logic fault; indicates a bug or heap/stack corruption. 154 * \retval OV_EINVAL Invalid setup request, eg, out of range argument. 155 * \retval OV_EIMPL Unimplemented mode; unable to comply with quality level request. 156 */ 157 extern int vorbis_encode_init_vbr(vorbis_info *vi, 158 long channels, 159 long rate, 160 161 float base_quality 162 ); 163 164 /** 165 * This function performs the last stage of three-step encoding setup, as 166 * described in the API overview under managed bitrate modes. 167 * 168 * Before this function is called, the \ref vorbis_info struct should be 169 * initialized by using vorbis_info_init() from the libvorbis API, one of 170 * \ref vorbis_encode_setup_managed() or \ref vorbis_encode_setup_vbr() called to 171 * initialize the high-level encoding setup, and \ref vorbis_encode_ctl() 172 * called if necessary to make encoding setup changes. 173 * vorbis_encode_setup_init() finalizes the highlevel encoding structure into 174 * a complete encoding setup after which the application may make no further 175 * setup changes. 176 * 177 * After encoding, vorbis_info_clear() should be called. 178 * 179 * \param vi Pointer to an initialized \ref vorbis_info struct. 180 * 181 * \return Zero for success, and negative values for failure. 182 * 183 * \retval 0 Success. 184 * \retval OV_EFAULT Internal logic fault; indicates a bug or heap/stack corruption. 185 * 186 * \retval OV_EINVAL Attempt to use vorbis_encode_setup_init() without first 187 * calling one of vorbis_encode_setup_managed() or vorbis_encode_setup_vbr() to 188 * initialize the high-level encoding setup 189 * 190 */ 191 extern int vorbis_encode_setup_init(vorbis_info *vi); 192 193 /** 194 * This function implements a generic interface to miscellaneous encoder 195 * settings similar to the classic UNIX 'ioctl()' system call. Applications 196 * may use vorbis_encode_ctl() to query or set bitrate management or quality 197 * mode details by using one of several \e request arguments detailed below. 198 * vorbis_encode_ctl() must be called after one of 199 * vorbis_encode_setup_managed() or vorbis_encode_setup_vbr(). When used 200 * to modify settings, \ref vorbis_encode_ctl() must be called before \ref 201 * vorbis_encode_setup_init(). 202 * 203 * \param vi Pointer to an initialized vorbis_info struct. 204 * 205 * \param number Specifies the desired action; See \ref encctlcodes "the list 206 * of available requests". 207 * 208 * \param arg void * pointing to a data structure matching the request 209 * argument. 210 * 211 * \retval 0 Success. Any further return information (such as the result of a 212 * query) is placed into the storage pointed to by *arg. 213 * 214 * \retval OV_EINVAL Invalid argument, or an attempt to modify a setting after 215 * calling vorbis_encode_setup_init(). 216 * 217 * \retval OV_EIMPL Unimplemented or unknown request 218 */ 219 extern int vorbis_encode_ctl(vorbis_info *vi,int number,void *arg); 220 221 /** 222 * \deprecated This is a deprecated interface. Please use vorbis_encode_ctl() 223 * with the \ref ovectl_ratemanage2_arg struct and \ref 224 * OV_ECTL_RATEMANAGE2_GET and \ref OV_ECTL_RATEMANAGE2_SET calls in new code. 225 * 226 * The \ref ovectl_ratemanage_arg structure is used with vorbis_encode_ctl() 227 * and the \ref OV_ECTL_RATEMANAGE_GET, \ref OV_ECTL_RATEMANAGE_SET, \ref 228 * OV_ECTL_RATEMANAGE_AVG, \ref OV_ECTL_RATEMANAGE_HARD calls in order to 229 * query and modify specifics of the encoder's bitrate management 230 * configuration. 231 */ 232 struct ovectl_ratemanage_arg { 233 int management_active; /**< nonzero if bitrate management is active*/ 234 /** hard lower limit (in kilobits per second) below which the stream bitrate 235 will never be allowed for any given bitrate_hard_window seconds of time.*/ 236 long bitrate_hard_min; 237 /** hard upper limit (in kilobits per second) above which the stream bitrate 238 will never be allowed for any given bitrate_hard_window seconds of time.*/ 239 long bitrate_hard_max; 240 /** the window period (in seconds) used to regulate the hard bitrate minimum 241 and maximum*/ 242 double bitrate_hard_window; 243 /** soft lower limit (in kilobits per second) below which the average bitrate 244 tracker will start nudging the bitrate higher.*/ 245 long bitrate_av_lo; 246 /** soft upper limit (in kilobits per second) above which the average bitrate 247 tracker will start nudging the bitrate lower.*/ 248 long bitrate_av_hi; 249 /** the window period (in seconds) used to regulate the average bitrate 250 minimum and maximum.*/ 251 double bitrate_av_window; 252 /** Regulates the relative centering of the average and hard windows; in 253 libvorbis 1.0 and 1.0.1, the hard window regulation overlapped but 254 followed the average window regulation. In libvorbis 1.1 a bit-reservoir 255 interface replaces the old windowing interface; the older windowing 256 interface is simulated and this field has no effect.*/ 257 double bitrate_av_window_center; 258 }; 259 260 /** 261 * \name struct ovectl_ratemanage2_arg 262 * 263 * The ovectl_ratemanage2_arg structure is used with vorbis_encode_ctl() and 264 * the OV_ECTL_RATEMANAGE2_GET and OV_ECTL_RATEMANAGE2_SET calls in order to 265 * query and modify specifics of the encoder's bitrate management 266 * configuration. 267 * 268 */ 269 struct ovectl_ratemanage2_arg { 270 int management_active; /**< nonzero if bitrate management is active */ 271 /** Lower allowed bitrate limit in kilobits per second */ 272 long bitrate_limit_min_kbps; 273 /** Upper allowed bitrate limit in kilobits per second */ 274 long bitrate_limit_max_kbps; 275 long bitrate_limit_reservoir_bits; /**<Size of the bitrate reservoir in bits */ 276 /** Regulates the bitrate reservoir's preferred fill level in a range from 0.0 277 * to 1.0; 0.0 tries to bank bits to buffer against future bitrate spikes, 1.0 278 * buffers against future sudden drops in instantaneous bitrate. Default is 279 * 0.1 280 */ 281 double bitrate_limit_reservoir_bias; 282 /** Average bitrate setting in kilobits per second */ 283 long bitrate_average_kbps; 284 /** Slew rate limit setting for average bitrate adjustment; sets the minimum 285 * time in seconds the bitrate tracker may swing from one extreme to the 286 * other when boosting or damping average bitrate. 287 */ 288 double bitrate_average_damping; 289 }; 290 291 292 /** 293 * \name vorbis_encode_ctl() codes 294 * 295 * \anchor encctlcodes 296 * 297 * These values are passed as the \c number parameter of vorbis_encode_ctl(). 298 * The type of the referent of that function's \c arg pointer depends on these 299 * codes. 300 */ 301 /*@{*/ 302 303 /** 304 * Query the current encoder bitrate management setting. 305 * 306 *Argument: <tt>struct ovectl_ratemanage2_arg *</tt> 307 * 308 * Used to query the current encoder bitrate management setting. Also used to 309 * initialize fields of an ovectl_ratemanage2_arg structure for use with 310 * \ref OV_ECTL_RATEMANAGE2_SET. 311 */ 312 #define OV_ECTL_RATEMANAGE2_GET 0x14 313 314 /** 315 * Set the current encoder bitrate management settings. 316 * 317 * Argument: <tt>struct ovectl_ratemanage2_arg *</tt> 318 * 319 * Used to set the current encoder bitrate management settings to the values 320 * listed in the ovectl_ratemanage2_arg. Passing a NULL pointer will disable 321 * bitrate management. 322 */ 323 #define OV_ECTL_RATEMANAGE2_SET 0x15 324 325 /** 326 * Returns the current encoder hard-lowpass setting (kHz) in the double 327 * pointed to by arg. 328 * 329 * Argument: <tt>double *</tt> 330 */ 331 #define OV_ECTL_LOWPASS_GET 0x20 332 333 /** 334 * Sets the encoder hard-lowpass to the value (kHz) pointed to by arg. Valid 335 * lowpass settings range from 2 to 99. 336 * 337 * Argument: <tt>double *</tt> 338 */ 339 #define OV_ECTL_LOWPASS_SET 0x21 340 341 /** 342 * Returns the current encoder impulse block setting in the double pointed 343 * to by arg. 344 * 345 * Argument: <tt>double *</tt> 346 */ 347 #define OV_ECTL_IBLOCK_GET 0x30 348 349 /** 350 * Sets the impulse block bias to the the value pointed to by arg. 351 * 352 * Argument: <tt>double *</tt> 353 * 354 * Valid range is -15.0 to 0.0 [default]. A negative impulse block bias will 355 * direct to encoder to use more bits when incoding short blocks that contain 356 * strong impulses, thus improving the accuracy of impulse encoding. 357 */ 358 #define OV_ECTL_IBLOCK_SET 0x31 359 360 /** 361 * Returns the current encoder coupling setting in the int pointed 362 * to by arg. 363 * 364 * Argument: <tt>int *</tt> 365 */ 366 #define OV_ECTL_COUPLING_GET 0x40 367 368 /** 369 * Enables/disables channel coupling in multichannel encoding according to arg. 370 * 371 * Argument: <tt>int *</tt> 372 * 373 * Zero disables channel coupling for multichannel inputs, nonzer enables 374 * channel coupling. Setting has no effect on monophonic encoding or 375 * multichannel counts that do not offer coupling. At present, coupling is 376 * available for stereo and 5.1 encoding. 377 */ 378 #define OV_ECTL_COUPLING_SET 0x41 379 380 /* deprecated rate management supported only for compatibility */ 381 382 /** 383 * Old interface to querying bitrate management settings. 384 * 385 * Deprecated after move to bit-reservoir style management in 1.1 rendered 386 * this interface partially obsolete. 387 388 * \deprecated Please use \ref OV_ECTL_RATEMANAGE2_GET instead. 389 * 390 * Argument: <tt>struct ovectl_ratemanage_arg *</tt> 391 */ 392 #define OV_ECTL_RATEMANAGE_GET 0x10 393 /** 394 * Old interface to modifying bitrate management settings. 395 * 396 * deprecated after move to bit-reservoir style management in 1.1 rendered 397 * this interface partially obsolete. 398 * 399 * \deprecated Please use \ref OV_ECTL_RATEMANAGE2_SET instead. 400 * 401 * Argument: <tt>struct ovectl_ratemanage_arg *</tt> 402 */ 403 #define OV_ECTL_RATEMANAGE_SET 0x11 404 /** 405 * Old interface to setting average-bitrate encoding mode. 406 * 407 * Deprecated after move to bit-reservoir style management in 1.1 rendered 408 * this interface partially obsolete. 409 * 410 * \deprecated Please use \ref OV_ECTL_RATEMANAGE2_SET instead. 411 * 412 * Argument: <tt>struct ovectl_ratemanage_arg *</tt> 413 */ 414 #define OV_ECTL_RATEMANAGE_AVG 0x12 415 /** 416 * Old interface to setting bounded-bitrate encoding modes. 417 * 418 * deprecated after move to bit-reservoir style management in 1.1 rendered 419 * this interface partially obsolete. 420 * 421 * \deprecated Please use \ref OV_ECTL_RATEMANAGE2_SET instead. 422 * 423 * Argument: <tt>struct ovectl_ratemanage_arg *</tt> 424 */ 425 #define OV_ECTL_RATEMANAGE_HARD 0x13 426 427 /*@}*/ 428 429 430 431 #ifdef __cplusplus 432 } 433 #endif /* __cplusplus */ 434 435 #endif 436