git.sesse.net Git - ffmpeg/blob - 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_Q6,   /** 16-bit 10.6 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 /**
  49  * Return the LIBAVRESAMPLE_VERSION_INT constant.
  50  */
  51 unsigned avresample_version(void);
  52
  53 /**
  54  * Return the libavresample build-time configuration.
  55  * @return  configure string
  56  */
  57 const char *avresample_configuration(void);
  58
  59 /**
  60  * Return the libavresample license.
  61  */
  62 const char *avresample_license(void);
  63
  64 /**
  65  * Get the AVClass for AVAudioResampleContext.
  66  *
  67  * Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options
  68  * without allocating a context.
  69  *
  70  * @see av_opt_find().
  71  *
  72  * @return AVClass for AVAudioResampleContext
  73  */
  74 const AVClass *avresample_get_class(void);
  75
  76 /**
  77  * Allocate AVAudioResampleContext and set options.
  78  *
  79  * @return  allocated audio resample context, or NULL on failure
  80  */
  81 AVAudioResampleContext *avresample_alloc_context(void);
  82
  83 /**
  84  * Initialize AVAudioResampleContext.
  85  *
  86  * @param avr  audio resample context
  87  * @return     0 on success, negative AVERROR code on failure
  88  */
  89 int avresample_open(AVAudioResampleContext *avr);
  90
  91 /**
  92  * Close AVAudioResampleContext.
  93  *
  94  * This closes the context, but it does not change the parameters. The context
  95  * can be reopened with avresample_open(). It does, however, clear the output
  96  * FIFO and any remaining leftover samples in the resampling delay buffer. If
  97  * there was a custom matrix being used, that is also cleared.
  98  *
  99  * @see avresample_convert()
 100  * @see avresample_set_matrix()
 101  *
 102  * @param avr  audio resample context
 103  */
 104 void avresample_close(AVAudioResampleContext *avr);
 105
 106 /**
 107  * Free AVAudioResampleContext and associated AVOption values.
 108  *
 109  * This also calls avresample_close() before freeing.
 110  *
 111  * @param avr  audio resample context
 112  */
 113 void avresample_free(AVAudioResampleContext **avr);
 114
 115 /**
 116  * Generate a channel mixing matrix.
 117  *
 118  * This function is the one used internally by libavresample for building the
 119  * default mixing matrix. It is made public just as a utility function for
 120  * building custom matrices.
 121  *
 122  * @param in_layout           input channel layout
 123  * @param out_layout          output channel layout
 124  * @param center_mix_level    mix level for the center channel
 125  * @param surround_mix_level  mix level for the surround channel(s)
 126  * @param lfe_mix_level       mix level for the low-frequency effects channel
 127  * @param normalize           if 1, coefficients will be normalized to prevent
 128  *                            overflow. if 0, coefficients will not be
 129  *                            normalized.
 130  * @param[out] matrix         mixing coefficients; matrix[i + stride * o] is
 131  *                            the weight of input channel i in output channel o.
 132  * @param stride              distance between adjacent input channels in the
 133  *                            matrix array
 134  * @return                    0 on success, negative AVERROR code on failure
 135  */
 136 int avresample_build_matrix(uint64_t in_layout, uint64_t out_layout,
 137                             double center_mix_level, double surround_mix_level,
 138                             double lfe_mix_level, int normalize, double *matrix,
 139                             int stride);
 140
 141 /**
 142  * Get the current channel mixing matrix.
 143  *
 144  * @param avr     audio resample context
 145  * @param matrix  mixing coefficients; matrix[i + stride * o] is the weight of
 146  *                input channel i in output channel o.
 147  * @param stride  distance between adjacent input channels in the matrix array
 148  * @return        0 on success, negative AVERROR code on failure
 149  */
 150 int avresample_get_matrix(AVAudioResampleContext *avr, double *matrix,
 151                           int stride);
 152
 153 /**
 154  * Set channel mixing matrix.
 155  *
 156  * Allows for setting a custom mixing matrix, overriding the default matrix
 157  * generated internally during avresample_open(). This function can be called
 158  * anytime on an allocated context, either before or after calling
 159  * avresample_open(). avresample_convert() always uses the current matrix.
 160  * Calling avresample_close() on the context will clear the current matrix.
 161  *
 162  * @see avresample_close()
 163  *
 164  * @param avr     audio resample context
 165  * @param matrix  mixing coefficients; matrix[i + stride * o] is the weight of
 166  *                input channel i in output channel o.
 167  * @param stride  distance between adjacent input channels in the matrix array
 168  * @return        0 on success, negative AVERROR code on failure
 169  */
 170 int avresample_set_matrix(AVAudioResampleContext *avr, const double *matrix,
 171                           int stride);
 172
 173 /**
 174  * Set compensation for resampling.
 175  *
 176  * This can be called anytime after avresample_open(). If resampling was not
 177  * being done previously, the AVAudioResampleContext is closed and reopened
 178  * with resampling enabled. In this case, any samples remaining in the output
 179  * FIFO and the current channel mixing matrix will be restored after reopening
 180  * the context.
 181  *
 182  * @param avr                    audio resample context
 183  * @param sample_delta           compensation delta, in samples
 184  * @param compensation_distance  compensation distance, in samples
 185  * @return                       0 on success, negative AVERROR code on failure
 186  */
 187 int avresample_set_compensation(AVAudioResampleContext *avr, int sample_delta,
 188                                 int compensation_distance);
 189
 190 /**
 191  * Convert input samples and write them to the output FIFO.
 192  *
 193  * The output data can be NULL or have fewer allocated samples than required.
 194  * In this case, any remaining samples not written to the output will be added
 195  * to an internal FIFO buffer, to be returned at the next call to this function
 196  * or to avresample_read().
 197  *
 198  * If converting sample rate, there may be data remaining in the internal
 199  * resampling delay buffer. avresample_get_delay() tells the number of remaining
 200  * samples. To get this data as output, call avresample_convert() with NULL
 201  * input.
 202  *
 203  * At the end of the conversion process, there may be data remaining in the
 204  * internal FIFO buffer. avresample_available() tells the number of remaining
 205  * samples. To get this data as output, either call avresample_convert() with
 206  * NULL input or call avresample_read().
 207  *
 208  * @see avresample_available()
 209  * @see avresample_read()
 210  * @see avresample_get_delay()
 211  *
 212  * @param avr             audio resample context
 213  * @param output          output data pointers
 214  * @param out_plane_size  output plane size, in bytes.
 215  *                        This can be 0 if unknown, but that will lead to
 216  *                        optimized functions not being used directly on the
 217  *                        output, which could slow down some conversions.
 218  * @param out_samples     maximum number of samples that the output buffer can hold
 219  * @param input           input data pointers
 220  * @param in_plane_size   input plane size, in bytes
 221  *                        This can be 0 if unknown, but that will lead to
 222  *                        optimized functions not being used directly on the
 223  *                        input, which could slow down some conversions.
 224  * @param in_samples      number of input samples to convert
 225  * @return                number of samples written to the output buffer,
 226  *                        not including converted samples added to the internal
 227  *                        output FIFO
 228  */
 229 int avresample_convert(AVAudioResampleContext *avr, void **output,
 230                        int out_plane_size, int out_samples, void **input,
 231                        int in_plane_size, int in_samples);
 232
 233 /**
 234  * Return the number of samples currently in the resampling delay buffer.
 235  *
 236  * When resampling, there may be a delay between the input and output. Any
 237  * unconverted samples in each call are stored internally in a delay buffer.
 238  * This function allows the user to determine the current number of samples in
 239  * the delay buffer, which can be useful for synchronization.
 240  *
 241  * @see avresample_convert()
 242  *
 243  * @param avr  audio resample context
 244  * @return     number of samples currently in the resampling delay buffer
 245  */
 246 int avresample_get_delay(AVAudioResampleContext *avr);
 247
 248 /**
 249  * Return the number of available samples in the output FIFO.
 250  *
 251  * During conversion, if the user does not specify an output buffer or
 252  * specifies an output buffer that is smaller than what is needed, remaining
 253  * samples that are not written to the output are stored to an internal FIFO
 254  * buffer. The samples in the FIFO can be read with avresample_read() or
 255  * avresample_convert().
 256  *
 257  * @see avresample_read()
 258  * @see avresample_convert()
 259  *
 260  * @param avr  audio resample context
 261  * @return     number of samples available for reading
 262  */
 263 int avresample_available(AVAudioResampleContext *avr);
 264
 265 /**
 266  * Read samples from the output FIFO.
 267  *
 268  * During conversion, if the user does not specify an output buffer or
 269  * specifies an output buffer that is smaller than what is needed, remaining
 270  * samples that are not written to the output are stored to an internal FIFO
 271  * buffer. This function can be used to read samples from that internal FIFO.
 272  *
 273  * @see avresample_available()
 274  * @see avresample_convert()
 275  *
 276  * @param avr         audio resample context
 277  * @param output      output data pointers
 278  * @param nb_samples  number of samples to read from the FIFO
 279  * @return            the number of samples written to output
 280  */
 281 int avresample_read(AVAudioResampleContext *avr, void **output, int nb_samples);
 282
 283 #endif /* AVRESAMPLE_AVRESAMPLE_H */