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

Files
file	avresample.h
	external API header

file	version.h
	Libavresample version macros.

Macros
#define	AVRESAMPLE_MAX_CHANNELS 32

Enumerations
enum	AVMixCoeffType { AV_MIX_COEFF_TYPE_Q8, AV_MIX_COEFF_TYPE_Q15, AV_MIX_COEFF_TYPE_FLT, AV_MIX_COEFF_TYPE_NB }
	Mixing Coefficient Types. More...

enum	AVResampleFilterType { AV_RESAMPLE_FILTER_TYPE_CUBIC, AV_RESAMPLE_FILTER_TYPE_BLACKMAN_NUTTALL, AV_RESAMPLE_FILTER_TYPE_KAISER }
	Resampling Filter Types. More...

enum	AVResampleDitherMethod { AV_RESAMPLE_DITHER_NONE, AV_RESAMPLE_DITHER_RECTANGULAR, AV_RESAMPLE_DITHER_TRIANGULAR, AV_RESAMPLE_DITHER_TRIANGULAR_HP, AV_RESAMPLE_DITHER_TRIANGULAR_NS, AV_RESAMPLE_DITHER_NB }

Functions
unsigned	avresample_version (void)
	Return the LIBAVRESAMPLE_VERSION_INT constant.

const char *	avresample_configuration (void)
	Return the libavresample build-time configuration.

const char *	avresample_license (void)
	Return the libavresample license.

const AVClass *	avresample_get_class (void)
	Get the AVClass for AVAudioResampleContext.

AVAudioResampleContext *	avresample_alloc_context (void)
	Allocate AVAudioResampleContext and set options.

int	avresample_open (AVAudioResampleContext *avr)
	Initialize AVAudioResampleContext.

int	avresample_is_open (AVAudioResampleContext *avr)
	Check whether an AVAudioResampleContext is open or closed.

void	avresample_close (AVAudioResampleContext *avr)
	Close AVAudioResampleContext.

void	avresample_free (AVAudioResampleContext **avr)
	Free AVAudioResampleContext and associated AVOption values.

int	avresample_build_matrix (uint64_t in_layout, uint64_t out_layout, double center_mix_level, double surround_mix_level, double lfe_mix_level, int normalize, double *matrix, int stride, enum AVMatrixEncoding matrix_encoding)
	Generate a channel mixing matrix.

int	avresample_get_matrix (AVAudioResampleContext avr, double matrix, int stride)
	Get the current channel mixing matrix.

int	avresample_set_matrix (AVAudioResampleContext avr, const double matrix, int stride)
	Set channel mixing matrix.

int	avresample_set_channel_mapping (AVAudioResampleContext avr, const int channel_map)
	Set a customized input channel mapping.

int	avresample_set_compensation (AVAudioResampleContext *avr, int sample_delta, int compensation_distance)
	Set compensation for resampling.

int	avresample_get_out_samples (AVAudioResampleContext *avr, int in_nb_samples)
	Provide the upper bound on the number of samples the configured conversion would output.

int	avresample_convert (AVAudioResampleContext avr, uint8_t output, int out_plane_size, int out_samples, uint8_t *input, int in_plane_size, int in_samples)
	Convert input samples and write them to the output FIFO.

int	avresample_get_delay (AVAudioResampleContext *avr)
	Return the number of samples currently in the resampling delay buffer.

int	avresample_available (AVAudioResampleContext *avr)
	Return the number of available samples in the output FIFO.

int	avresample_read (AVAudioResampleContext avr, uint8_t *output, int nb_samples)
	Read samples from the output FIFO.

Detailed Description

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

Interaction with lavr is done through AVAudioResampleContext, which is allocated with avresample_alloc_context(). 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):

AVAudioResampleContext *avr = avresample_alloc_context();
av_opt_set_int(avr, "in_channel_layout",  AV_CH_LAYOUT_5POINT1, 0);
av_opt_set_int(avr, "out_channel_layout", AV_CH_LAYOUT_STEREO,  0);
av_opt_set_int(avr, "in_sample_rate",     48000,                0);
av_opt_set_int(avr, "out_sample_rate",    44100,                0);
av_opt_set_int(avr, "in_sample_fmt",      AV_SAMPLE_FMT_FLTP,   0);
av_opt_set_int(avr, "out_sample_fmt",     AV_SAMPLE_FMT_S16,    0);

