FFmpeg: Libswresample

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.

SwrContext destructor functions

void swr_free (struct SwrContext **s)

Free the given SwrContext and set the pointer to NULL.

void swr_close (struct SwrContext *s)

Closes the context so that swr_is_initialized() returns 0.

Core conversion functions

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

Convert audio.

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.

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

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

Set a customized input channel mapping.

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

Set a customized remix matrix.

Sample handling functions

int swr_drop_output (struct SwrContext *s, int count)

Drops the specified number of output samples.

int swr_inject_silence (struct SwrContext *s, int count)

Injects the specified number of silence samples.

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.

Configuration accessors

unsigned swresample_version (void)

Return the LIBSWRESAMPLE_VERSION_INT constant.

const char * swresample_configuration (void)

Return the swr build-time configuration.

const char * swresample_license (void)

Return the swr license.

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.

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_opts(). 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_opts() as well:

SwrContext *swr = swr_alloc_set_opts(NULL, // we're allocating a new context

AV_CH_LAYOUT_STEREO, // out_ch_layout

AV_SAMPLE_FMT_S16, // out_sample_fmt

44100, // out_sample_rate

AV_CH_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_opts(), 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

#define SWR_CH_MAX 32

Maximum number of channels.

Definition at line 129 of file swresample.h.

Referenced by audiogen(), auto_matrix(), config_props(), conv_fltp_to_s16_nch_neon(), filter_frame(), main(), query_formats(), sane_layout(), setup_array(), swr_convert(), swr_init(), swr_inject_silence(), and swri_rematrix_init().

#define SWR_FLAG_RESAMPLE 1

Force resampling even if equal sample rate.

Definition at line 139 of file swresample.h.

Referenced by swr_init(), and swr_set_compensation().

Enumeration Type Documentation

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

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

Function Documentation

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

Definition at line 143 of file options.c.

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

struct SwrContext* swr_alloc ( void )

read

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 148 of file options.c.

Referenced by config_audio_output(), init_dict(), main(), open_audio(), opt_default(), opus_decode_init(), and swr_alloc_set_opts().

int swr_init ( struct SwrContext * s )

Initialize context after user parameters have been set.

Parameters: [in,out] s Swr context to initialize

Returns: AVERROR error code in case of failure.

Definition at line 126 of file swresample.c.

Referenced by audio_decode_frame(), config_audio_output(), config_output(), config_props(), init_resampler(), main(), open_audio(), opus_init_resample(), and swr_set_compensation().

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

Definition at line 614 of file swresample.c.

Referenced by opus_decode_frame(), opus_decode_subpacket(), and swr_convert().

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

)

read

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: s existing Swr context if available, or NULL if not

out_ch_layout output channel layout (AV_CH_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 (AV_CH_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: NULL on error, allocated context otherwise

Definition at line 55 of file swresample.c.

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

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

Definition at line 111 of file swresample.c.

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

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

Definition at line 122 of file swresample.c.

Referenced by opus_decode_flush(), and opus_decode_subpacket().

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

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

Definition at line 788 of file swresample.c.

Referenced by filter_frame(), and request_frame().

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.

Definition at line 768 of file swresample.c.

Referenced by audio_decode_frame(), and swr_next_pts().

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.

Definition at line 48 of file swresample.c.

Referenced by config_props().

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.

Definition at line 60 of file rematrix.c.

Referenced by config_props().

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

Definition at line 722 of file swresample.c.

Referenced by swr_next_pts().

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

Definition at line 732 of file swresample.c.

Referenced by swr_inject_silence(), and swr_next_pts().

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.

Definition at line 760 of file swresample.c.

Referenced by filter_frame(), main(), swr_next_pts(), and write_audio_frame().

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

Definition at line 31 of file swresample.c.

const char* swresample_configuration ( void )

Return the swr build-time configuration.

Returns: the build-time ./configure flags

Definition at line 37 of file swresample.c.

const char* swresample_license ( void )

Return the swr license.

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

Definition at line 42 of file swresample.c.

Generated on Sun Jul 20 2014 23:06:28 for FFmpeg by doxygen 1.8.2