avresample.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503
  1. /*
  2. * Copyright (c) 2012 Justin Ruggles <justin.ruggles@gmail.com>
  3. *
  4. * This file is part of FFmpeg.
  5. *
  6. * FFmpeg 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. * FFmpeg 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 FFmpeg; 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_get_out_samples(avr, in_samples);
  77. *
  78. * av_samples_alloc(&output, &out_linesize, 2, out_samples,
  79. * AV_SAMPLE_FMT_S16, 0);
  80. * out_samples = avresample_convert(avr, &output, out_linesize, out_samples,
  81. * input, in_linesize, in_samples);
  82. * handle_output(output, out_linesize, out_samples);
  83. * av_freep(&output);
  84. * }
  85. * @endcode
  86. *
  87. * When the conversion is finished and the FIFOs are flushed if required, the
  88. * conversion context and everything associated with it must be freed with
  89. * avresample_free().
  90. */
  91. #include "libavutil/avutil.h"
  92. #include "libavutil/channel_layout.h"
  93. #include "libavutil/dict.h"
  94. #include "libavutil/frame.h"
  95. #include "libavutil/log.h"
  96. #include "libavutil/mathematics.h"
  97. #include "libavresample/version.h"
  98. #define AVRESAMPLE_MAX_CHANNELS 32
  99. typedef struct AVAudioResampleContext AVAudioResampleContext;
  100. /** Mixing Coefficient Types */
  101. enum AVMixCoeffType {
  102. AV_MIX_COEFF_TYPE_Q8, /** 16-bit 8.8 fixed-point */
  103. AV_MIX_COEFF_TYPE_Q15, /** 32-bit 17.15 fixed-point */
  104. AV_MIX_COEFF_TYPE_FLT, /** floating-point */
  105. AV_MIX_COEFF_TYPE_NB, /** Number of coeff types. Not part of ABI */
  106. };
  107. /** Resampling Filter Types */
  108. enum AVResampleFilterType {
  109. AV_RESAMPLE_FILTER_TYPE_CUBIC, /**< Cubic */
  110. AV_RESAMPLE_FILTER_TYPE_BLACKMAN_NUTTALL, /**< Blackman Nuttall Windowed Sinc */
  111. AV_RESAMPLE_FILTER_TYPE_KAISER, /**< Kaiser Windowed Sinc */
  112. };
  113. enum AVResampleDitherMethod {
  114. AV_RESAMPLE_DITHER_NONE, /**< Do not use dithering */
  115. AV_RESAMPLE_DITHER_RECTANGULAR, /**< Rectangular Dither */
  116. AV_RESAMPLE_DITHER_TRIANGULAR, /**< Triangular Dither*/
  117. AV_RESAMPLE_DITHER_TRIANGULAR_HP, /**< Triangular Dither with High Pass */
  118. AV_RESAMPLE_DITHER_TRIANGULAR_NS, /**< Triangular Dither with Noise Shaping */
  119. AV_RESAMPLE_DITHER_NB, /**< Number of dither types. Not part of ABI. */
  120. };
  121. /**
  122. * Return the LIBAVRESAMPLE_VERSION_INT constant.
  123. */
  124. unsigned avresample_version(void);
  125. /**
  126. * Return the libavresample build-time configuration.
  127. * @return configure string
  128. */
  129. const char *avresample_configuration(void);
  130. /**
  131. * Return the libavresample license.
  132. */
  133. const char *avresample_license(void);
  134. /**
  135. * Get the AVClass for AVAudioResampleContext.
  136. *
  137. * Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options
  138. * without allocating a context.
  139. *
  140. * @see av_opt_find().
  141. *
  142. * @return AVClass for AVAudioResampleContext
  143. */
  144. const AVClass *avresample_get_class(void);
  145. /**
  146. * Allocate AVAudioResampleContext and set options.
  147. *
  148. * @return allocated audio resample context, or NULL on failure
  149. */
  150. AVAudioResampleContext *avresample_alloc_context(void);
  151. /**
  152. * Initialize AVAudioResampleContext.
  153. * @note The context must be configured using the AVOption API.
  154. * @note The fields "in_channel_layout", "out_channel_layout",
  155. * "in_sample_rate", "out_sample_rate", "in_sample_fmt",
  156. * "out_sample_fmt" must be set.
  157. *
  158. * @see av_opt_set_int()
  159. * @see av_opt_set_dict()
  160. * @see av_get_default_channel_layout()
  161. *
  162. * @param avr audio resample context
  163. * @return 0 on success, negative AVERROR code on failure
  164. */
  165. int avresample_open(AVAudioResampleContext *avr);
  166. /**
  167. * Check whether an AVAudioResampleContext is open or closed.
  168. *
  169. * @param avr AVAudioResampleContext to check
  170. * @return 1 if avr is open, 0 if avr is closed.
  171. */
  172. int avresample_is_open(AVAudioResampleContext *avr);
  173. /**
  174. * Close AVAudioResampleContext.
  175. *
  176. * This closes the context, but it does not change the parameters. The context
  177. * can be reopened with avresample_open(). It does, however, clear the output
  178. * FIFO and any remaining leftover samples in the resampling delay buffer. If
  179. * there was a custom matrix being used, that is also cleared.
  180. *
  181. * @see avresample_convert()
  182. * @see avresample_set_matrix()
  183. *
  184. * @param avr audio resample context
  185. */
  186. void avresample_close(AVAudioResampleContext *avr);
  187. /**
  188. * Free AVAudioResampleContext and associated AVOption values.
  189. *
  190. * This also calls avresample_close() before freeing.
  191. *
  192. * @param avr audio resample context
  193. */
  194. void avresample_free(AVAudioResampleContext **avr);
  195. /**
  196. * Generate a channel mixing matrix.
  197. *
  198. * This function is the one used internally by libavresample for building the
  199. * default mixing matrix. It is made public just as a utility function for
  200. * building custom matrices.
  201. *
  202. * @param in_layout input channel layout
  203. * @param out_layout output channel layout
  204. * @param center_mix_level mix level for the center channel
  205. * @param surround_mix_level mix level for the surround channel(s)
  206. * @param lfe_mix_level mix level for the low-frequency effects channel
  207. * @param normalize if 1, coefficients will be normalized to prevent
  208. * overflow. if 0, coefficients will not be
  209. * normalized.
  210. * @param[out] matrix mixing coefficients; matrix[i + stride * o] is
  211. * the weight of input channel i in output channel o.
  212. * @param stride distance between adjacent input channels in the
  213. * matrix array
  214. * @param matrix_encoding matrixed stereo downmix mode (e.g. dplii)
  215. * @return 0 on success, negative AVERROR code on failure
  216. */
  217. int avresample_build_matrix(uint64_t in_layout, uint64_t out_layout,
  218. double center_mix_level, double surround_mix_level,
  219. double lfe_mix_level, int normalize, double *matrix,
  220. int stride, enum AVMatrixEncoding matrix_encoding);
  221. /**
  222. * Get the current channel mixing matrix.
  223. *
  224. * If no custom matrix has been previously set or the AVAudioResampleContext is
  225. * not open, an error is returned.
  226. *
  227. * @param avr audio resample context
  228. * @param matrix mixing coefficients; matrix[i + stride * o] is the weight of
  229. * input channel i in output channel o.
  230. * @param stride distance between adjacent input channels in the matrix array
  231. * @return 0 on success, negative AVERROR code on failure
  232. */
  233. int avresample_get_matrix(AVAudioResampleContext *avr, double *matrix,
  234. int stride);
  235. /**
  236. * Set channel mixing matrix.
  237. *
  238. * Allows for setting a custom mixing matrix, overriding the default matrix
  239. * generated internally during avresample_open(). This function can be called
  240. * anytime on an allocated context, either before or after calling
  241. * avresample_open(), as long as the channel layouts have been set.
  242. * avresample_convert() always uses the current matrix.
  243. * Calling avresample_close() on the context will clear the current matrix.
  244. *
  245. * @see avresample_close()
  246. *
  247. * @param avr audio resample context
  248. * @param matrix mixing coefficients; matrix[i + stride * o] is the weight of
  249. * input channel i in output channel o.
  250. * @param stride distance between adjacent input channels in the matrix array
  251. * @return 0 on success, negative AVERROR code on failure
  252. */
  253. int avresample_set_matrix(AVAudioResampleContext *avr, const double *matrix,
  254. int stride);
  255. /**
  256. * Set a customized input channel mapping.
  257. *
  258. * This function can only be called when the allocated context is not open.
  259. * Also, the input channel layout must have already been set.
  260. *
  261. * Calling avresample_close() on the context will clear the channel mapping.
  262. *
  263. * The map for each input channel specifies the channel index in the source to
  264. * use for that particular channel, or -1 to mute the channel. Source channels
  265. * can be duplicated by using the same index for multiple input channels.
  266. *
  267. * Examples:
  268. *
  269. * Reordering 5.1 AAC order (C,L,R,Ls,Rs,LFE) to FFmpeg order (L,R,C,LFE,Ls,Rs):
  270. * { 1, 2, 0, 5, 3, 4 }
  271. *
  272. * Muting the 3rd channel in 4-channel input:
  273. * { 0, 1, -1, 3 }
  274. *
  275. * Duplicating the left channel of stereo input:
  276. * { 0, 0 }
  277. *
  278. * @param avr audio resample context
  279. * @param channel_map customized input channel mapping
  280. * @return 0 on success, negative AVERROR code on failure
  281. */
  282. int avresample_set_channel_mapping(AVAudioResampleContext *avr,
  283. const int *channel_map);
  284. /**
  285. * Set compensation for resampling.
  286. *
  287. * This can be called anytime after avresample_open(). If resampling is not
  288. * automatically enabled because of a sample rate conversion, the
  289. * "force_resampling" option must have been set to 1 when opening the context
  290. * in order to use resampling compensation.
  291. *
  292. * @param avr audio resample context
  293. * @param sample_delta compensation delta, in samples
  294. * @param compensation_distance compensation distance, in samples
  295. * @return 0 on success, negative AVERROR code on failure
  296. */
  297. int avresample_set_compensation(AVAudioResampleContext *avr, int sample_delta,
  298. int compensation_distance);
  299. /**
  300. * Provide the upper bound on the number of samples the configured
  301. * conversion would output.
  302. *
  303. * @param avr audio resample context
  304. * @param in_nb_samples number of input samples
  305. *
  306. * @return number of samples or AVERROR(EINVAL) if the value
  307. * would exceed INT_MAX
  308. */
  309. int avresample_get_out_samples(AVAudioResampleContext *avr, int in_nb_samples);
  310. /**
  311. * Convert input samples and write them to the output FIFO.
  312. *
  313. * The upper bound on the number of output samples can be obtained through
  314. * avresample_get_out_samples().
  315. *
  316. * The output data can be NULL or have fewer allocated samples than required.
  317. * In this case, any remaining samples not written to the output will be added
  318. * to an internal FIFO buffer, to be returned at the next call to this function
  319. * or to avresample_read().
  320. *
  321. * If converting sample rate, there may be data remaining in the internal
  322. * resampling delay buffer. avresample_get_delay() tells the number of remaining
  323. * samples. To get this data as output, call avresample_convert() with NULL
  324. * input.
  325. *
  326. * At the end of the conversion process, there may be data remaining in the
  327. * internal FIFO buffer. avresample_available() tells the number of remaining
  328. * samples. To get this data as output, either call avresample_convert() with
  329. * NULL input or call avresample_read().
  330. *
  331. * @see avresample_get_out_samples()
  332. * @see avresample_read()
  333. * @see avresample_get_delay()
  334. *
  335. * @param avr audio resample context
  336. * @param output output data pointers
  337. * @param out_plane_size output plane size, in bytes.
  338. * This can be 0 if unknown, but that will lead to
  339. * optimized functions not being used directly on the
  340. * output, which could slow down some conversions.
  341. * @param out_samples maximum number of samples that the output buffer can hold
  342. * @param input input data pointers
  343. * @param in_plane_size input plane size, in bytes
  344. * This can be 0 if unknown, but that will lead to
  345. * optimized functions not being used directly on the
  346. * input, which could slow down some conversions.
  347. * @param in_samples number of input samples to convert
  348. * @return number of samples written to the output buffer,
  349. * not including converted samples added to the internal
  350. * output FIFO
  351. */
  352. int avresample_convert(AVAudioResampleContext *avr, uint8_t **output,
  353. int out_plane_size, int out_samples,
  354. uint8_t * const *input, int in_plane_size,
  355. int in_samples);
  356. /**
  357. * Return the number of samples currently in the resampling delay buffer.
  358. *
  359. * When resampling, there may be a delay between the input and output. Any
  360. * unconverted samples in each call are stored internally in a delay buffer.
  361. * This function allows the user to determine the current number of samples in
  362. * the delay buffer, which can be useful for synchronization.
  363. *
  364. * @see avresample_convert()
  365. *
  366. * @param avr audio resample context
  367. * @return number of samples currently in the resampling delay buffer
  368. */
  369. int avresample_get_delay(AVAudioResampleContext *avr);
  370. /**
  371. * Return the number of available samples in the output FIFO.
  372. *
  373. * During conversion, if the user does not specify an output buffer or
  374. * specifies an output buffer that is smaller than what is needed, remaining
  375. * samples that are not written to the output are stored to an internal FIFO
  376. * buffer. The samples in the FIFO can be read with avresample_read() or
  377. * avresample_convert().
  378. *
  379. * @see avresample_read()
  380. * @see avresample_convert()
  381. *
  382. * @param avr audio resample context
  383. * @return number of samples available for reading
  384. */
  385. int avresample_available(AVAudioResampleContext *avr);
  386. /**
  387. * Read samples from the output FIFO.
  388. *
  389. * During conversion, if the user does not specify an output buffer or
  390. * specifies an output buffer that is smaller than what is needed, remaining
  391. * samples that are not written to the output are stored to an internal FIFO
  392. * buffer. This function can be used to read samples from that internal FIFO.
  393. *
  394. * @see avresample_available()
  395. * @see avresample_convert()
  396. *
  397. * @param avr audio resample context
  398. * @param output output data pointers. May be NULL, in which case
  399. * nb_samples of data is discarded from output FIFO.
  400. * @param nb_samples number of samples to read from the FIFO
  401. * @return the number of samples written to output
  402. */
  403. int avresample_read(AVAudioResampleContext *avr, uint8_t **output, int nb_samples);
  404. /**
  405. * Convert the samples in the input AVFrame and write them to the output AVFrame.
  406. *
  407. * Input and output AVFrames must have channel_layout, sample_rate and format set.
  408. *
  409. * The upper bound on the number of output samples is obtained through
  410. * avresample_get_out_samples().
  411. *
  412. * If the output AVFrame does not have the data pointers allocated the nb_samples
  413. * field will be set using avresample_get_out_samples() and av_frame_get_buffer()
  414. * is called to allocate the frame.
  415. *
  416. * The output AVFrame can be NULL or have fewer allocated samples than required.
  417. * In this case, any remaining samples not written to the output will be added
  418. * to an internal FIFO buffer, to be returned at the next call to this function
  419. * or to avresample_convert() or to avresample_read().
  420. *
  421. * If converting sample rate, there may be data remaining in the internal
  422. * resampling delay buffer. avresample_get_delay() tells the number of
  423. * remaining samples. To get this data as output, call this function or
  424. * avresample_convert() with NULL input.
  425. *
  426. * At the end of the conversion process, there may be data remaining in the
  427. * internal FIFO buffer. avresample_available() tells the number of remaining
  428. * samples. To get this data as output, either call this function or
  429. * avresample_convert() with NULL input or call avresample_read().
  430. *
  431. * If the AVAudioResampleContext configuration does not match the output and
  432. * input AVFrame settings the conversion does not take place and depending on
  433. * which AVFrame is not matching AVERROR_OUTPUT_CHANGED, AVERROR_INPUT_CHANGED
  434. * or AVERROR_OUTPUT_CHANGED|AVERROR_INPUT_CHANGED is returned.
  435. *
  436. * @see avresample_get_out_samples()
  437. * @see avresample_available()
  438. * @see avresample_convert()
  439. * @see avresample_read()
  440. * @see avresample_get_delay()
  441. *
  442. * @param avr audio resample context
  443. * @param output output AVFrame
  444. * @param input input AVFrame
  445. * @return 0 on success, AVERROR on failure or nonmatching
  446. * configuration.
  447. */
  448. int avresample_convert_frame(AVAudioResampleContext *avr,
  449. AVFrame *output, AVFrame *input);
  450. /**
  451. * Configure or reconfigure the AVAudioResampleContext using the information
  452. * provided by the AVFrames.
  453. *
  454. * The original resampling context is reset even on failure.
  455. * The function calls avresample_close() internally if the context is open.
  456. *
  457. * @see avresample_open();
  458. * @see avresample_close();
  459. *
  460. * @param avr audio resample context
  461. * @param output output AVFrame
  462. * @param input input AVFrame
  463. * @return 0 on success, AVERROR on failure.
  464. */
  465. int avresample_config(AVAudioResampleContext *avr, AVFrame *out, AVFrame *in);
  466. /**
  467. * @}
  468. */
  469. #endif /* AVRESAMPLE_AVRESAMPLE_H */