You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

596 lines
21KB

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