FFmpeg  4.0
Files | Macros | Functions | Variables
libavresample

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
 

Functions

attribute_deprecated unsigned avresample_version (void)
 
attribute_deprecated const char * avresample_configuration (void)
 
attribute_deprecated const char * avresample_license (void)
 
attribute_deprecated const AVClassavresample_get_class (void)
 
attribute_deprecated AVAudioResampleContextavresample_alloc_context (void)
 
attribute_deprecated int avresample_open (AVAudioResampleContext *avr)
 
attribute_deprecated int avresample_is_open (AVAudioResampleContext *avr)
 
attribute_deprecated void avresample_close (AVAudioResampleContext *avr)
 
attribute_deprecated void avresample_free (AVAudioResampleContext **avr)
 
attribute_deprecated 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)
 
attribute_deprecated int avresample_get_matrix (AVAudioResampleContext *avr, double *matrix, int stride)
 
attribute_deprecated int avresample_set_matrix (AVAudioResampleContext *avr, const double *matrix, int stride)
 
attribute_deprecated int avresample_set_channel_mapping (AVAudioResampleContext *avr, const int *channel_map)
 
attribute_deprecated int avresample_set_compensation (AVAudioResampleContext *avr, int sample_delta, int compensation_distance)
 
attribute_deprecated int avresample_get_out_samples (AVAudioResampleContext *avr, int in_nb_samples)
 
attribute_deprecated int avresample_convert (AVAudioResampleContext *avr, uint8_t **output, int out_plane_size, int out_samples, uint8_t *const *input, int in_plane_size, int in_samples)
 
attribute_deprecated int avresample_get_delay (AVAudioResampleContext *avr)
 
attribute_deprecated int avresample_available (AVAudioResampleContext *avr)
 
attribute_deprecated int avresample_read (AVAudioResampleContext *avr, uint8_t **output, int nb_samples)
 
attribute_deprecated int avresample_convert_frame (AVAudioResampleContext *avr, AVFrame *output, AVFrame *input)
 
attribute_deprecated int avresample_config (AVAudioResampleContext *avr, AVFrame *out, AVFrame *in)
 

Variables

enum attribute_deprecated AVMixCoeffType
 
enum attribute_deprecated AVResampleFilterType
 
enum attribute_deprecated AVResampleDitherMethod
 

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

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

◆ AVRESAMPLE_MAX_CHANNELS

#define AVRESAMPLE_MAX_CHANNELS   32

Function Documentation

◆ avresample_version()

attribute_deprecated unsigned avresample_version ( void  )
Deprecated:
use libswresample

Return the LIBAVRESAMPLE_VERSION_INT constant.

Definition at line 779 of file utils.c.

◆ avresample_configuration()

attribute_deprecated const char* avresample_configuration ( void  )
Deprecated:
use libswresample

Return the libavresample build-time configuration.

Returns
configure string

Definition at line 790 of file utils.c.

◆ avresample_license()

attribute_deprecated const char* avresample_license ( void  )
Deprecated:
use libswresample

Return the libavresample license.

Definition at line 784 of file utils.c.

◆ avresample_get_class()

attribute_deprecated const AVClass* avresample_get_class ( void  )
Deprecated:
use libswresample

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

◆ avresample_alloc_context()

attribute_deprecated AVAudioResampleContext* avresample_alloc_context ( void  )
Deprecated:
use libswresample

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(), and main().

◆ avresample_open()

attribute_deprecated int avresample_open ( AVAudioResampleContext avr)
Deprecated:
use libswresample

Initialize AVAudioResampleContext.

Note
The context must be configured using the AVOption API.
The fields "in_channel_layout", "out_channel_layout", "in_sample_rate", "out_sample_rate", "in_sample_fmt", "out_sample_fmt" must be set.
See also
av_opt_set_int()
av_opt_set_dict()
av_get_default_channel_layout()
Parameters
avraudio resample context
Returns
0 on success, negative AVERROR code on failure

Definition at line 36 of file utils.c.

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

◆ avresample_is_open()

attribute_deprecated int avresample_is_open ( AVAudioResampleContext avr)
Deprecated:
use libswresample

Check whether an AVAudioResampleContext is open or closed.

Parameters
avrAVAudioResampleContext to check
Returns
1 if avr is open, 0 if avr is closed.

Definition at line 257 of file utils.c.

Referenced by avresample_config(), avresample_convert_frame(), and avresample_open().

◆ avresample_close()

attribute_deprecated void avresample_close ( AVAudioResampleContext avr)
Deprecated:
use libswresample

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
avraudio resample context

Definition at line 262 of file utils.c.

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

◆ avresample_free()

attribute_deprecated void avresample_free ( AVAudioResampleContext **  avr)
Deprecated:
use libswresample

Free AVAudioResampleContext and associated AVOption values.

This also calls avresample_close() before freeing.

Parameters
avraudio resample context

Definition at line 278 of file utils.c.

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

◆ avresample_build_matrix()

attribute_deprecated 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 
)
Deprecated:
use libswresample

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_layoutinput channel layout
out_layoutoutput channel layout
center_mix_levelmix level for the center channel
surround_mix_levelmix level for the surround channel(s)
lfe_mix_levelmix level for the low-frequency effects channel
normalizeif 1, coefficients will be normalized to prevent overflow. if 0, coefficients will not be normalized.
[out]matrixmixing coefficients; matrix[i + stride * o] is the weight of input channel i in output channel o.
stridedistance between adjacent input channels in the matrix array
matrix_encodingmatrixed 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().

