swresample.h 18.8 KB
Newer Older
Michael Niedermayer's avatar
Michael Niedermayer committed
1
/*
2
 * Copyright (C) 2011-2013 Michael Niedermayer (michaelni@gmx.at)
Michael Niedermayer's avatar
Michael Niedermayer committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
 *
 * This file is part of libswresample
 *
 * libswresample is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * libswresample is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with libswresample; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

21 22 23
#ifndef SWRESAMPLE_SWRESAMPLE_H
#define SWRESAMPLE_SWRESAMPLE_H

24 25
/**
 * @file
26
 * @ingroup lswr
27 28 29
 * libswresample public header
 */

30 31 32 33 34 35 36 37 38 39 40
/**
 * @defgroup lswr Libswresample
 * @{
 *
 * Libswresample (lswr) is a library that handles audio resampling, sample
 * format conversion and mixing.
 *
 * Interaction with lswr is done through SwrContext, which is
 * allocated with swr_alloc() or swr_alloc_set_opts(). It is opaque, so all parameters
 * must be set with the @ref avoptions API.
 *
41 42 43 44 45 46
 * The first thing you will need to do in order to use lswr is to allocate
 * SwrContext. This can be done with swr_alloc() or swr_alloc_set_opts(). If you
 * are using the former, you must set options through the @ref avoptions API.
 * The latter function provides the same feature, but it allows you to set some
 * common options in the same statement.
 *
47 48 49
 * For example the following code will setup conversion from planar float sample
 * format to interleaved signed 16-bit integer, downsampling from 48kHz to
 * 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing
50
 * matrix). This is using the swr_alloc() function.
51 52
 * @code
 * SwrContext *swr = swr_alloc();
53 54
 * av_opt_set_channel_layout(swr, "in_channel_layout",  AV_CH_LAYOUT_5POINT1, 0);
 * av_opt_set_channel_layout(swr, "out_channel_layout", AV_CH_LAYOUT_STEREO,  0);
55 56
 * av_opt_set_int(swr, "in_sample_rate",     48000,                0);
 * av_opt_set_int(swr, "out_sample_rate",    44100,                0);
57 58
 * av_opt_set_sample_fmt(swr, "in_sample_fmt",  AV_SAMPLE_FMT_FLTP, 0);
 * av_opt_set_sample_fmt(swr, "out_sample_fmt", AV_SAMPLE_FMT_S16,  0);
59 60
 * @endcode
 *
61 62 63 64 65 66 67 68 69 70 71 72 73
 * The same job can be done using swr_alloc_set_opts() as well:
 * @code
 * SwrContext *swr = swr_alloc_set_opts(NULL,  // we're allocating a new context
 *                       AV_CH_LAYOUT_STEREO,  // out_ch_layout
 *                       AV_SAMPLE_FMT_S16,    // out_sample_fmt
 *                       44100,                // out_sample_rate
 *                       AV_CH_LAYOUT_5POINT1, // in_ch_layout
 *                       AV_SAMPLE_FMT_FLTP,   // in_sample_fmt
 *                       48000,                // in_sample_rate
 *                       0,                    // log_offset
 *                       NULL);                // log_ctx
 * @endcode
 *
74 75
 * Once all values have been set, it must be initialized with swr_init(). If
 * you need to change the conversion parameters, you can change the parameters
76 77 78
 * using @ref AVOptions, as described above in the first example; or by using
 * swr_alloc_set_opts(), but with the first argument the allocated context.
 * You must then call swr_init() again.
79 80 81 82 83 84 85 86 87
 *
 * The conversion itself is done by repeatedly calling swr_convert().
 * Note that the samples may get buffered in swr if you provide insufficient
 * output space or if sample rate conversion is done, which requires "future"
 * samples. Samples that do not require future input can be retrieved at any
 * time by using swr_convert() (in_count can be set to 0).
 * At the end of conversion the resampling buffer can be flushed by calling
 * swr_convert() with NULL in and 0 in_count.
 *
88 89 90 91
 * The samples used in the conversion process can be managed with the libavutil
 * @ref lavu_sampmanip "samples manipulation" API, including av_samples_alloc()
 * function used in the following example.
 *
92 93 94 95 96 97 98 99 100 101
 * The delay between input and output, can at any time be found by using
 * swr_get_delay().
 *
 * The following code demonstrates the conversion loop assuming the parameters
 * from above and caller-defined functions get_input() and handle_output():
 * @code
 * uint8_t **input;
 * int in_samples;
 *
 * while (get_input(&input, &in_samples)) {
102
 *     uint8_t *output;
103 104 105 106 107 108 109 110
 *     int out_samples = av_rescale_rnd(swr_get_delay(swr, 48000) +
 *                                      in_samples, 44100, 48000, AV_ROUND_UP);
 *     av_samples_alloc(&output, NULL, 2, out_samples,
 *                      AV_SAMPLE_FMT_S16, 0);
 *     out_samples = swr_convert(swr, &output, out_samples,
 *                                      input, in_samples);
 *     handle_output(output, out_samples);
 *     av_freep(&output);
111 112
 * }
 * @endcode
113 114 115
 *
 * When the conversion is finished, the conversion
 * context and everything associated with it must be freed with swr_free().
116 117 118
 * A swr_close() function is also available, but it exists mainly for
 * compatibility with libavresample, and is not required to be called.
 *
119 120 121
 * There will be no memory leak if the data is not completely flushed before
 * swr_free().
 */
