avresample.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409
  1. /*
  2. * Copyright (c) 2012 Justin Ruggles <justin.ruggles@gmail.com>
  3. *
  4. * This file is part of Libav.
  5. *
  6. * Libav is free software; you can redistribute it and/or
  7. * modify it under the terms of the GNU Lesser General Public
  8. * License as published by the Free Software Foundation; either
  9. * version 2.1 of the License, or (at your option) any later version.
  10. *
  11. * Libav is distributed in the hope that it will be useful,
  12. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  14. * Lesser General Public License for more details.
  15. *
  16. * You should have received a copy of the GNU Lesser General Public
  17. * License along with Libav; if not, write to the Free Software
  18. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19. */
  20. #ifndef AVRESAMPLE_AVRESAMPLE_H
  21. #define AVRESAMPLE_AVRESAMPLE_H
  22. /**
  23. * @file
  24. * @ingroup lavr
  25. * external API header
  26. */
  27. /**
  28. * @defgroup lavr Libavresample
  29. * @{
  30. *
  31. * Libavresample (lavr) is a library that handles audio resampling, sample
  32. * format conversion and mixing.
  33. *
  34. * Interaction with lavr is done through AVAudioResampleContext, which is
  35. * allocated with avresample_alloc_context(). It is opaque, so all parameters
  36. * must be set with the @ref avoptions API.
  37. *
  38. * For example the following code will setup conversion from planar float sample
  39. * format to interleaved signed 16-bit integer, downsampling from 48kHz to
  40. * 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing
  41. * matrix):
  42. * @code
  43. * AVAudioResampleContext *avr = avresample_alloc_context();
  44. * av_opt_set_int(avr, "in_channel_layout", AV_CH_LAYOUT_5POINT1, 0);
  45. * av_opt_set_int(avr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0);
  46. * av_opt_set_int(avr, "in_sample_rate", 48000, 0);
  47. * av_opt_set_int(avr, "out_sample_rate", 44100, 0);
  48. * av_opt_set_int(avr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0);
  49. * av_opt_set_int(avr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0);
  50. * @endcode
  51. *
  52. * Once the context is initialized, it must be opened with avresample_open(). If
  53. * you need to change the conversion parameters, you must close the context with
  54. * avresample_close(), change the parameters as described above, then reopen it
  55. * again.
  56. *
  57. * The conversion itself is done by repeatedly calling avresample_convert().
  58. * Note that the samples may get buffered in two places in lavr. The first one
  59. * is the output FIFO, where the samples end up if the output buffer is not
  60. * large enough. The data stored in there may be retrieved at any time with
  61. * avresample_read(). The second place is the resampling delay buffer,
  62. * applicable only when resampling is done. The samples in it require more input
  63. * before they can be processed. Their current amount is returned by
  64. * avresample_get_delay(). At the end of conversion the resampling buffer can be
  65. * flushed by calling avresample_convert() with NULL input.
  66. *
  67. * The following code demonstrates the conversion loop assuming the parameters
  68. * from above and caller-defined functions get_input() and handle_output():
  69. * @code
  70. * uint8_t **input;
  71. * int in_linesize, in_samples;
  72. *
  73. * while (get_input(&input, &in_linesize, &in_samples)) {
  74. * uint8_t *output
  75. * int out_linesize;
  76. * int out_samples = avresample_available(avr) +
  77. * av_rescale_rnd(avresample_get_delay(avr) +
  78. * in_samples, 44100, 48000, AV_ROUND_UP);
  79. * av_samples_alloc(&output, &out_linesize, 2, out_samples,
  80. * AV_SAMPLE_FMT_S16, 0);
  81. * out_samples = avresample_convert(avr, &output, out_linesize, out_samples,
  82. * input, in_linesize, in_samples);
  83. * handle_output(output, out_linesize, out_samples);
  84. * av_freep(&output);
  85. * }
  86. * @endcode
  87. *
  88. * When the conversion is finished and the FIFOs are flushed if required, the
  89. * conversion context and everything associated with it must be freed with
  90. * avresample_free().
  91. */
  92. #include "libavutil/avutil.h"
  93. #include "libavutil/channel_layout.h"
  94. #include "libavutil/dict.h"
  95. #include "libavutil/log.h"
  96. #include "libavresample/version.h"
  97. #define AVRESAMPLE_MAX_CHANNELS 32
  98. typedef struct AVAudioResampleContext AVAudioResampleContext;
  99. /** Mixing Coefficient Types */
  100. enum AVMixCoeffType {
  101. AV_MIX_COEFF_TYPE_Q8, /** 16-bit 8.8 fixed-point */
  102. AV_MIX_COEFF_TYPE_Q15, /** 32-bit 17.15 fixed-point */
  103. AV_MIX_COEFF_TYPE_FLT, /** floating-point */
  104. AV_MIX_COEFF_TYPE_NB, /** Number of coeff types. Not part of ABI */
  105. };
  106. /** Resampling Filter Types */
  107. enum AVResampleFilterType {
  108. AV_RESAMPLE_FILTER_TYPE_CUBIC, /**< Cubic */
  109. AV_RESAMPLE_FILTER_TYPE_BLACKMAN_NUTTALL, /**< Blackman Nuttall Windowed Sinc */
  110. AV_RESAMPLE_FILTER_TYPE_KAISER, /**< Kaiser Windowed Sinc */
  111. };
  112. enum AVResampleDitherMethod {
  113. AV_RESAMPLE_DITHER_NONE, /**< Do not use dithering */
  114. AV_RESAMPLE_DITHER_RECTANGULAR, /**< Rectangular Dither */
  115. AV_RESAMPLE_DITHER_TRIANGULAR, /**< Triangular Dither*/
  116. AV_RESAMPLE_DITHER_TRIANGULAR_HP, /**< Triangular Dither with High Pass */
  117. AV_RESAMPLE_DITHER_TRIANGULAR_NS, /**< Triangular Dither with Noise Shaping */
  118. AV_RESAMPLE_DITHER_NB, /**< Number of dither types. Not part of ABI. */
  119. };
  120. /**
  121. * Return the LIBAVRESAMPLE_VERSION_INT constant.
  122. */
  123. unsigned avresample_version(void);
  124. /**
  125. * Return the libavresample build-time configuration.
  126. * @return configure string
  127. */
  128. const char *avresample_configuration(void);
  129. /**
  130. * Return the libavresample license.
  131. */
  132. const char *avresample_license(void);
  133. /**
  134. * Get the AVClass for AVAudioResampleContext.
  135. *
  136. * Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options
  137. * without allocating a context.
  138. *
  139. * @see av_opt_find().
  140. *
  141. * @return AVClass for AVAudioResampleContext
  142. */
  143. const AVClass *avresample_get_class(void);
  144. /**
  145. * Allocate AVAudioResampleContext and set options.
  146. *
  147. * @return allocated audio resample context, or NULL on failure
  148. */
  149. AVAudioResampleContext *avresample_alloc_context(void);
  150. /**
  151. * Initialize AVAudioResampleContext.
  152. *
  153. * @param avr audio resample context
  154. * @return 0 on success, negative AVERROR code on failure
  155. */
  156. int avresample_open(AVAudioResampleContext *avr);
  157. /**
  158. * Close AVAudioResampleContext.
  159. *
  160. * This closes the context, but it does not change the parameters. The context
  161. * can be reopened with avresample_open(). It does, however, clear the output
  162. * FIFO and any remaining leftover samples in the resampling delay buffer. If
  163. * there was a custom matrix being used, that is also cleared.
  164. *
  165. * @see avresample_convert()
  166. * @see avresample_set_matrix()
  167. *
  168. * @param avr audio resample context
  169. */
  170. void avresample_close(AVAudioResampleContext *avr);
  171. /**
  172. * Free AVAudioResampleContext and associated AVOption values.
  173. *
  174. * This also calls avresample_close() before freeing.
  175. *
  176. * @param avr audio resample context
  177. */
  178. void avresample_free(AVAudioResampleContext **avr);
  179. /**
  180. * Generate a channel mixing matrix.
  181. *
  182. * This function is the one used internally by libavresample for building the
  183. * default mixing matrix. It is made public just as a utility function for
  184. * building custom matrices.
  185. *
  186. * @param in_layout input channel layout
  187. * @param out_layout output channel layout
  188. * @param center_mix_level mix level for the center channel
  189. * @param surround_mix_level mix level for the surround channel(s)
  190. * @param lfe_mix_level mix level for the low-frequency effects channel
  191. * @param normalize if 1, coefficients will be normalized to prevent
  192. * overflow. if 0, coefficients will not be
  193. * normalized.
  194. * @param[out] matrix mixing coefficients; matrix[i + stride * o] is
  195. * the weight of input channel i in output channel o.
  196. * @param stride distance between adjacent input channels in the
  197. * matrix array
  198. * @param matrix_encoding matrixed stereo downmix mode (e.g. dplii)
  199. * @return 0 on success, negative AVERROR code on failure
  200. */
  201. int avresample_build_matrix(uint64_t in_layout, uint64_t out_layout,
  202. double center_mix_level, double surround_mix_level,
  203. double lfe_mix_level, int normalize, double *matrix,
  204. int stride, enum AVMatrixEncoding matrix_encoding);
  205. /**
  206. * Get the current channel mixing matrix.
  207. *
  208. * If no custom matrix has been previously set or the AVAudioResampleContext is
  209. * not open, an error is returned.
  210. *
  211. * @param avr audio resample context
  212. * @param matrix mixing coefficients; matrix[i + stride * o] is the weight of
  213. * input channel i in output channel o.
  214. * @param stride distance between adjacent input channels in the matrix array
  215. * @return 0 on success, negative AVERROR code on failure
  216. */
  217. int avresample_get_matrix(AVAudioResampleContext *avr, double *matrix,
  218. int stride);
  219. /**
  220. * Set channel mixing matrix.
  221. *
  222. * Allows for setting a custom mixing matrix, overriding the default matrix
  223. * generated internally during avresample_open(). This function can be called
  224. * anytime on an allocated context, either before or after calling
  225. * avresample_open(), as long as the channel layouts have been set.
  226. * avresample_convert() always uses the current matrix.
  227. * Calling avresample_close() on the context will clear the current matrix.
  228. *
  229. * @see avresample_close()
  230. *
  231. * @param avr audio resample context
  232. * @param matrix mixing coefficients; matrix[i + stride * o] is the weight of
  233. * input channel i in output channel o.
  234. * @param stride distance between adjacent input channels in the matrix array
  235. * @return 0 on success, negative AVERROR code on failure
  236. */
  237. int avresample_set_matrix(AVAudioResampleContext *avr, const double *matrix,
  238. int stride);
  239. /**
  240. * Set a customized input channel mapping.
  241. *
  242. * This function can only be called when the allocated context is not open.
  243. * Also, the input channel layout must have already been set.
  244. *
  245. * Calling avresample_close() on the context will clear the channel mapping.
  246. *
  247. * The map for each input channel specifies the channel index in the source to
  248. * use for that particular channel, or -1 to mute the channel. Source channels
  249. * can be duplicated by using the same index for multiple input channels.
  250. *
  251. * Examples:
  252. *
  253. * Reordering 5.1 AAC order (C,L,R,Ls,Rs,LFE) to Libav order (L,R,C,LFE,Ls,Rs):
  254. * { 1, 2, 0, 5, 3, 4 }
  255. *
  256. * Muting the 3rd channel in 4-channel input:
  257. * { 0, 1, -1, 3 }
  258. *
  259. * Duplicating the left channel of stereo input:
  260. * { 0, 0 }
  261. *
  262. * @param avr audio resample context
  263. * @param channel_map customized input channel mapping
  264. * @return 0 on success, negative AVERROR code on failure
  265. */
  266. int avresample_set_channel_mapping(AVAudioResampleContext *avr,
  267. const int *channel_map);
  268. /**
  269. * Set compensation for resampling.
  270. *
  271. * This can be called anytime after avresample_open(). If resampling is not
  272. * automatically enabled because of a sample rate conversion, the
  273. * "force_resampling" option must have been set to 1 when opening the context
  274. * in order to use resampling compensation.
  275. *
  276. * @param avr audio resample context
  277. * @param sample_delta compensation delta, in samples
  278. * @param compensation_distance compensation distance, in samples
  279. * @return 0 on success, negative AVERROR code on failure
  280. */
  281. int avresample_set_compensation(AVAudioResampleContext *avr, int sample_delta,
  282. int compensation_distance);
  283. /**
  284. * Convert input samples and write them to the output FIFO.
  285. *
  286. * The upper bound on the number of output samples is given by
  287. * avresample_available() + (avresample_get_delay() + number of input samples) *
  288. * output sample rate / input sample rate.
  289. *
  290. * The output data can be NULL or have fewer allocated samples than required.
  291. * In this case, any remaining samples not written to the output will be added
  292. * to an internal FIFO buffer, to be returned at the next call to this function
  293. * or to avresample_read().
  294. *
  295. * If converting sample rate, there may be data remaining in the internal
  296. * resampling delay buffer. avresample_get_delay() tells the number of remaining
  297. * samples. To get this data as output, call avresample_convert() with NULL
  298. * input.
  299. *
  300. * At the end of the conversion process, there may be data remaining in the
  301. * internal FIFO buffer. avresample_available() tells the number of remaining
  302. * samples. To get this data as output, either call avresample_convert() with
  303. * NULL input or call avresample_read().
  304. *
  305. * @see avresample_available()
  306. * @see avresample_read()
  307. * @see avresample_get_delay()
  308. *
  309. * @param avr audio resample context
  310. * @param output output data pointers
  311. * @param out_plane_size output plane size, in bytes.
  312. * This can be 0 if unknown, but that will lead to
  313. * optimized functions not being used directly on the
  314. * output, which could slow down some conversions.
  315. * @param out_samples maximum number of samples that the output buffer can hold
  316. * @param input input data pointers
  317. * @param in_plane_size input plane size, in bytes
  318. * This can be 0 if unknown, but that will lead to
  319. * optimized functions not being used directly on the
  320. * input, which could slow down some conversions.
  321. * @param in_samples number of input samples to convert
  322. * @return number of samples written to the output buffer,
  323. * not including converted samples added to the internal
  324. * output FIFO
  325. */
  326. int avresample_convert(AVAudioResampleContext *avr, uint8_t **output,
  327. int out_plane_size, int out_samples, uint8_t **input,
  328. int in_plane_size, int in_samples);
  329. /**
  330. * Return the number of samples currently in the resampling delay buffer.
  331. *
  332. * When resampling, there may be a delay between the input and output. Any
  333. * unconverted samples in each call are stored internally in a delay buffer.
  334. * This function allows the user to determine the current number of samples in
  335. * the delay buffer, which can be useful for synchronization.
  336. *
  337. * @see avresample_convert()
  338. *
  339. * @param avr audio resample context
  340. * @return number of samples currently in the resampling delay buffer
  341. */
  342. int avresample_get_delay(AVAudioResampleContext *avr);
  343. /**
  344. * Return the number of available samples in the output FIFO.
  345. *
  346. * During conversion, if the user does not specify an output buffer or
  347. * specifies an output buffer that is smaller than what is needed, remaining
  348. * samples that are not written to the output are stored to an internal FIFO
  349. * buffer. The samples in the FIFO can be read with avresample_read() or
  350. * avresample_convert().
  351. *
  352. * @see avresample_read()
  353. * @see avresample_convert()
  354. *
  355. * @param avr audio resample context
  356. * @return number of samples available for reading
  357. */
  358. int avresample_available(AVAudioResampleContext *avr);
  359. /**
  360. * Read samples from the output FIFO.
  361. *
  362. * During conversion, if the user does not specify an output buffer or
  363. * specifies an output buffer that is smaller than what is needed, remaining
  364. * samples that are not written to the output are stored to an internal FIFO
  365. * buffer. This function can be used to read samples from that internal FIFO.
  366. *
  367. * @see avresample_available()
  368. * @see avresample_convert()
  369. *
  370. * @param avr audio resample context
  371. * @param output output data pointers. May be NULL, in which case
  372. * nb_samples of data is discarded from output FIFO.
  373. * @param nb_samples number of samples to read from the FIFO
  374. * @return the number of samples written to output
  375. */
  376. int avresample_read(AVAudioResampleContext *avr, uint8_t **output, int nb_samples);
  377. /**
  378. * @}
  379. */
  380. #endif /* AVRESAMPLE_AVRESAMPLE_H */