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