avresample.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292
  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. * external API header
  25. */
  26. #include "libavutil/audioconvert.h"
  27. #include "libavutil/avutil.h"
  28. #include "libavutil/dict.h"
  29. #include "libavutil/log.h"
  30. #include "libavresample/version.h"
  31. #define AVRESAMPLE_MAX_CHANNELS 32
  32. typedef struct AVAudioResampleContext AVAudioResampleContext;
  33. /** Mixing Coefficient Types */
  34. enum AVMixCoeffType {
  35. AV_MIX_COEFF_TYPE_Q8, /** 16-bit 8.8 fixed-point */
  36. AV_MIX_COEFF_TYPE_Q15, /** 32-bit 17.15 fixed-point */
  37. AV_MIX_COEFF_TYPE_FLT, /** floating-point */
  38. AV_MIX_COEFF_TYPE_NB, /** Number of coeff types. Not part of ABI */
  39. };
  40. /** Resampling Filter Types */
  41. enum AVResampleFilterType {
  42. AV_RESAMPLE_FILTER_TYPE_CUBIC, /**< Cubic */
  43. AV_RESAMPLE_FILTER_TYPE_BLACKMAN_NUTTALL, /**< Blackman Nuttall Windowed Sinc */
  44. AV_RESAMPLE_FILTER_TYPE_KAISER, /**< Kaiser Windowed Sinc */
  45. };
  46. /**
  47. * Return the LIBAVRESAMPLE_VERSION_INT constant.
  48. */
  49. unsigned avresample_version(void);
  50. /**
  51. * Return the libavresample build-time configuration.
  52. * @return configure string
  53. */
  54. const char *avresample_configuration(void);
  55. /**
  56. * Return the libavresample license.
  57. */
  58. const char *avresample_license(void);
  59. /**
  60. * Get the AVClass for AVAudioResampleContext.
  61. *
  62. * Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options
  63. * without allocating a context.
  64. *
  65. * @see av_opt_find().
  66. *
  67. * @return AVClass for AVAudioResampleContext
  68. */
  69. const AVClass *avresample_get_class(void);
  70. /**
  71. * Allocate AVAudioResampleContext and set options.
  72. *
  73. * @return allocated audio resample context, or NULL on failure
  74. */
  75. AVAudioResampleContext *avresample_alloc_context(void);
  76. /**
  77. * Initialize AVAudioResampleContext.
  78. *
  79. * @param avr audio resample context
  80. * @return 0 on success, negative AVERROR code on failure
  81. */
  82. int avresample_open(AVAudioResampleContext *avr);
  83. /**
  84. * Close AVAudioResampleContext.
  85. *
  86. * This closes the context, but it does not change the parameters. The context
  87. * can be reopened with avresample_open(). It does, however, clear the output
  88. * FIFO and any remaining leftover samples in the resampling delay buffer. If
  89. * there was a custom matrix being used, that is also cleared.
  90. *
  91. * @see avresample_convert()
  92. * @see avresample_set_matrix()
  93. *
  94. * @param avr audio resample context
  95. */
  96. void avresample_close(AVAudioResampleContext *avr);
  97. /**
  98. * Free AVAudioResampleContext and associated AVOption values.
  99. *
  100. * This also calls avresample_close() before freeing.
  101. *
  102. * @param avr audio resample context
  103. */
  104. void avresample_free(AVAudioResampleContext **avr);
  105. /**
  106. * Generate a channel mixing matrix.
  107. *
  108. * This function is the one used internally by libavresample for building the
  109. * default mixing matrix. It is made public just as a utility function for
  110. * building custom matrices.
  111. *
  112. * @param in_layout input channel layout
  113. * @param out_layout output channel layout
  114. * @param center_mix_level mix level for the center channel
  115. * @param surround_mix_level mix level for the surround channel(s)
  116. * @param lfe_mix_level mix level for the low-frequency effects channel
  117. * @param normalize if 1, coefficients will be normalized to prevent
  118. * overflow. if 0, coefficients will not be
  119. * normalized.
  120. * @param[out] matrix mixing coefficients; matrix[i + stride * o] is
  121. * the weight of input channel i in output channel o.
  122. * @param stride distance between adjacent input channels in the
  123. * matrix array
  124. * @param matrix_encoding matrixed stereo downmix mode (e.g. dplii)
  125. * @return 0 on success, negative AVERROR code on failure
  126. */
  127. int avresample_build_matrix(uint64_t in_layout, uint64_t out_layout,
  128. double center_mix_level, double surround_mix_level,
  129. double lfe_mix_level, int normalize, double *matrix,
  130. int stride, enum AVMatrixEncoding matrix_encoding);
  131. /**
  132. * Get the current channel mixing matrix.
  133. *
  134. * @param avr audio resample context
  135. * @param matrix mixing coefficients; matrix[i + stride * o] is the weight of
  136. * input channel i in output channel o.
  137. * @param stride distance between adjacent input channels in the matrix array
  138. * @return 0 on success, negative AVERROR code on failure
  139. */
  140. int avresample_get_matrix(AVAudioResampleContext *avr, double *matrix,
  141. int stride);
  142. /**
  143. * Set channel mixing matrix.
  144. *
  145. * Allows for setting a custom mixing matrix, overriding the default matrix
  146. * generated internally during avresample_open(). This function can be called
  147. * anytime on an allocated context, either before or after calling
  148. * avresample_open(). avresample_convert() always uses the current matrix.
  149. * Calling avresample_close() on the context will clear the current matrix.
  150. *
  151. * @see avresample_close()
  152. *
  153. * @param avr audio resample context
  154. * @param matrix mixing coefficients; matrix[i + stride * o] is the weight of
  155. * input channel i in output channel o.
  156. * @param stride distance between adjacent input channels in the matrix array
  157. * @return 0 on success, negative AVERROR code on failure
  158. */
  159. int avresample_set_matrix(AVAudioResampleContext *avr, const double *matrix,
  160. int stride);
  161. /**
  162. * Set compensation for resampling.
  163. *
  164. * This can be called anytime after avresample_open(). If resampling was not
  165. * being done previously, the AVAudioResampleContext is closed and reopened
  166. * with resampling enabled. In this case, any samples remaining in the output
  167. * FIFO and the current channel mixing matrix will be restored after reopening
  168. * the context.
  169. *
  170. * @param avr audio resample context
  171. * @param sample_delta compensation delta, in samples
  172. * @param compensation_distance compensation distance, in samples
  173. * @return 0 on success, negative AVERROR code on failure
  174. */
  175. int avresample_set_compensation(AVAudioResampleContext *avr, int sample_delta,
  176. int compensation_distance);
  177. /**
  178. * Convert input samples and write them to the output FIFO.
  179. *
  180. * The output data can be NULL or have fewer allocated samples than required.
  181. * In this case, any remaining samples not written to the output will be added
  182. * to an internal FIFO buffer, to be returned at the next call to this function
  183. * or to avresample_read().
  184. *
  185. * If converting sample rate, there may be data remaining in the internal
  186. * resampling delay buffer. avresample_get_delay() tells the number of remaining
  187. * samples. To get this data as output, call avresample_convert() with NULL
  188. * input.
  189. *
  190. * At the end of the conversion process, there may be data remaining in the
  191. * internal FIFO buffer. avresample_available() tells the number of remaining
  192. * samples. To get this data as output, either call avresample_convert() with
  193. * NULL input or call avresample_read().
  194. *
  195. * @see avresample_available()
  196. * @see avresample_read()
  197. * @see avresample_get_delay()
  198. *
  199. * @param avr audio resample context
  200. * @param output output data pointers
  201. * @param out_plane_size output plane size, in bytes.
  202. * This can be 0 if unknown, but that will lead to
  203. * optimized functions not being used directly on the
  204. * output, which could slow down some conversions.
  205. * @param out_samples maximum number of samples that the output buffer can hold
  206. * @param input input data pointers
  207. * @param in_plane_size input plane size, in bytes
  208. * This can be 0 if unknown, but that will lead to
  209. * optimized functions not being used directly on the
  210. * input, which could slow down some conversions.
  211. * @param in_samples number of input samples to convert
  212. * @return number of samples written to the output buffer,
  213. * not including converted samples added to the internal
  214. * output FIFO
  215. */
  216. int avresample_convert(AVAudioResampleContext *avr, void **output,
  217. int out_plane_size, int out_samples, void **input,
  218. int in_plane_size, int in_samples);
  219. /**
  220. * Return the number of samples currently in the resampling delay buffer.
  221. *
  222. * When resampling, there may be a delay between the input and output. Any
  223. * unconverted samples in each call are stored internally in a delay buffer.
  224. * This function allows the user to determine the current number of samples in
  225. * the delay buffer, which can be useful for synchronization.
  226. *
  227. * @see avresample_convert()
  228. *
  229. * @param avr audio resample context
  230. * @return number of samples currently in the resampling delay buffer
  231. */
  232. int avresample_get_delay(AVAudioResampleContext *avr);
  233. /**
  234. * Return the number of available samples in the output FIFO.
  235. *
  236. * During conversion, if the user does not specify an output buffer or
  237. * specifies an output buffer that is smaller than what is needed, remaining
  238. * samples that are not written to the output are stored to an internal FIFO
  239. * buffer. The samples in the FIFO can be read with avresample_read() or
  240. * avresample_convert().
  241. *
  242. * @see avresample_read()
  243. * @see avresample_convert()
  244. *
  245. * @param avr audio resample context
  246. * @return number of samples available for reading
  247. */
  248. int avresample_available(AVAudioResampleContext *avr);
  249. /**
  250. * Read samples from the output FIFO.
  251. *
  252. * During conversion, if the user does not specify an output buffer or
  253. * specifies an output buffer that is smaller than what is needed, remaining
  254. * samples that are not written to the output are stored to an internal FIFO
  255. * buffer. This function can be used to read samples from that internal FIFO.
  256. *
  257. * @see avresample_available()
  258. * @see avresample_convert()
  259. *
  260. * @param avr audio resample context
  261. * @param output output data pointers. May be NULL, in which case
  262. * nb_samples of data is discarded from output FIFO.
  263. * @param nb_samples number of samples to read from the FIFO
  264. * @return the number of samples written to output
  265. */
  266. int avresample_read(AVAudioResampleContext *avr, void **output, int nb_samples);
  267. #endif /* AVRESAMPLE_AVRESAMPLE_H */