GstAudio meta

GstAudio meta — Buffer metadata for audio downmix matrix handling

Functions

Types and Values

Includes

#include <gst/audio/audio.h>

Description

GstAudioDownmixMeta defines an audio downmix matrix to be send along with audio buffers. These functions in this module help to create and attach the meta as well as extracting it.

Functions

gst_buffer_add_audio_meta ()

GstAudioMeta *
gst_buffer_add_audio_meta (GstBuffer *buffer,
                           const GstAudioInfo *info,
                           gsize samples,
                           gsize offsets[]);

Allocates and attaches a GstAudioMeta on buffer , which must be writable for that purpose. The fields of the GstAudioMeta are directly populated from the arguments of this function.

When info->layout is GST_AUDIO_LAYOUT_NON_INTERLEAVED and offsets is NULL, the offsets are calculated with a formula that assumes the planes are tightly packed and in sequence: offsets[channel] = channel * samples * sample_stride

It is not allowed for channels to overlap in memory, i.e. for each i in [0, channels), the range [offsets [i], offsets [i] + samples * sample_stride) must not overlap with any other such range. This function will assert if the parameters specified cause this restriction to be violated.

It is, obviously, also not allowed to specify parameters that would cause out-of-bounds memory access on buffer . This is also checked, which means that you must add enough memory on the buffer before adding this meta.

Parameters

buffer

a GstBuffer

 

info

the audio properties of the buffer

 

samples

the number of valid samples in the buffer

 

offsets

the offsets (in bytes) where each channel plane starts in the buffer or NULL to calculate it (see below); must be NULL also when info->layout is GST_AUDIO_LAYOUT_INTERLEAVED.

[nullable]

Returns

the GstAudioMeta that was attached on the buffer

Since: 1.16


gst_buffer_get_audio_meta()

#define             gst_buffer_get_audio_meta(b)

gst_buffer_add_audio_downmix_meta ()

GstAudioDownmixMeta *
gst_buffer_add_audio_downmix_meta (GstBuffer *buffer,
                                   const GstAudioChannelPosition *from_position,
                                   gint from_channels,
                                   const GstAudioChannelPosition *to_position,
                                   gint to_channels,
                                   const gfloat **matrix);

Attaches GstAudioDownmixMeta metadata to buffer with the given parameters.

matrix is an two-dimensional array of to_channels times from_channels coefficients, i.e. the i-th output channels is constructed by multiplicating the input channels with the coefficients in matrix [i] and taking the sum of the results.

Parameters

buffer

a GstBuffer

 

from_position

the channel positions of the source.

[array length=from_channels]

from_channels

The number of channels of the source

 

to_position

the channel positions of the destination.

[array length=to_channels]

to_channels

The number of channels of the destination

 

matrix

The matrix coefficients.

 

Returns

the GstAudioDownmixMeta on buffer .

[transfer none]


gst_buffer_get_audio_downmix_meta()

#define gst_buffer_get_audio_downmix_meta(b) ((GstAudioDownmixMeta*)gst_buffer_get_meta((b), GST_AUDIO_DOWNMIX_META_API_TYPE))

gst_buffer_get_audio_downmix_meta_for_channels ()

GstAudioDownmixMeta *
gst_buffer_get_audio_downmix_meta_for_channels
                               (GstBuffer *buffer,
                                const GstAudioChannelPosition *to_position,
                                gint to_channels);

Find the GstAudioDownmixMeta on buffer for the given destination channel positions.

Parameters

buffer

a GstBuffer

 

to_position

the channel positions of the destination.

[array length=to_channels]

to_channels

The number of channels of the destination

 

Returns

the GstAudioDownmixMeta on buffer .

[transfer none]


gst_buffer_add_audio_clipping_meta ()

GstAudioClippingMeta *
gst_buffer_add_audio_clipping_meta (GstBuffer *buffer,
                                    GstFormat format,
                                    guint64 start,
                                    guint64 end);

Attaches GstAudioClippingMeta metadata to buffer with the given parameters.

Parameters

buffer

a GstBuffer

 

format