Once the context is initialized, it must be opened with avresample_open(). If you need to change the conversion parameters, you must close the context with avresample_close(), change the parameters as described above, then reopen it again.

The conversion itself is done by repeatedly calling avresample_convert(). Note that the samples may get buffered in two places in lavr. The first one is the output FIFO, where the samples end up if the output buffer is not large enough. The data stored in there may be retrieved at any time with avresample_read(). The second place is the resampling delay buffer, applicable only when resampling is done. The samples in it require more input before they can be processed. Their current amount is returned by avresample_get_delay(). At the end of conversion the resampling buffer can be flushed by calling avresample_convert() with NULL input.

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_linesize, in_samples;
while (get_input(&input, &in_linesize, &in_samples)) {
    uint8_t *output
    int out_linesize;
    int out_samples = avresample_get_out_samples(avr, in_samples);
    av_samples_alloc(&output, &out_linesize, 2, out_samples,
                     AV_SAMPLE_FMT_S16, 0);
    out_samples = avresample_convert(avr, &output, out_linesize, out_samples,
                                     input, in_linesize, in_samples);
    handle_output(output, out_linesize, out_samples);
    av_freep(&output);
 }

When the conversion is finished and the FIFOs are flushed if required, the conversion context and everything associated with it must be freed with avresample_free().

Macro Definition Documentation

#define AVRESAMPLE_MAX_CHANNELS 32

Definition at line 103 of file avresample.h.

Referenced by audiogen(), avresample_build_matrix(), avresample_get_matrix(), avresample_open(), avresample_set_channel_mapping(), avresample_set_compensation(), avresample_set_matrix(), ff_audio_data_add_to_fifo(), ff_audio_data_alloc(), ff_audio_data_init(), ff_audio_data_realloc(), ff_audio_data_set_channels(), ff_audio_mix(), ff_audio_mix_get_matrix(), ff_audio_mix_set_matrix(), and main().

Enumeration Type Documentation

enum AVMixCoeffType

Mixing Coefficient Types.

Enumerator:

AV_MIX_COEFF_TYPE_Q8
AV_MIX_COEFF_TYPE_Q15	16-bit 8.8 fixed-point
AV_MIX_COEFF_TYPE_FLT	32-bit 17.15 fixed-point
AV_MIX_COEFF_TYPE_NB	floating-point

Definition at line 108 of file avresample.h.

enum AVResampleFilterType

Resampling Filter Types.

Enumerator:

AV_RESAMPLE_FILTER_TYPE_CUBIC	Cubic.
AV_RESAMPLE_FILTER_TYPE_BLACKMAN_NUTTALL	Blackman Nuttall Windowed Sinc.
AV_RESAMPLE_FILTER_TYPE_KAISER	Kaiser Windowed Sinc.

Definition at line 116 of file avresample.h.

enum AVResampleDitherMethod

Enumerator:

AV_RESAMPLE_DITHER_NONE	Do not use dithering.
AV_RESAMPLE_DITHER_RECTANGULAR	Rectangular Dither.
AV_RESAMPLE_DITHER_TRIANGULAR	Triangular Dither.
AV_RESAMPLE_DITHER_TRIANGULAR_HP	Triangular Dither with High Pass.
AV_RESAMPLE_DITHER_TRIANGULAR_NS	Triangular Dither with Noise Shaping.
AV_RESAMPLE_DITHER_NB	Number of dither types. Not part of ABI.

Definition at line 122 of file avresample.h.

Function Documentation

unsigned avresample_version ( void )

Return the LIBAVRESAMPLE_VERSION_INT constant.

Definition at line 651 of file utils.c.

const char* avresample_configuration ( void )

Return the libavresample build-time configuration.

Returns: configure string

Definition at line 662 of file utils.c.

const char* avresample_license ( void )

Return the libavresample license.

Definition at line 656 of file utils.c.

const AVClass* avresample_get_class ( void )

Get the AVClass for AVAudioResampleContext.

Can be used in combination with AV_OPT_SEARCH_FAKE_OBJ for examining options without allocating a context.

See Also: av_opt_find().

Returns: AVClass for AVAudioResampleContext

