Functions¶

	`audio_buffer_clip` (buffer, segment, rate, bpf)
	`audio_buffer_map` (info, gstbuffer, flags)
	`audio_buffer_reorder_channels` (buffer, format, from_, to)
	`audio_buffer_truncate` (buffer, bpf, trim, samples)
	`audio_channel_get_fallback_mask` (channels)
	`audio_channel_positions_from_mask` (channel_mask, position)
	`audio_channel_positions_to_mask` (position, force_order)
	`audio_channel_positions_to_string` (position)
	`audio_channel_positions_to_valid_order` (position)
	`audio_check_valid_channel_positions` (position, force_order)
	`audio_clipping_meta_api_get_type` ()
	`audio_clipping_meta_get_info` ()
	`audio_downmix_meta_api_get_type` ()
	`audio_downmix_meta_get_info` ()
	`audio_format_build_integer` (sign, endianness, width, depth)
	`audio_format_fill_silence` (info, dest)
	`audio_format_from_string` (format)
	`audio_format_get_info` (format)
	`audio_format_info_get_type` ()
	`audio_format_to_string` (format)
	`audio_formats_raw` ()
	`audio_get_channel_reorder_map` (from_, to, reorder_map)
	`audio_iec61937_frame_size` (spec)
	`audio_iec61937_payload` (src, dst, spec, endianness)
	`audio_info_from_caps` (caps)
	`audio_info_init` ()
	`audio_level_meta_api_get_type` ()
	`audio_level_meta_get_info` ()
	`audio_make_raw_caps` (formats, layout)
	`audio_meta_api_get_type` ()
	`audio_meta_get_info` ()
	`audio_reorder_channels` (data, format, from_, to)
	`audio_resampler_new` (method, flags, format, channels, in_rate, out_rate, options)
	`audio_resampler_options_set_quality` (method, quality, in_rate, out_rate, options)
	`buffer_add_audio_clipping_meta` (buffer, format, start, end)
	`buffer_add_audio_downmix_meta` (buffer, from_position, to_position, matrix)
	`buffer_add_audio_level_meta` (buffer, level, voice_activity)
	`buffer_add_audio_meta` (buffer, info, samples, offsets)
	`buffer_add_dsd_plane_offset_meta` (buffer, num_channels, num_bytes_per_channel, offsets)
	`buffer_get_audio_downmix_meta_for_channels` (buffer, to_position)
	`buffer_get_audio_level_meta` (buffer)
	`dsd_convert` (input_data, output_data, input_format, output_format, input_layout, output_layout, input_plane_offsets, output_plane_offsets, num_dsd_bytes, num_channels, reverse_byte_bits)
	`dsd_format_from_string` (str)
	`dsd_format_get_width` (format)
	`dsd_format_to_string` (format)
	`dsd_info_from_caps` (caps)
	`dsd_info_init` ()
	`dsd_plane_offset_meta_api_get_type` ()
	`dsd_plane_offset_meta_get_info` ()
	`stream_volume_convert_volume` (from_, to, val)

Details¶

GstAudio.audio_buffer_clip(buffer, segment, rate, bpf)[source]¶

Parameters:

buffer (Gst.Buffer) – The buffer to clip.
segment (Gst.Segment) – Segment in Gst.Format.TIME or Gst.Format.DEFAULT to which the buffer should be clipped.
rate (int) – sample rate.
bpf (int) – size of one audio frame in bytes. This is the size of one sample * number of channels.

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.

GstAudio.audio_buffer_map(info, gstbuffer, flags)[source]¶

Parameters:

info (GstAudio.AudioInfo) – the audio properties of the buffer
gstbuffer (Gst.Buffer) – the Gst.Buffer to be mapped
flags (Gst.MapFlags) – the access mode for the memory

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.

GstAudio.audio_buffer_reorder_channels(buffer, format, from_, to)[source]¶

Parameters:

buffer (Gst.Buffer) – The buffer to reorder.
format (GstAudio.AudioFormat) – The GstAudio.AudioFormat of the buffer.
from ([GstAudio.AudioChannelPosition]) – The channel positions in the buffer.
to ([GstAudio.AudioChannelPosition]) – The channel positions to convert to.

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.

