Commit | Line | Data |
---|---|---|
2ba45a60 DM |
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 | * Libswresample (lswr) is a library that handles audio resampling, sample | |
35 | * format conversion and mixing. | |
36 | * | |
37 | * Interaction with lswr is done through SwrContext, which is | |
38 | * allocated with swr_alloc() or swr_alloc_set_opts(). It is opaque, so all parameters | |
39 | * must be set with the @ref avoptions API. | |
40 | * | |
41 | * The first thing you will need to do in order to use lswr is to allocate | |
42 | * SwrContext. This can be done with swr_alloc() or swr_alloc_set_opts(). If you | |
43 | * are using the former, you must set options through the @ref avoptions API. | |
44 | * The latter function provides the same feature, but it allows you to set some | |
45 | * common options in the same statement. | |
46 | * | |
47 | * For example the following code will setup conversion from planar float sample | |
48 | * format to interleaved signed 16-bit integer, downsampling from 48kHz to | |
49 | * 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing | |
50 | * matrix). This is using the swr_alloc() function. | |
51 | * @code | |
52 | * SwrContext *swr = swr_alloc(); | |
53 | * av_opt_set_channel_layout(swr, "in_channel_layout", AV_CH_LAYOUT_5POINT1, 0); | |
54 | * av_opt_set_channel_layout(swr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0); | |
55 | * av_opt_set_int(swr, "in_sample_rate", 48000, 0); | |
56 | * av_opt_set_int(swr, "out_sample_rate", 44100, 0); | |
57 | * av_opt_set_sample_fmt(swr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0); | |
58 | * av_opt_set_sample_fmt(swr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0); | |
59 | * @endcode | |
60 | * | |
61 | * The same job can be done using swr_alloc_set_opts() as well: | |
62 | * @code | |
63 | * SwrContext *swr = swr_alloc_set_opts(NULL, // we're allocating a new context | |
64 | * AV_CH_LAYOUT_STEREO, // out_ch_layout | |
65 | * AV_SAMPLE_FMT_S16, // out_sample_fmt | |
66 | * 44100, // out_sample_rate | |
67 | * AV_CH_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_opts(), 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/frame.h" | |
125 | #include "libavutil/samplefmt.h" | |
126 | ||
127 | #include "libswresample/version.h" | |
128 | ||
129 | #if LIBSWRESAMPLE_VERSION_MAJOR < 1 | |
130 | #define SWR_CH_MAX 32 ///< Maximum number of channels | |
131 | #endif | |
132 | ||
133 | /** | |
134 | * @name Option constants | |
135 | * These constants are used for the @ref avoptions interface for lswr. | |
136 | * @{ | |
137 | * | |
138 | */ | |
139 | ||
140 | #define SWR_FLAG_RESAMPLE 1 ///< Force resampling even if equal sample rate | |
141 | //TODO use int resample ? | |
142 | //long term TODO can we enable this dynamically? | |
143 | ||
144 | /** Dithering algorithms */ | |
145 | enum SwrDitherType { | |
146 | SWR_DITHER_NONE = 0, | |
147 | SWR_DITHER_RECTANGULAR, | |
148 | SWR_DITHER_TRIANGULAR, | |
149 | SWR_DITHER_TRIANGULAR_HIGHPASS, | |
150 | ||
151 | SWR_DITHER_NS = 64, ///< not part of API/ABI | |
152 | SWR_DITHER_NS_LIPSHITZ, | |
153 | SWR_DITHER_NS_F_WEIGHTED, | |
154 | SWR_DITHER_NS_MODIFIED_E_WEIGHTED, | |
155 | SWR_DITHER_NS_IMPROVED_E_WEIGHTED, | |
156 | SWR_DITHER_NS_SHIBATA, | |
157 | SWR_DITHER_NS_LOW_SHIBATA, | |
158 | SWR_DITHER_NS_HIGH_SHIBATA, | |
159 | SWR_DITHER_NB, ///< not part of API/ABI | |
160 | }; | |
161 | ||
162 | /** Resampling Engines */ | |
163 | enum SwrEngine { | |
164 | SWR_ENGINE_SWR, /**< SW Resampler */ | |
165 | SWR_ENGINE_SOXR, /**< SoX Resampler */ | |
166 | SWR_ENGINE_NB, ///< not part of API/ABI | |
167 | }; | |
168 | ||
169 | /** Resampling Filter Types */ | |
170 | enum SwrFilterType { | |
171 | SWR_FILTER_TYPE_CUBIC, /**< Cubic */ | |
172 | SWR_FILTER_TYPE_BLACKMAN_NUTTALL, /**< Blackman Nuttall Windowed Sinc */ | |
173 | SWR_FILTER_TYPE_KAISER, /**< Kaiser Windowed Sinc */ | |
174 | }; | |
175 | ||
176 | /** | |
177 | * @} | |
178 | */ | |
179 | ||
180 | /** | |
181 | * The libswresample context. Unlike libavcodec and libavformat, this structure | |
182 | * is opaque. This means that if you would like to set options, you must use | |
183 | * the @ref avoptions API and cannot directly set values to members of the | |
184 | * structure. | |
185 | */ | |
186 | typedef struct SwrContext SwrContext; | |
187 | ||
188 | /** | |
189 | * Get the AVClass for SwrContext. It can be used in combination with | |
190 | * AV_OPT_SEARCH_FAKE_OBJ for examining options. | |
191 | * | |
192 | * @see av_opt_find(). | |
193 | * @return the AVClass of SwrContext | |
194 | */ | |
195 | const AVClass *swr_get_class(void); | |
196 | ||
197 | /** | |
198 | * @name SwrContext constructor functions | |
199 | * @{ | |
200 | */ | |
201 | ||
202 | /** | |
203 | * Allocate SwrContext. | |
204 | * | |
205 | * If you use this function you will need to set the parameters (manually or | |
206 | * with swr_alloc_set_opts()) before calling swr_init(). | |
207 | * | |
208 | * @see swr_alloc_set_opts(), swr_init(), swr_free() | |
209 | * @return NULL on error, allocated context otherwise | |
210 | */ | |
211 | struct SwrContext *swr_alloc(void); | |
212 | ||
213 | /** | |
214 | * Initialize context after user parameters have been set. | |
215 | * @note The context must be configured using the AVOption API. | |
216 | * | |
217 | * @see av_opt_set_int() | |
218 | * @see av_opt_set_dict() | |
219 | * | |
220 | * @param[in,out] s Swr context to initialize | |
221 | * @return AVERROR error code in case of failure. | |
222 | */ | |
223 | int swr_init(struct SwrContext *s); | |
224 | ||
225 | /** | |
226 | * Check whether an swr context has been initialized or not. | |
227 | * | |
228 | * @param[in] s Swr context to check | |
229 | * @see swr_init() | |
230 | * @return positive if it has been initialized, 0 if not initialized | |
231 | */ | |
232 | int swr_is_initialized(struct SwrContext *s); | |
233 | ||
234 | /** | |
235 | * Allocate SwrContext if needed and set/reset common parameters. | |
236 | * | |
237 | * This function does not require s to be allocated with swr_alloc(). On the | |
238 | * other hand, swr_alloc() can use swr_alloc_set_opts() to set the parameters | |
239 | * on the allocated context. | |
240 | * | |
241 | * @param s existing Swr context if available, or NULL if not | |
242 | * @param out_ch_layout output channel layout (AV_CH_LAYOUT_*) | |
243 | * @param out_sample_fmt output sample format (AV_SAMPLE_FMT_*). | |
244 | * @param out_sample_rate output sample rate (frequency in Hz) | |
245 | * @param in_ch_layout input channel layout (AV_CH_LAYOUT_*) | |
246 | * @param in_sample_fmt input sample format (AV_SAMPLE_FMT_*). | |
247 | * @param in_sample_rate input sample rate (frequency in Hz) | |
248 | * @param log_offset logging level offset | |
249 | * @param log_ctx parent logging context, can be NULL | |
250 | * | |
251 | * @see swr_init(), swr_free() | |
252 | * @return NULL on error, allocated context otherwise | |
253 | */ | |
254 | struct SwrContext *swr_alloc_set_opts(struct SwrContext *s, | |
255 | int64_t out_ch_layout, enum AVSampleFormat out_sample_fmt, int out_sample_rate, | |
256 | int64_t in_ch_layout, enum AVSampleFormat in_sample_fmt, int in_sample_rate, | |
257 | int log_offset, void *log_ctx); | |
258 | ||
259 | /** | |
260 | * @} | |
261 | * | |
262 | * @name SwrContext destructor functions | |
263 | * @{ | |
264 | */ | |
265 | ||
266 | /** | |
267 | * Free the given SwrContext and set the pointer to NULL. | |
268 | * | |
269 | * @param[in] s a pointer to a pointer to Swr context | |
270 | */ | |
271 | void swr_free(struct SwrContext **s); | |
272 | ||
273 | /** | |
274 | * Closes the context so that swr_is_initialized() returns 0. | |
275 | * | |
276 | * The context can be brought back to life by running swr_init(), | |
277 | * swr_init() can also be used without swr_close(). | |
278 | * This function is mainly provided for simplifying the usecase | |
279 | * where one tries to support libavresample and libswresample. | |
280 | * | |
281 | * @param[in,out] s Swr context to be closed | |
282 | */ | |
283 | void swr_close(struct SwrContext *s); | |
284 | ||
285 | /** | |
286 | * @} | |
287 | * | |
288 | * @name Core conversion functions | |
289 | * @{ | |
290 | */ | |
291 | ||
292 | /** Convert audio. | |
293 | * | |
294 | * in and in_count can be set to 0 to flush the last few samples out at the | |
295 | * end. | |
296 | * | |
297 | * If more input is provided than output space then the input will be buffered. | |
298 | * You can avoid this buffering by providing more output space than input. | |
299 | * Conversion will run directly without copying whenever possible. | |
300 | * | |
301 | * @param s allocated Swr context, with parameters set | |
302 | * @param out output buffers, only the first one need be set in case of packed audio | |
303 | * @param out_count amount of space available for output in samples per channel | |
304 | * @param in input buffers, only the first one need to be set in case of packed audio | |
305 | * @param in_count number of input samples available in one channel | |
306 | * | |
307 | * @return number of samples output per channel, negative value on error | |
308 | */ | |
309 | int swr_convert(struct SwrContext *s, uint8_t **out, int out_count, | |
310 | const uint8_t **in , int in_count); | |
311 | ||
312 | /** | |
313 | * Convert the next timestamp from input to output | |
314 | * timestamps are in 1/(in_sample_rate * out_sample_rate) units. | |
315 | * | |
316 | * @note There are 2 slightly differently behaving modes. | |
317 | * @li When automatic timestamp compensation is not used, (min_compensation >= FLT_MAX) | |
318 | * in this case timestamps will be passed through with delays compensated | |
319 | * @li When automatic timestamp compensation is used, (min_compensation < FLT_MAX) | |
320 | * in this case the output timestamps will match output sample numbers. | |
321 | * See ffmpeg-resampler(1) for the two modes of compensation. | |
322 | * | |
323 | * @param s[in] initialized Swr context | |
324 | * @param pts[in] timestamp for the next input sample, INT64_MIN if unknown | |
325 | * @see swr_set_compensation(), swr_drop_output(), and swr_inject_silence() are | |
326 | * function used internally for timestamp compensation. | |
327 | * @return the output timestamp for the next output sample | |
328 | */ | |
329 | int64_t swr_next_pts(struct SwrContext *s, int64_t pts); | |
330 | ||
331 | /** | |
332 | * @} | |
333 | * | |
334 | * @name Low-level option setting functions | |
335 | * These functons provide a means to set low-level options that is not possible | |
336 | * with the AVOption API. | |
337 | * @{ | |
338 | */ | |
339 | ||
340 | /** | |
341 | * Activate resampling compensation ("soft" compensation). This function is | |
342 | * internally called when needed in swr_next_pts(). | |
343 | * | |
344 | * @param[in,out] s allocated Swr context. If it is not initialized, | |
345 | * or SWR_FLAG_RESAMPLE is not set, swr_init() is | |
346 | * called with the flag set. | |
347 | * @param[in] sample_delta delta in PTS per sample | |
348 | * @param[in] compensation_distance number of samples to compensate for | |
349 | * @return >= 0 on success, AVERROR error codes if: | |
350 | * @li @c s is NULL, | |
351 | * @li @c compensation_distance is less than 0, | |
352 | * @li @c compensation_distance is 0 but sample_delta is not, | |
353 | * @li compensation unsupported by resampler, or | |
354 | * @li swr_init() fails when called. | |
355 | */ | |
356 | int swr_set_compensation(struct SwrContext *s, int sample_delta, int compensation_distance); | |
357 | ||
358 | /** | |
359 | * Set a customized input channel mapping. | |
360 | * | |
361 | * @param[in,out] s allocated Swr context, not yet initialized | |
362 | * @param[in] channel_map customized input channel mapping (array of channel | |
363 | * indexes, -1 for a muted channel) | |
364 | * @return >= 0 on success, or AVERROR error code in case of failure. | |
365 | */ | |
366 | int swr_set_channel_mapping(struct SwrContext *s, const int *channel_map); | |
367 | ||
368 | /** | |
369 | * Set a customized remix matrix. | |
370 | * | |
371 | * @param s allocated Swr context, not yet initialized | |
372 | * @param matrix remix coefficients; matrix[i + stride * o] is | |
373 | * the weight of input channel i in output channel o | |
374 | * @param stride offset between lines of the matrix | |
375 | * @return >= 0 on success, or AVERROR error code in case of failure. | |
376 | */ | |
377 | int swr_set_matrix(struct SwrContext *s, const double *matrix, int stride); | |
378 | ||
379 | /** | |
380 | * @} | |
381 | * | |
382 | * @name Sample handling functions | |
383 | * @{ | |
384 | */ | |
385 | ||
386 | /** | |
387 | * Drops the specified number of output samples. | |
388 | * | |
389 | * This function, along with swr_inject_silence(), is called by swr_next_pts() | |
390 | * if needed for "hard" compensation. | |
391 | * | |
392 | * @param s allocated Swr context | |
393 | * @param count number of samples to be dropped | |
394 | * | |
395 | * @return >= 0 on success, or a negative AVERROR code on failure | |
396 | */ | |
397 | int swr_drop_output(struct SwrContext *s, int count); | |
398 | ||
399 | /** | |
400 | * Injects the specified number of silence samples. | |
401 | * | |
402 | * This function, along with swr_drop_output(), is called by swr_next_pts() | |
403 | * if needed for "hard" compensation. | |
404 | * | |
405 | * @param s allocated Swr context | |
406 | * @param count number of samples to be dropped | |
407 | * | |
408 | * @return >= 0 on success, or a negative AVERROR code on failure | |
409 | */ | |
410 | int swr_inject_silence(struct SwrContext *s, int count); | |
411 | ||
412 | /** | |
413 | * Gets the delay the next input sample will experience relative to the next output sample. | |
414 | * | |
415 | * Swresample can buffer data if more input has been provided than available | |
416 | * output space, also converting between sample rates needs a delay. | |
417 | * This function returns the sum of all such delays. | |
418 | * The exact delay is not necessarily an integer value in either input or | |
419 | * output sample rate. Especially when downsampling by a large value, the | |
420 | * output sample rate may be a poor choice to represent the delay, similarly | |
421 | * for upsampling and the input sample rate. | |
422 | * | |
423 | * @param s swr context | |
424 | * @param base timebase in which the returned delay will be: | |
425 | * @li if it's set to 1 the returned delay is in seconds | |
426 | * @li if it's set to 1000 the returned delay is in milliseconds | |
427 | * @li if it's set to the input sample rate then the returned | |
428 | * delay is in input samples | |
429 | * @li if it's set to the output sample rate then the returned | |
430 | * delay is in output samples | |
431 | * @li if it's the least common multiple of in_sample_rate and | |
432 | * out_sample_rate then an exact rounding-free delay will be | |
433 | * returned | |
434 | * @returns the delay in 1 / @c base units. | |
435 | */ | |
436 | int64_t swr_get_delay(struct SwrContext *s, int64_t base); | |
437 | ||
438 | /** | |
439 | * @} | |
440 | * | |
441 | * @name Configuration accessors | |
442 | * @{ | |
443 | */ | |
444 | ||
445 | /** | |
446 | * Return the @ref LIBSWRESAMPLE_VERSION_INT constant. | |
447 | * | |
448 | * This is useful to check if the build-time libswresample has the same version | |
449 | * as the run-time one. | |
450 | * | |
451 | * @returns the unsigned int-typed version | |
452 | */ | |
453 | unsigned swresample_version(void); | |
454 | ||
455 | /** | |
456 | * Return the swr build-time configuration. | |
457 | * | |
458 | * @returns the build-time @c ./configure flags | |
459 | */ | |
460 | const char *swresample_configuration(void); | |
461 | ||
462 | /** | |
463 | * Return the swr license. | |
464 | * | |
465 | * @returns the license of libswresample, determined at build-time | |
466 | */ | |
467 | const char *swresample_license(void); | |
468 | ||
469 | /** | |
470 | * @} | |
471 | * | |
472 | * @name AVFrame based API | |
473 | * @{ | |
474 | */ | |
475 | ||
476 | /** | |
477 | * Convert the samples in the input AVFrame and write them to the output AVFrame. | |
478 | * | |
479 | * Input and output AVFrames must have channel_layout, sample_rate and format set. | |
480 | * | |
481 | * If the output AVFrame does not have the data pointers allocated the nb_samples | |
482 | * field will be set using av_frame_get_buffer() | |
483 | * is called to allocate the frame. | |
484 | * | |
485 | * The output AVFrame can be NULL or have fewer allocated samples than required. | |
486 | * In this case, any remaining samples not written to the output will be added | |
487 | * to an internal FIFO buffer, to be returned at the next call to this function | |
488 | * or to swr_convert(). | |
489 | * | |
490 | * If converting sample rate, there may be data remaining in the internal | |
491 | * resampling delay buffer. swr_get_delay() tells the number of | |
492 | * remaining samples. To get this data as output, call this function or | |
493 | * swr_convert() with NULL input. | |
494 | * | |
495 | * If the SwrContext configuration does not match the output and | |
496 | * input AVFrame settings the conversion does not take place and depending on | |
497 | * which AVFrame is not matching AVERROR_OUTPUT_CHANGED, AVERROR_INPUT_CHANGED | |
498 | * or the result of a bitwise-OR of them is returned. | |
499 | * | |
500 | * @see swr_delay() | |
501 | * @see swr_convert() | |
502 | * @see swr_get_delay() | |
503 | * | |
504 | * @param swr audio resample context | |
505 | * @param output output AVFrame | |
506 | * @param input input AVFrame | |
507 | * @return 0 on success, AVERROR on failure or nonmatching | |
508 | * configuration. | |
509 | */ | |
510 | int swr_convert_frame(SwrContext *swr, | |
511 | AVFrame *output, const AVFrame *input); | |
512 | ||
513 | /** | |
514 | * Configure or reconfigure the SwrContext using the information | |
515 | * provided by the AVFrames. | |
516 | * | |
517 | * The original resampling context is reset even on failure. | |
518 | * The function calls swr_close() internally if the context is open. | |
519 | * | |
520 | * @see swr_close(); | |
521 | * | |
522 | * @param swr audio resample context | |
523 | * @param output output AVFrame | |
524 | * @param input input AVFrame | |
525 | * @return 0 on success, AVERROR on failure. | |
526 | */ | |
527 | int swr_config_frame(SwrContext *swr, const AVFrame *out, const AVFrame *in); | |
528 | ||
529 | /** | |
530 | * @} | |
531 | * @} | |
532 | */ | |
533 | ||
534 | #endif /* SWRESAMPLE_SWRESAMPLE_H */ |