Michael Niedermayer's avatar
Michael Niedermayer committed
122

123
#include <stdint.h>
124
#include "libavutil/frame.h"
Michael Niedermayer's avatar
Michael Niedermayer committed
125 126
#include "libavutil/samplefmt.h"

127
#include "libswresample/version.h"
128

129
#if LIBSWRESAMPLE_VERSION_MAJOR < 1
130
#define SWR_CH_MAX 32   ///< Maximum number of channels
131
#endif
Michael Niedermayer's avatar
Michael Niedermayer committed
132

133 134 135 136 137 138 139
/**
 * @name Option constants
 * These constants are used for the @ref avoptions interface for lswr.
 * @{
 *
 */

140
#define SWR_FLAG_RESAMPLE 1 ///< Force resampling even if equal sample rate
Michael Niedermayer's avatar
Michael Niedermayer committed
141 142 143
//TODO use int resample ?
//long term TODO can we enable this dynamically?

144
/** Dithering algorithms */
145 146 147
enum SwrDitherType {
    SWR_DITHER_NONE = 0,
    SWR_DITHER_RECTANGULAR,
148
    SWR_DITHER_TRIANGULAR,
149
    SWR_DITHER_TRIANGULAR_HIGHPASS,
150 151 152 153 154 155 156 157 158

    SWR_DITHER_NS = 64,         ///< not part of API/ABI
    SWR_DITHER_NS_LIPSHITZ,
    SWR_DITHER_NS_F_WEIGHTED,
    SWR_DITHER_NS_MODIFIED_E_WEIGHTED,
    SWR_DITHER_NS_IMPROVED_E_WEIGHTED,
    SWR_DITHER_NS_SHIBATA,
    SWR_DITHER_NS_LOW_SHIBATA,
    SWR_DITHER_NS_HIGH_SHIBATA,
159 160
    SWR_DITHER_NB,              ///< not part of API/ABI
};
Michael Niedermayer's avatar
Michael Niedermayer committed
161

162 163 164
/** Resampling Engines */
enum SwrEngine {
    SWR_ENGINE_SWR,             /**< SW Resampler */
165
    SWR_ENGINE_SOXR,            /**< SoX Resampler */
166 167 168
    SWR_ENGINE_NB,              ///< not part of API/ABI
};

169 170 171 172 173 174 175
/** Resampling Filter Types */
enum SwrFilterType {
    SWR_FILTER_TYPE_CUBIC,              /**< Cubic */
    SWR_FILTER_TYPE_BLACKMAN_NUTTALL,   /**< Blackman Nuttall Windowed Sinc */
    SWR_FILTER_TYPE_KAISER,             /**< Kaiser Windowed Sinc */
};

176 177 178 179
/**
 * @}
 */

180 181 182 183 184 185
/**
 * The libswresample context. Unlike libavcodec and libavformat, this structure
 * is opaque. This means that if you would like to set options, you must use
 * the @ref avoptions API and cannot directly set values to members of the
 * structure.
 */
186
typedef struct SwrContext SwrContext;
Michael Niedermayer's avatar
Michael Niedermayer committed
187

