Libswresample

Libswresample (lswr) is a library that handles audio resampling, sample format conversion and mixing. More...

Files

file  swresample.h
 libswresample public header
 

Macros

#define SWR_CH_MAX   32
 Maximum number of channels. More...
 
#define SWR_FLAG_RESAMPLE   1
 Force resampling even if equal sample rate. More...
 

Typedefs

typedef struct SwrContext SwrContext
 

Enumerations

enum  SwrDitherType {
  SWR_DITHER_NONE = 0, SWR_DITHER_RECTANGULAR, SWR_DITHER_TRIANGULAR, SWR_DITHER_TRIANGULAR_HIGHPASS,
  SWR_DITHER_NS = 64, SWR_DITHER_NS_LIPSHITZ, SWR_DITHER_NS_F_WEIGHTED, SWR_DITHER_NS_MODIFIED_E_WEIGHTED,
  SWR_DITHER_NS_IMPROVED_E_WEIGHTED, SWR_DITHER_NS_SHIBATA, SWR_DITHER_NS_LOW_SHIBATA, SWR_DITHER_NS_HIGH_SHIBATA,
  SWR_DITHER_NB
}
 
enum  SwrEngine { SWR_ENGINE_SWR, SWR_ENGINE_SOXR, SWR_ENGINE_NB }
 Resampling Engines. More...
 
enum  SwrFilterType { SWR_FILTER_TYPE_CUBIC, SWR_FILTER_TYPE_BLACKMAN_NUTTALL, SWR_FILTER_TYPE_KAISER }
 Resampling Filter Types. More...
 

Functions

const AVClassswr_get_class (void)
 Get the AVClass for swrContext. More...
 
struct SwrContextswr_alloc (void)
 Allocate SwrContext. More...
 
int swr_init (struct SwrContext *s)
 Initialize context after user parameters have been set. More...
 
struct SwrContextswr_alloc_set_opts (struct SwrContext *s, int64_t out_ch_layout, enum AVSampleFormat out_sample_fmt, int out_sample_rate, int64_t in_ch_layout, enum AVSampleFormat in_sample_fmt, int in_sample_rate, int log_offset, void *log_ctx)
 Allocate SwrContext if needed and set/reset common parameters. More...
 
void swr_free (struct SwrContext **s)
 Free the given SwrContext and set the pointer to NULL. More...
 
int swr_convert (struct SwrContext *s, uint8_t **out, int out_count, const uint8_t **in, int in_count)
 Convert audio. More...
 
int64_t swr_next_pts (struct SwrContext *s, int64_t pts)
 Convert the next timestamp from input to output timestamps are in 1/(in_sample_rate * out_sample_rate) units. More...
 
int swr_set_compensation (struct SwrContext *s, int sample_delta, int compensation_distance)
 Activate resampling compensation. More...
 
int swr_set_channel_mapping (struct SwrContext *s, const int *channel_map)
 Set a customized input channel mapping. More...
 
int swr_set_matrix (struct SwrContext *s, const double *matrix, int stride)
 Set a customized remix matrix. More...
 
int swr_drop_output (struct SwrContext *s, int count)
 Drops the specified number of output samples. More...
 
int swr_inject_silence (struct SwrContext *s, int count)
 Injects the specified number of silence samples. More...
 
int64_t swr_get_delay (struct SwrContext *s, int64_t base)
 Gets the delay the next input sample will experience relative to the next output sample. More...
 
unsigned swresample_version (void)
 Return the LIBSWRESAMPLE_VERSION_INT constant. More...
 
const char * swresample_configuration (void)
 Return the swr build-time configuration. More...
 
const char * swresample_license (void)
 Return the swr license. More...
 

Detailed Description

Libswresample (lswr) is a library that handles audio resampling, sample format conversion and mixing.

Interaction with lswr is done through SwrContext, which is allocated with swr_alloc() or swr_alloc_set_opts(). It is opaque, so all parameters must be set with the AVOptions API.

For example the following code will setup conversion from planar float sample format to interleaved signed 16-bit integer, downsampling from 48kHz to 44.1kHz and downmixing from 5.1 channels to stereo (using the default mixing matrix):

av_opt_set_int(swr, "in_channel_layout", AV_CH_LAYOUT_5POINT1, 0);
av_opt_set_int(swr, "out_channel_layout", AV_CH_LAYOUT_STEREO, 0);
av_opt_set_int(swr, "in_sample_rate", 48000, 0);
av_opt_set_int(swr, "out_sample_rate", 44100, 0);
av_opt_set_sample_fmt(swr, "in_sample_fmt", AV_SAMPLE_FMT_FLTP, 0);
av_opt_set_sample_fmt(swr, "out_sample_fmt", AV_SAMPLE_FMT_S16, 0);

