swresample.h 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650
  1. /*
  2. * Copyright (C) 2011-2013 Michael Niedermayer (michaelni@gmx.at)
  3. *
  4. * This file is part of libswresample
  5. *
  6. * libswresample 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. * libswresample 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 libswresample; if not, write to the Free Software
  18. * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19. */
  20. #ifndef SWRESAMPLE_SWRESAMPLE_H
  21. #define SWRESAMPLE_SWRESAMPLE_H
  22. /**
  23. * @file
  24. * @ingroup lswr
  25. * libswresample public header
  26. */
  27. /**
  28. * @defgroup lswr libswresample
  29. * @{
  30. *
  31. * Audio resampling, sample format conversion and mixing library.
  32. *
  33. * Interaction with lswr is done through SwrContext, which is
  34. * allocated with swr_alloc() or swr_alloc_set_opts2(). It is opaque, so all parameters
  35. * must be set with the @ref avoptions API.
  36. *
  37. * The first thing you will need to do in order to use lswr is to allocate
  38. * SwrContext. This can be done with swr_alloc() or swr_alloc_set_opts2(). If you
  39. * are using the former, you must set options through the @ref avoptions API.
  40. * The latter function provides the same feature, but it allows you to set some
  41. * common options in the same statement.
  42. *
  43. * For example the following code will setup conversion from planar float sample
  44. * format to interleaved signed 16-bit integer, downsampling from 48kHz to
  45. * 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing
  46. * matrix). This is using the swr_alloc() function.
  47. * @code
  48. * SwrContext *swr = swr_alloc();
  49. * av_opt_set_channel_layout(swr, "in_channel_layout", AV_CH_LAYOUT_5POINT1, 0);
  50. * av_opt_set_channel_layout(swr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0);
  51. * av_opt_set_int(swr, "in_sample_rate", 48000, 0);
  52. * av_opt_set_int(swr, "out_sample_rate", 44100, 0);
  53. * av_opt_set_sample_fmt(swr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0);
  54. * av_opt_set_sample_fmt(swr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0);
  55. * @endcode
  56. *
  57. * The same job can be done using swr_alloc_set_opts2() as well:
  58. * @code
  59. * SwrContext *swr = NULL;
  60. * int ret = swr_alloc_set_opts2(&swr, // we're allocating a new context
  61. * &(AVChannelLayout)AV_CHANNEL_LAYOUT_STEREO, // out_ch_layout
  62. * AV_SAMPLE_FMT_S16, // out_sample_fmt
  63. * 44100, // out_sample_rate
  64. * &(AVChannelLayout)AV_CHANNEL_LAYOUT_5POINT1, // in_ch_layout
  65. * AV_SAMPLE_FMT_FLTP, // in_sample_fmt
  66. * 48000, // in_sample_rate
  67. * 0, // log_offset
  68. * NULL); // log_ctx
  69. * @endcode
  70. *
  71. * Once all values have been set, it must be initialized with swr_init(). If
  72. * you need to change the conversion parameters, you can change the parameters
  73. * using @ref AVOptions, as described above in the first example; or by using
  74. * swr_alloc_set_opts2(), but with the first argument the allocated context.
  75. * You must then call swr_init() again.
  76. *
  77. * The conversion itself is done by repeatedly calling swr_convert().
  78. * Note that the samples may get buffered in swr if you provide insufficient
  79. * output space or if sample rate conversion is done, which requires "future"
  80. * samples. Samples that do not require future input can be retrieved at any
  81. * time by using swr_convert() (in_count can be set to 0).
  82. * At the end of conversion the resampling buffer can be flushed by calling
  83. * swr_convert() with NULL in and 0 in_count.
  84. *
  85. * The samples used in the conversion process can be managed with the libavutil
  86. * @ref lavu_sampmanip "samples manipulation" API, including av_samples_alloc()
  87. * function used in the following example.
  88. *
  89. * The delay between input and output, can at any time be found by using
  90. * swr_get_delay().
  91. *
  92. * The following code demonstrates the conversion loop assuming the parameters
  93. * from above and caller-defined functions get_input() and handle_output():
  94. * @code
  95. * uint8_t **input;
  96. * int in_samples;
  97. *
  98. * while (get_input(&input, &in_samples)) {
  99. * uint8_t *output;
  100. * int out_samples = av_rescale_rnd(swr_get_delay(swr, 48000) +
  101. * in_samples, 44100, 48000, AV_ROUND_UP);
  102. * av_samples_alloc(&output, NULL, 2, out_samples,
  103. * AV_SAMPLE_FMT_S16, 0);
  104. * out_samples = swr_convert(swr, &output, out_samples,
  105. * input, in_samples);
  106. * handle_output(output, out_samples);
  107. * av_freep(&output);
  108. * }
  109. * @endcode
  110. *
  111. * When the conversion is finished, the conversion
  112. * context and everything associated with it must be freed with swr_free().
  113. * A swr_close() function is also available, but it exists mainly for
  114. * compatibility with libavresample, and is not required to be called.
  115. *
  116. * There will be no memory leak if the data is not completely flushed before
  117. * swr_free().
  118. */
  119. #include <stdint.h>
  120. #include "libavutil/channel_layout.h"
  121. #include "libavutil/frame.h"
  122. #include "libavutil/samplefmt.h"
  123. #include "libswresample/version_major.h"
  124. #ifndef HAVE_AV_CONFIG_H
  125. /* When included as part of the ffmpeg build, only include the major version
  126. * to avoid unnecessary rebuilds. When included externally, keep including
  127. * the full version information. */
  128. #include "libswresample/version.h"
  129. #endif
  130. /**
  131. * @name Option constants
  132. * These constants are used for the @ref avoptions interface for lswr.
  133. * @{
  134. *
  135. */
  136. #define SWR_FLAG_RESAMPLE 1 ///< Force resampling even if equal sample rate
  137. //TODO use int resample ?
  138. //long term TODO can we enable this dynamically?
  139. /** Dithering algorithms */
  140. enum SwrDitherType {
  141. SWR_DITHER_NONE = 0,
  142. SWR_DITHER_RECTANGULAR,
  143. SWR_DITHER_TRIANGULAR,
  144. SWR_DITHER_TRIANGULAR_HIGHPASS,
  145. SWR_DITHER_NS = 64, ///< not part of API/ABI
  146. SWR_DITHER_NS_LIPSHITZ,
  147. SWR_DITHER_NS_F_WEIGHTED,
  148. SWR_DITHER_NS_MODIFIED_E_WEIGHTED,
  149. SWR_DITHER_NS_IMPROVED_E_WEIGHTED,
  150. SWR_DITHER_NS_SHIBATA,
  151. SWR_DITHER_NS_LOW_SHIBATA,
  152. SWR_DITHER_NS_HIGH_SHIBATA,
  153. SWR_DITHER_NB, ///< not part of API/ABI
  154. };
  155. /** Resampling Engines */
  156. enum SwrEngine {
  157. SWR_ENGINE_SWR, /**< SW Resampler */
  158. SWR_ENGINE_SOXR, /**< SoX Resampler */
  159. SWR_ENGINE_NB, ///< not part of API/ABI
  160. };
  161. /** Resampling Filter Types */
  162. enum SwrFilterType {
  163. SWR_FILTER_TYPE_CUBIC, /**< Cubic */
  164. SWR_FILTER_TYPE_BLACKMAN_NUTTALL, /**< Blackman Nuttall windowed sinc */
  165. SWR_FILTER_TYPE_KAISER, /**< Kaiser windowed sinc */
  166. };
  167. /**
  168. * @}
  169. */
  170. /**
  171. * The libswresample context. Unlike libavcodec and libavformat, this structure
  172. * is opaque. This means that if you would like to set options, you must use
  173. * the @ref avoptions API and cannot directly set values to members of the
  174. * structure.
  175. */
  176. typedef struct SwrContext SwrContext;
  177. /**
  178. * Get the AVClass for SwrContext. It can be used in combination with
  179. * AV_OPT_SEARCH_FAKE_OBJ for examining options.
  180. *
  181. * @see av_opt_find().
  182. * @return the AVClass of SwrContext
  183. */
  184. const AVClass *swr_get_class(void);
  185. /**
  186. * @name SwrContext constructor functions
  187. * @{
  188. */
  189. /**
  190. * Allocate SwrContext.
  191. *
  192. * If you use this function you will need to set the parameters (manually or
  193. * with swr_alloc_set_opts2()) before calling swr_init().
  194. *
  195. * @see swr_alloc_set_opts2(), swr_init(), swr_free()
  196. * @return NULL on error, allocated context otherwise
  197. */
  198. struct SwrContext *swr_alloc(void);
  199. /**
  200. * Initialize context after user parameters have been set.
  201. * @note The context must be configured using the AVOption API.
  202. *
  203. * @see av_opt_set_int()
  204. * @see av_opt_set_dict()
  205. *
  206. * @param[in,out] s Swr context to initialize
  207. * @return AVERROR error code in case of failure.
  208. */
  209. int swr_init(struct SwrContext *s);
  210. /**
  211. * Check whether an swr context has been initialized or not.
  212. *
  213. * @param[in] s Swr context to check
  214. * @see swr_init()
  215. * @return positive if it has been initialized, 0 if not initialized
  216. */
  217. int swr_is_initialized(struct SwrContext *s);
  218. #if FF_API_OLD_CHANNEL_LAYOUT
  219. /**
  220. * Allocate SwrContext if needed and set/reset common parameters.
  221. *
  222. * This function does not require s to be allocated with swr_alloc(). On the
  223. * other hand, swr_alloc() can use swr_alloc_set_opts() to set the parameters
  224. * on the allocated context.
  225. *
  226. * @param s existing Swr context if available, or NULL if not
  227. * @param out_ch_layout output channel layout (AV_CH_LAYOUT_*)
  228. * @param out_sample_fmt output sample format (AV_SAMPLE_FMT_*).
  229. * @param out_sample_rate output sample rate (frequency in Hz)
  230. * @param in_ch_layout input channel layout (AV_CH_LAYOUT_*)
  231. * @param in_sample_fmt input sample format (AV_SAMPLE_FMT_*).
  232. * @param in_sample_rate input sample rate (frequency in Hz)
  233. * @param log_offset logging level offset
  234. * @param log_ctx parent logging context, can be NULL
  235. *
  236. * @see swr_init(), swr_free()
  237. * @return NULL on error, allocated context otherwise
  238. * @deprecated use @ref swr_alloc_set_opts2()
  239. */
  240. attribute_deprecated
  241. struct SwrContext *swr_alloc_set_opts(struct SwrContext *s,
  242. int64_t out_ch_layout, enum AVSampleFormat out_sample_fmt, int out_sample_rate,
  243. int64_t in_ch_layout, enum AVSampleFormat in_sample_fmt, int in_sample_rate,
  244. int log_offset, void *log_ctx);
  245. #endif
  246. /**
  247. * Allocate SwrContext if needed and set/reset common parameters.
  248. *
  249. * This function does not require *ps to be allocated with swr_alloc(). On the
  250. * other hand, swr_alloc() can use swr_alloc_set_opts2() to set the parameters
  251. * on the allocated context.
  252. *
  253. * @param ps Pointer to an existing Swr context if available, or to NULL if not.
  254. * On success, *ps will be set to the allocated context.
  255. * @param out_ch_layout output channel layout (e.g. AV_CHANNEL_LAYOUT_*)
  256. * @param out_sample_fmt output sample format (AV_SAMPLE_FMT_*).
  257. * @param out_sample_rate output sample rate (frequency in Hz)
  258. * @param in_ch_layout input channel layout (e.g. AV_CHANNEL_LAYOUT_*)
  259. * @param in_sample_fmt input sample format (AV_SAMPLE_FMT_*).
  260. * @param in_sample_rate input sample rate (frequency in Hz)
  261. * @param log_offset logging level offset
  262. * @param log_ctx parent logging context, can be NULL
  263. *
  264. * @see swr_init(), swr_free()
  265. * @return 0 on success, a negative AVERROR code on error.
  266. * On error, the Swr context is freed and *ps set to NULL.
  267. */
  268. int swr_alloc_set_opts2(struct SwrContext **ps,
  269. AVChannelLayout *out_ch_layout, enum AVSampleFormat out_sample_fmt, int out_sample_rate,
  270. AVChannelLayout *in_ch_layout, enum AVSampleFormat in_sample_fmt, int in_sample_rate,
  271. int log_offset, void *log_ctx);
  272. /**
  273. * @}
  274. *
  275. * @name SwrContext destructor functions
  276. * @{
  277. */
  278. /**
  279. * Free the given SwrContext and set the pointer to NULL.
  280. *
  281. * @param[in] s a pointer to a pointer to Swr context
  282. */
  283. void swr_free(struct SwrContext **s);
  284. /**
  285. * Closes the context so that swr_is_initialized() returns 0.
  286. *
  287. * The context can be brought back to life by running swr_init(),
  288. * swr_init() can also be used without swr_close().
  289. * This function is mainly provided for simplifying the usecase
  290. * where one tries to support libavresample and libswresample.
  291. *
  292. * @param[in,out] s Swr context to be closed
  293. */
  294. void swr_close(struct SwrContext *s);
  295. /**
  296. * @}
  297. *
  298. * @name Core conversion functions
  299. * @{
  300. */
  301. /** Convert audio.
  302. *
  303. * in and in_count can be set to 0 to flush the last few samples out at the
  304. * end.
  305. *
  306. * If more input is provided than output space, then the input will be buffered.
  307. * You can avoid this buffering by using swr_get_out_samples() to retrieve an
  308. * upper bound on the required number of output samples for the given number of
  309. * input samples. Conversion will run directly without copying whenever possible.
  310. *
  311. * @param s allocated Swr context, with parameters set
  312. * @param out output buffers, only the first one need be set in case of packed audio
  313. * @param out_count amount of space available for output in samples per channel
  314. * @param in input buffers, only the first one need to be set in case of packed audio
  315. * @param in_count number of input samples available in one channel
  316. *
  317. * @return number of samples output per channel, negative value on error
  318. */
  319. int swr_convert(struct SwrContext *s, uint8_t **out, int out_count,
  320. const uint8_t **in , int in_count);
  321. /**
  322. * Convert the next timestamp from input to output
  323. * timestamps are in 1/(in_sample_rate * out_sample_rate) units.
  324. *
  325. * @note There are 2 slightly differently behaving modes.
  326. * @li When automatic timestamp compensation is not used, (min_compensation >= FLT_MAX)
  327. * in this case timestamps will be passed through with delays compensated
  328. * @li When automatic timestamp compensation is used, (min_compensation < FLT_MAX)
  329. * in this case the output timestamps will match output sample numbers.
  330. * See ffmpeg-resampler(1) for the two modes of compensation.
  331. *
  332. * @param s[in] initialized Swr context
  333. * @param pts[in] timestamp for the next input sample, INT64_MIN if unknown
  334. * @see swr_set_compensation(), swr_drop_output(), and swr_inject_silence() are
  335. * function used internally for timestamp compensation.
  336. * @return the output timestamp for the next output sample
  337. */
  338. int64_t swr_next_pts(struct SwrContext *s, int64_t pts);
  339. /**
  340. * @}
  341. *
  342. * @name Low-level option setting functions
  343. * These functons provide a means to set low-level options that is not possible
  344. * with the AVOption API.
  345. * @{
  346. */
  347. /**
  348. * Activate resampling compensation ("soft" compensation). This function is
  349. * internally called when needed in swr_next_pts().
  350. *
  351. * @param[in,out] s allocated Swr context. If it is not initialized,
  352. * or SWR_FLAG_RESAMPLE is not set, swr_init() is
  353. * called with the flag set.
  354. * @param[in] sample_delta delta in PTS per sample
  355. * @param[in] compensation_distance number of samples to compensate for
  356. * @return >= 0 on success, AVERROR error codes if:
  357. * @li @c s is NULL,
  358. * @li @c compensation_distance is less than 0,
  359. * @li @c compensation_distance is 0 but sample_delta is not,
  360. * @li compensation unsupported by resampler, or
  361. * @li swr_init() fails when called.
  362. */
  363. int swr_set_compensation(struct SwrContext *s, int sample_delta, int compensation_distance);
  364. /**
  365. * Set a customized input channel mapping.
  366. *
  367. * @param[in,out] s allocated Swr context, not yet initialized
  368. * @param[in] channel_map customized input channel mapping (array of channel
  369. * indexes, -1 for a muted channel)
  370. * @return >= 0 on success, or AVERROR error code in case of failure.
  371. */
  372. int swr_set_channel_mapping(struct SwrContext *s, const int *channel_map);
  373. #if FF_API_OLD_CHANNEL_LAYOUT
  374. /**
  375. * Generate a channel mixing matrix.
  376. *
  377. * This function is the one used internally by libswresample for building the
  378. * default mixing matrix. It is made public just as a utility function for
  379. * building custom matrices.
  380. *
  381. * @param in_layout input channel layout
  382. * @param out_layout output channel layout
  383. * @param center_mix_level mix level for the center channel
  384. * @param surround_mix_level mix level for the surround channel(s)
  385. * @param lfe_mix_level mix level for the low-frequency effects channel
  386. * @param rematrix_maxval if 1.0, coefficients will be normalized to prevent
  387. * overflow. if INT_MAX, coefficients will not be
  388. * normalized.
  389. * @param[out] matrix mixing coefficients; matrix[i + stride * o] is
  390. * the weight of input channel i in output channel o.
  391. * @param stride distance between adjacent input channels in the
  392. * matrix array
  393. * @param matrix_encoding matrixed stereo downmix mode (e.g. dplii)
  394. * @param log_ctx parent logging context, can be NULL
  395. * @return 0 on success, negative AVERROR code on failure
  396. * @deprecated use @ref swr_build_matrix2()
  397. */
  398. attribute_deprecated
  399. int swr_build_matrix(uint64_t in_layout, uint64_t out_layout,
  400. double center_mix_level, double surround_mix_level,
  401. double lfe_mix_level, double rematrix_maxval,
  402. double rematrix_volume, double *matrix,
  403. int stride, enum AVMatrixEncoding matrix_encoding,
  404. void *log_ctx);
  405. #endif
  406. /**
  407. * Generate a channel mixing matrix.
  408. *
  409. * This function is the one used internally by libswresample for building the
  410. * default mixing matrix. It is made public just as a utility function for
  411. * building custom matrices.
  412. *
  413. * @param in_layout input channel layout
  414. * @param out_layout output channel layout
  415. * @param center_mix_level mix level for the center channel
  416. * @param surround_mix_level mix level for the surround channel(s)
  417. * @param lfe_mix_level mix level for the low-frequency effects channel
  418. * @param rematrix_maxval if 1.0, coefficients will be normalized to prevent
  419. * overflow. if INT_MAX, coefficients will not be
  420. * normalized.
  421. * @param[out] matrix mixing coefficients; matrix[i + stride * o] is
  422. * the weight of input channel i in output channel o.
  423. * @param stride distance between adjacent input channels in the
  424. * matrix array
  425. * @param matrix_encoding matrixed stereo downmix mode (e.g. dplii)
  426. * @param log_ctx parent logging context, can be NULL
  427. * @return 0 on success, negative AVERROR code on failure
  428. */
  429. int swr_build_matrix2(const AVChannelLayout *in_layout, const AVChannelLayout *out_layout,
  430. double center_mix_level, double surround_mix_level,
  431. double lfe_mix_level, double maxval,
  432. double rematrix_volume, double *matrix,
  433. ptrdiff_t stride, enum AVMatrixEncoding matrix_encoding,
  434. void *log_context);
  435. /**
  436. * Set a customized remix matrix.
  437. *
  438. * @param s allocated Swr context, not yet initialized
  439. * @param matrix remix coefficients; matrix[i + stride * o] is
  440. * the weight of input channel i in output channel o
  441. * @param stride offset between lines of the matrix
  442. * @return >= 0 on success, or AVERROR error code in case of failure.
  443. */
  444. int swr_set_matrix(struct SwrContext *s, const double *matrix, int stride);
  445. /**
  446. * @}
  447. *
  448. * @name Sample handling functions
  449. * @{
  450. */
  451. /**
  452. * Drops the specified number of output samples.
  453. *
  454. * This function, along with swr_inject_silence(), is called by swr_next_pts()
  455. * if needed for "hard" compensation.
  456. *
  457. * @param s allocated Swr context
  458. * @param count number of samples to be dropped
  459. *
  460. * @return >= 0 on success, or a negative AVERROR code on failure
  461. */
  462. int swr_drop_output(struct SwrContext *s, int count);
  463. /**
  464. * Injects the specified number of silence samples.
  465. *
  466. * This function, along with swr_drop_output(), is called by swr_next_pts()
  467. * if needed for "hard" compensation.
  468. *
  469. * @param s allocated Swr context
  470. * @param count number of samples to be dropped
  471. *
  472. * @return >= 0 on success, or a negative AVERROR code on failure
  473. */
  474. int swr_inject_silence(struct SwrContext *s, int count);
  475. /**
  476. * Gets the delay the next input sample will experience relative to the next output sample.
  477. *
  478. * Swresample can buffer data if more input has been provided than available
  479. * output space, also converting between sample rates needs a delay.
  480. * This function returns the sum of all such delays.
  481. * The exact delay is not necessarily an integer value in either input or
  482. * output sample rate. Especially when downsampling by a large value, the
  483. * output sample rate may be a poor choice to represent the delay, similarly
  484. * for upsampling and the input sample rate.
  485. *
  486. * @param s swr context
  487. * @param base timebase in which the returned delay will be:
  488. * @li if it's set to 1 the returned delay is in seconds
  489. * @li if it's set to 1000 the returned delay is in milliseconds
  490. * @li if it's set to the input sample rate then the returned
  491. * delay is in input samples
  492. * @li if it's set to the output sample rate then the returned
  493. * delay is in output samples
  494. * @li if it's the least common multiple of in_sample_rate and
  495. * out_sample_rate then an exact rounding-free delay will be
  496. * returned
  497. * @returns the delay in 1 / @c base units.
  498. */
  499. int64_t swr_get_delay(struct SwrContext *s, int64_t base);
  500. /**
  501. * Find an upper bound on the number of samples that the next swr_convert
  502. * call will output, if called with in_samples of input samples. This
  503. * depends on the internal state, and anything changing the internal state
  504. * (like further swr_convert() calls) will may change the number of samples
  505. * swr_get_out_samples() returns for the same number of input samples.
  506. *
  507. * @param in_samples number of input samples.
  508. * @note any call to swr_inject_silence(), swr_convert(), swr_next_pts()
  509. * or swr_set_compensation() invalidates this limit
  510. * @note it is recommended to pass the correct available buffer size
  511. * to all functions like swr_convert() even if swr_get_out_samples()
  512. * indicates that less would be used.
  513. * @returns an upper bound on the number of samples that the next swr_convert
  514. * will output or a negative value to indicate an error
  515. */
  516. int swr_get_out_samples(struct SwrContext *s, int in_samples);
  517. /**
  518. * @}
  519. *
  520. * @name Configuration accessors
  521. * @{
  522. */
  523. /**
  524. * Return the @ref LIBSWRESAMPLE_VERSION_INT constant.
  525. *
  526. * This is useful to check if the build-time libswresample has the same version
  527. * as the run-time one.
  528. *
  529. * @returns the unsigned int-typed version
  530. */
  531. unsigned swresample_version(void);
  532. /**
  533. * Return the swr build-time configuration.
  534. *
  535. * @returns the build-time @c ./configure flags
  536. */
  537. const char *swresample_configuration(void);
  538. /**
  539. * Return the swr license.
  540. *
  541. * @returns the license of libswresample, determined at build-time
  542. */
  543. const char *swresample_license(void);
  544. /**
  545. * @}
  546. *
  547. * @name AVFrame based API
  548. * @{
  549. */
  550. /**
  551. * Convert the samples in the input AVFrame and write them to the output AVFrame.
  552. *
  553. * Input and output AVFrames must have channel_layout, sample_rate and format set.
  554. *
  555. * If the output AVFrame does not have the data pointers allocated the nb_samples
  556. * field will be set using av_frame_get_buffer()
  557. * is called to allocate the frame.
  558. *
  559. * The output AVFrame can be NULL or have fewer allocated samples than required.
  560. * In this case, any remaining samples not written to the output will be added
  561. * to an internal FIFO buffer, to be returned at the next call to this function
  562. * or to swr_convert().
  563. *
  564. * If converting sample rate, there may be data remaining in the internal
  565. * resampling delay buffer. swr_get_delay() tells the number of
  566. * remaining samples. To get this data as output, call this function or
  567. * swr_convert() with NULL input.
  568. *
  569. * If the SwrContext configuration does not match the output and
  570. * input AVFrame settings the conversion does not take place and depending on
  571. * which AVFrame is not matching AVERROR_OUTPUT_CHANGED, AVERROR_INPUT_CHANGED
  572. * or the result of a bitwise-OR of them is returned.
  573. *
  574. * @see swr_delay()
  575. * @see swr_convert()
  576. * @see swr_get_delay()
  577. *
  578. * @param swr audio resample context
  579. * @param output output AVFrame
  580. * @param input input AVFrame
  581. * @return 0 on success, AVERROR on failure or nonmatching
  582. * configuration.
  583. */
  584. int swr_convert_frame(SwrContext *swr,
  585. AVFrame *output, const AVFrame *input);
  586. /**
  587. * Configure or reconfigure the SwrContext using the information
  588. * provided by the AVFrames.
  589. *
  590. * The original resampling context is reset even on failure.
  591. * The function calls swr_close() internally if the context is open.
  592. *
  593. * @see swr_close();
  594. *
  595. * @param swr audio resample context
  596. * @param output output AVFrame
  597. * @param input input AVFrame
  598. * @return 0 on success, AVERROR on failure.
  599. */
  600. int swr_config_frame(SwrContext *swr, const AVFrame *out, const AVFrame *in);
  601. /**
  602. * @}
  603. * @}
  604. */
  605. #endif /* SWRESAMPLE_SWRESAMPLE_H */