◆ avresample_get_matrix()

attribute_deprecated int avresample_get_matrix ( AVAudioResampleContext avr,
double *  matrix,
int  stride 
)
Deprecated:
use libswresample

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
avraudio resample context
matrixmixing coefficients; matrix[i + stride * o] is the weight of input channel i in output channel o.
stridedistance between adjacent input channels in the matrix array
Returns
0 on success, negative AVERROR code on failure

Definition at line 637 of file utils.c.

◆ avresample_set_matrix()

attribute_deprecated int avresample_set_matrix ( AVAudioResampleContext avr,
const double *  matrix,
int  stride 
)
Deprecated:
use libswresample

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
avraudio resample context
matrixmixing coefficients; matrix[i + stride * o] is the weight of input channel i in output channel o.
stridedistance between adjacent input channels in the matrix array
Returns
0 on success, negative AVERROR code on failure

Definition at line 666 of file utils.c.

◆ avresample_set_channel_mapping()

attribute_deprecated int avresample_set_channel_mapping ( AVAudioResampleContext avr,
const int channel_map 
)
Deprecated:
use libswresample

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
avraudio resample context
channel_mapcustomized input channel mapping
Returns
0 on success, negative AVERROR code on failure

Definition at line 697 of file utils.c.

◆ avresample_set_compensation()

attribute_deprecated int avresample_set_compensation ( AVAudioResampleContext avr,
int  sample_delta,
int  compensation_distance 
)
Deprecated:
use libswresample

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
avraudio resample context
sample_deltacompensation delta, in samples
compensation_distancecompensation distance, in samples
Returns
0 on success, negative AVERROR code on failure

Definition at line 233 of file resample.c.

◆ avresample_get_out_samples()

attribute_deprecated int avresample_get_out_samples ( AVAudioResampleContext avr,
int  in_nb_samples 
)
Deprecated:
use libswresample

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

Parameters
avraudio resample context
in_nb_samplesnumber of input samples
Returns
number of samples or AVERROR(EINVAL) if the value would exceed INT_MAX

Definition at line 753 of file utils.c.

Referenced by avresample_convert_frame(), filter_frame(), and request_frame().

◆ avresample_convert()

attribute_deprecated int avresample_convert ( AVAudioResampleContext avr,
uint8_t **  output,
int  out_plane_size,
int  out_samples,
uint8_t *const *  input,
int  in_plane_size,
int  in_samples 
)
Deprecated:
use libswresample

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
avraudio resample context
outputoutput data pointers
out_plane_sizeoutput 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_samplesmaximum number of samples that the output buffer can hold
inputinput data pointers
in_plane_sizeinput 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_samplesnumber 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 330 of file utils.c.

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

◆ avresample_get_delay()

attribute_deprecated int avresample_get_delay ( AVAudioResampleContext avr)
Deprecated:
use libswresample

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
avraudio resample context
Returns
number of samples currently in the resampling delay buffer

Definition at line 438 of file resample.c.

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

◆ avresample_available()

attribute_deprecated int avresample_available ( AVAudioResampleContext avr)
Deprecated:
use libswresample

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
avraudio resample context
Returns
number of samples available for reading

Definition at line 748 of file utils.c.

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

◆ avresample_read()

attribute_deprecated int avresample_read ( AVAudioResampleContext avr,
uint8_t **  output,
int  nb_samples 
)
Deprecated:
use libswresample

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
avraudio resample context
outputoutput data pointers. May be NULL, in which case nb_samples of data is discarded from output FIFO.
nb_samplesnumber of samples to read from the FIFO
Returns
the number of samples written to output

Definition at line 772 of file utils.c.

◆ avresample_convert_frame()

attribute_deprecated int avresample_convert_frame ( AVAudioResampleContext avr,
AVFrame output,
AVFrame input 
)
Deprecated:
use libswresample

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.

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

If the output AVFrame does not have the data pointers allocated the nb_samples field will be set using avresample_get_out_samples() and 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 avresample_convert() 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 this function or 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 this function or avresample_convert() with NULL input or call avresample_read().

If the AVAudioResampleContext 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 AVERROR_OUTPUT_CHANGED|AVERROR_INPUT_CHANGED is returned.

See also
avresample_get_out_samples()
avresample_available()
avresample_convert()
avresample_read()
avresample_get_delay()
Parameters
avraudio resample context
outputoutput AVFrame
inputinput AVFrame
Returns
0 on success, AVERROR on failure or nonmatching configuration.

Definition at line 603 of file utils.c.

◆ avresample_config()

attribute_deprecated int avresample_config ( AVAudioResampleContext avr,
AVFrame out,
AVFrame in 
)
Deprecated:
use libswresample

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

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

See also
avresample_open();
avresample_close();
Parameters
avraudio resample context
outoutput AVFrame
ininput AVFrame
Returns
0 on success, AVERROR on failure.

Definition at line 505 of file utils.c.

Referenced by avresample_convert_frame().

Variable Documentation

◆ AVMixCoeffType

enum attribute_deprecated AVMixCoeffType
Deprecated:
use libswresample

Mixing Coefficient Types

Definition at line 112 of file avresample.h.

◆ AVResampleFilterType

enum attribute_deprecated AVResampleFilterType
Deprecated:
use libswresample

Resampling Filter Types

Definition at line 123 of file avresample.h.

◆ AVResampleDitherMethod

enum attribute_deprecated AVResampleDitherMethod
Deprecated:
use libswresample

Definition at line 132 of file avresample.h.