GstAudio.audio_buffer_truncate(buffer, bpf, trim, samples)[source]¶

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.

GstAudio.audio_channel_get_fallback_mask(channels)[source]¶

Parameters:: channels (int) – the number of channels
Returns:: a fallback channel-mask for channels or 0 when there is no mask and mono.
Return type:: int

Get the fallback channel-mask for the given number of channels.

This function returns a reasonable fallback channel-mask and should be called as a last resort when the specific channel map is unknown.

New in version 1.8.

GstAudio.audio_channel_positions_from_mask(channel_mask, position)[source]¶

Parameters:

channel_mask (int) – The input channel_mask
position ([GstAudio.AudioChannelPosition]) – The GstAudio.AudioChannelPosition s

Returns:

True if channel and channel mask are valid and could be converted

Return type:

bool

Convert the channels present in channel_mask to a position array (which should have at least channels entries ensured by caller). If channel_mask is set to 0, it is considered as ‘not present’ for purpose of conversion. A partially valid channel_mask with less bits set than the number of channels is considered valid.

GstAudio.audio_channel_positions_to_mask(position, force_order)[source]¶

Parameters:

position ([GstAudio.AudioChannelPosition]) – The GstAudio.AudioChannelPositions
force_order (bool) – Only consider the GStreamer channel order.

Returns:

True if the channel positions are valid and could be converted.

channel_mask:: the output channel mask

Return type:

(bool, channel_mask: int)

Convert the position array of channels channels to a bitmask.

If force_order is True it additionally checks if the channels are in the order required by GStreamer.

GstAudio.audio_channel_positions_to_string(position)[source]¶

Parameters:: position ([GstAudio.AudioChannelPosition]) – The GstAudio.AudioChannelPositions to convert.
Returns:: a newly allocated string representing position
Return type:: str

Converts position to a human-readable string representation for debugging purposes.

New in version 1.10.

GstAudio.audio_channel_positions_to_valid_order(position)[source]¶

Parameters:: position ([GstAudio.AudioChannelPosition]) – The channel positions to reorder to.
Returns:: True if the channel positions are valid and reordering was successful.
Return type:: bool

Reorders the channel positions in position from any order to the GStreamer channel order.

GstAudio.audio_check_valid_channel_positions(position, force_order)[source]¶

Parameters:

position ([GstAudio.AudioChannelPosition]) – The GstAudio.AudioChannelPositions to check.
force_order (bool) – Only consider the GStreamer channel order.

Returns:

True if the channel positions are valid.

Return type:

bool

Checks if position contains valid channel positions for channels channels. If force_order is True it additionally checks if the channels are in the order required by GStreamer.

GstAudio.audio_clipping_meta_api_get_type()[source]¶

Return type:: GObject.GType

GstAudio.audio_clipping_meta_get_info()[source]¶

Return type:: Gst.MetaInfo

GstAudio.audio_downmix_meta_api_get_type()[source]¶

Return type:: GObject.GType

GstAudio.audio_downmix_meta_get_info()[source]¶

Return type:: Gst.MetaInfo

GstAudio.audio_format_build_integer(sign, endianness, width, depth)[source]¶

Parameters:

sign (bool) – signed or unsigned format
endianness (int) – GLib.LITTLE_ENDIAN or GLib.BIG_ENDIAN
width (int) – amount of bits used per sample
depth (int) – amount of used bits in width

Returns:

a GstAudio.AudioFormat or GstAudio.AudioFormat.UNKNOWN when no audio format exists with the given parameters.

Return type:

GstAudio.AudioFormat

Construct a GstAudio.AudioFormat with given parameters.

GstAudio.audio_format_fill_silence(info, dest)[source]¶

Parameters:

info (GstAudio.AudioFormatInfo) – a GstAudio.AudioFormatInfo
dest (bytes) – a destination to fill

Fill length bytes in dest with silence samples for info.

Deprecated since version 1.20: Use GstAudio.AudioFormatInfo.fill_silence() instead.

GstAudio.audio_format_from_string(format)[source]¶

