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
libswresample
swresample.h
Go to the documentation of this file.
1
/*
2
* Copyright (C) 2011-2013 Michael Niedermayer (michaelni@gmx.at)
3
*
4
* This file is part of libswresample
5
*
6
* libswresample 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
* libswresample 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 libswresample; if not, write to the Free Software
18
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19
*/
20
21
#ifndef SWRESAMPLE_SWRESAMPLE_H
22
#define SWRESAMPLE_SWRESAMPLE_H
23
24
/**
25
* @file
26
* @ingroup lswr
27
* libswresample public header
28
*/
29
30
/**
31
* @defgroup lswr Libswresample
32
* @{
33
*
34
* Libswresample (lswr) is a library that handles audio resampling, sample
35
* format conversion and mixing.
36
*
37
* Interaction with lswr is done through SwrContext, which is
38
* allocated with swr_alloc() or swr_alloc_set_opts(). 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
* SwrContext *swr = swr_alloc();
47
* av_opt_set_channel_layout(swr, "in_channel_layout", AV_CH_LAYOUT_5POINT1, 0);
48
* av_opt_set_channel_layout(swr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0);
49
* av_opt_set_int(swr, "in_sample_rate", 48000, 0);
50
* av_opt_set_int(swr, "out_sample_rate", 44100, 0);
51
* av_opt_set_sample_fmt(swr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0);
52
* av_opt_set_sample_fmt(swr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0);
53
* @endcode
54
*
55
* Once all values have been set, it must be initialized with swr_init(). If
56
* you need to change the conversion parameters, you can change the parameters
57
* as described above, or by using swr_alloc_set_opts(), then call swr_init()
58
* again.
59
*
60
* The conversion itself is done by repeatedly calling swr_convert().
61
* Note that the samples may get buffered in swr if you provide insufficient
62
* output space or if sample rate conversion is done, which requires "future"
63
* samples. Samples that do not require future input can be retrieved at any
64
* time by using swr_convert() (in_count can be set to 0).
65
* At the end of conversion the resampling buffer can be flushed by calling
66
* swr_convert() with NULL in and 0 in_count.
67
*
68
* The delay between input and output, can at any time be found by using
69
* swr_get_delay().
70
*
71
* The following code demonstrates the conversion loop assuming the parameters
72
* from above and caller-defined functions get_input() and handle_output():
73
* @code
74
* uint8_t **input;
75
* int in_samples;
76
*
77
* while (get_input(&input, &in_samples)) {
78
* uint8_t *output;
79
* int out_samples = av_rescale_rnd(swr_get_delay(swr, 48000) +
80
* in_samples, 44100, 48000, AV_ROUND_UP);
81
* av_samples_alloc(&output, NULL, 2, out_samples,
82
* AV_SAMPLE_FMT_S16, 0);
83
* out_samples = swr_convert(swr, &output, out_samples,
84
* input, in_samples);
85
* handle_output(output, out_samples);
86
* av_freep(&output);
87
* }
88
* @endcode
89
*
90
* When the conversion is finished, the conversion
91
* context and everything associated with it must be freed with swr_free().
92
* There will be no memory leak if the data is not completely flushed before
93
* swr_free().
94
*/
95
96
#include <stdint.h>
97
#include "
libavutil/samplefmt.h
"
98
99
#include "
libswresample/version.h
"
100
101
#if LIBSWRESAMPLE_VERSION_MAJOR < 1
102
#define SWR_CH_MAX 32
///< Maximum number of channels
103
#endif
104
105
#define SWR_FLAG_RESAMPLE 1
///< Force resampling even if equal sample rate
106
//TODO use int resample ?
107
//long term TODO can we enable this dynamically?
108
109
enum
SwrDitherType
{
110
SWR_DITHER_NONE
= 0,
111
SWR_DITHER_RECTANGULAR
,
112
SWR_DITHER_TRIANGULAR
,
113
SWR_DITHER_TRIANGULAR_HIGHPASS
,
114
115
SWR_DITHER_NS
= 64,
///< not part of API/ABI
116
SWR_DITHER_NS_LIPSHITZ
,
117
SWR_DITHER_NS_F_WEIGHTED
,
118
SWR_DITHER_NS_MODIFIED_E_WEIGHTED
,
119
SWR_DITHER_NS_IMPROVED_E_WEIGHTED
,
120
SWR_DITHER_NS_SHIBATA
,
121
SWR_DITHER_NS_LOW_SHIBATA
,
122
SWR_DITHER_NS_HIGH_SHIBATA
,
123
SWR_DITHER_NB
,
///< not part of API/ABI
124
};
125
126
/** Resampling Engines */
127
enum
SwrEngine
{
128
SWR_ENGINE_SWR
,
/**< SW Resampler */
129
SWR_ENGINE_SOXR
,
/**< SoX Resampler */
130
SWR_ENGINE_NB
,
///< not part of API/ABI
131
};
132
133
/** Resampling Filter Types */
134
enum
SwrFilterType
{
135
SWR_FILTER_TYPE_CUBIC
,
/**< Cubic */
136
SWR_FILTER_TYPE_BLACKMAN_NUTTALL
,
/**< Blackman Nuttall Windowed Sinc */
137
SWR_FILTER_TYPE_KAISER
,
/**< Kaiser Windowed Sinc */
138
};
139
140
typedef
struct
SwrContext
SwrContext
;
141
142
/**
143
* Get the AVClass for swrContext. It can be used in combination with
144
* AV_OPT_SEARCH_FAKE_OBJ for examining options.
145
*
146
* @see av_opt_find().
147
*/
148
const
AVClass
*
swr_get_class
(
void
);
149
150
/**
151
* Allocate SwrContext.
152
*
153
* If you use this function you will need to set the parameters (manually or
154
* with swr_alloc_set_opts()) before calling swr_init().
155
*
156
* @see swr_alloc_set_opts(), swr_init(), swr_free()
157
* @return NULL on error, allocated context otherwise
158
*/
159
struct
SwrContext
*
swr_alloc
(
void
);
160
161
/**
162
* Initialize context after user parameters have been set.
163
*
164
* @return AVERROR error code in case of failure.
165
*/
166
int
swr_init
(
struct
SwrContext
*
s
);
167
168
/**
169
* Check whether an swr context has been initialized or not.
170
*
171
* @return positive if it has been initialized, 0 if not initialized
172
*/
173
int
swr_is_initialized
(
struct
SwrContext
*
s
);
174
175
/**
176
* Allocate SwrContext if needed and set/reset common parameters.
177
*
178
* This function does not require s to be allocated with swr_alloc(). On the
179
* other hand, swr_alloc() can use swr_alloc_set_opts() to set the parameters
180
* on the allocated context.
181
*
182
* @param s Swr context, can be NULL
183
* @param out_ch_layout output channel layout (AV_CH_LAYOUT_*)
184
* @param out_sample_fmt output sample format (AV_SAMPLE_FMT_*).
185
* @param out_sample_rate output sample rate (frequency in Hz)
186
* @param in_ch_layout input channel layout (AV_CH_LAYOUT_*)
187
* @param in_sample_fmt input sample format (AV_SAMPLE_FMT_*).
188
* @param in_sample_rate input sample rate (frequency in Hz)
189
* @param log_offset logging level offset
190
* @param log_ctx parent logging context, can be NULL
191
*
192
* @see swr_init(), swr_free()
193
* @return NULL on error, allocated context otherwise
194
*/
195
struct
SwrContext
*
swr_alloc_set_opts
(
struct
SwrContext
*
s
,
196
int64_t
out_ch_layout
,
enum
AVSampleFormat
out_sample_fmt
,
int
out_sample_rate
,
197
int64_t
in_ch_layout
,
enum
AVSampleFormat
in_sample_fmt
,
int
in_sample_rate
,
198
int
log_offset,
void
*
log_ctx
);
199
200
/**
201
* Free the given SwrContext and set the pointer to NULL.
202
*/
203
void
swr_free
(
struct
SwrContext
**
s
);
204
205
/**
206
* Convert audio.
207
*
208
* in and in_count can be set to 0 to flush the last few samples out at the
209
* end.
210
*
211
* If more input is provided than output space then the input will be buffered.
212
* You can avoid this buffering by providing more output space than input.
213
* Convertion will run directly without copying whenever possible.
214
*
215
* @param s allocated Swr context, with parameters set
216
* @param out output buffers, only the first one need be set in case of packed audio
217
* @param out_count amount of space available for output in samples per channel
218
* @param in input buffers, only the first one need to be set in case of packed audio
219
* @param in_count number of input samples available in one channel
220
*
221
* @return number of samples output per channel, negative value on error
222
*/
223
int
swr_convert
(
struct
SwrContext
*
s
,
uint8_t
**
out
,
int
out_count,
224
const
uint8_t
**
in
,
int
in_count);
225
226
/**
227
* Convert the next timestamp from input to output
228
* timestamps are in 1/(in_sample_rate * out_sample_rate) units.
229
*
230
* @note There are 2 slightly differently behaving modes.
231
* First is when automatic timestamp compensation is not used, (min_compensation >= FLT_MAX)
232
* in this case timestamps will be passed through with delays compensated
233
* Second is when automatic timestamp compensation is used, (min_compensation < FLT_MAX)
234
* in this case the output timestamps will match output sample numbers
235
*
236
* @param pts timestamp for the next input sample, INT64_MIN if unknown
237
* @return the output timestamp for the next output sample
238
*/
239
int64_t
swr_next_pts
(
struct
SwrContext
*
s
, int64_t pts);
240
241
/**
242
* Activate resampling compensation.
243
*/
244
int
swr_set_compensation
(
struct
SwrContext
*
s
,
int
sample_delta,
int
compensation_distance);
245
246
/**
247
* Set a customized input channel mapping.
248
*
249
* @param s allocated Swr context, not yet initialized
250
* @param channel_map customized input channel mapping (array of channel
251
* indexes, -1 for a muted channel)
252
* @return AVERROR error code in case of failure.
253
*/
254
int
swr_set_channel_mapping
(
struct
SwrContext
*
s
,
const
int
*
channel_map
);
255
256
/**
257
* Set a customized remix matrix.
258
*
259
* @param s allocated Swr context, not yet initialized
260
* @param matrix remix coefficients; matrix[i + stride * o] is
261
* the weight of input channel i in output channel o
262
* @param stride offset between lines of the matrix
263
* @return AVERROR error code in case of failure.
264
*/
265
int
swr_set_matrix
(
struct
SwrContext
*
s
,
const
double
*
matrix
,
int
stride
);
266
267
/**
268
* Drops the specified number of output samples.
269
*/
270
int
swr_drop_output
(
struct
SwrContext
*
s
,
int
count
);
271
272
/**
273
* Injects the specified number of silence samples.
274
*/
275
int
swr_inject_silence
(
struct
SwrContext
*
s
,
int
count
);
276
277
/**
278
* Gets the delay the next input sample will experience relative to the next output sample.
279
*
280
* Swresample can buffer data if more input has been provided than available
281
* output space, also converting between sample rates needs a delay.
282
* This function returns the sum of all such delays.
283
* The exact delay is not necessarily an integer value in either input or
284
* output sample rate. Especially when downsampling by a large value, the
285
* output sample rate may be a poor choice to represent the delay, similarly
286
* for upsampling and the input sample rate.
287
*
288
* @param s swr context
289
* @param base timebase in which the returned delay will be
290
* if its set to 1 the returned delay is in seconds
291
* if its set to 1000 the returned delay is in milli seconds
292
* if its set to the input sample rate then the returned delay is in input samples
293
* if its set to the output sample rate then the returned delay is in output samples
294
* an exact rounding free delay can be found by using LCM(in_sample_rate, out_sample_rate)
295
* @returns the delay in 1/base units.
296
*/
297
int64_t
swr_get_delay
(
struct
SwrContext
*
s
, int64_t base);
298
299
/**
300
* Return the LIBSWRESAMPLE_VERSION_INT constant.
301
*/
302
unsigned
swresample_version
(
void
);
303
304
/**
305
* Return the swr build-time configuration.
306
*/
307
const
char
*
swresample_configuration
(
void
);
308
309
/**
310
* Return the swr license.
311
*/
312
const
char
*
swresample_license
(
void
);
313
314
/**
315
* @}
316
*/
317
318
#endif
/* SWRESAMPLE_SWRESAMPLE_H */
Generated on Sun Mar 23 2014 23:50:15 for FFmpeg by
1.8.2