Audio resampling, sample format conversion and mixing library. More...

Files
file	swresample.h
	libswresample public header

Typedefs
typedef struct SwrContext	SwrContext
	The libswresample context. More...

Functions
const AVClass *	swr_get_class (void)
	Get the AVClass for SwrContext. More...

Option constants
These constants are used for the AVOptions interface for lswr.
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 }
	Dithering algorithms. More...

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...

#define	SWR_FLAG_RESAMPLE 1
	Force resampling even if equal sample rate. More...

SwrContext constructor functions
struct SwrContext *	swr_alloc (void)
	Allocate SwrContext. More...

int	swr_init (struct SwrContext *s)
	Initialize context after user parameters have been set. More...

int	swr_is_initialized (struct SwrContext *s)
	Check whether an swr context has been initialized or not. More...

int	swr_alloc_set_opts2 (struct SwrContext *ps, AVChannelLayout out_ch_layout, enum AVSampleFormat out_sample_fmt, int out_sample_rate, AVChannelLayout 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...

SwrContext destructor functions
void	swr_free (struct SwrContext **s)
	Free the given SwrContext and set the pointer to NULL. More...

void	swr_close (struct SwrContext *s)
	Closes the context so that swr_is_initialized() returns 0. More...

Core conversion functions
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...

Low-level option setting functions
These functons provide a means to set low-level options that is not possible with the AVOption API.
int	swr_set_compensation (struct SwrContext *s, int sample_delta, int compensation_distance)
	Activate resampling compensation ("soft" compensation). More...

int	swr_set_channel_mapping (struct SwrContext s, const int channel_map)
	Set a customized input channel mapping. More...

int	swr_build_matrix2 (const AVChannelLayout in_layout, const AVChannelLayout out_layout, double center_mix_level, double surround_mix_level, double lfe_mix_level, double maxval, double rematrix_volume, double matrix, ptrdiff_t stride, enum AVMatrixEncoding matrix_encoding, void log_context)
	Generate a channel mixing matrix. More...

int	swr_set_matrix (struct SwrContext s, const double matrix, int stride)
	Set a customized remix matrix. More...

Sample handling functions
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...

int	swr_get_out_samples (struct SwrContext *s, int in_samples)
	Find an upper bound on the number of samples that the next swr_convert call will output, if called with in_samples of input samples. More...

Configuration accessors
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...

AVFrame based API
int	swr_convert_frame (SwrContext swr, AVFrame output, const AVFrame *input)
	Convert the samples in the input AVFrame and write them to the output AVFrame. More...

int	swr_config_frame (SwrContext swr, const AVFrame out, const AVFrame *in)
	Configure or reconfigure the SwrContext using the information provided by the AVFrames. More...

Detailed Description

Audio resampling, sample format conversion and mixing library.

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

The first thing you will need to do in order to use lswr is to allocate SwrContext. This can be done with swr_alloc() or swr_alloc_set_opts2(). If you are using the former, you must set options through the AVOptions API. The latter function provides the same feature, but it allows you to set some common options in the same statement.

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). This is using the swr_alloc() function.

SwrContext *swr = swr_alloc();
av_opt_set_channel_layout(swr, "in_channel_layout",  AV_CH_LAYOUT_5POINT1, 0);
av_opt_set_channel_layout(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);

The same job can be done using swr_alloc_set_opts2() as well:

SwrContext *swr = NULL;
int ret = swr_alloc_set_opts2(&swr,         // we're allocating a new context
                      &(AVChannelLayout)AV_CHANNEL_LAYOUT_STEREO, // out_ch_layout
                      AV_SAMPLE_FMT_S16,    // out_sample_fmt
                      44100,                // out_sample_rate
                      &(AVChannelLayout)AV_CHANNEL_LAYOUT_5POINT1, // in_ch_layout
                      AV_SAMPLE_FMT_FLTP,   // in_sample_fmt
                      48000,                // in_sample_rate
                      0,                    // log_offset
                      NULL);                // log_ctx

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 using AVOptions, as described above in the first example; or by using swr_alloc_set_opts2(), but with the first argument the allocated context. You must 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 samples used in the conversion process can be managed with the libavutil samples manipulation API, including av_samples_alloc() function used in the following example.

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():

uint8_t **input;
int in_samples;
 