188
/**
189
 * Get the AVClass for SwrContext. It can be used in combination with
190 191 192
 * AV_OPT_SEARCH_FAKE_OBJ for examining options.
 *
 * @see av_opt_find().
193
 * @return the AVClass of SwrContext
194 195 196
 */
const AVClass *swr_get_class(void);

197 198 199 200 201
/**
 * @name SwrContext constructor functions
 * @{
 */

Michael Niedermayer's avatar
Michael Niedermayer committed
202 203
/**
 * Allocate SwrContext.
204 205 206 207 208 209
 *
 * If you use this function you will need to set the parameters (manually or
 * with swr_alloc_set_opts()) before calling swr_init().
 *
 * @see swr_alloc_set_opts(), swr_init(), swr_free()
 * @return NULL on error, allocated context otherwise
Michael Niedermayer's avatar
Michael Niedermayer committed
210 211 212 213 214
 */
struct SwrContext *swr_alloc(void);

/**
 * Initialize context after user parameters have been set.
215 216 217 218
 * @note The context must be configured using the AVOption API.
 *
 * @see av_opt_set_int()
 * @see av_opt_set_dict()
219
 *
220
 * @param[in,out]   s Swr context to initialize
221
 * @return AVERROR error code in case of failure.
Michael Niedermayer's avatar
Michael Niedermayer committed
222 223 224
 */
int swr_init(struct SwrContext *s);

225 226 227
/**
 * Check whether an swr context has been initialized or not.
 *
228 229
 * @param[in]       s Swr context to check
 * @see swr_init()
230 231 232 233
 * @return positive if it has been initialized, 0 if not initialized
 */
int swr_is_initialized(struct SwrContext *s);

Michael Niedermayer's avatar
Michael Niedermayer committed
234
/**
235 236 237 238 239 240
 * Allocate SwrContext if needed and set/reset common parameters.
 *
 * This function does not require s to be allocated with swr_alloc(). On the
 * other hand, swr_alloc() can use swr_alloc_set_opts() to set the parameters
 * on the allocated context.
 *
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 245
 * @param out_sample_rate output sample rate (frequency in Hz)
 * @param in_ch_layout    input channel layout (AV_CH_LAYOUT_*)
246
 * @param in_sample_fmt   input sample format (AV_SAMPLE_FMT_*).
247 248 249 250 251 252
 * @param in_sample_rate  input sample rate (frequency in Hz)
 * @param log_offset      logging level offset
 * @param log_ctx         parent logging context, can be NULL
 *
 * @see swr_init(), swr_free()
 * @return NULL on error, allocated context otherwise
Michael Niedermayer's avatar
Michael Niedermayer committed
253
 */
254 255 256
struct SwrContext *swr_alloc_set_opts(struct SwrContext *s,
                                      int64_t out_ch_layout, enum AVSampleFormat out_sample_fmt, int out_sample_rate,
                                      int64_t  in_ch_layout, enum AVSampleFormat  in_sample_fmt, int  in_sample_rate,
257
                                      int log_offset, void *log_ctx);
Michael Niedermayer's avatar
Michael Niedermayer committed
258

259 260 261 262 263 264 265
/**
 * @}
 *
 * @name SwrContext destructor functions
 * @{
 */

Michael Niedermayer's avatar
Michael Niedermayer committed
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
Michael Niedermayer's avatar
Michael Niedermayer committed
270 271 272
 */
void swr_free(struct SwrContext **s);

273 274 275
/**
 * Closes the context so that swr_is_initialized() returns 0.
 *
276
 * The context can be brought back to life by running swr_init(),
277 278
 * swr_init() can also be used without swr_close().
 * 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 284
 */
void swr_close(struct SwrContext *s);

Michael Niedermayer's avatar
Michael Niedermayer committed
285
/**
286 287 288 289 290 291 292
 * @}
 *
 * @name Core conversion functions
 * @{
 */