Parameters:: format (str) – a format string
Returns:: the GstAudio.AudioFormat for format or GstAudio.AudioFormat.UNKNOWN when the string is not a known format.
Return type:: GstAudio.AudioFormat

Convert the format string to its GstAudio.AudioFormat.

GstAudio.audio_format_get_info(format)[source]¶

Parameters:: format (GstAudio.AudioFormat) – a GstAudio.AudioFormat
Returns:: The GstAudio.AudioFormatInfo for format.
Return type:: GstAudio.AudioFormatInfo

Get the GstAudio.AudioFormatInfo for format

GstAudio.audio_format_info_get_type()[source]¶

Return type:: GObject.GType

GstAudio.audio_format_to_string(format)[source]¶

Parameters:: format (GstAudio.AudioFormat) –
Return type:: str

GstAudio.audio_formats_raw()[source]¶

Returns:: an array of GstAudio.AudioFormat
Return type:: [GstAudio.AudioFormat]

Return all the raw audio formats supported by GStreamer.

New in version 1.18.

GstAudio.audio_get_channel_reorder_map(from_, to, reorder_map)[source]¶

Parameters:

from ([GstAudio.AudioChannelPosition]) – The channel positions to reorder from.
to ([GstAudio.AudioChannelPosition]) – The channel positions to reorder to.
reorder_map ([int]) – Pointer to the reorder map.

Returns:

True if the channel positions are valid and reordering is possible.

Return type:

bool

Returns a reorder map for from to to that can be used in custom channel reordering code, e.g. to convert from or to the GStreamer channel order. from and to must contain the same number of positions and the same positions, only in a different order.

The resulting reorder_map can be used for reordering by assigning channel i of the input to channel reorder_map[i] of the output.

GstAudio.audio_iec61937_frame_size(spec)[source]¶

Parameters:: spec (GstAudio.AudioRingBufferSpec) – the ringbufer spec
Returns:: the size or 0 if the given type is not supported or cannot be payloaded.
Return type:: int

Calculated the size of the buffer expected by GstAudio.audio_iec61937_payload() for payloading type from spec.

GstAudio.audio_iec61937_payload(src, dst, spec, endianness)[source]¶

Parameters:

src (bytes) – a buffer containing the data to payload
dst (bytes) – the destination buffer to store the payloaded contents in. Should not overlap with src
spec (GstAudio.AudioRingBufferSpec) – the ringbufer spec for src
endianness (int) – the expected byte order of the payloaded data

Returns:

transfer-full: True if the payloading was successful, False otherwise.

Return type:

bool

Payloads src in the form specified by IEC 61937 for the type from spec and stores the result in dst. src must contain exactly one frame of data and the frame is not checked for errors.

GstAudio.audio_info_from_caps(caps)[source]¶

Parameters:

caps (Gst.Caps) – a Gst.Caps

Returns:

True if caps could be parsed

info:: a GstAudio.AudioInfo

Return type:

(bool, info: GstAudio.AudioInfo)

Parse caps and update info.

GstAudio.audio_info_init()[source]¶

Returns:: a GstAudio.AudioInfo
Return type:: info: GstAudio.AudioInfo

Initialize info with default values.

GstAudio.audio_level_meta_api_get_type()[source]¶

Returns:: a GObject.GType
Return type:: GObject.GType

Return the GObject.GType associated with GstAudio.AudioLevelMeta.

New in version 1.20.

GstAudio.audio_level_meta_get_info()[source]¶

Returns:: a Gst.MetaInfo
Return type:: Gst.MetaInfo

Return the Gst.MetaInfo associated with GstAudio.AudioLevelMeta.

New in version 1.20.

GstAudio.audio_make_raw_caps(formats, layout)[source]¶

Parameters:

formats ([GstAudio.AudioFormat] or None) – an array of raw GstAudio.AudioFormat, or None
layout (GstAudio.AudioLayout) – the layout of audio samples

Returns:

an audio GstCaps

Return type:

Gst.Caps

Return a generic raw audio caps for formats defined in formats. If formats is None returns a caps for all the supported raw audio formats, see GstAudio.audio_formats_raw().

New in version 1.18.

GstAudio.audio_meta_api_get_type()[source]¶

