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
* The first thing you will need to do in order to use lswr is to allocate
42
* SwrContext. This can be done with swr_alloc() or swr_alloc_set_opts(). If you
43
* are using the former, you must set options through the @ref avoptions API.
44
* The latter function provides the same feature, but it allows you to set some
45
* common options in the same statement.
46
*
47
* For example the following code will setup conversion from planar float sample
48
* format to interleaved signed 16-bit integer, downsampling from 48kHz to
49
* 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing
50
* matrix). This is using the swr_alloc() function.
51
* @code
52
* SwrContext *swr = swr_alloc();
53
* av_opt_set_channel_layout(swr, "in_channel_layout", AV_CH_LAYOUT_5POINT1, 0);
54
* av_opt_set_channel_layout(swr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0);
55
* av_opt_set_int(swr, "in_sample_rate", 48000, 0);
56
* av_opt_set_int(swr, "out_sample_rate", 44100, 0);
57
* av_opt_set_sample_fmt(swr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0);
58
* av_opt_set_sample_fmt(swr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0);
59
* @endcode
60
*
61
* The same job can be done using swr_alloc_set_opts() as well:
62
* @code
63
* SwrContext *swr = swr_alloc_set_opts(NULL, // we're allocating a new context
64
* AV_CH_LAYOUT_STEREO, // out_ch_layout
65
* AV_SAMPLE_FMT_S16, // out_sample_fmt
66
* 44100, // out_sample_rate
67
* AV_CH_LAYOUT_5POINT1, // in_ch_layout
68
* AV_SAMPLE_FMT_FLTP, // in_sample_fmt
69
* 48000, // in_sample_rate
70
* 0, // log_offset
71
* NULL); // log_ctx
72
* @endcode
73
*
74
* Once all values have been set, it must be initialized with swr_init(). If
75
* you need to change the conversion parameters, you can change the parameters
76
* using @ref AVOptions, as described above in the first example; or by using
77
* swr_alloc_set_opts(), but with the first argument the allocated context.
78
* You must then call swr_init() again.
79
*
80
* The conversion itself is done by repeatedly calling swr_convert().
81
* Note that the samples may get buffered in swr if you provide insufficient
82
* output space or if sample rate conversion is done, which requires "future"
83
* samples. Samples that do not require future input can be retrieved at any
84
* time by using swr_convert() (in_count can be set to 0).
85
* At the end of conversion the resampling buffer can be flushed by calling
86
* swr_convert() with NULL in and 0 in_count.
87
*
88
* The samples used in the conversion process can be managed with the libavutil
89
* @ref lavu_sampmanip "samples manipulation" API, including av_samples_alloc()
90
* function used in the following example.
91
*
92
* The delay between input and output, can at any time be found by using
93
* swr_get_delay().
94
*
95
* The following code demonstrates the conversion loop assuming the parameters
96
* from above and caller-defined functions get_input() and handle_output():
97
* @code
98
* uint8_t **input;
99
* int in_samples;
100
*
101
* while (get_input(&input, &in_samples)) {
102
* uint8_t *output;
103
* int out_samples = av_rescale_rnd(swr_get_delay(swr, 48000) +
104
* in_samples, 44100, 48000, AV_ROUND_UP);
105
* av_samples_alloc(&output, NULL, 2, out_samples,
106
* AV_SAMPLE_FMT_S16, 0);
107
* out_samples = swr_convert(swr, &output, out_samples,
108
* input, in_samples);
109
* handle_output(output, out_samples);
110
* av_freep(&output);
111
* }
112
* @endcode
113
*
114
* When the conversion is finished, the conversion
115
* context and everything associated with it must be freed with swr_free().
116
* A swr_close() function is also available, but it exists mainly for
117
* compatibility with libavresample, and is not required to be called.
118
*
119
* There will be no memory leak if the data is not completely flushed before
120
* swr_free().
121
*/
122
123
#include <stdint.h>
124
#include "
libavutil/samplefmt.h
"
125
126
#include "
libswresample/version.h
"
127
128
#if LIBSWRESAMPLE_VERSION_MAJOR < 1
129
#define SWR_CH_MAX 32
///< Maximum number of channels
130
#endif
131
132
/**
133
* @name Option constants
134
* These constants are used for the @ref avoptions interface for lswr.
135
* @{
136
*
137
*/
138
139
#define SWR_FLAG_RESAMPLE 1
///< Force resampling even if equal sample rate
140
//TODO use int resample ?
141
//long term TODO can we enable this dynamically?
142
143
/** Dithering algorithms */
144
enum
SwrDitherType
{
145
SWR_DITHER_NONE
= 0,
146
SWR_DITHER_RECTANGULAR
,
147
SWR_DITHER_TRIANGULAR
,
148
SWR_DITHER_TRIANGULAR_HIGHPASS
,
149
150
SWR_DITHER_NS
= 64,
///< not part of API/ABI
151
SWR_DITHER_NS_LIPSHITZ
,
152
SWR_DITHER_NS_F_WEIGHTED
,
153
SWR_DITHER_NS_MODIFIED_E_WEIGHTED
,
154
SWR_DITHER_NS_IMPROVED_E_WEIGHTED
,
155
SWR_DITHER_NS_SHIBATA
,
156
SWR_DITHER_NS_LOW_SHIBATA
,
157
SWR_DITHER_NS_HIGH_SHIBATA
,
158
SWR_DITHER_NB
,
///< not part of API/ABI
159
};
160
161
/** Resampling Engines */
162
enum
SwrEngine
{
163
SWR_ENGINE_SWR
,
/**< SW Resampler */
164
SWR_ENGINE_SOXR
,
/**< SoX Resampler */
165
SWR_ENGINE_NB
,
///< not part of API/ABI
166
};
167
168
/** Resampling Filter Types */
169
enum
SwrFilterType
{
170
SWR_FILTER_TYPE_CUBIC
,
/**< Cubic */
171
SWR_FILTER_TYPE_BLACKMAN_NUTTALL
,
/**< Blackman Nuttall Windowed Sinc */
172
SWR_FILTER_TYPE_KAISER
,
/**< Kaiser Windowed Sinc */
173
};
174
175
/**
176
* @}
177
*/
178
179
/**
180
* The libswresample context. Unlike libavcodec and libavformat, this structure
181
* is opaque. This means that if you would like to set options, you must use
182
* the @ref avoptions API and cannot directly set values to members of the
183
* structure.
184
*/
185
typedef
struct
SwrContext
SwrContext
;
186
187
/**
188
* Get the AVClass for SwrContext. It can be used in combination with
189
* AV_OPT_SEARCH_FAKE_OBJ for examining options.
190
*
191
* @see av_opt_find().
192
* @return the AVClass of SwrContext
193
*/
194
const
AVClass
*
swr_get_class
(
void
);
195
196
/**
197
* @name SwrContext constructor functions
198
* @{
199
*/
200
201
/**
202
* Allocate SwrContext.
203
*
204
* If you use this function you will need to set the parameters (manually or
205
* with swr_alloc_set_opts()) before calling swr_init().
206
*
207
* @see swr_alloc_set_opts(), swr_init(), swr_free()
208
* @return NULL on error, allocated context otherwise
209
*/
210
struct
SwrContext
*
swr_alloc
(
void
);
211
212
/**
213
* Initialize context after user parameters have been set.
214
*
215
* @param[in,out] s Swr context to initialize
216
* @return AVERROR error code in case of failure.
217
*/
218
int
swr_init
(
struct
SwrContext
*
s
);
219
220
/**
221
* Check whether an swr context has been initialized or not.
222
*
223
* @param[in] s Swr context to check
224
* @see swr_init()
225
* @return positive if it has been initialized, 0 if not initialized
226
*/
227
int
swr_is_initialized
(
struct
SwrContext
*
s
);
228
229
/**
230
* Allocate SwrContext if needed and set/reset common parameters.
231
*
232
* This function does not require s to be allocated with swr_alloc(). On the
233
* other hand, swr_alloc() can use swr_alloc_set_opts() to set the parameters
234
* on the allocated context.
235
*
236
* @param s existing Swr context if available, or NULL if not
237
* @param out_ch_layout output channel layout (AV_CH_LAYOUT_*)
238
* @param out_sample_fmt output sample format (AV_SAMPLE_FMT_*).
239
* @param out_sample_rate output sample rate (frequency in Hz)
240
* @param in_ch_layout input channel layout (AV_CH_LAYOUT_*)
241
* @param in_sample_fmt input sample format (AV_SAMPLE_FMT_*).
242
* @param in_sample_rate input sample rate (frequency in Hz)
243
* @param log_offset logging level offset
244
* @param log_ctx parent logging context, can be NULL
245
*
246
* @see swr_init(), swr_free()
247
* @return NULL on error, allocated context otherwise
248
*/
249
struct
SwrContext
*
swr_alloc_set_opts
(
struct
SwrContext
*
s
,
250
int64_t
out_ch_layout
,
enum
AVSampleFormat
out_sample_fmt
,
int
out_sample_rate
,
251
int64_t
in_ch_layout
,
enum
AVSampleFormat
in_sample_fmt
,
int
in_sample_rate
,
252
int
log_offset,
void
*
log_ctx
);
253
254
/**
255
* @}
256
*
257
* @name SwrContext destructor functions
258
* @{
259
*/
260
261
/**
262
* Free the given SwrContext and set the pointer to NULL.
263
*
264
* @param[in] s a pointer to a pointer to Swr context
265
*/
266
void
swr_free
(
struct
SwrContext
**
s
);
267
268
/**
269
* Closes the context so that swr_is_initialized() returns 0.
270
*
271
* The context can be brought back to life by running swr_init(),
272
* swr_init() can also be used without swr_close().
273
* This function is mainly provided for simplifying the usecase
274
* where one tries to support libavresample and libswresample.
275
*
276
* @param[in,out] s Swr context to be closed
277
*/
278
void
swr_close
(
struct
SwrContext
*
s
);
279
280
/**
281
* @}
282
*
283
* @name Core conversion functions
284
* @{
285
*/
286
287
/** Convert audio.
288
*
289
* in and in_count can be set to 0 to flush the last few samples out at the
290
* end.
291
*
292
* If more input is provided than output space then the input will be buffered.
293
* You can avoid this buffering by providing more output space than input.
294
* Conversion will run directly without copying whenever possible.
295
*
296
* @param s allocated Swr context, with parameters set
297
* @param out output buffers, only the first one need be set in case of packed audio
298
* @param out_count amount of space available for output in samples per channel
299
* @param in input buffers, only the first one need to be set in case of packed audio
300
* @param in_count number of input samples available in one channel
301
*
302
* @return number of samples output per channel, negative value on error
303
*/
304
int
swr_convert
(
struct
SwrContext
*
s
,
uint8_t
**
out
,
int
out_count,
305
const
uint8_t
**
in
,
int
in_count);
306
307
/**
308
* Convert the next timestamp from input to output
309
* timestamps are in 1/(in_sample_rate * out_sample_rate) units.
310
*
311
* @note There are 2 slightly differently behaving modes.
312
* @li When automatic timestamp compensation is not used, (min_compensation >= FLT_MAX)
313
* in this case timestamps will be passed through with delays compensated
314
* @li When automatic timestamp compensation is used, (min_compensation < FLT_MAX)
315
* in this case the output timestamps will match output sample numbers.
316
* See ffmpeg-resampler(1) for the two modes of compensation.
317
*
318
* @param s[in] initialized Swr context
319
* @param pts[in] timestamp for the next input sample, INT64_MIN if unknown
320
* @see swr_set_compensation(), swr_drop_output(), and swr_inject_silence() are
321
* function used internally for timestamp compensation.
322
* @return the output timestamp for the next output sample
323
*/
324
int64_t
swr_next_pts
(
struct
SwrContext
*
s
, int64_t pts);
325
326
/**
327
* @}
328
*
329
* @name Low-level option setting functions
330
* These functons provide a means to set low-level options that is not possible
331
* with the AVOption API.
332
* @{
333
*/
334
335
/**
336
* Activate resampling compensation ("soft" compensation). This function is
337
* internally called when needed in swr_next_pts().
338
*
339
* @param[in,out] s allocated Swr context. If it is not initialized,
340
* or SWR_FLAG_RESAMPLE is not set, swr_init() is
341
* called with the flag set.
342
* @param[in] sample_delta delta in PTS per sample
343
* @param[in] compensation_distance number of samples to compensate for
344
* @return >= 0 on success, AVERROR error codes if:
345
* @li @c s is NULL,
346
* @li @c compensation_distance is less than 0,
347
* @li @c compensation_distance is 0 but sample_delta is not,
348
* @li compensation unsupported by resampler, or
349
* @li swr_init() fails when called.
350
*/
351
int
swr_set_compensation
(
struct
SwrContext
*
s
,
int
sample_delta,
int
compensation_distance);
352
353
/**
354
* Set a customized input channel mapping.
355
*
356
* @param[in,out] s allocated Swr context, not yet initialized
357
* @param[in] channel_map customized input channel mapping (array of channel
358
* indexes, -1 for a muted channel)
359
* @return >= 0 on success, or AVERROR error code in case of failure.
360
*/
361
int
swr_set_channel_mapping
(
struct
SwrContext
*
s
,
const
int
*
channel_map
);
362
363
/**
364
* Set a customized remix matrix.
365
*
366
* @param s allocated Swr context, not yet initialized
367
* @param matrix remix coefficients; matrix[i + stride * o] is
368
* the weight of input channel i in output channel o
369
* @param stride offset between lines of the matrix
370
* @return >= 0 on success, or AVERROR error code in case of failure.
371
*/
372
int
swr_set_matrix
(
struct
SwrContext
*
s
,
const
double
*
matrix
,
int
stride
);
373
374
/**
375
* @}
376
*
377
* @name Sample handling functions
378
* @{
379
*/
380
381
/**
382
* Drops the specified number of output samples.
383
*
384
* This function, along with swr_inject_silence(), is called by swr_next_pts()
385
* if needed for "hard" compensation.
386
*
387
* @param s allocated Swr context
388
* @param count number of samples to be dropped
389
*
390
* @return >= 0 on success, or a negative AVERROR code on failure
391
*/
392
int
swr_drop_output
(
struct
SwrContext
*
s
,
int
count
);
393
394
/**
395
* Injects the specified number of silence samples.
396
*
397
* This function, along with swr_drop_output(), is called by swr_next_pts()
398
* if needed for "hard" compensation.
399
*
400
* @param s allocated Swr context
401
* @param count number of samples to be dropped
402
*
403
* @return >= 0 on success, or a negative AVERROR code on failure
404
*/
405
int
swr_inject_silence
(
struct
SwrContext
*
s
,
int
count
);
406
407
/**
408
* Gets the delay the next input sample will experience relative to the next output sample.
409
*
410
* Swresample can buffer data if more input has been provided than available
411
* output space, also converting between sample rates needs a delay.
412
* This function returns the sum of all such delays.
413
* The exact delay is not necessarily an integer value in either input or
414
* output sample rate. Especially when downsampling by a large value, the
415
* output sample rate may be a poor choice to represent the delay, similarly
416
* for upsampling and the input sample rate.
417
*
418
* @param s swr context
419
* @param base timebase in which the returned delay will be:
420
* @li if it's set to 1 the returned delay is in seconds
421
* @li if it's set to 1000 the returned delay is in milliseconds
422
* @li if it's set to the input sample rate then the returned
423
* delay is in input samples
424
* @li if it's set to the output sample rate then the returned
425
* delay is in output samples
426
* @li if it's the least common multiple of in_sample_rate and
427
* out_sample_rate then an exact rounding-free delay will be
428
* returned
429
* @returns the delay in 1 / @c base units.
430
*/
431
int64_t
swr_get_delay
(
struct
SwrContext
*
s
, int64_t base);
432
433
/**
434
* @}
435
*
436
* @name Configuration accessors
437
* @{
438
*/
439
440
/**
441
* Return the @ref LIBSWRESAMPLE_VERSION_INT constant.
442
*
443
* This is useful to check if the build-time libswresample has the same version
444
* as the run-time one.
445
*
446
* @returns the unsigned int-typed version
447
*/
448
unsigned
swresample_version
(
void
);
449
450
/**
451
* Return the swr build-time configuration.
452
*
453
* @returns the build-time @c ./configure flags
454
*/
455
const
char
*
swresample_configuration
(
void
);
456
457
/**
458
* Return the swr license.
459
*
460
* @returns the license of libswresample, determined at build-time
461
*/
462
const
char
*
swresample_license
(
void
);
463
464
/**
465
* @}
466
* @}
467
*/
468
469
#endif
/* SWRESAMPLE_SWRESAMPLE_H */
Generated on Sun Jul 20 2014 23:06:08 for FFmpeg by
1.8.2