git.sesse.net Git - ffmpeg/blob - libavresample/avresample.h

   1 /*
   2  * Copyright (c) 2012 Justin Ruggles <justin.ruggles@gmail.com>
   3  *
   4  * This file is part of Libav.
   5  *
   6  * Libav 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  * Libav 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 Libav; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19  */
  20
  21 #ifndef AVRESAMPLE_AVRESAMPLE_H
  22 #define AVRESAMPLE_AVRESAMPLE_H
  23
  24 /**
  25  * @file
  26  * external API header
  27  */
  28
  29 #include "libavutil/audioconvert.h"
  30 #include "libavutil/avutil.h"
  31 #include "libavutil/dict.h"
  32 #include "libavutil/log.h"
  33
  34 #include "libavresample/version.h"
  35
  36 #define AVRESAMPLE_MAX_CHANNELS 32
  37
  38 typedef struct AVAudioResampleContext AVAudioResampleContext;
  39
  40 /** Mixing Coefficient Types */
  41 enum AVMixCoeffType {
  42     AV_MIX_COEFF_TYPE_Q8,   /** 16-bit 8.8 fixed-point                      */
  43     AV_MIX_COEFF_TYPE_Q15,  /** 32-bit 17.15 fixed-point                    */
  44     AV_MIX_COEFF_TYPE_FLT,  /** floating-point                              */
  45     AV_MIX_COEFF_TYPE_NB,   /** Number of coeff types. Not part of ABI      */
  46 };
  47
  48 /** Resampling Filter Types */
  49 enum AVResampleFilterType {
  50     AV_RESAMPLE_FILTER_TYPE_CUBIC,              /**< Cubic */
  51     AV_RESAMPLE_FILTER_TYPE_BLACKMAN_NUTTALL,   /**< Blackman Nuttall Windowed Sinc */
  52     AV_RESAMPLE_FILTER_TYPE_KAISER,             /**< Kaiser Windowed Sinc */
  53 };
  54
  55 /**
  56  * Return the LIBAVRESAMPLE_VERSION_INT constant.
  57  */
  58 unsigned avresample_version(void);
  59
  60 /**
  61  * Return the libavresample build-time configuration.
  62  * @return  configure string
  63  */
  64 const char *avresample_configuration(void);
  65
  66 /**
  67  * Return the libavresample license.
  68  */
  69 const char *avresample_license(void);
  70
  71 /**
  72  * Get the AVClass for AVAudioResampleContext.
  73  *
  74  * Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options
  75  * without allocating a context.
  76  *
  77  * @see av_opt_find().
  78  *
  79  * @return AVClass for AVAudioResampleContext
  80  */
  81 const AVClass *avresample_get_class(void);
  82
  83 /**
  84  * Allocate AVAudioResampleContext and set options.
  85  *
  86  * @return  allocated audio resample context, or NULL on failure
  87  */
  88 AVAudioResampleContext *avresample_alloc_context(void);
  89
  90 /**
  91  * Initialize AVAudioResampleContext.
  92  *
  93  * @param avr  audio resample context
  94  * @return     0 on success, negative AVERROR code on failure
  95  */
  96 int avresample_open(AVAudioResampleContext *avr);
  97
  98 /**
  99  * Close AVAudioResampleContext.
 100  *
 101  * This closes the context, but it does not change the parameters. The context
 102  * can be reopened with avresample_open(). It does, however, clear the output
 103  * FIFO and any remaining leftover samples in the resampling delay buffer. If
 104  * there was a custom matrix being used, that is also cleared.
 105  *
 106  * @see avresample_convert()
 107  * @see avresample_set_matrix()
 108  *
 109  * @param avr  audio resample context
 110  */
 111 void avresample_close(AVAudioResampleContext *avr);
 112
 113 /**
 114  * Free AVAudioResampleContext and associated AVOption values.
 115  *
 116  * This also calls avresample_close() before freeing.
 117  *
 118  * @param avr  audio resample context
 119  */
 120 void avresample_free(AVAudioResampleContext **avr);
 121
 122 /**
 123  * Generate a channel mixing matrix.
 124  *
 125  * This function is the one used internally by libavresample for building the
 126  * default mixing matrix. It is made public just as a utility function for
 127  * building custom matrices.
 128  *
 129  * @param in_layout           input channel layout
 130  * @param out_layout          output channel layout
 131  * @param center_mix_level    mix level for the center channel
 132  * @param surround_mix_level  mix level for the surround channel(s)
 133  * @param lfe_mix_level       mix level for the low-frequency effects channel
 134  * @param normalize           if 1, coefficients will be normalized to prevent
 135  *                            overflow. if 0, coefficients will not be
 136  *                            normalized.
 137  * @param[out] matrix         mixing coefficients; matrix[i + stride * o] is
 138  *                            the weight of input channel i in output channel o.
 139  * @param stride              distance between adjacent input channels in the
 140  *                            matrix array
 141  * @param matrix_encoding     matrixed stereo downmix mode (e.g. dplii)
 142  * @return                    0 on success, negative AVERROR code on failure
 143  */
 144 int avresample_build_matrix(uint64_t in_layout, uint64_t out_layout,
 145                             double center_mix_level, double surround_mix_level,
 146                             double lfe_mix_level, int normalize, double *matrix,
 147                             int stride, enum AVMatrixEncoding matrix_encoding);
 148
 149 /**
 150  * Get the current channel mixing matrix.
 151  *
 152  * @param avr     audio resample context
 153  * @param matrix  mixing coefficients; matrix[i + stride * o] is the weight of
 154  *                input channel i in output channel o.
 155  * @param stride  distance between adjacent input channels in the matrix array
 156  * @return        0 on success, negative AVERROR code on failure
 157  */
 158 int avresample_get_matrix(AVAudioResampleContext *avr, double *matrix,
 159                           int stride);
 160
 161 /**
 162  * Set channel mixing matrix.
 163  *
 164  * Allows for setting a custom mixing matrix, overriding the default matrix
 165  * generated internally during avresample_open(). This function can be called
 166  * anytime on an allocated context, either before or after calling
 167  * avresample_open(). avresample_convert() always uses the current matrix.
 168  * Calling avresample_close() on the context will clear the current matrix.
 169  *
 170  * @see avresample_close()
 171  *
 172  * @param avr     audio resample context
 173  * @param matrix  mixing coefficients; matrix[i + stride * o] is the weight of
 174  *                input channel i in output channel o.
 175  * @param stride  distance between adjacent input channels in the matrix array
 176  * @return        0 on success, negative AVERROR code on failure
 177  */
 178 int avresample_set_matrix(AVAudioResampleContext *avr, const double *matrix,
 179                           int stride);
 180
 181 /**
 182  * Set compensation for resampling.
 183  *
 184  * This can be called anytime after avresample_open(). If resampling was not
 185  * being done previously, the AVAudioResampleContext is closed and reopened
 186  * with resampling enabled. In this case, any samples remaining in the output
 187  * FIFO and the current channel mixing matrix will be restored after reopening
 188  * the context.
 189  *
 190  * @param avr                    audio resample context
 191  * @param sample_delta           compensation delta, in samples
 192  * @param compensation_distance  compensation distance, in samples
 193  * @return                       0 on success, negative AVERROR code on failure
 194  */
 195 int avresample_set_compensation(AVAudioResampleContext *avr, int sample_delta,
 196                                 int compensation_distance);
 197
 198 /**
 199  * Convert input samples and write them to the output FIFO.
 200  *
 201  * The output data can be NULL or have fewer allocated samples than required.
 202  * In this case, any remaining samples not written to the output will be added
 203  * to an internal FIFO buffer, to be returned at the next call to this function
 204  * or to avresample_read().
 205  *
 206  * If converting sample rate, there may be data remaining in the internal
 207  * resampling delay buffer. avresample_get_delay() tells the number of remaining
 208  * samples. To get this data as output, call avresample_convert() with NULL
 209  * input.
 210  *
 211  * At the end of the conversion process, there may be data remaining in the
 212  * internal FIFO buffer. avresample_available() tells the number of remaining
 213  * samples. To get this data as output, either call avresample_convert() with
 214  * NULL input or call avresample_read().
 215  *
 216  * @see avresample_available()
 217  * @see avresample_read()
 218  * @see avresample_get_delay()
 219  *
 220  * @param avr             audio resample context
 221  * @param output          output data pointers
 222  * @param out_plane_size  output plane size, in bytes.
 223  *                        This can be 0 if unknown, but that will lead to
 224  *                        optimized functions not being used directly on the
 225  *                        output, which could slow down some conversions.
 226  * @param out_samples     maximum number of samples that the output buffer can hold
 227  * @param input           input data pointers
 228  * @param in_plane_size   input plane size, in bytes
 229  *                        This can be 0 if unknown, but that will lead to
 230  *                        optimized functions not being used directly on the
 231  *                        input, which could slow down some conversions.
 232  * @param in_samples      number of input samples to convert
 233  * @return                number of samples written to the output buffer,
 234  *                        not including converted samples added to the internal
 235  *                        output FIFO
 236  */
 237 int avresample_convert(AVAudioResampleContext *avr, void **output,
 238                        int out_plane_size, int out_samples, void **input,
 239                        int in_plane_size, int in_samples);
 240
 241 /**
 242  * Return the number of samples currently in the resampling delay buffer.
 243  *
 244  * When resampling, there may be a delay between the input and output. Any
 245  * unconverted samples in each call are stored internally in a delay buffer.
 246  * This function allows the user to determine the current number of samples in
 247  * the delay buffer, which can be useful for synchronization.
 248  *
 249  * @see avresample_convert()
 250  *
 251  * @param avr  audio resample context
 252  * @return     number of samples currently in the resampling delay buffer
 253  */
 254 int avresample_get_delay(AVAudioResampleContext *avr);
 255
 256 /**
 257  * Return the number of available samples in the output FIFO.
 258  *
 259  * During conversion, if the user does not specify an output buffer or
 260  * specifies an output buffer that is smaller than what is needed, remaining
 261  * samples that are not written to the output are stored to an internal FIFO
 262  * buffer. The samples in the FIFO can be read with avresample_read() or
 263  * avresample_convert().
 264  *
 265  * @see avresample_read()
 266  * @see avresample_convert()
 267  *
 268  * @param avr  audio resample context
 269  * @return     number of samples available for reading
 270  */
 271 int avresample_available(AVAudioResampleContext *avr);
 272
 273 /**
 274  * Read samples from the output FIFO.
 275  *
 276  * During conversion, if the user does not specify an output buffer or
 277  * specifies an output buffer that is smaller than what is needed, remaining
 278  * samples that are not written to the output are stored to an internal FIFO
 279  * buffer. This function can be used to read samples from that internal FIFO.
 280  *
 281  * @see avresample_available()
 282  * @see avresample_convert()
 283  *
 284  * @param avr         audio resample context
 285  * @param output      output data pointers. May be NULL, in which case
 286  *                    nb_samples of data is discarded from output FIFO.
 287  * @param nb_samples  number of samples to read from the FIFO
 288  * @return            the number of samples written to output
 289  */
 290 int avresample_read(AVAudioResampleContext *avr, void **output, int nb_samples);
 291
 292 #endif /* AVRESAMPLE_AVRESAMPLE_H */