/** Convert audio.
293
 *
294 295 296
 * in and in_count can be set to 0 to flush the last few samples out at the
 * end.
 *
297 298
 * If more input is provided than output space then the input will be buffered.
 * You can avoid this buffering by providing more output space than input.
299
 * Conversion will run directly without copying whenever possible.
300
 *
301 302 303 304 305 306
 * @param s         allocated Swr context, with parameters set
 * @param out       output buffers, only the first one need be set in case of packed audio
 * @param out_count amount of space available for output in samples per channel
 * @param in        input buffers, only the first one need to be set in case of packed audio
 * @param in_count  number of input samples available in one channel
 *
307
 * @return number of samples output per channel, negative value on error
Michael Niedermayer's avatar
Michael Niedermayer committed
308
 */
309 310
int swr_convert(struct SwrContext *s, uint8_t **out, int out_count,
                                const uint8_t **in , int in_count);
Michael Niedermayer's avatar
Michael Niedermayer committed
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 320 321 322 323 324 325 326
 *       @li When automatic timestamp compensation is used, (min_compensation < FLT_MAX)
 *              in this case the output timestamps will match output sample numbers.
 *              See ffmpeg-resampler(1) for the two modes of compensation.
 *
 * @param s[in]     initialized Swr context
 * @param pts[in]   timestamp for the next input sample, INT64_MIN if unknown
 * @see swr_set_compensation(), swr_drop_output(), and swr_inject_silence() are
 *      function used internally for timestamp compensation.
327
 * @return the output timestamp for the next output sample
328 329 330
 */
int64_t swr_next_pts(struct SwrContext *s, int64_t pts);

331 332 333 334 335 336 337 338 339
/**
 * @}
 *
 * @name Low-level option setting functions
 * These functons provide a means to set low-level options that is not possible
 * with the AVOption API.
 * @{
 */

340
/**
341 342 343 344 345 346 347 348 349 350 351 352 353 354
 * Activate resampling compensation ("soft" compensation). This function is
 * internally called when needed in swr_next_pts().
 *
 * @param[in,out] s             allocated Swr context. If it is not initialized,
 *                              or SWR_FLAG_RESAMPLE is not set, swr_init() is
 *                              called with the flag set.
 * @param[in]     sample_delta  delta in PTS per sample
 * @param[in]     compensation_distance number of samples to compensate for
 * @return    >= 0 on success, AVERROR error codes if:
 *            @li @c s is NULL,
 *            @li @c compensation_distance is less than 0,
 *            @li @c compensation_distance is 0 but sample_delta is not,
 *            @li compensation unsupported by resampler, or
 *            @li swr_init() fails when called.
355
 */
356
int swr_set_compensation(struct SwrContext *s, int sample_delta, int compensation_distance);
Michael Niedermayer's avatar
Michael Niedermayer committed
357

358 359 360
/**
 * Set a customized input channel mapping.
 *
361 362 363 364
 * @param[in,out] s           allocated Swr context, not yet initialized
 * @param[in]     channel_map customized input channel mapping (array of channel
 *                            indexes, -1 for a muted channel)
 * @return >= 0 on success, or AVERROR error code in case of failure.
365 366 367
 */
int swr_set_channel_mapping(struct SwrContext *s, const int *channel_map);

368 369 370 371 372 373 374
/**
 * Set a customized remix matrix.
 *
 * @param s       allocated Swr context, not yet initialized
 * @param matrix  remix coefficients; matrix[i + stride * o] is
 *                the weight of input channel i in output channel o
 * @param stride  offset between lines of the matrix
375
 * @return  >= 0 on success, or AVERROR error code in case of failure.
376 377 378
 */
int swr_set_matrix(struct SwrContext *s, const double *matrix, int stride);

379 380 381 382 383 384 385
/**
 * @}
 *
 * @name Sample handling functions
 * @{
 */

386 387
/**
 * Drops the specified number of output samples.
388 389 390 391 392 393 394 395
 *
 * This function, along with swr_inject_silence(), is called by swr_next_pts()
 * if needed for "hard" compensation.
 *
 * @param s     allocated Swr context
 * @param count number of samples to be dropped
 *
 * @return >= 0 on success, or a negative AVERROR code on failure
396 397 398
 */
int swr_drop_output(struct SwrContext *s, int count);

399 400
/**
 * Injects the specified number of silence samples.
401 402 403 404 405 406 407 408
 *
 * This function, along with swr_drop_output(), is called by swr_next_pts()
 * if needed for "hard" compensation.
 *
 * @param s     allocated Swr context
 * @param count number of samples to be dropped
 *
 * @return >= 0 on success, or a negative AVERROR code on failure
409 410 411
 */