Once all values have been set, it must be initialized with swr_init(). If you need to change the conversion parameters, you can change the parameters as described above, or by using swr_alloc_set_opts(), then call swr_init() again.

The conversion itself is done by repeatedly calling swr_convert(). Note that the samples may get buffered in swr if you provide insufficient output space or if sample rate conversion is done, which requires "future" samples. Samples that do not require future input can be retrieved at any time by using swr_convert() (in_count can be set to 0). At the end of conversion the resampling buffer can be flushed by calling swr_convert() with NULL in and 0 in_count.

The delay between input and output, can at any time be found by using swr_get_delay().

The following code demonstrates the conversion loop assuming the parameters from above and caller-defined functions get_input() and handle_output():

int in_samples;
while (get_input(&input, &in_samples)) {
int out_samples = av_rescale_rnd(swr_get_delay(swr, 48000) +
in_samples, 44100, 48000, AV_ROUND_UP);
av_samples_alloc(&output, NULL, 2, out_samples,
out_samples = swr_convert(swr, &output, out_samples,
input, in_samples);
handle_output(output, out_samples);
av_freep(&output);
}

When the conversion is finished, the conversion context and everything associated with it must be freed with swr_free(). There will be no memory leak if the data is not completely flushed before swr_free().

Macro Definition Documentation

#define SWR_FLAG_RESAMPLE   1

Force resampling even if equal sample rate.

Definition at line 105 of file swresample.h.

Referenced by swr_init(), and swr_set_compensation().

Typedef Documentation

typedef struct SwrContext SwrContext

Definition at line 140 of file swresample.h.

Enumeration Type Documentation

Enumerator
SWR_DITHER_NONE 
SWR_DITHER_RECTANGULAR 
SWR_DITHER_TRIANGULAR 
SWR_DITHER_TRIANGULAR_HIGHPASS 
SWR_DITHER_NS 

not part of API/ABI

SWR_DITHER_NS_LIPSHITZ 
SWR_DITHER_NS_F_WEIGHTED 
SWR_DITHER_NS_MODIFIED_E_WEIGHTED 
SWR_DITHER_NS_IMPROVED_E_WEIGHTED 
SWR_DITHER_NS_SHIBATA 
SWR_DITHER_NS_LOW_SHIBATA 
SWR_DITHER_NS_HIGH_SHIBATA 
SWR_DITHER_NB 

not part of API/ABI

Definition at line 109 of file swresample.h.

enum SwrEngine

Resampling Engines.

Enumerator
SWR_ENGINE_SWR 

SW Resampler.

SWR_ENGINE_SOXR 

SoX Resampler.

SWR_ENGINE_NB 

not part of API/ABI

Definition at line 127 of file swresample.h.

Resampling Filter Types.

Enumerator
SWR_FILTER_TYPE_CUBIC 

Cubic.

SWR_FILTER_TYPE_BLACKMAN_NUTTALL 

Blackman Nuttall Windowed Sinc.

SWR_FILTER_TYPE_KAISER 

Kaiser Windowed Sinc.

Definition at line 134 of file swresample.h.

Function Documentation

struct SwrContext* swr_alloc ( void  )

Allocate SwrContext.

If you use this function you will need to set the parameters (manually or with swr_alloc_set_opts()) before calling swr_init().

See also
swr_alloc_set_opts(), swr_init(), swr_free()
Returns
NULL on error, allocated context otherwise

Definition at line 177 of file swresample.c.

Referenced by init_dict(), main(), opt_default(), and swr_alloc_set_opts().

struct SwrContext* swr_alloc_set_opts ( struct SwrContext s,
int64_t  out_ch_layout,
enum AVSampleFormat  out_sample_fmt,
int  out_sample_rate,
int64_t  in_ch_layout,
enum AVSampleFormat  in_sample_fmt,
int  in_sample_rate,
int  log_offset,
void log_ctx 
)

Allocate SwrContext if needed and set/reset common parameters.

This function does not require s to be allocated with swr_alloc(). On the other hand, swr_alloc() can use swr_alloc_set_opts() to set the parameters on the allocated context.

Parameters
sSwr context, can be NULL
out_ch_layoutoutput channel layout (AV_CH_LAYOUT_*)
out_sample_fmtoutput sample format (AV_SAMPLE_FMT_*).
out_sample_rateoutput sample rate (frequency in Hz)
in_ch_layoutinput channel layout (AV_CH_LAYOUT_*)
in_sample_fmtinput sample format (AV_SAMPLE_FMT_*).
in_sample_rateinput sample rate (frequency in Hz)
log_offsetlogging level offset
log_ctxparent logging context, can be NULL
See also
swr_init(), swr_free()
Returns
NULL on error, allocated context otherwise

Definition at line 186 of file swresample.c.

Referenced by audio_decode_frame(), config_output(), config_props(), and main().

int swr_convert ( struct SwrContext s,
uint8_t **  out,
int  out_count,
const uint8_t **  in,
int  in_count 
)

Convert audio.

in and in_count can be set to 0 to flush the last few samples out at the end.

If more input is provided than output space then the input will be buffered. You can avoid this buffering by providing more output space than input. Convertion will run directly without copying whenever possible.

Parameters
sallocated Swr context, with parameters set
outoutput buffers, only the first one need be set in case of packed audio
out_countamount of space available for output in samples per channel
ininput buffers, only the first one need to be set in case of packed audio
in_countnumber of input samples available in one channel
Returns
number of samples output per channel, negative value on error
int swr_drop_output ( struct SwrContext s,
int  count 
)

Drops the specified number of output samples.

Definition at line 834 of file swresample.c.

Referenced by swr_next_pts().

void swr_free ( struct SwrContext **  s)

Free the given SwrContext and set the pointer to NULL.

Definition at line 220 of file swresample.c.

Referenced by audio_decode_frame(), main(), opt_default(), stream_component_close(), and uninit().

const AVClass* swr_get_class ( void  )

Get the AVClass for swrContext.

It can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options.

See also
av_opt_find().

Definition at line 172 of file swresample.c.

Referenced by opt_default(), resample_child_class_next(), and show_help_default().

int64_t swr_get_delay ( struct SwrContext s,
int64_t  base 
)

Gets the delay the next input sample will experience relative to the next output sample.

Swresample can buffer data if more input has been provided than available output space, also converting between sample rates needs a delay. This function returns the sum of all such delays. The exact delay is not necessarily an integer value in either input or output sample rate. Especially when downsampling by a large value, the output sample rate may be a poor choice to represent the delay, similarly for upsampling and the input sample rate.

Parameters
sswr context
basetimebase in which the returned delay will be if its set to 1 the returned delay is in seconds if its set to 1000 the returned delay is in milli seconds if its set to the input sample rate then the returned delay is in input samples if its set to the output sample rate then the returned delay is in output samples an exact rounding free delay can be found by using LCM(in_sample_rate, out_sample_rate)
Returns
the delay in 1/base units.

Definition at line 872 of file swresample.c.

Referenced by main(), and swr_next_pts().

int swr_init ( struct SwrContext s)

Initialize context after user parameters have been set.

Returns
AVERROR error code in case of failure.

Definition at line 242 of file swresample.c.

Referenced by audio_decode_frame(), config_output(), config_props(), main(), and swr_set_compensation().

int swr_inject_silence ( struct SwrContext s,
int  count 
)

Injects the specified number of silence samples.

Definition at line 844 of file swresample.c.

Referenced by swr_inject_silence(), and swr_next_pts().

int64_t swr_next_pts ( struct SwrContext s,
int64_t  pts 
)

Convert the next timestamp from input to output timestamps are in 1/(in_sample_rate * out_sample_rate) units.

Note
There are 2 slightly differently behaving modes. First is when automatic timestamp compensation is not used, (min_compensation >= FLT_MAX) in this case timestamps will be passed through with delays compensated Second is when automatic timestamp compensation is used, (min_compensation < FLT_MAX) in this case the output timestamps will match output sample numbers
Parameters
ptstimestamp for the next input sample, INT64_MIN if unknown
Returns
the output timestamp for the next output sample

Definition at line 900 of file swresample.c.

Referenced by filter_frame(), and request_frame().

int swr_set_channel_mapping ( struct SwrContext s,
const int *  channel_map 
)

Set a customized input channel mapping.

Parameters
sallocated Swr context, not yet initialized
channel_mapcustomized input channel mapping (array of channel indexes, -1 for a muted channel)
Returns
AVERROR error code in case of failure.

Definition at line 165 of file swresample.c.

Referenced by config_props().

int swr_set_compensation ( struct SwrContext s,
int  sample_delta,
int  compensation_distance 
)

Activate resampling compensation.

Definition at line 880 of file swresample.c.

Referenced by audio_decode_frame(), and swr_next_pts().

int swr_set_matrix ( struct SwrContext s,
const double *  matrix,
int  stride 
)

Set a customized remix matrix.

Parameters
sallocated Swr context, not yet initialized
matrixremix coefficients; matrix[i + stride * o] is the weight of input channel i in output channel o
strideoffset between lines of the matrix
Returns
AVERROR error code in case of failure.

Definition at line 56 of file rematrix.c.

Referenced by config_props().

const char* swresample_configuration ( void  )

Return the swr build-time configuration.

Definition at line 154 of file swresample.c.

const char* swresample_license ( void  )

Return the swr license.

Definition at line 159 of file swresample.c.

unsigned swresample_version ( void  )

Return the LIBSWRESAMPLE_VERSION_INT constant.

Definition at line 148 of file swresample.c.