vorbisenc.h 17 KB

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