while (get_input(&input, &in_samples)) {
    uint8_t *output;
    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,
                     AV_SAMPLE_FMT_S16, 0);
    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(). A swr_close() function is also available, but it exists mainly for compatibility with libavresample, and is not required to be called.

There will be no memory leak if the data is not completely flushed before swr_free().

Macro Definition Documentation

◆ SWR_FLAG_RESAMPLE

#define SWR_FLAG_RESAMPLE 1

Force resampling even if equal sample rate.

Definition at line 143 of file swresample.h.

Typedef Documentation

◆ SwrContext

typedef struct SwrContext SwrContext

The libswresample context.

Unlike libavcodec and libavformat, this structure is opaque. This means that if you would like to set options, you must use the AVOptions API and cannot directly set values to members of the structure.

Definition at line 189 of file swresample.h.

Enumeration Type Documentation

◆ SwrDitherType

enum SwrDitherType

Dithering algorithms.

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 148 of file swresample.h.

◆ SwrEngine

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 166 of file swresample.h.

◆ SwrFilterType

enum SwrFilterType

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 173 of file swresample.h.

Function Documentation

◆ swr_get_class()

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().

Returns: the AVClass of SwrContext

◆ swr_alloc()

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_opts2()) before calling swr_init().

See also: swr_alloc_set_opts2(), swr_init(), swr_free()

Returns: NULL on error, allocated context otherwise

Examples: muxing.c, and resampling_audio.c.

Referenced by main(), and open_audio().

◆ swr_init()

int swr_init ( struct SwrContext * s )

Initialize context after user parameters have been set.

Note: The context must be configured using the AVOption API.

See also: av_opt_set_int(); av_opt_set_dict()

Parameters

[in,out] s Swr context to initialize

Returns: AVERROR error code in case of failure.

Examples: muxing.c, resampling_audio.c, and transcode_aac.c.

Referenced by init_resampler(), main(), and open_audio().

◆ swr_is_initialized()

int swr_is_initialized ( struct SwrContext * s )

Check whether an swr context has been initialized or not.

Parameters

[in] s Swr context to check

See also: swr_init()

Returns: positive if it has been initialized, 0 if not initialized

◆ swr_alloc_set_opts2()