GstFormat of start and stop , GST_FORMAT_DEFAULT is samples

 

start

Amount of audio to clip from start of buffer

 

end

Amount of to clip from end of buffer

 

Returns

the GstAudioClippingMeta on buffer .

[transfer none]

Since: 1.8


gst_buffer_get_audio_clipping_meta()

#define gst_buffer_get_audio_clipping_meta(b) ((GstAudioClippingMeta*)gst_buffer_get_meta((b), GST_AUDIO_CLIPPING_META_API_TYPE))

Types and Values

struct GstAudioMeta

struct GstAudioMeta {
  GstMeta      meta;

  GstAudioInfo info;
  gsize        samples;
  gsize        *offsets;
};

Buffer metadata describing how data is laid out inside the buffer. This is useful for non-interleaved (planar) buffers, where it is necessary to have a place to store where each plane starts and how long each plane is.

It is a requirement for non-interleaved buffers to have this metadata attached and to be mapped with gst_audio_buffer_map() in order to ensure correct handling of clipping and channel reordering.

The different channels in offsets are always in the GStreamer channel order. Zero-copy channel reordering can be implemented by swapping the values in offsets .

It is not allowed for channels to overlap in memory, i.e. for each i in [0, channels), the range [offsets [i], offsets [i] + samples * sample_stride) must not overlap with any other such range.

It is, however, allowed to have parts of the buffer memory unused, by using offsets and samples in such a way that leave gaps on it. This is used to implement zero-copy clipping in non-interleaved buffers.

Obviously, due to the above, it is not safe to infer the number of valid samples from the size of the buffer. You should always use the samples variable of this metadata.

Note that for interleaved audio it is not a requirement to have this metadata attached and at the moment of writing, there is actually no use case to do so. It is, however, allowed to attach it, for some potential future use case.

Members

GstMeta meta;

parent GstMeta

 

GstAudioInfo info;

the audio properties of the buffer

 

gsize samples;

the number of valid samples in the buffer

 

gsize *offsets;

the offsets (in bytes) where each channel plane starts in the buffer or NULL if the buffer has interleaved layout; if not NULL, this is guaranteed to be an array of info.channels elements

 

Since: 1.16


struct GstAudioDownmixMeta

struct GstAudioDownmixMeta {
  GstMeta      meta;

  GstAudioChannelPosition *from_position;
  GstAudioChannelPosition *to_position;
  gint        from_channels, to_channels;
  gfloat       **matrix;
};

Extra buffer metadata describing audio downmixing matrix. This metadata is attached to audio buffers and contains a matrix to downmix the buffer number of channels to channels .

matrix is an two-dimensional array of to_channels times from_channels coefficients, i.e. the i-th output channels is constructed by multiplicating the input channels with the coefficients in matrix [i] and taking the sum of the results.

Members

GstMeta meta;

parent GstMeta

 

GstAudioChannelPosition *from_position;

the channel positions of the source

 

GstAudioChannelPosition *to_position;

the channel positions of the destination

 

gint from_channels;

the number of channels of the source

 

gint to_channels;

the number of channels of the destination

 

gfloat **matrix;

the matrix coefficients.

 

struct GstAudioClippingMeta

struct GstAudioClippingMeta {
  GstMeta   meta;

  GstFormat format;
  guint64   start;
  guint64   end;
};

Extra buffer metadata describing how much audio has to be clipped from the start or end of a buffer. This is used for compressed formats, where the first frame usually has some additional samples due to encoder and decoder delays, and the last frame usually has some additional samples to be able to fill the complete last frame.

This is used to ensure that decoded data in the end has the same amount of samples, and multiply decoded streams can be gaplessly concatenated.

Note: If clipping of the start is done by adjusting the segment, this meta has to be dropped from buffers as otherwise clipping could happen twice.

Members

GstMeta meta;

parent GstMeta

 

GstFormat format;

GstFormat of start and stop , GST_FORMAT_DEFAULT is samples

 

guint64 start;

Amount of audio to clip from start of buffer

 

guint64 end;

Amount of to clip from end of buffer

 

Since: 1.8