libswresample/swresample.h

   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_opts(). 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_opts(). 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_opts() as well:
  61  * @code
  62  * SwrContext *swr = swr_alloc_set_opts(NULL,  // we're allocating a new context
  63  *                       AV_CH_LAYOUT_STEREO,  // out_ch_layout
  64  *                       AV_SAMPLE_FMT_S16,    // out_sample_fmt
  65  *                       44100,                // out_sample_rate
  66  *                       AV_CH_LAYOUT_5POINT1, // in_ch_layout
  67  *                       AV_SAMPLE_FMT_FLTP,   // in_sample_fmt
  68  *                       48000,                // in_sample_rate
  69  *                       0,                    // log_offset
  70  *                       NULL);                // log_ctx
  71  * @endcode
  72  *
  73  * Once all values have been set, it must be initialized with swr_init(). If
  74  * you need to change the conversion parameters, you can change the parameters
  75  * using @ref AVOptions, as described above in the first example; or by using
  76  * swr_alloc_set_opts(), but with the first argument the allocated context.
  77  * You must then call swr_init() again.
  78  *
  79  * The conversion itself is done by repeatedly calling swr_convert().
  80  * Note that the samples may get buffered in swr if you provide insufficient
  81  * output space or if sample rate conversion is done, which requires "future"
  82  * samples. Samples that do not require future input can be retrieved at any
  83  * time by using swr_convert() (in_count can be set to 0).
  84  * At the end of conversion the resampling buffer can be flushed by calling
  85  * swr_convert() with NULL in and 0 in_count.
  86  *
  87  * The samples used in the conversion process can be managed with the libavutil
  88  * @ref lavu_sampmanip "samples manipulation" API, including av_samples_alloc()
  89  * function used in the following example.
  90  *
  91  * The delay between input and output, can at any time be found by using
  92  * swr_get_delay().
  93  *
  94  * The following code demonstrates the conversion loop assuming the parameters
  95  * from above and caller-defined functions get_input() and handle_output():
  96  * @code
  97  * uint8_t **input;
  98  * int in_samples;
  99  *
 100  * while (get_input(&input, &in_samples)) {
 101  *     uint8_t *output;
 102  *     int out_samples = av_rescale_rnd(swr_get_delay(swr, 48000) +
 103  *                                      in_samples, 44100, 48000, AV_ROUND_UP);
 104  *     av_samples_alloc(&output, NULL, 2, out_samples,
 105  *                      AV_SAMPLE_FMT_S16, 0);
 106  *     out_samples = swr_convert(swr, &output, out_samples,
 107  *                                      input, in_samples);
 108  *     handle_output(output, out_samples);
 109  *     av_freep(&output);
 110  * }
 111  * @endcode
 112  *
 113  * When the conversion is finished, the conversion
 114  * context and everything associated with it must be freed with swr_free().
 115  * A swr_close() function is also available, but it exists mainly for
 116  * compatibility with libavresample, and is not required to be called.
 117  *
 118  * There will be no memory leak if the data is not completely flushed before
 119  * swr_free().
 120  */
 121
 122 #include <stdint.h>
 123 #include "libavutil/channel_layout.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 using swr_get_out_samples() to retrieve an
 299  * upper bound on the required number of output samples for the given number of
 300  * input samples. Conversion will run directly without copying whenever possible.
 301  *
 302  * @param s         allocated Swr context, with parameters set
 303  * @param out       output buffers, only the first one need be set in case of packed audio
 304  * @param out_count amount of space available for output in samples per channel
 305  * @param in        input buffers, only the first one need to be set in case of packed audio
 306  * @param in_count  number of input samples available in one channel
 307  *
 308  * @return number of samples output per channel, negative value on error
 309  */
 310 int swr_convert(struct SwrContext *s, uint8_t **out, int out_count,
 311                                 const uint8_t **in , int in_count);
 312
 313 /**
 314  * Convert the next timestamp from input to output
 315  * timestamps are in 1/(in_sample_rate * out_sample_rate) units.
 316  *
 317  * @note There are 2 slightly differently behaving modes.
 318  *       @li When automatic timestamp compensation is not used, (min_compensation >= FLT_MAX)
 319  *              in this case timestamps will be passed through with delays compensated
 320  *       @li When automatic timestamp compensation is used, (min_compensation < FLT_MAX)
 321  *              in this case the output timestamps will match output sample numbers.
 322  *              See ffmpeg-resampler(1) for the two modes of compensation.
 323  *
 324  * @param s[in]     initialized Swr context
 325  * @param pts[in]   timestamp for the next input sample, INT64_MIN if unknown
 326  * @see swr_set_compensation(), swr_drop_output(), and swr_inject_silence() are
 327  *      function used internally for timestamp compensation.
 328  * @return the output timestamp for the next output sample
 329  */
 330 int64_t swr_next_pts(struct SwrContext *s, int64_t pts);
 331
 332 /**
 333  * @}
 334  *
 335  * @name Low-level option setting functions
 336  * These functons provide a means to set low-level options that is not possible
 337  * with the AVOption API.
 338  * @{
 339  */
 340
 341 /**
 342  * Activate resampling compensation ("soft" compensation). This function is
 343  * internally called when needed in swr_next_pts().
 344  *
 345  * @param[in,out] s             allocated Swr context. If it is not initialized,
 346  *                              or SWR_FLAG_RESAMPLE is not set, swr_init() is
 347  *                              called with the flag set.
 348  * @param[in]     sample_delta  delta in PTS per sample
 349  * @param[in]     compensation_distance number of samples to compensate for
 350  * @return    >= 0 on success, AVERROR error codes if:
 351  *            @li @c s is NULL,
 352  *            @li @c compensation_distance is less than 0,
 353  *            @li @c compensation_distance is 0 but sample_delta is not,
 354  *            @li compensation unsupported by resampler, or
 355  *            @li swr_init() fails when called.
 356  */
 357 int swr_set_compensation(struct SwrContext *s, int sample_delta, int compensation_distance);
 358
 359 /**
 360  * Set a customized input channel mapping.
 361  *
 362  * @param[in,out] s           allocated Swr context, not yet initialized
 363  * @param[in]     channel_map customized input channel mapping (array of channel
 364  *                            indexes, -1 for a muted channel)
 365  * @return >= 0 on success, or AVERROR error code in case of failure.
 366  */
 367 int swr_set_channel_mapping(struct SwrContext *s, const int *channel_map);
 368
 369 /**
 370  * Generate a channel mixing matrix.
 371  *
 372  * This function is the one used internally by libswresample for building the
 373  * default mixing matrix. It is made public just as a utility function for
 374  * building custom matrices.
 375  *
 376  * @param in_layout           input channel layout
 377  * @param out_layout          output channel layout
 378  * @param center_mix_level    mix level for the center channel
 379  * @param surround_mix_level  mix level for the surround channel(s)
 380  * @param lfe_mix_level       mix level for the low-frequency effects channel
 381  * @param rematrix_maxval     if 1.0, coefficients will be normalized to prevent
 382  *                            overflow. if INT_MAX, coefficients will not be
 383  *                            normalized.
 384  * @param[out] matrix         mixing coefficients; matrix[i + stride * o] is
 385  *                            the weight of input channel i in output channel o.
 386  * @param stride              distance between adjacent input channels in the
 387  *                            matrix array
 388  * @param matrix_encoding     matrixed stereo downmix mode (e.g. dplii)
 389  * @param log_ctx             parent logging context, can be NULL
 390  * @return                    0 on success, negative AVERROR code on failure
 391  */
 392 int swr_build_matrix(uint64_t in_layout, uint64_t out_layout,
 393                      double center_mix_level, double surround_mix_level,
 394                      double lfe_mix_level, double rematrix_maxval,
 395                      double rematrix_volume, double *matrix,
 396                      int stride, enum AVMatrixEncoding matrix_encoding,
 397                      void *log_ctx);
 398
 399 /**
 400  * Set a customized remix matrix.
 401  *
 402  * @param s       allocated Swr context, not yet initialized
 403  * @param matrix  remix coefficients; matrix[i + stride * o] is
 404  *                the weight of input channel i in output channel o
 405  * @param stride  offset between lines of the matrix
 406  * @return  >= 0 on success, or AVERROR error code in case of failure.
 407  */
 408 int swr_set_matrix(struct SwrContext *s, const double *matrix, int stride);
 409
 410 /**
 411  * @}
 412  *
 413  * @name Sample handling functions
 414  * @{
 415  */
 416
 417 /**
 418  * Drops the specified number of output samples.
 419  *
 420  * This function, along with swr_inject_silence(), is called by swr_next_pts()
 421  * if needed for "hard" compensation.
 422  *
 423  * @param s     allocated Swr context
 424  * @param count number of samples to be dropped
 425  *
 426  * @return >= 0 on success, or a negative AVERROR code on failure
 427  */
 428 int swr_drop_output(struct SwrContext *s, int count);
 429
 430 /**
 431  * Injects the specified number of silence samples.
 432  *
 433  * This function, along with swr_drop_output(), is called by swr_next_pts()
 434  * if needed for "hard" compensation.
 435  *
 436  * @param s     allocated Swr context
 437  * @param count number of samples to be dropped
 438  *
 439  * @return >= 0 on success, or a negative AVERROR code on failure
 440  */
 441 int swr_inject_silence(struct SwrContext *s, int count);
 442
 443 /**
 444  * Gets the delay the next input sample will experience relative to the next output sample.
 445  *
 446  * Swresample can buffer data if more input has been provided than available
 447  * output space, also converting between sample rates needs a delay.
 448  * This function returns the sum of all such delays.
 449  * The exact delay is not necessarily an integer value in either input or
 450  * output sample rate. Especially when downsampling by a large value, the
 451  * output sample rate may be a poor choice to represent the delay, similarly
 452  * for upsampling and the input sample rate.
 453  *
 454  * @param s     swr context
 455  * @param base  timebase in which the returned delay will be:
 456  *              @li if it's set to 1 the returned delay is in seconds
 457  *              @li if it's set to 1000 the returned delay is in milliseconds
 458  *              @li if it's set to the input sample rate then the returned
 459  *                  delay is in input samples
 460  *              @li if it's set to the output sample rate then the returned
 461  *                  delay is in output samples
 462  *              @li if it's the least common multiple of in_sample_rate and
 463  *                  out_sample_rate then an exact rounding-free delay will be
 464  *                  returned
 465  * @returns     the delay in 1 / @c base units.
 466  */
 467 int64_t swr_get_delay(struct SwrContext *s, int64_t base);
 468
 469 /**
 470  * Find an upper bound on the number of samples that the next swr_convert
 471  * call will output, if called with in_samples of input samples. This
 472  * depends on the internal state, and anything changing the internal state
 473  * (like further swr_convert() calls) will may change the number of samples
 474  * swr_get_out_samples() returns for the same number of input samples.
 475  *
 476  * @param in_samples    number of input samples.
 477  * @note any call to swr_inject_silence(), swr_convert(), swr_next_pts()
 478  *       or swr_set_compensation() invalidates this limit
 479  * @note it is recommended to pass the correct available buffer size
 480  *       to all functions like swr_convert() even if swr_get_out_samples()
 481  *       indicates that less would be used.
 482  * @returns an upper bound on the number of samples that the next swr_convert
 483  *          will output or a negative value to indicate an error
 484  */
 485 int swr_get_out_samples(struct SwrContext *s, int in_samples);
 486
 487 /**
 488  * @}
 489  *
 490  * @name Configuration accessors
 491  * @{
 492  */
 493
 494 /**
 495  * Return the @ref LIBSWRESAMPLE_VERSION_INT constant.
 496  *
 497  * This is useful to check if the build-time libswresample has the same version
 498  * as the run-time one.
 499  *
 500  * @returns     the unsigned int-typed version
 501  */
 502 unsigned swresample_version(void);
 503
 504 /**
 505  * Return the swr build-time configuration.
 506  *
 507  * @returns     the build-time @c ./configure flags
 508  */
 509 const char *swresample_configuration(void);
 510
 511 /**
 512  * Return the swr license.
 513  *
 514  * @returns     the license of libswresample, determined at build-time
 515  */
 516 const char *swresample_license(void);
 517
 518 /**
 519  * @}
 520  *
 521  * @name AVFrame based API
 522  * @{
 523  */
 524
 525 /**
 526  * Convert the samples in the input AVFrame and write them to the output AVFrame.
 527  *
 528  * Input and output AVFrames must have channel_layout, sample_rate and format set.
 529  *
 530  * If the output AVFrame does not have the data pointers allocated the nb_samples
 531  * field will be set using av_frame_get_buffer()
 532  * is called to allocate the frame.
 533  *
 534  * The output AVFrame can be NULL or have fewer allocated samples than required.
 535  * In this case, any remaining samples not written to the output will be added
 536  * to an internal FIFO buffer, to be returned at the next call to this function
 537  * or to swr_convert().
 538  *
 539  * If converting sample rate, there may be data remaining in the internal
 540  * resampling delay buffer. swr_get_delay() tells the number of
 541  * remaining samples. To get this data as output, call this function or
 542  * swr_convert() with NULL input.
 543  *
 544  * If the SwrContext configuration does not match the output and
 545  * input AVFrame settings the conversion does not take place and depending on
 546  * which AVFrame is not matching AVERROR_OUTPUT_CHANGED, AVERROR_INPUT_CHANGED
 547  * or the result of a bitwise-OR of them is returned.
 548  *
 549  * @see swr_delay()
 550  * @see swr_convert()
 551  * @see swr_get_delay()
 552  *
 553  * @param swr             audio resample context
 554  * @param output          output AVFrame
 555  * @param input           input AVFrame
 556  * @return                0 on success, AVERROR on failure or nonmatching
 557  *                        configuration.
 558  */
 559 int swr_convert_frame(SwrContext *swr,
 560                       AVFrame *output, const AVFrame *input);
 561
 562 /**
 563  * Configure or reconfigure the SwrContext using the information
 564  * provided by the AVFrames.
 565  *
 566  * The original resampling context is reset even on failure.
 567  * The function calls swr_close() internally if the context is open.
 568  *
 569  * @see swr_close();
 570  *
 571  * @param swr             audio resample context
 572  * @param output          output AVFrame
 573  * @param input           input AVFrame
 574  * @return                0 on success, AVERROR on failure.
 575  */
 576 int swr_config_frame(SwrContext *swr, const AVFrame *out, const AVFrame *in);
 577
 578 /**
 579  * @}
 580  * @}
 581  */
 582
 583 #endif /* SWRESAMPLE_SWRESAMPLE_H */