int swr_alloc_set_opts2	(	struct SwrContext **	ps,
		AVChannelLayout *	out_ch_layout,
		enum AVSampleFormat	out_sample_fmt,
		int	out_sample_rate,
		AVChannelLayout *	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 *ps to be allocated with swr_alloc(). On the other hand, swr_alloc() can use swr_alloc_set_opts2() to set the parameters on the allocated context.

Parameters

ps	Pointer to an existing Swr context if available, or to NULL if not. On success, *ps will be set to the allocated context.
out_ch_layout	output channel layout (e.g. AV_CHANNEL_LAYOUT_*)
out_sample_fmt	output sample format (AV_SAMPLE_FMT_*).
out_sample_rate	output sample rate (frequency in Hz)
in_ch_layout	input channel layout (e.g. AV_CHANNEL_LAYOUT_*)
in_sample_fmt	input sample format (AV_SAMPLE_FMT_*).
in_sample_rate	input sample rate (frequency in Hz)
log_offset	logging level offset
log_ctx	parent logging context, can be NULL

See also: swr_init(), swr_free()

Returns: 0 on success, a negative AVERROR code on error. On error, the Swr context is freed and *ps set to NULL.

Examples: transcode_aac.c.

Referenced by init_resampler().

◆ swr_free()

void swr_free ( struct SwrContext ** s )

Free the given SwrContext and set the pointer to NULL.

Parameters

[in] s a pointer to a pointer to Swr context

Examples: muxing.c, resampling_audio.c, and transcode_aac.c.

Referenced by close_stream(), init_resampler(), and main().

◆ swr_close()

void swr_close ( struct SwrContext * s )

Closes the context so that swr_is_initialized() returns 0.

The context can be brought back to life by running swr_init(), swr_init() can also be used without swr_close(). This function is mainly provided for simplifying the usecase where one tries to support libavresample and libswresample.

Parameters

[in,out] s Swr context to be closed

◆ swr_convert()

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 using swr_get_out_samples() to retrieve an upper bound on the required number of output samples for the given number of input samples. Conversion will run directly without copying whenever possible.

Parameters

s	allocated Swr context, with parameters set
out	output buffers, only the first one need be set in case of packed audio
out_count	amount of space available for output in samples per channel
in	input buffers, only the first one need to be set in case of packed audio
in_count	number of input samples available in one channel

Returns: number of samples output per channel, negative value on error

Examples: muxing.c, resampling_audio.c, and transcode_aac.c.

Referenced by convert_samples(), main(), and write_audio_frame().

◆ 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.

When automatic timestamp compensation is not used, (min_compensation >= FLT_MAX) in this case timestamps will be passed through with delays compensated
When automatic timestamp compensation is used, (min_compensation < FLT_MAX) in this case the output timestamps will match output sample numbers. See ffmpeg-resampler(1) for the two modes of compensation.

Parameters

s[in]	initialized Swr context
pts[in]	timestamp for the next input sample, INT64_MIN if unknown

See also: swr_set_compensation(), swr_drop_output(), and swr_inject_silence() are function used internally for timestamp compensation.

Returns: the output timestamp for the next output sample

◆ swr_set_compensation()

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

Activate resampling compensation ("soft" compensation).

This function is internally called when needed in swr_next_pts().

Parameters

[in,out]	s	allocated Swr context. If it is not initialized, or SWR_FLAG_RESAMPLE is not set, swr_init() is called with the flag set.
[in]	sample_delta	delta in PTS per sample
[in]	compensation_distance	number of samples to compensate for

Returns

>= 0 on success, AVERROR error codes if:

s is NULL,
compensation_distance is less than 0,
compensation_distance is 0 but sample_delta is not,
compensation unsupported by resampler, or
swr_init() fails when called.

◆ swr_set_channel_mapping()

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

Set a customized input channel mapping.

Parameters

[in,out]	s	allocated Swr context, not yet initialized
[in]	channel_map	customized input channel mapping (array of channel indexes, -1 for a muted channel)

Returns: >= 0 on success, or AVERROR error code in case of failure.

◆ swr_build_matrix2()

int swr_build_matrix2	(	const AVChannelLayout *	in_layout,
		const AVChannelLayout *	out_layout,
		double	center_mix_level,
		double	surround_mix_level,
		double	lfe_mix_level,
		double	maxval,
		double	rematrix_volume,
		double *	matrix,
		ptrdiff_t	stride,
		enum AVMatrixEncoding	matrix_encoding,
		void *	log_context
	)

Generate a channel mixing matrix.

This function is the one used internally by libswresample for building the default mixing matrix. It is made public just as a utility function for building custom matrices.

Parameters

	in_layout	input channel layout
	out_layout	output channel layout
	center_mix_level	mix level for the center channel
	surround_mix_level	mix level for the surround channel(s)
	lfe_mix_level	mix level for the low-frequency effects channel
	rematrix_maxval	if 1.0, coefficients will be normalized to prevent overflow. if INT_MAX, coefficients will not be normalized.
[out]	matrix	mixing coefficients; matrix[i + stride * o] is the weight of input channel i in output channel o.
	stride	distance between adjacent input channels in the matrix array
	matrix_encoding	matrixed stereo downmix mode (e.g. dplii)
	log_ctx	parent logging context, can be NULL

Returns: 0 on success, negative AVERROR code on failure

◆ swr_set_matrix()

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

Set a customized remix matrix.

Parameters

s	allocated Swr context, not yet initialized
matrix	remix coefficients; matrix[i + stride * o] is the weight of input channel i in output channel o
stride	offset between lines of the matrix

Returns: >= 0 on success, or AVERROR error code in case of failure.

◆ swr_drop_output()

int swr_drop_output	(	struct SwrContext *	s,
		int	count
	)

Drops the specified number of output samples.

This function, along with swr_inject_silence(), is called by swr_next_pts() if needed for "hard" compensation.

Parameters

s	allocated Swr context
count	number of samples to be dropped

Returns: >= 0 on success, or a negative AVERROR code on failure

◆ swr_inject_silence()

int swr_inject_silence	(	struct SwrContext *	s,
		int	count
	)

Injects the specified number of silence samples.

This function, along with swr_drop_output(), is called by swr_next_pts() if needed for "hard" compensation.

Parameters

s	allocated Swr context
count	number of samples to be dropped

Returns: >= 0 on success, or a negative AVERROR code on failure

◆ swr_get_delay()

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

s swr context

base

timebase in which the returned delay will be:

if it's set to 1 the returned delay is in seconds
if it's set to 1000 the returned delay is in milliseconds
if it's set to the input sample rate then the returned delay is in input samples
if it's set to the output sample rate then the returned delay is in output samples
if it's the least common multiple of in_sample_rate and out_sample_rate then an exact rounding-free delay will be returned

Returns: the delay in 1 / base units.

Examples: muxing.c, and resampling_audio.c.

Referenced by main(), and write_audio_frame().

◆ swr_get_out_samples()

int swr_get_out_samples	(	struct SwrContext *	s,
		int	in_samples
	)

Find an upper bound on the number of samples that the next swr_convert call will output, if called with in_samples of input samples.

This depends on the internal state, and anything changing the internal state (like further swr_convert() calls) will may change the number of samples swr_get_out_samples() returns for the same number of input samples.

Parameters

in_samples number of input samples.

Note: any call to swr_inject_silence(), swr_convert(), swr_next_pts() or swr_set_compensation() invalidates this limit; it is recommended to pass the correct available buffer size to all functions like swr_convert() even if swr_get_out_samples() indicates that less would be used.

Returns: an upper bound on the number of samples that the next swr_convert will output or a negative value to indicate an error

◆ swresample_version()

unsigned swresample_version ( void )

Return the LIBSWRESAMPLE_VERSION_INT constant.

This is useful to check if the build-time libswresample has the same version as the run-time one.

Returns: the unsigned int-typed version

◆ swresample_configuration()

const char * swresample_configuration ( void )

Return the swr build-time configuration.

Returns: the build-time ./configure flags

◆ swresample_license()

const char * swresample_license ( void )

Return the swr license.

Returns: the license of libswresample, determined at build-time

◆ swr_convert_frame()

int swr_convert_frame	(	SwrContext *	swr,
		AVFrame *	output,
		const AVFrame *	input
	)

Convert the samples in the input AVFrame and write them to the output AVFrame.

Input and output AVFrames must have channel_layout, sample_rate and format set.

If the output AVFrame does not have the data pointers allocated the nb_samples field will be set using av_frame_get_buffer() is called to allocate the frame.

The output AVFrame can be NULL or have fewer allocated samples than required. In this case, any remaining samples not written to the output will be added to an internal FIFO buffer, to be returned at the next call to this function or to swr_convert().

If converting sample rate, there may be data remaining in the internal resampling delay buffer. swr_get_delay() tells the number of remaining samples. To get this data as output, call this function or swr_convert() with NULL input.

If the SwrContext configuration does not match the output and input AVFrame settings the conversion does not take place and depending on which AVFrame is not matching AVERROR_OUTPUT_CHANGED, AVERROR_INPUT_CHANGED or the result of a bitwise-OR of them is returned.

See also: swr_delay(); swr_convert(); swr_get_delay()

Parameters

swr	audio resample context
output	output AVFrame
input	input AVFrame

Returns: 0 on success, AVERROR on failure or nonmatching configuration.

◆ swr_config_frame()

int swr_config_frame	(	SwrContext *	swr,
		const AVFrame *	out,
		const AVFrame *	in
	)

Configure or reconfigure the SwrContext using the information provided by the AVFrames.

The original resampling context is reset even on failure. The function calls swr_close() internally if the context is open.

See also: swr_close();

Parameters

swr	audio resample context
output	output AVFrame
input	input AVFrame

Returns: 0 on success, AVERROR on failure.

Files

Typedefs

Functions

Option constants

SwrContext constructor functions

SwrContext destructor functions

Core conversion functions

Low-level option setting functions

Sample handling functions

Configuration accessors

AVFrame based API

Detailed Description

Macro Definition Documentation

◆ SWR_FLAG_RESAMPLE

Typedef Documentation

◆ SwrContext

Enumeration Type Documentation

◆ SwrDitherType

◆ SwrEngine

◆ SwrFilterType

Function Documentation

◆ swr_get_class()

◆ swr_alloc()

◆ swr_init()

◆ swr_is_initialized()

◆ swr_alloc_set_opts2()

◆ swr_free()

◆ swr_close()

◆ swr_convert()

◆ swr_next_pts()

◆ swr_set_compensation()

◆ swr_set_channel_mapping()

◆ swr_build_matrix2()

◆ swr_set_matrix()

◆ swr_drop_output()

◆ swr_inject_silence()

◆ swr_get_delay()

◆ swr_get_out_samples()

◆ swresample_version()

◆ swresample_configuration()

◆ swresample_license()

◆ swr_convert_frame()

◆ swr_config_frame()