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_get_audio_downmix_meta_for_channels (buffer, to_position)

buffer_get_audio_level_meta (buffer)

stream_volume_convert_volume (from_, to, val)

Details

GstAudio.audio_buffer_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.

GstAudio.audio_buffer_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.

GstAudio.audio_buffer_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.

GstAudio.audio_buffer_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.

GstAudio.audio_channel_get_fallback_mask(channels)
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)
Parameters:
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)
Parameters:
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)
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)
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)
Parameters:
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()
Return type:

GObject.GType

GstAudio.audio_clipping_meta_get_info()
Return type:

Gst.MetaInfo

GstAudio.audio_downmix_meta_api_get_type()
Return type:

GObject.GType

GstAudio.audio_downmix_meta_get_info()
Return type:

Gst.MetaInfo

GstAudio.audio_format_build_integer(sign, endianness, width, depth)
Parameters:
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)
Parameters:

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)
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)
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()
Return type:

GObject.GType

GstAudio.audio_format_to_string(format)
Parameters:

format (GstAudio.AudioFormat) –

Return type:

str

GstAudio.audio_formats_raw()
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)
Parameters:
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)
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)
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)
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()
Returns:

a GstAudio.AudioInfo

Return type:

info: GstAudio.AudioInfo

Initialize info with default values.

GstAudio.audio_level_meta_api_get_type()
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()
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)
Parameters:
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()
Return type:

GObject.GType

GstAudio.audio_meta_get_info()
Return type:

Gst.MetaInfo

GstAudio.audio_reorder_channels(data, format, from_, to)
Parameters:
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)
Parameters:
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)
Parameters:

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)
Parameters:
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)
Parameters:
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)
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)
Parameters:
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_get_audio_downmix_meta_for_channels(buffer, to_position)
Parameters:
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)
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.stream_volume_convert_volume(from_, to, val)
Parameters:
Returns:

the converted volume

Return type:

float