Audio frame
Audio

Container for audio data. More...

## Data Structures

union | gavl_audio_samples_t
| Container for interleaved audio samples. More...
union | gavl_audio_channels_t
| Container for noninterleaved audio samples. More...
struct | gavl_audio_frame_t
| Generic container for audio samples. More...

## Functions

GAVL_PUBLIC gavl_audio_frame_t * | gavl_audio_frame_create (const gavl_audio_format_t *format)
| Create audio frame.
GAVL_PUBLIC void | gavl_audio_frame_null (gavl_audio_frame_t *frame)
| Zero all pointers in the audio frame.
GAVL_PUBLIC void | gavl_audio_frame_destroy (gavl_audio_frame_t *frame)
| Destroy an audio frame.
GAVL_PUBLIC void | gavl_audio_frame_mute (gavl_audio_frame_t *frame, const gavl_audio_format_t *format)
| Mute an audio frame.
GAVL_PUBLIC void | gavl_audio_frame_mute_samples (gavl_audio_frame_t *frame, const gavl_audio_format_t *format, int num_samples)
| Mute a number of samples at the start of an audio frame.
GAVL_PUBLIC void | gavl_audio_frame_mute_channel (gavl_audio_frame_t *frame, const gavl_audio_format_t *format, int channel)
| Mute a single channel of an audio frame.
GAVL_PUBLIC int | gavl_audio_frame_copy (const gavl_audio_format_t *format, gavl_audio_frame_t *dst, const gavl_audio_frame_t *src, int dst_pos, int src_pos, int dst_size, int src_size)
| Copy audio data from one frame to another.
GAVL_PUBLIC void | gavl_audio_frame_copy_ptrs (const gavl_audio_format_t *format, gavl_audio_frame_t *dst, const gavl_audio_frame_t *src)
| Copy audio data from one frame to another.
GAVL_PUBLIC void | gavl_audio_frame_get_subframe (const gavl_audio_format_t *format, gavl_audio_frame_t *src, gavl_audio_frame_t *dst, int start, int len)
| Set an audio frame to a subframe of another frame.
GAVL_PUBLIC int | gavl_audio_frames_equal (const gavl_audio_format_t *format, const gavl_audio_frame_t *f1, const gavl_audio_frame_t *f2)
| Check if 2 audio frames are bit-identical.
GAVL_PUBLIC int | gavl_audio_frame_continuous (const gavl_audio_format_t *format, const gavl_audio_frame_t *f)
| Check if an audio frames is continuous in memory.
GAVL_PUBLIC void | gavl_audio_frame_set_channels (gavl_audio_frame_t *f, const gavl_audio_format_t *format, uint8_t *data)
| Set the channel pointers of an audio frame.
GAVL_PUBLIC void | gavl_audio_frame_from_data (gavl_audio_frame_t *f, const gavl_audio_format_t *format, uint8_t *data, int len)
| Set the channel pointers of an audio frame.
GAVL_PUBLIC int | gavl_audio_frame_skip (const gavl_audio_format_t *format, gavl_audio_frame_t *f, int num_samples)
| Skip samples in am audio frame.
GAVL_PUBLIC int | gavl_audio_frame_plot (const gavl_audio_format_t *format, const gavl_audio_frame_t *frame, const char *name_base)
| Plot an audio frame to an ASCII file.

## Detailed Description

Container for audio data.

## Function Documentation

## gavl_audio_frame_create()

GAVL_PUBLIC gavl_audio_frame_t * gavl_audio_frame_create | ( | const gavl_audio_format_t * | format | ) |

Create audio frame.

Parameters

  format | Format of the data to be stored in this frame or NULL

Creates an audio frame for a given format and allocates buffers for the audio data. The buffer size is determined by the samples_per_frame member of the format. To create an audio frame from your custom memory, pass NULL for the format and you'll get an empty frame in which you can set the pointers manually.

## gavl_audio_frame_null()

GAVL_PUBLIC void gavl_audio_frame_null | ( | gavl_audio_frame_t * | frame | ) |

Zero all pointers in the audio frame.

Parameters

  frame | An audio frame

Zero all pointers, so gavl_audio_frame_destroy won't free them. Call this for audio frames, which were created with a NULL format before destroying them.

## gavl_audio_frame_destroy()

GAVL_PUBLIC void gavl_audio_frame_destroy | ( | gavl_audio_frame_t * | frame | ) |

Destroy an audio frame.

Parameters

  frame | An audio frame

Destroys an audio frame and frees all associated memory. If you used your custom memory to allocate the frame, call gavl_audio_frame_null before.

## gavl_audio_frame_mute()

GAVL_PUBLIC void gavl_audio_frame_mute | ( | gavl_audio_frame_t * | frame,
|  | const gavl_audio_format_t * | format )

Mute an audio frame.

Parameters

  frame | An audio frame
  format | The format of the frame

Fills the frame with digital zero samples according to the audio format

## gavl_audio_frame_mute_samples()

GAVL_PUBLIC void gavl_audio_frame_mute_samples | ( | gavl_audio_frame_t * | frame,
|  | const gavl_audio_format_t * | format,
|  | int | num_samples )

Mute a number of samples at the start of an audio frame.

Parameters

  frame | An audio frame
  format | The format of the frame
  num_samples | Number of samples to mute

Fills the frame with digital zero samples according to the audio format