Definition at line 110 of file options.c.

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

AVAudioResampleContext* avresample_alloc_context ( void )

Allocate AVAudioResampleContext and set options.

Returns: allocated audio resample context, or NULL on failure

Definition at line 96 of file options.c.

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

int avresample_open ( AVAudioResampleContext * avr )

Initialize AVAudioResampleContext.

Parameters

avr	audio resample context

Returns: 0 on success, negative AVERROR code on failure

Definition at line 35 of file utils.c.

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

int avresample_is_open ( AVAudioResampleContext * avr )

Check whether an AVAudioResampleContext is open or closed.

Parameters

avr	AVAudioResampleContext to check

Returns: 1 if avr is open, 0 if avr is closed.

Definition at line 262 of file utils.c.

Referenced by avresample_open().

void avresample_close ( AVAudioResampleContext * avr )

Close AVAudioResampleContext.

This closes the context, but it does not change the parameters. The context can be reopened with avresample_open(). It does, however, clear the output FIFO and any remaining leftover samples in the resampling delay buffer. If there was a custom matrix being used, that is also cleared.

See Also: avresample_convert(); avresample_set_matrix()

Parameters

avr	audio resample context

Definition at line 267 of file utils.c.

Referenced by avresample_free(), avresample_open(), avresample_set_compensation(), config_output(), main(), and uninit().

void avresample_free ( AVAudioResampleContext ** avr )

Free AVAudioResampleContext and associated AVOption values.

This also calls avresample_close() before freeing.

Parameters

avr	audio resample context

Definition at line 283 of file utils.c.

Referenced by config_output(), main(), and uninit().

int avresample_build_matrix	(	uint64_t	in_layout,
		uint64_t	out_layout,
		double	center_mix_level,
		double	surround_mix_level,
		double	lfe_mix_level,
		int	normalize,
		double *	matrix,
		int	stride,
		enum AVMatrixEncoding	matrix_encoding
	)

Generate a channel mixing matrix.

This function is the one used internally by libavresample 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
	normalize	if 1, coefficients will be normalized to prevent overflow. if 0, 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)

Returns: 0 on success, negative AVERROR code on failure

Definition at line 87 of file audio_mix_matrix.c.

Referenced by ff_audio_mix_alloc().

int avresample_get_matrix	(	AVAudioResampleContext *	avr,
		double *	matrix,
		int	stride
	)

Get the current channel mixing matrix.

If no custom matrix has been previously set or the AVAudioResampleContext is not open, an error is returned.

Parameters

avr	audio resample context
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

Returns: 0 on success, negative AVERROR code on failure

Definition at line 509 of file utils.c.

Referenced by avresample_set_compensation().

int avresample_set_matrix	(	AVAudioResampleContext *	avr,
		const double *	matrix,
		int	stride
	)

Set channel mixing matrix.

Allows for setting a custom mixing matrix, overriding the default matrix generated internally during avresample_open(). This function can be called anytime on an allocated context, either before or after calling avresample_open(), as long as the channel layouts have been set. avresample_convert() always uses the current matrix. Calling avresample_close() on the context will clear the current matrix.

See Also: avresample_close()

Parameters

avr	audio resample context
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

Returns: 0 on success, negative AVERROR code on failure

Definition at line 538 of file utils.c.

Referenced by avresample_set_compensation().

int avresample_set_channel_mapping	(	AVAudioResampleContext *	avr,
		const int *	channel_map
	)

Set a customized input channel mapping.

This function can only be called when the allocated context is not open. Also, the input channel layout must have already been set.

Calling avresample_close() on the context will clear the channel mapping.

The map for each input channel specifies the channel index in the source to use for that particular channel, or -1 to mute the channel. Source channels can be duplicated by using the same index for multiple input channels.

Examples:

Reordering 5.1 AAC order (C,L,R,Ls,Rs,LFE) to FFmpeg order (L,R,C,LFE,Ls,Rs): { 1, 2, 0, 5, 3, 4 }

Muting the 3rd channel in 4-channel input: { 0, 1, -1, 3 }

Duplicating the left channel of stereo input: { 0, 0 }

Parameters

avr	audio resample context
channel_map	customized input channel mapping

Returns: 0 on success, negative AVERROR code on failure

