2 * Copyright (c) 2012 Justin Ruggles <justin.ruggles@gmail.com>
4 * This file is part of Libav.
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.
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.
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
21 #ifndef AVRESAMPLE_AVRESAMPLE_H
22 #define AVRESAMPLE_AVRESAMPLE_H
29 #include "libavutil/audioconvert.h"
30 #include "libavutil/avutil.h"
31 #include "libavutil/dict.h"
32 #include "libavutil/log.h"
34 #include "libavresample/version.h"
36 #define AVRESAMPLE_MAX_CHANNELS 32
38 typedef struct AVAudioResampleContext AVAudioResampleContext;
40 /** Mixing Coefficient Types */
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 */
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 */
56 * Return the LIBAVRESAMPLE_VERSION_INT constant.
58 unsigned avresample_version(void);
61 * Return the libavresample build-time configuration.
62 * @return configure string
64 const char *avresample_configuration(void);
67 * Return the libavresample license.
69 const char *avresample_license(void);
72 * Get the AVClass for AVAudioResampleContext.
74 * Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options
75 * without allocating a context.
79 * @return AVClass for AVAudioResampleContext
81 const AVClass *avresample_get_class(void);
84 * Allocate AVAudioResampleContext and set options.
86 * @return allocated audio resample context, or NULL on failure
88 AVAudioResampleContext *avresample_alloc_context(void);
91 * Initialize AVAudioResampleContext.
93 * @param avr audio resample context
94 * @return 0 on success, negative AVERROR code on failure
96 int avresample_open(AVAudioResampleContext *avr);
99 * Close AVAudioResampleContext.
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.
106 * @see avresample_convert()
107 * @see avresample_set_matrix()
109 * @param avr audio resample context
111 void avresample_close(AVAudioResampleContext *avr);
114 * Free AVAudioResampleContext and associated AVOption values.
116 * This also calls avresample_close() before freeing.
118 * @param avr audio resample context
120 void avresample_free(AVAudioResampleContext **avr);
123 * Generate a channel mixing matrix.
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.
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
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
141 * @param matrix_encoding matrixed stereo downmix mode (e.g. dplii)
142 * @return 0 on success, negative AVERROR code on failure
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);
150 * Get the current channel mixing matrix.
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
158 int avresample_get_matrix(AVAudioResampleContext *avr, double *matrix,
162 * Set channel mixing matrix.
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.
170 * @see avresample_close()
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
178 int avresample_set_matrix(AVAudioResampleContext *avr, const double *matrix,
182 * Set compensation for resampling.
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
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
195 int avresample_set_compensation(AVAudioResampleContext *avr, int sample_delta,
196 int compensation_distance);
199 * Convert input samples and write them to the output FIFO.
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().
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
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().
216 * @see avresample_available()
217 * @see avresample_read()
218 * @see avresample_get_delay()
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
237 int avresample_convert(AVAudioResampleContext *avr, uint8_t **output,
238 int out_plane_size, int out_samples, uint8_t **input,
239 int in_plane_size, int in_samples);
242 * Return the number of samples currently in the resampling delay buffer.
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.
249 * @see avresample_convert()
251 * @param avr audio resample context
252 * @return number of samples currently in the resampling delay buffer
254 int avresample_get_delay(AVAudioResampleContext *avr);
257 * Return the number of available samples in the output FIFO.
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().
265 * @see avresample_read()
266 * @see avresample_convert()
268 * @param avr audio resample context
269 * @return number of samples available for reading
271 int avresample_available(AVAudioResampleContext *avr);
274 * Read samples from the output FIFO.
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.
281 * @see avresample_available()
282 * @see avresample_convert()
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
290 int avresample_read(AVAudioResampleContext *avr, uint8_t **output, int nb_samples);
292 #endif /* AVRESAMPLE_AVRESAMPLE_H */