## gavl_audio_frame_mute_channel()

GAVL_PUBLIC void gavl_audio_frame_mute_channel | ( | gavl_audio_frame_t * | frame,
|  | const gavl_audio_format_t * | format,
|  | int | channel )

Mute a single channel of an audio frame.

Parameters

  frame | An audio frame
  format | The format of the frame
  channel | The channel to mute

Fills the frame with digital zero samples according to the audio format

## gavl_audio_frame_copy()

GAVL_PUBLIC int gavl_audio_frame_copy | ( | const gavl_audio_format_t * | format,
|  | gavl_audio_frame_t * | dst,
|  | const gavl_audio_frame_t * | src,
|  | int | dst_pos,
|  | int | src_pos,
|  | int | dst_size,
|  | int | src_size )

Copy audio data from one frame to another.

Parameters

  format | Format, must be equal for source and destination frames
  dst | Destination frame
  src | Source frame
  dst_pos | Offset (in samples) in the destination frame
  src_pos | Offset (in samples) in the source frame
  dst_size | Available samples in the destination frame
  src_size | Available samples in the source frame

Returns
  The actual number of copied samples

This function copies audio samples from src (starting at src_offset) to dst (starting at dst_offset). The number of copied samples will be the smaller one of src_size and dst_size.

You can use this function for creating a simple but effective audio buffer.

## gavl_audio_frame_copy_ptrs()

GAVL_PUBLIC void gavl_audio_frame_copy_ptrs | ( | const gavl_audio_format_t * | format,
|  | gavl_audio_frame_t * | dst,
|  | const gavl_audio_frame_t * | src )

Copy audio data from one frame to another.

Parameters

  format | Format, must be equal for source and destination frames
  dst | Destination frame
  src | Source frame

This function copies the pointers of the frame, not the actual data

Since 1.1.1

## gavl_audio_frame_get_subframe()

GAVL_PUBLIC void gavl_audio_frame_get_subframe | ( | const gavl_audio_format_t * | format,
|  | gavl_audio_frame_t * | src,
|  | gavl_audio_frame_t * | dst,
|  | int | start,
|  | int | len )

Set an audio frame to a subframe of another frame.

Parameters

  format | Format
  src | Source frame
  dst | Destination frame
  start | Start position in the source frame
  len | Length in samples

This sets all pointers and the valid_samples member in dst to a subframe of src. dst should be created with a NULL format and gavl_audio_frame_null should be called before destroying it.

Since 1.1.2

## gavl_audio_frames_equal()

GAVL_PUBLIC int gavl_audio_frames_equal | ( | const gavl_audio_format_t * | format,
|  | const gavl_audio_frame_t * | f1,
|  | const gavl_audio_frame_t * | f2 )

Check if 2 audio frames are bit-identical.

Parameters

  format | Format
  f1 | First frame
  f2 | Second frame

Returns
  1 if the frames are equal, 0 else

Since 1.2.0

## gavl_audio_frame_continuous()

GAVL_PUBLIC int gavl_audio_frame_continuous | ( | const gavl_audio_format_t * | format,
|  | const gavl_audio_frame_t * | f )

Check if an audio frames is continuous in memory.

Parameters

  format | Format
  f | Frame

Returns
  1 if the frame is continuous 0 else

Since 1.5.0

## gavl_audio_frame_set_channels()

GAVL_PUBLIC void gavl_audio_frame_set_channels | ( | gavl_audio_frame_t * | f,
|  | const gavl_audio_format_t * | format,
|  | uint8_t * | data )

Set the channel pointers of an audio frame.

Parameters

  f | Frame
  format | Format
  data | Address of the first sample of the first channel

Since 1.5.0

## gavl_audio_frame_from_data()

GAVL_PUBLIC void gavl_audio_frame_from_data | ( | gavl_audio_frame_t * | f,
|  | const gavl_audio_format_t * | format,
|  | uint8_t * | data,
|  | int | len )

Set the channel pointers of an audio frame.

Parameters

  f | Frame
  format | Format
  data | Address of the first sample of the first channel
  len | Total bytes

## gavl_audio_frame_skip()

GAVL_PUBLIC int gavl_audio_frame_skip | ( | const gavl_audio_format_t * | format,
|  | gavl_audio_frame_t * | f,
|  | int | num_samples )

Skip samples in am audio frame.

Parameters

  format | Format
  f | Audio frame
  num_samples | Number of samples skipped

Returns
  Number of samples actually skipped

Skip samples in an audio frame. If there are samples remaining, they are moved to the start of the frame. If not enough samples are there to skip, valid_samples will be zero after the call and the number of skipped samples is returned.

Since 1.5.0

## gavl_audio_frame_plot()

GAVL_PUBLIC int gavl_audio_frame_plot | ( | const gavl_audio_format_t * | format,
|  | const gavl_audio_frame_t * | frame,
|  | const char * | name_base )

Plot an audio frame to an ASCII file.

Parameters

  format | Format
  frame | An audio frame
  name_base | Filename base

Returns
  1 in success, 0 in failure

Plots an audio frame into an ascii file with one line per sample in the format: sample_number channel1 channel2 ...

In addition, a file for making a plot with gnuplot is generated. name_base is used for generating the filenames. For the data file, the extension ".dat" is appended. For the gnuplot file it's ".gnu"

Since 1.2.0