FFmpeg
Main Page
Related Pages
Modules
Namespaces
Data Structures
Files
Examples
File List
Globals
•
All
Data Structures
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
libavresample
avresample.h
Go to the documentation of this file.
1
/*
2
* Copyright (c) 2012 Justin Ruggles <justin.ruggles@gmail.com>
3
*
4
* This file is part of FFmpeg.
5
*
6
* FFmpeg 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
* FFmpeg 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 FFmpeg; 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
* @ingroup lavr
27
* external API header
28
*/
29
30
/**
31
* @defgroup lavr Libavresample
32
* @{
33
*
34
* Libavresample (lavr) is a library that handles audio resampling, sample
35
* format conversion and mixing.
36
*
37
* Interaction with lavr is done through AVAudioResampleContext, which is
38
* allocated with avresample_alloc_context(). It is opaque, so all parameters
39
* must be set with the @ref avoptions API.
40
*
41
* For example the following code will setup conversion from planar float sample
42
* format to interleaved signed 16-bit integer, downsampling from 48kHz to
43
* 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing
44
* matrix):
45
* @code
46
* AVAudioResampleContext *avr = avresample_alloc_context();
47
* av_opt_set_int(avr, "in_channel_layout", AV_CH_LAYOUT_5POINT1, 0);
48
* av_opt_set_int(avr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0);
49
* av_opt_set_int(avr, "in_sample_rate", 48000, 0);
50
* av_opt_set_int(avr, "out_sample_rate", 44100, 0);
51
* av_opt_set_int(avr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0);
52
* av_opt_set_int(avr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0);
53
* @endcode
54
*
55
* Once the context is initialized, it must be opened with avresample_open(). If
56
* you need to change the conversion parameters, you must close the context with
57
* avresample_close(), change the parameters as described above, then reopen it
58
* again.
59
*
60
* The conversion itself is done by repeatedly calling avresample_convert().
61
* Note that the samples may get buffered in two places in lavr. The first one
62
* is the output FIFO, where the samples end up if the output buffer is not
63
* large enough. The data stored in there may be retrieved at any time with
64
* avresample_read(). The second place is the resampling delay buffer,
65
* applicable only when resampling is done. The samples in it require more input
66
* before they can be processed. Their current amount is returned by
67
* avresample_get_delay(). At the end of conversion the resampling buffer can be
68
* flushed by calling avresample_convert() with NULL input.
69
*
70
* The following code demonstrates the conversion loop assuming the parameters
71
* from above and caller-defined functions get_input() and handle_output():
72
* @code
73
* uint8_t **input;
74
* int in_linesize, in_samples;
75
*
76
* while (get_input(&input, &in_linesize, &in_samples)) {
77
* uint8_t *output
78
* int out_linesize;
79
* int out_samples = avresample_available(avr) +
80
* av_rescale_rnd(avresample_get_delay(avr) +
81
* in_samples, 44100, 48000, AV_ROUND_UP);
82
* av_samples_alloc(&output, &out_linesize, 2, out_samples,
83
* AV_SAMPLE_FMT_S16, 0);
84
* out_samples = avresample_convert(avr, &output, out_linesize, out_samples,
85
* input, in_linesize, in_samples);
86
* handle_output(output, out_linesize, out_samples);
87
* av_freep(&output);
88
* }
89
* @endcode
90
*
91
* When the conversion is finished and the FIFOs are flushed if required, the
92
* conversion context and everything associated with it must be freed with
93
* avresample_free().
94
*/
95
96
#include "
libavutil/avutil.h
"
97
#include "
libavutil/channel_layout.h
"
98
#include "
libavutil/dict.h
"
99
#include "
libavutil/log.h
"
100
101
#include "
libavresample/version.h
"
102
103
#define AVRESAMPLE_MAX_CHANNELS 32
104
105
typedef
struct
AVAudioResampleContext
AVAudioResampleContext
;
106
107
/** Mixing Coefficient Types */
108
enum
AVMixCoeffType
{
109
AV_MIX_COEFF_TYPE_Q8
,
/** 16-bit 8.8 fixed-point */
110
AV_MIX_COEFF_TYPE_Q15
,
/** 32-bit 17.15 fixed-point */
111
AV_MIX_COEFF_TYPE_FLT
,
/** floating-point */
112
AV_MIX_COEFF_TYPE_NB
,
/** Number of coeff types. Not part of ABI */
113
};
114
115
/** Resampling Filter Types */
116
enum
AVResampleFilterType
{
117
AV_RESAMPLE_FILTER_TYPE_CUBIC
,
/**< Cubic */
118
AV_RESAMPLE_FILTER_TYPE_BLACKMAN_NUTTALL
,
/**< Blackman Nuttall Windowed Sinc */
119
AV_RESAMPLE_FILTER_TYPE_KAISER
,
/**< Kaiser Windowed Sinc */
120
};
121
122
enum
AVResampleDitherMethod
{
123
AV_RESAMPLE_DITHER_NONE
,
/**< Do not use dithering */
124
AV_RESAMPLE_DITHER_RECTANGULAR
,
/**< Rectangular Dither */
125
AV_RESAMPLE_DITHER_TRIANGULAR
,
/**< Triangular Dither*/
126
AV_RESAMPLE_DITHER_TRIANGULAR_HP
,
/**< Triangular Dither with High Pass */
127
AV_RESAMPLE_DITHER_TRIANGULAR_NS
,
/**< Triangular Dither with Noise Shaping */
128
AV_RESAMPLE_DITHER_NB
,
/**< Number of dither types. Not part of ABI. */
129
};
130
131
/**
132
* Return the LIBAVRESAMPLE_VERSION_INT constant.
133
*/
134
unsigned
avresample_version
(
void
);
135
136
/**
137
* Return the libavresample build-time configuration.
138
* @return configure string
139
*/
140
const
char
*
avresample_configuration
(
void
);
141
142
/**
143
* Return the libavresample license.
144
*/
145
const
char
*
avresample_license
(
void
);
146
147
/**
148
* Get the AVClass for AVAudioResampleContext.
149
*
150
* Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options
151
* without allocating a context.
152
*
153
* @see av_opt_find().
154
*
155
* @return AVClass for AVAudioResampleContext
156
*/
157
const
AVClass
*
avresample_get_class
(
void
);
158
159
/**
160
* Allocate AVAudioResampleContext and set options.
161
*
162
* @return allocated audio resample context, or NULL on failure
163
*/
164
AVAudioResampleContext
*
avresample_alloc_context
(
void
);
165
166
/**
167
* Initialize AVAudioResampleContext.
168
*
169
* @param avr audio resample context
170
* @return 0 on success, negative AVERROR code on failure
171
*/
172
int
avresample_open
(
AVAudioResampleContext
*avr);
173
174
/**
175
* Check whether an AVAudioResampleContext is open or closed.
176
*
177
* @param avr AVAudioResampleContext to check
178
* @return 1 if avr is open, 0 if avr is closed.
179
*/
180
int
avresample_is_open
(
AVAudioResampleContext
*avr);
181
182
/**
183
* Close AVAudioResampleContext.
184
*
185
* This closes the context, but it does not change the parameters. The context
186
* can be reopened with avresample_open(). It does, however, clear the output
187
* FIFO and any remaining leftover samples in the resampling delay buffer. If
188
* there was a custom matrix being used, that is also cleared.
189
*
190
* @see avresample_convert()
191
* @see avresample_set_matrix()
192
*
193
* @param avr audio resample context
194
*/
195
void
avresample_close
(
AVAudioResampleContext
*avr);
196
197
/**
198
* Free AVAudioResampleContext and associated AVOption values.
199
*
200
* This also calls avresample_close() before freeing.
201
*
202
* @param avr audio resample context
203
*/
204
void
avresample_free
(
AVAudioResampleContext
**avr);
205
206
/**
207
* Generate a channel mixing matrix.
208
*
209
* This function is the one used internally by libavresample for building the
210
* default mixing matrix. It is made public just as a utility function for
211
* building custom matrices.
212
*
213
* @param in_layout input channel layout
214
* @param out_layout output channel layout
215
* @param center_mix_level mix level for the center channel
216
* @param surround_mix_level mix level for the surround channel(s)
217
* @param lfe_mix_level mix level for the low-frequency effects channel
218
* @param normalize if 1, coefficients will be normalized to prevent
219
* overflow. if 0, coefficients will not be
220
* normalized.
221
* @param[out] matrix mixing coefficients; matrix[i + stride * o] is
222
* the weight of input channel i in output channel o.
223
* @param stride distance between adjacent input channels in the
224
* matrix array
225
* @param matrix_encoding matrixed stereo downmix mode (e.g. dplii)
226
* @return 0 on success, negative AVERROR code on failure
227
*/
228
int
avresample_build_matrix
(uint64_t in_layout, uint64_t out_layout,
229
double
center_mix_level
,
double
surround_mix_level
,
230
double
lfe_mix_level
,
int
normalize,
double
*matrix,
231
int
stride
,
enum
AVMatrixEncoding
matrix_encoding
);
232
233
/**
234
* Get the current channel mixing matrix.
235
*
236
* If no custom matrix has been previously set or the AVAudioResampleContext is
237
* not open, an error is returned.
238
*
239
* @param avr audio resample context
240
* @param matrix mixing coefficients; matrix[i + stride * o] is the weight of
241
* input channel i in output channel o.
242
* @param stride distance between adjacent input channels in the matrix array
243
* @return 0 on success, negative AVERROR code on failure
244
*/
245
int
avresample_get_matrix
(
AVAudioResampleContext
*avr,
double
*matrix,
246
int
stride
);
247
248
/**
249
* Set channel mixing matrix.
250
*
251
* Allows for setting a custom mixing matrix, overriding the default matrix
252
* generated internally during avresample_open(). This function can be called
253
* anytime on an allocated context, either before or after calling
254
* avresample_open(), as long as the channel layouts have been set.
255
* avresample_convert() always uses the current matrix.
256
* Calling avresample_close() on the context will clear the current matrix.
257
*
258
* @see avresample_close()
259
*
260
* @param avr audio resample context
261
* @param matrix mixing coefficients; matrix[i + stride * o] is the weight of
262
* input channel i in output channel o.
263
* @param stride distance between adjacent input channels in the matrix array
264
* @return 0 on success, negative AVERROR code on failure
265
*/
266
int
avresample_set_matrix
(
AVAudioResampleContext
*avr,
const
double
*matrix,
267
int
stride
);
268
269
/**
270
* Set a customized input channel mapping.
271
*
272
* This function can only be called when the allocated context is not open.
273
* Also, the input channel layout must have already been set.
274
*
275
* Calling avresample_close() on the context will clear the channel mapping.
276
*
277
* The map for each input channel specifies the channel index in the source to
278
* use for that particular channel, or -1 to mute the channel. Source channels
279
* can be duplicated by using the same index for multiple input channels.
280
*
281
* Examples:
282
*
283
* Reordering 5.1 AAC order (C,L,R,Ls,Rs,LFE) to FFmpeg order (L,R,C,LFE,Ls,Rs):
284
* { 1, 2, 0, 5, 3, 4 }
285
*
286
* Muting the 3rd channel in 4-channel input:
287
* { 0, 1, -1, 3 }
288
*
289
* Duplicating the left channel of stereo input:
290
* { 0, 0 }
291
*
292
* @param avr audio resample context
293
* @param channel_map customized input channel mapping
294
* @return 0 on success, negative AVERROR code on failure
295
*/
296
int
avresample_set_channel_mapping
(
AVAudioResampleContext
*avr,
297
const
int
*channel_map);
298
299
/**
300
* Set compensation for resampling.
301
*
302
* This can be called anytime after avresample_open(). If resampling is not
303
* automatically enabled because of a sample rate conversion, the
304
* "force_resampling" option must have been set to 1 when opening the context
305
* in order to use resampling compensation.
306
*
307
* @param avr audio resample context
308
* @param sample_delta compensation delta, in samples
309
* @param compensation_distance compensation distance, in samples
310
* @return 0 on success, negative AVERROR code on failure
311
*/
312
int
avresample_set_compensation
(
AVAudioResampleContext
*avr,
int
sample_delta,
313
int
compensation_distance);
314
315
/**
316
* Convert input samples and write them to the output FIFO.
317
*
318
* The upper bound on the number of output samples is given by
319
* avresample_available() + (avresample_get_delay() + number of input samples) *
320
* output sample rate / input sample rate.
321
*
322
* The output data can be NULL or have fewer allocated samples than required.
323
* In this case, any remaining samples not written to the output will be added
324
* to an internal FIFO buffer, to be returned at the next call to this function
325
* or to avresample_read().
326
*
327
* If converting sample rate, there may be data remaining in the internal
328
* resampling delay buffer. avresample_get_delay() tells the number of remaining
329
* samples. To get this data as output, call avresample_convert() with NULL
330
* input.
331
*
332
* At the end of the conversion process, there may be data remaining in the
333
* internal FIFO buffer. avresample_available() tells the number of remaining
334
* samples. To get this data as output, either call avresample_convert() with
335
* NULL input or call avresample_read().
336
*
337
* @see avresample_available()
338
* @see avresample_read()
339
* @see avresample_get_delay()
340
*
341
* @param avr audio resample context
342
* @param output output data pointers
343
* @param out_plane_size output plane size, in bytes.
344
* This can be 0 if unknown, but that will lead to
345
* optimized functions not being used directly on the
346
* output, which could slow down some conversions.
347
* @param out_samples maximum number of samples that the output buffer can hold
348
* @param input input data pointers
349
* @param in_plane_size input plane size, in bytes
350
* This can be 0 if unknown, but that will lead to
351
* optimized functions not being used directly on the
352
* input, which could slow down some conversions.
353
* @param in_samples number of input samples to convert
354
* @return number of samples written to the output buffer,
355
* not including converted samples added to the internal
356
* output FIFO
357
*/
358
int
avresample_convert
(
AVAudioResampleContext
*avr,
uint8_t
**output,
359
int
out_plane_size,
int
out_samples,
uint8_t
**input,
360
int
in_plane_size,
int
in_samples);
361
362
/**
363
* Return the number of samples currently in the resampling delay buffer.
364
*
365
* When resampling, there may be a delay between the input and output. Any
366
* unconverted samples in each call are stored internally in a delay buffer.
367
* This function allows the user to determine the current number of samples in
368
* the delay buffer, which can be useful for synchronization.
369
*
370
* @see avresample_convert()
371
*
372
* @param avr audio resample context
373
* @return number of samples currently in the resampling delay buffer
374
*/
375
int
avresample_get_delay
(
AVAudioResampleContext
*avr);
376
377
/**
378
* Return the number of available samples in the output FIFO.
379
*
380
* During conversion, if the user does not specify an output buffer or
381
* specifies an output buffer that is smaller than what is needed, remaining
382
* samples that are not written to the output are stored to an internal FIFO
383
* buffer. The samples in the FIFO can be read with avresample_read() or
384
* avresample_convert().
385
*
386
* @see avresample_read()
387
* @see avresample_convert()
388
*
389
* @param avr audio resample context
390
* @return number of samples available for reading
391
*/
392
int
avresample_available
(
AVAudioResampleContext
*avr);
393
394
/**
395
* Read samples from the output FIFO.
396
*
397
* During conversion, if the user does not specify an output buffer or
398
* specifies an output buffer that is smaller than what is needed, remaining
399
* samples that are not written to the output are stored to an internal FIFO
400
* buffer. This function can be used to read samples from that internal FIFO.
401
*
402
* @see avresample_available()
403
* @see avresample_convert()
404
*
405
* @param avr audio resample context
406
* @param output output data pointers. May be NULL, in which case
407
* nb_samples of data is discarded from output FIFO.
408
* @param nb_samples number of samples to read from the FIFO
409
* @return the number of samples written to output
410
*/
411
int
avresample_read
(
AVAudioResampleContext
*avr,
uint8_t
**output,
int
nb_samples);
412
413
/**
414
* @}
415
*/
416
417
#endif
/* AVRESAMPLE_AVRESAMPLE_H */
Generated on Sun Mar 23 2014 23:50:14 for FFmpeg by
1.8.2