Return type:: GObject.GType

GstAudio.audio_meta_get_info()[source]¶

Return type:: Gst.MetaInfo

GstAudio.audio_reorder_channels(data, format, from_, to)[source]¶

Parameters:

data (bytes) – The pointer to the memory.
format (GstAudio.AudioFormat) – The GstAudio.AudioFormat of the buffer.
from ([GstAudio.AudioChannelPosition]) – The channel positions in the buffer.
to ([GstAudio.AudioChannelPosition]) – The channel positions to convert to.

Returns:

True if the reordering was possible.

Return type:

bool

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

Note: this function assumes the audio data is in interleaved layout

GstAudio.audio_resampler_new(method, flags, format, channels, in_rate, out_rate, options)[source]¶

Parameters:

method (GstAudio.AudioResamplerMethod) – a GstAudio.AudioResamplerMethod
flags (GstAudio.AudioResamplerFlags) – GstAudio.AudioResamplerFlags
format (GstAudio.AudioFormat) – the GstAudio.AudioFormat
channels (int) – the number of channels
in_rate (int) – input rate
out_rate (int) – output rate
options (Gst.Structure) – extra options

Returns:

The new GstAudio.AudioResampler.

Return type:

GstAudio.AudioResampler

Make a new resampler.

GstAudio.audio_resampler_options_set_quality(method, quality, in_rate, out_rate, options)[source]¶

Parameters:

method (GstAudio.AudioResamplerMethod) – a GstAudio.AudioResamplerMethod
quality (int) – the quality
in_rate (int) – the input rate
out_rate (int) – the output rate
options (Gst.Structure) – a Gst.Structure

Set the parameters for resampling from in_rate to out_rate using method for quality in options.

GstAudio.buffer_add_audio_clipping_meta(buffer, format, start, end)[source]¶

Parameters:

buffer (Gst.Buffer) – a Gst.Buffer
format (Gst.Format) – Gst.Format of start and stop, Gst.Format.DEFAULT is samples
start (int) – Amount of audio to clip from start of buffer
end (int) – Amount of to clip from end of buffer

Returns:

the GstAudio.AudioClippingMeta on buffer.

Return type:

GstAudio.AudioClippingMeta

Attaches GstAudio.AudioClippingMeta metadata to buffer with the given parameters.

New in version 1.8.

GstAudio.buffer_add_audio_downmix_meta(buffer, from_position, to_position, matrix)[source]¶

Parameters:

buffer (Gst.Buffer) – a Gst.Buffer
from_position ([GstAudio.AudioChannelPosition]) – the channel positions of the source
to_position ([GstAudio.AudioChannelPosition]) – the channel positions of the destination
matrix (float) – The matrix coefficients.

Returns:

the GstAudio.AudioDownmixMeta on buffer.

Return type:

GstAudio.AudioDownmixMeta

Attaches GstAudio.AudioDownmixMeta 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.

GstAudio.buffer_add_audio_level_meta(buffer, level, voice_activity)[source]¶

Parameters:

buffer (Gst.Buffer) – a Gst.Buffer
level (int) – the -dBov from 0-127 (127 is silence).
voice_activity (bool) – whether the buffer contains voice activity.

Returns:

the GstAudio.AudioLevelMeta on buffer.

Return type:

GstAudio.AudioLevelMeta or None

Attaches audio level information to buffer. (RFC 6464)

New in version 1.20.

GstAudio.buffer_add_audio_meta(buffer, info, samples, offsets)[source]¶

Parameters:

buffer (Gst.Buffer) – a Gst.Buffer
info (GstAudio.AudioInfo) – the audio properties of the buffer
samples (int) – the number of valid samples in the buffer
offsets (int or None) – the offsets (in bytes) where each channel plane starts in the buffer or None to calculate it (see below); must be None also when info->layout is GstAudio.AudioLayout.INTERLEAVED

Returns:

the GstAudio.AudioMeta that was attached on the buffer

Return type:

GstAudio.AudioMeta

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

When info->layout is GstAudio.AudioLayout.NON_INTERLEAVED and offsets is None, 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.

New in version 1.16.