Definition at line 569 of file utils.c.

int avresample_set_compensation	(	AVAudioResampleContext *	avr,
		int	sample_delta,
		int	compensation_distance
	)

Set compensation for resampling.

This can be called anytime after avresample_open(). If resampling is not automatically enabled because of a sample rate conversion, the "force_resampling" option must have been set to 1 when opening the context in order to use resampling compensation.

Parameters

avr	audio resample context
sample_delta	compensation delta, in samples
compensation_distance	compensation distance, in samples

Returns: 0 on success, negative AVERROR code on failure

Definition at line 231 of file resample.c.

Referenced by filter_frame().

int avresample_get_out_samples	(	AVAudioResampleContext *	avr,
		int	in_nb_samples
	)

Provide the upper bound on the number of samples the configured conversion would output.

Parameters

avr	audio resample context
in_nb_samples	number of input samples

Returns: number of samples or AVERROR(EINVAL) if the value would exceed INT_MAX

Definition at line 625 of file utils.c.

Referenced by filter_frame(), and request_frame().

int avresample_convert	(	AVAudioResampleContext *	avr,
		uint8_t **	output,
		int	out_plane_size,
		int	out_samples,
		uint8_t **	input,
		int	in_plane_size,
		int	in_samples
	)

Convert input samples and write them to the output FIFO.

The upper bound on the number of output samples can be obtained through avresample_get_out_samples().

The output data 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 avresample_read().

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

At the end of the conversion process, there may be data remaining in the internal FIFO buffer. avresample_available() tells the number of remaining samples. To get this data as output, either call avresample_convert() with NULL input or call avresample_read().

See Also: avresample_get_out_samples(); avresample_read(); avresample_get_delay()

Parameters

avr	audio resample context
output	output data pointers
out_plane_size	output plane size, in bytes. This can be 0 if unknown, but that will lead to optimized functions not being used directly on the output, which could slow down some conversions.
out_samples	maximum number of samples that the output buffer can hold
input	input data pointers
in_plane_size	input plane size, in bytes This can be 0 if unknown, but that will lead to optimized functions not being used directly on the input, which could slow down some conversions.
in_samples	number of input samples to convert

Returns: number of samples written to the output buffer, not including converted samples added to the internal output FIFO

Definition at line 335 of file utils.c.

Referenced by filter_frame(), main(), request_frame(), wrap(), and write_to_fifo().

int avresample_get_delay ( AVAudioResampleContext * avr )

Return the number of samples currently in the resampling delay buffer.

When resampling, there may be a delay between the input and output. Any unconverted samples in each call are stored internally in a delay buffer. This function allows the user to determine the current number of samples in the delay buffer, which can be useful for synchronization.

See Also: avresample_convert()

Parameters

avr	audio resample context

Returns: number of samples currently in the resampling delay buffer

Definition at line 493 of file resample.c.

Referenced by avresample_get_out_samples(), filter_frame(), get_delay(), and main().

int avresample_available ( AVAudioResampleContext * avr )

Return the number of available samples in the output FIFO.

During conversion, if the user does not specify an output buffer or specifies an output buffer that is smaller than what is needed, remaining samples that are not written to the output are stored to an internal FIFO buffer. The samples in the FIFO can be read with avresample_read() or avresample_convert().

See Also: avresample_read(); avresample_convert()

Parameters

avr	audio resample context

Returns: number of samples available for reading

Definition at line 620 of file utils.c.

Referenced by avresample_get_out_samples(), filter_frame(), get_delay(), handle_trimming(), and main().

int avresample_read	(	AVAudioResampleContext *	avr,
		uint8_t **	output,
		int	nb_samples
	)

Read samples from the output FIFO.

During conversion, if the user does not specify an output buffer or specifies an output buffer that is smaller than what is needed, remaining samples that are not written to the output are stored to an internal FIFO buffer. This function can be used to read samples from that internal FIFO.

See Also: avresample_available(); avresample_convert()

Parameters

avr	audio resample context
output	output data pointers. May be NULL, in which case nb_samples of data is discarded from output FIFO.
nb_samples	number of samples to read from the FIFO

Returns: the number of samples written to output

Definition at line 644 of file utils.c.

Referenced by filter_frame(), and handle_trimming().

Files

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation