gavl: Audio converter

gavl

Typedefs | Functions
Audio converter
Audio

Audio format converter. More...

## Typedefs
typedef struct gavl_audio_converter_s | gavl_audio_converter_t
| Opaque audio converter structure.

## Functions
GAVL_PUBLIC gavl_audio_converter_t * | gavl_audio_converter_create (void)
| Creates an audio converter.
GAVL_PUBLIC void | gavl_audio_converter_destroy (gavl_audio_converter_t *cnv)
| Destroys an audio converter and frees all associated memory.
GAVL_PUBLIC gavl_audio_options_t * | gavl_audio_converter_get_options (gavl_audio_converter_t *cnv)
| gets options of an audio converter
GAVL_PUBLIC int | gavl_audio_converter_init (gavl_audio_converter_t *cnv, const gavl_audio_format_t *input_format, const gavl_audio_format_t *output_format)
| Initialize an audio converter.
GAVL_PUBLIC int | gavl_audio_converter_init_resample (gavl_audio_converter_t *cnv, const gavl_audio_format_t *format)
| Initialize an audio converter just for resampling.
GAVL_PUBLIC int | gavl_audio_converter_reinit (gavl_audio_converter_t *cnv)
| Reinitialize an audio converter.
GAVL_PUBLIC void | gavl_audio_convert (gavl_audio_converter_t *cnv, const gavl_audio_frame_t *input_frame, gavl_audio_frame_t *output_frame)
| Convert audio.
GAVL_PUBLIC int | gavl_audio_converter_set_resample_ratio (gavl_audio_converter_t *cnv, double ratio)
| Set samplerate conversion ratio.
GAVL_PUBLIC void | gavl_audio_converter_resample (gavl_audio_converter_t *cnv, gavl_audio_frame_t *input_frame, gavl_audio_frame_t *output_frame, double ratio)
| Convert audio.

## Detailed Description

Audio format converter.

This is a generic converter, which converts audio frames from one arbitrary format to another. It does:

- Up-/Downmixing of channel configurations
- Resampling
- Conversion of interleave modes
- Conversion of sample formats

Quality levels below 3 mainly result if poor but fast resampling methods. Quality levels above 3 will enable high quality resampling methods, dithering and floating point mixing.

Create an audio converter with gavl_audio_converter_create. If you want to configure it, get the options pointer with gavl_audio_converter_get_options and change the options (See Audio conversion options). Call gavl_audio_converter_init to initialize the converter for the input and output formats. Audio frames are then converted with gavl_audio_convert.

When you are done, you can either reinitialize the converter or destroy it with gavl_audio_converter_destroy.

## Typedef Documentation

## ◆ gavl_audio_converter_t

typedef struct gavl_audio_converter_s gavl_audio_converter_t

Opaque audio converter structure.

You don't want to know what's inside.

## Function Documentation

## ◆ gavl_audio_converter_create()

GAVL_PUBLIC gavl_audio_converter_t * gavl_audio_converter_create | ( | void |  | ) |

Creates an audio converter.

Returns
  A newly allocated audio converter

## ◆ gavl_audio_converter_destroy()

GAVL_PUBLIC void gavl_audio_converter_destroy | ( | gavl_audio_converter_t * | cnv | ) |

Destroys an audio converter and frees all associated memory.

Parameters

  cnv | An audio converter

## ◆ gavl_audio_converter_get_options()

GAVL_PUBLIC gavl_audio_options_t * gavl_audio_converter_get_options | ( | gavl_audio_converter_t * | cnv | ) |

gets options of an audio converter

Parameters

  cnv | An audio converter

After you called this, you can use the gavl_audio_options_set_*() functions to change the options. Options will become valid with the next call to gavl_audio_converter_init or gavl_audio_converter_reinit

## ◆ gavl_audio_converter_init()

GAVL_PUBLIC int gavl_audio_converter_init | ( | gavl_audio_converter_t * | cnv,
|  | const gavl_audio_format_t * | input_format,
|  | const gavl_audio_format_t * | output_format )

Initialize an audio converter.

Parameters

  cnv | An audio converter
  input_format | Input format
  output_format | Output format

Returns
  The number of single conversion steps necessary to perform the conversion. It may be 0, in this case you must not use the converter and have to pass the audio frames directly. If something goes wrong (should never happen), -1 is returned.

This function can be called multiple times with one instance

## ◆ gavl_audio_converter_init_resample()

GAVL_PUBLIC int gavl_audio_converter_init_resample | ( | gavl_audio_converter_t * | cnv,
|  | const gavl_audio_format_t * | format )

Initialize an audio converter just for resampling.

Parameters

  cnv | An audio converter
  format | Input and output format. (They are the same except for output samplerate ratio will vary)

Returns
  The number of single conversion steps necessary to perform the conversion. Unlike, gavl_audio_converter_init, it should never return 0. If the sample_format < GALV_SAMPLE_FLOAT extra conversions will be added to the internal conversion chain.

This function can be called multiple times with one instance

Since 1.1.0.

## ◆ gavl_audio_converter_reinit()

GAVL_PUBLIC int gavl_audio_converter_reinit | ( | gavl_audio_converter_t * | cnv | ) |

Reinitialize an audio converter.

Parameters

  cnv | An audio converter

Returns
  The number of single conversion steps necessary to perform the conversion. It may be 0, in this case you must not use the converter and have to pass the audio frames directly. If something goes wrong (should never happen), -1 is returned.

This function can be called if the input and output formats didn't change but the options did.

## ◆ gavl_audio_convert()

GAVL_PUBLIC void gavl_audio_convert | ( | gavl_audio_converter_t * | cnv,
|  | const gavl_audio_frame_t * | input_frame,
|  | gavl_audio_frame_t * | output_frame )

Convert audio.

Parameters

  cnv | An audio converter
  input_frame | Input frame
  output_frame | Output frame

Be careful when resampling: gavl will assume, that your output frame is big enough. Minimum size is input_frame_size * output_samplerate / input_samplerate + 10

## ◆ gavl_audio_converter_set_resample_ratio()

GAVL_PUBLIC int gavl_audio_converter_set_resample_ratio | ( | gavl_audio_converter_t * | cnv,
|  | double | ratio )

Set samplerate conversion ratio.

Parameters

  cnv | An resample only audio converter created with gavl_audio_converter_init_resample
  ratio | desired src_ratio
       Max ratio = 256, Min ratio = 1/256 as defined by libsamplerate
       You should set this function before you call gavl_audio_converter_resample
       for the very first time.  If you call this function continually before subsequent
       calls to gavl_audio_converter_resample, the internal libsamplrate will step sample
       rate conversion up to the new ratio on your output audio frame in
       gavl_audio_converter_resample.  If you do NOT call this
       function before gavl_audio_converter_resample libsamplerate will linearly ramp
       the previous src_ratio to the new ratio for the given output audio frame in
       gavl_audio_converter_resample.

Since 1.1.0.

## ◆ gavl_audio_converter_resample()

GAVL_PUBLIC void gavl_audio_converter_resample | ( | gavl_audio_converter_t * | cnv,
|  | gavl_audio_frame_t * | input_frame,
|  | gavl_audio_frame_t * | output_frame,
|  | double | ratio )

Convert audio.

Parameters

  cnv | An audio converter
  input_frame | Input frame
  output_frame | Output frame
  ratio | src_ratio (output_frame.samplerate = ratio * input_frame.samplerate)

Be careful when resampling: gavl will assume, that your output frame is big enough. Minimum size for output_frame_size = input_frame_size * ratio (where ratio can be max 256.0 as defined by libsamplerate)

Since 1.1.0.