int swr_inject_silence(struct SwrContext *s, int count);

412 413 414 415 416 417
/**
 * Gets the delay the next input sample will experience relative to the next output sample.
 *
 * Swresample can buffer data if more input has been provided than available
 * output space, also converting between sample rates needs a delay.
 * This function returns the sum of all such delays.
418
 * The exact delay is not necessarily an integer value in either input or
419 420 421
 * output sample rate. Especially when downsampling by a large value, the
 * output sample rate may be a poor choice to represent the delay, similarly
 * for upsampling and the input sample rate.
422 423
 *
 * @param s     swr context
424 425 426 427 428 429 430 431 432 433 434
 * @param base  timebase in which the returned delay will be:
 *              @li if it's set to 1 the returned delay is in seconds
 *              @li if it's set to 1000 the returned delay is in milliseconds
 *              @li if it's set to the input sample rate then the returned
 *                  delay is in input samples
 *              @li if it's set to the output sample rate then the returned
 *                  delay is in output samples
 *              @li if it's the least common multiple of in_sample_rate and
 *                  out_sample_rate then an exact rounding-free delay will be
 *                  returned
 * @returns     the delay in 1 / @c base units.
435 436 437
 */
int64_t swr_get_delay(struct SwrContext *s, int64_t base);

438 439 440 441 442 443 444
/**
 * @}
 *
 * @name Configuration accessors
 * @{
 */

445
/**
446 447 448 449 450 451
 * Return the @ref LIBSWRESAMPLE_VERSION_INT constant.
 *
 * This is useful to check if the build-time libswresample has the same version
 * as the run-time one.
 *
 * @returns     the unsigned int-typed version
452 453 454 455 456
 */
unsigned swresample_version(void);

/**
 * Return the swr build-time configuration.
457 458
 *
 * @returns     the build-time @c ./configure flags
459 460 461 462 463
 */
const char *swresample_configuration(void);

/**
 * Return the swr license.
464 465
 *
 * @returns     the license of libswresample, determined at build-time
466 467 468
 */
const char *swresample_license(void);

469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528
/**
 * @}
 *
 * @name AVFrame based API
 * @{
 */

/**
 * Convert the samples in the input AVFrame and write them to the output AVFrame.
 *
 * Input and output AVFrames must have channel_layout, sample_rate and format set.
 *
 * If the output AVFrame does not have the data pointers allocated the nb_samples
 * field will be set using av_frame_get_buffer()
 * is called to allocate the frame.
 *
 * The output AVFrame can be NULL or have fewer allocated samples than required.
 * In this case, any remaining samples not written to the output will be added
 * to an internal FIFO buffer, to be returned at the next call to this function
 * or to swr_convert().
 *
 * If converting sample rate, there may be data remaining in the internal
 * resampling delay buffer. swr_get_delay() tells the number of
 * remaining samples. To get this data as output, call this function or
 * swr_convert() with NULL input.
 *
 * If the SwrContext configuration does not match the output and
 * input AVFrame settings the conversion does not take place and depending on
 * which AVFrame is not matching AVERROR_OUTPUT_CHANGED, AVERROR_INPUT_CHANGED
 * or the result of a bitwise-OR of them is returned.
 *
 * @see swr_delay()
 * @see swr_convert()
 * @see swr_get_delay()
 *
 * @param swr             audio resample context
 * @param output          output AVFrame
 * @param input           input AVFrame
 * @return                0 on success, AVERROR on failure or nonmatching
 *                        configuration.
 */
int swr_convert_frame(SwrContext *swr,
                      AVFrame *output, const AVFrame *input);

/**
 * Configure or reconfigure the SwrContext using the information
 * provided by the AVFrames.
 *
 * The original resampling context is reset even on failure.
 * The function calls swr_close() internally if the context is open.
 *
 * @see swr_close();
 *
 * @param swr             audio resample context
 * @param output          output AVFrame
 * @param input           input AVFrame
 * @return                0 on success, AVERROR on failure.
 */
int swr_config_frame(SwrContext *swr, const AVFrame *out, const AVFrame *in);

529
/**
530
 * @}
531 532 533
 * @}
 */

534
#endif /* SWRESAMPLE_SWRESAMPLE_H */