b93aba5d73558043de55a6249160cee7323303f9
[libav.git] / 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 */