GstAudio.buffer_add_dsd_plane_offset_meta(buffer, num_channels, num_bytes_per_channel, offsets)[source]¶

Parameters:

buffer (Gst.Buffer) – a Gst.Buffer
num_channels (int) – Number of channels in the DSD data
num_bytes_per_channel (int) – Number of bytes per channel
offsets (int or None) – the offsets (in bytes) where each channel plane starts in the buffer

Returns:

the GstAudio.DsdPlaneOffsetMeta that was attached on the buffer

Return type:

GstAudio.DsdPlaneOffsetMeta

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

If offsets is None, then the meta’s offsets field is left uninitialized. This is useful if for example offset values are to be calculated in the meta’s offsets field in-place. Similarly, num_bytes_per_channel can be set to 0, but only if offsets is None. This is useful if the number of bytes per channel is known only later.

It is not allowed for channels to overlap in memory, i.e. for each i in [0, channels), the range [offsets[i], offsets[i] + num_bytes_per_channel) 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.

This meta is only needed for non-interleaved (= planar) DSD data.

New in version 1.24.

GstAudio.buffer_get_audio_downmix_meta_for_channels(buffer, to_position)[source]¶

Parameters:

buffer (Gst.Buffer) – a Gst.Buffer
to_position ([GstAudio.AudioChannelPosition]) – the channel positions of the destination

Returns:

the GstAudio.AudioDownmixMeta on buffer.

Return type:

GstAudio.AudioDownmixMeta

Find the GstAudio.AudioDownmixMeta on buffer for the given destination channel positions.

GstAudio.buffer_get_audio_level_meta(buffer)[source]¶

Parameters:: buffer (Gst.Buffer) – a Gst.Buffer
Returns:: the GstAudio.AudioLevelMeta or None when there is no such metadata on buffer.
Return type:: GstAudio.AudioLevelMeta or None

Find the GstAudio.AudioLevelMeta on buffer.

New in version 1.20.

GstAudio.dsd_convert(input_data, output_data, input_format, output_format, input_layout, output_layout, input_plane_offsets, output_plane_offsets, num_dsd_bytes, num_channels, reverse_byte_bits)[source]¶

Parameters:

input_data (int) – the DSD format conversion’s input source
output_data (int) – the DSD format conversion’s output destination
input_format (GstAudio.DsdFormat) – DSD format of the input data to convert from
output_format (GstAudio.DsdFormat) – DSD format of the output data to convert to
input_layout (GstAudio.AudioLayout) – Input data layout
output_layout (GstAudio.AudioLayout) – Output data layout
input_plane_offsets (int) – Plane offsets for non-interleaved input data
output_plane_offsets (int) – Plane offsets for non-interleaved output data
num_dsd_bytes (int) – How many bytes with DSD data to convert
num_channels (int) – Number of channels (must be at least 1)
reverse_byte_bits (bool) – If True, reverse the bits in each DSD byte

Converts DSD data from one layout and grouping format to another. num_bytes must be an integer multiple of the width of both input and output format. For example, if the input format is GstAudio.DsdFormat.DSD_FORMAT_U32LE, and the output format is GstAudio.DsdFormat.DSD_FORMAT_U16BE, then num_bytes must be an integer multiple of both 4 (U32LE width) and 2 (U16BE width).

reverse_byte_bits is necessary if the bit order within the DSD bytes needs to be reversed. This is rarely necessary, and is not to be confused with the endianness of formats (which determines the ordering of *bytes*).

input_plane_offsets must not be None if input_layout is set to GstAudio.AudioLayout.NON_INTERLEAVED. The same applies to output_plane_offsets. These plane offsets define the starting offset of the planes (there is exactly one plane per channel) within input_data and output_data respectively. If GstAudio.AudioLayout.INTERLEAVED is used, the plane offsets are ignored.

New in version 1.24.

GstAudio.dsd_format_from_string(str)[source]¶

Parameters:: str (str) – a DSD format string
Returns:: the GstAudio.DsdFormat for format or GstAudio.DsdFormat.DSD_FORMAT_UNKNOWN when the string is not a known format.
Return type:: GstAudio.DsdFormat