GstAudio.AudioBuffer

Fields

Name

Type

Access

Description

buffer

Gst.Buffer

r/w

the mapped buffer

info

GstAudio.AudioInfo

r/w

a GstAudio.AudioInfo describing the audio properties of this buffer

map_infos

Gst.MapInfo

r

n_planes

int

r/w

the number of planes available

n_samples

int

r/w

the size of the buffer in samples

planes

object

r/w

an array of n_planes pointers pointing to the start of each plane in the mapped buffer

priv_map_infos_arr

[Gst.MapInfo]

r

priv_planes_arr

[object]

r

Methods

class

clip (buffer, segment, rate, bpf)

class

map (info, gstbuffer, flags)

class

reorder_channels (buffer, format, from_, to)

class

truncate (buffer, bpf, trim, samples)

unmap ()

Details

class GstAudio.AudioBuffer

A structure containing the result of an audio buffer map operation, which is executed with GstAudio.AudioBuffer.map(). For non-interleaved (planar) buffers, the beginning of each channel in the buffer has its own pointer in the planes array. For interleaved buffers, the planes array only contains one item, which is the pointer to the beginning of the buffer, and n_planes equals 1.

The different channels in planes are always in the GStreamer channel order.

New in version 1.16.

classmethod clip(buffer, segment, rate, bpf)
Parameters:
Returns:

None if the buffer is completely outside the configured segment, otherwise the clipped buffer is returned.

If the buffer has no timestamp, it is assumed to be inside the segment and is not clipped

Return type:

Gst.Buffer or None

Clip the buffer to the given Gst.Segment.

After calling this function the caller does not own a reference to buffer anymore.

classmethod map(info, gstbuffer, flags)
Parameters:
Returns:

True if the map operation succeeded or False on failure

buffer:

pointer to a GstAudio.AudioBuffer

Return type:

(bool, buffer: GstAudio.AudioBuffer)

Maps an audio gstbuffer so that it can be read or written and stores the result of the map operation in buffer.

This is especially useful when the gstbuffer is in non-interleaved (planar) layout, in which case this function will use the information in the gstbuffer's attached GstAudio.AudioMeta in order to map each channel in a separate “plane” in GstAudio.AudioBuffer. If a GstAudio.AudioMeta is not attached on the gstbuffer, then it must be in interleaved layout.

If a GstAudio.AudioMeta is attached, then the GstAudio.AudioInfo on the meta is checked against info. Normally, they should be equal, but in case they are not, a g_critical will be printed and the GstAudio.AudioInfo from the meta will be used.

In non-interleaved buffers, it is possible to have each channel on a separate Gst.Memory. In this case, each memory will be mapped separately to avoid copying their contents in a larger memory area. Do note though that it is not supported to have a single channel spanning over two or more different Gst.Memory objects. Although the map operation will likely succeed in this case, it will be highly sub-optimal and it is recommended to merge all the memories in the buffer before calling this function.

Note: The actual Gst.Buffer is not ref’ed, but it is required to stay valid as long as it’s mapped.

New in version 1.16.

classmethod reorder_channels(buffer, format, from_, to)
Parameters:
Returns:

True if the reordering was possible.

Return type:

bool

Reorders buffer from the channel positions from to the channel positions to. from and to must contain the same number of positions and the same positions, only in a different order. buffer must be writable.

classmethod truncate(buffer, bpf, trim, samples)
Parameters:

  • buffer (Gst.Buffer) – The buffer to truncate.

  • bpf (int) – size of one audio frame in bytes. This is the size of one sample * number of channels.

  • trim (int) – the number of samples to remove from the beginning of the buffer

  • samples (int) – the final number of samples that should exist in this buffer or -1 to use all the remaining samples if you are only removing samples from the beginning.

Returns:

the truncated buffer

Return type:

Gst.Buffer

Truncate the buffer to finally have samples number of samples, removing the necessary amount of samples from the end and trim number of samples from the beginning.

This function does not know the audio rate, therefore the caller is responsible for re-setting the correct timestamp and duration to the buffer. However, timestamp will be preserved if trim == 0, and duration will also be preserved if there is no trimming to be done. Offset and offset end will be preserved / updated.

After calling this function the caller does not own a reference to buffer anymore.

New in version 1.16.

unmap()

Unmaps an audio buffer that was previously mapped with GstAudio.AudioBuffer.map().

New in version 1.16.