GstAudio.AudioRingBuffer

Subclasses:

None

Methods

Inherited:

Gst.Object (27), GObject.Object (37)

Structs:

GObject.ObjectClass (5)

class	debug_spec_buff (spec)
class	debug_spec_caps (spec)
class	parse_caps (spec, caps)
	acquire (spec)
	activate (active)
	advance (advance)
	clear (segment)
	clear_all ()
	close_device ()
	commit (sample, data, out_samples, accum)
	convert (src_fmt, src_val, dest_fmt)
	delay ()
	device_is_open ()
	is_acquired ()
	is_active ()
	is_flushing ()
	may_start (allowed)
	open_device ()
	pause ()
	prepare_read ()
	read (sample, data)
	release ()
	samples_done ()
	set_callback (cb, *user_data)
	set_channel_positions (position)
	set_errored ()
	set_flushing (flushing)
	set_sample (sample)
	set_timestamp (readseg, timestamp)
	start ()
	stop ()

Virtual Methods

Inherited:

Gst.Object (1), GObject.Object (7)

	do_acquire (spec)
	do_activate (active)
	do_clear_all ()
	do_close_device ()
	do_commit (sample, data, out_samples, accum)
	do_delay ()
	do_open_device ()
	do_pause ()
	do_release ()
	do_resume ()
	do_start ()
	do_stop ()

Properties

Inherited:

Gst.Object (2)

Signals

Inherited:

Gst.Object (1), GObject.Object (1)

Fields

Inherited:

Gst.Object (1), GObject.Object (1)

Name	Type	Access	Description
acquired	bool	r	boolean indicating that the ringbuffer is acquired
active	bool	r
callback	GstAudio.AudioRingBufferCallback	r
cb_data	object	r
cb_data_notify	GLib.DestroyNotify	r
channel_reorder_map	[int]	r
cond	GLib.Cond	r	used to signal start/stop/pause/resume actions
empty_seg	int	r	pointer to memory holding one segment of silence samples
flushing	bool	r
memory	int	r	data in the ringbuffer
need_reorder	bool	r
object	Gst.Object	r
open	bool	r	boolean indicating that the ringbuffer is open
samples_per_seg	int	r	number of samples in one segment
segbase	int	r	segment corresponding to segment 0 (unused)
segdone	int	r	readpointer in the ringbuffer
size	int	r	size of data in the ringbuffer
spec	GstAudio.AudioRingBufferSpec	r	format and layout of the ringbuffer data
state	int	r	state of the buffer
timestamps	int	r
waiting	int	r	is a reader or writer waiting for a free segment

Class Details

class GstAudio.AudioRingBuffer(**kwargs)

Bases:

Gst.Object

Abstract:

Yes

Structure:

GstAudio.AudioRingBufferClass

This object is the base class for audio ringbuffers used by the base audio source and sink classes.

The ringbuffer abstracts a circular buffer of data. One reader and one writer can operate on the data from different threads in a lockfree manner. The base class is sufficiently flexible to be used as an abstraction for DMA based ringbuffers as well as a pure software implementations.

classmethod debug_spec_buff(spec)

Parameters:

spec (GstAudio.AudioRingBufferSpec) – the spec to debug

Print debug info about the buffer sized in spec to the debug log.

classmethod debug_spec_caps(spec)

Parameters:

spec (GstAudio.AudioRingBufferSpec) – the spec to debug

Print debug info about the parsed caps in spec to the debug log.

classmethod parse_caps(spec, caps)

Parameters:

• spec (GstAudio.AudioRingBufferSpec) – a spec

• caps (Gst.Caps) – a Gst.Caps

Returns:

True if the caps could be parsed.

Return type:

bool

Parse caps into spec.

acquire(spec)

Parameters:

spec (GstAudio.AudioRingBufferSpec) – the specs of the buffer

Returns:

True if the device could be acquired, False on error.

MT safe.

Return type:

bool

Allocate the resources for the ringbuffer. This function fills in the data pointer of the ring buffer with a valid Gst.Buffer to which samples can be written.

activate(active)

Parameters:

active (bool) – the new mode

Returns:

True if the device could be activated in the requested mode, False on error.

Return type:

bool

Activate self to start or stop pulling data.

MT safe.

advance(advance)

Parameters:

advance (int) – the number of segments written

Subclasses should call this function to notify the fact that advance segments are now processed by the device.

MT safe.

clear(segment)

Parameters:

segment (int) – the segment to clear

Clear the given segment of the buffer with silence samples. This function is used by subclasses.

MT safe.

clear_all()

Clear all samples from the ringbuffer.

MT safe.

close_device()

Returns:

True if the device could be closed, False on error.

MT safe.

Return type:

bool

Close the audio device associated with the ring buffer. The ring buffer should already have been released via GstAudio.AudioRingBuffer.release().

commit(sample, data, out_samples, accum)

Parameters:

• sample (int) – the sample position of the data

• data (bytes) – the data to commit

• out_samples (int) – the number of samples to write to the ringbuffer

• accum (int) – accumulator for rate conversion.

Returns:

The number of samples written to the ringbuffer or -1 on error. The number of samples written can be less than out_samples when self was interrupted with a flush or stop.

sample:

the sample position of the data

accum:

accumulator for rate conversion.

Return type:

(int, sample: int, accum: int)

Commit in_samples samples pointed to by data to the ringbuffer self.

in_samples and out_samples define the rate conversion to perform on the samples in data. For negative rates, out_samples must be negative and in_samples positive.

When out_samples is positive, the first sample will be written at position sample in the ringbuffer. When out_samples is negative, the last sample will be written to sample in reverse order.

out_samples does not need to be a multiple of the segment size of the ringbuffer although it is recommended for optimal performance.

accum will hold a temporary accumulator used in rate conversion and should be set to 0 when this function is first called. In case the commit operation is interrupted, one can resume the processing by passing the previously returned accum value back to this function.

MT safe.

convert(src_fmt, src_val, dest_fmt)

Parameters:

• src_fmt (Gst.Format) – the source format

• src_val (int) – the source value

• dest_fmt (Gst.Format) – the destination format

Returns:

True if the conversion succeeded.

dest_val:

a location to store the converted value

Return type:

(bool, dest_val: int)

Convert src_val in src_fmt to the equivalent value in dest_fmt. The result will be put in dest_val.

delay()

Returns:

The number of samples queued in the audio device.

MT safe.

Return type:

int

Get the number of samples queued in the audio device. This is usually less than the segment size but can be bigger when the implementation uses another internal buffer between the audio device.

For playback ringbuffers this is the amount of samples transferred from the ringbuffer to the device but still not played.

For capture ringbuffers this is the amount of samples in the device that are not yet transferred to the ringbuffer.

device_is_open()

Returns:

True if the device was open, False if it was closed.

MT safe.

Return type:

bool

Checks the status of the device associated with the ring buffer.

is_acquired()

Returns:

True if the ringbuffer is acquired, False on error.

MT safe.

Return type:

bool

Check if the ringbuffer is acquired and ready to use.

is_active()

Returns:

True if the device is active.

Return type:

bool

Check if self is activated.

MT safe.

is_flushing()

Returns:

True if the device is flushing.

Return type:

bool

Check if self is flushing.

MT safe.

may_start(allowed)

Parameters:

allowed (bool) – the new value

Tell the ringbuffer that it is allowed to start playback when the ringbuffer is filled with samples.

MT safe.

open_device()

Returns:

True if the device could be opened, False on error.

MT safe.

Return type:

bool

Open the audio device associated with the ring buffer. Does not perform any setup on the device. You must open the device before acquiring the ring buffer.

pause()

Returns:

True if the device could be paused, False on error.

MT safe.

Return type:

bool

Pause processing samples from the ringbuffer.

prepare_read()

Returns:

False if the buffer is not started.

MT safe.

segment:

the segment to read

readptr:

the pointer to the memory where samples can be read

Return type:

(bool, segment: int, readptr: bytes)

Returns a pointer to memory where the data from segment segment can be found. This function is mostly used by subclasses.

read(sample, data)

Parameters:

• sample (int) – the sample position of the data

• data (bytes) – where the data should be read

Returns:

The number of samples read from the ringbuffer or -1 on error.

MT safe.

timestamp:

where the timestamp is returned

Return type:

(int, timestamp: int)

Read len samples from the ringbuffer into the memory pointed to by data. The first sample should be read from position sample in the ringbuffer.

len should not be a multiple of the segment size of the ringbuffer although it is recommended.

timestamp will return the timestamp associated with the data returned.

release()

Returns:

True if the device could be released, False on error.

MT safe.

Return type:

bool

Free the resources of the ringbuffer.

samples_done()

Returns:

The number of samples processed by the ringbuffer.

MT safe.

Return type:

int

Get the number of samples that were processed by the ringbuffer since it was last started. This does not include the number of samples not yet processed (see GstAudio.AudioRingBuffer.delay()).

set_callback(cb, *user_data)

Parameters:

• cb (GstAudio.AudioRingBufferCallback or None) – the callback to set

• user_data (object or None) – user data passed to the callback

Sets the given callback function on the buffer. This function will be called every time a segment has been written to a device.

MT safe.

New in version 1.12.

set_channel_positions(position)

Parameters:

position ([GstAudio.AudioChannelPosition]) – the device channel positions

Tell the ringbuffer about the device’s channel positions. This must be called in when the ringbuffer is acquired.

set_errored()

Mark the ringbuffer as errored after it has started.

MT safe.

New in version 1.24.

set_flushing(flushing)

Parameters:

flushing (bool) – the new mode

Set the ringbuffer to flushing mode or normal mode.

MT safe.

set_sample(sample)

Parameters:

sample (int) – the sample number to set

Make sure that the next sample written to the device is accounted for as being the sample sample written to the device. This value will be used in reporting the current sample position of the ringbuffer.

This function will also clear the buffer with silence.

MT safe.

set_timestamp(readseg, timestamp)

Parameters:

• readseg (int) –

• timestamp (int) –

start()

Returns:

True if the device could be started, False on error.

MT safe.

Return type:

bool

Start processing samples from the ringbuffer.

stop()

Returns:

True if the device could be stopped, False on error.

MT safe.

Return type:

bool

Stop processing samples from the ringbuffer.

do_acquire(spec) virtual

Parameters:

spec (GstAudio.AudioRingBufferSpec) – the specs of the buffer

Returns:

True if the device could be acquired, False on error.

MT safe.

Return type:

bool

Allocate the resources for the ringbuffer. This function fills in the data pointer of the ring buffer with a valid Gst.Buffer to which samples can be written.

do_activate(active) virtual

Parameters:

active (bool) – the new mode

Returns:

True if the device could be activated in the requested mode, False on error.

Return type:

bool

Activate buf to start or stop pulling data.

MT safe.

do_clear_all() virtual

Clear all samples from the ringbuffer.

MT safe.

do_close_device() virtual

Returns:

True if the device could be closed, False on error.

MT safe.

Return type:

bool

Close the audio device associated with the ring buffer. The ring buffer should already have been released via GstAudio.AudioRingBuffer.release().

do_commit(sample, data, out_samples, accum) virtual

Parameters:

• sample (int) – the sample position of the data

• data (bytes) – the data to commit

• out_samples (int) – the number of samples to write to the ringbuffer

• accum (int) – accumulator for rate conversion.

Returns:

The number of samples written to the ringbuffer or -1 on error. The number of samples written can be less than out_samples when buf was interrupted with a flush or stop.

sample:

the sample position of the data

accum:

accumulator for rate conversion.

Return type:

(int, sample: int, accum: int)

Commit in_samples samples pointed to by data to the ringbuffer buf.

in_samples and out_samples define the rate conversion to perform on the samples in data. For negative rates, out_samples must be negative and in_samples positive.

When out_samples is positive, the first sample will be written at position sample in the ringbuffer. When out_samples is negative, the last sample will be written to sample in reverse order.

out_samples does not need to be a multiple of the segment size of the ringbuffer although it is recommended for optimal performance.

accum will hold a temporary accumulator used in rate conversion and should be set to 0 when this function is first called. In case the commit operation is interrupted, one can resume the processing by passing the previously returned accum value back to this function.

MT safe.

do_delay() virtual

Returns:

The number of samples queued in the audio device.

MT safe.

Return type:

int

Get the number of samples queued in the audio device. This is usually less than the segment size but can be bigger when the implementation uses another internal buffer between the audio device.

For playback ringbuffers this is the amount of samples transferred from the ringbuffer to the device but still not played.

For capture ringbuffers this is the amount of samples in the device that are not yet transferred to the ringbuffer.

do_open_device() virtual

Returns:

True if the device could be opened, False on error.

MT safe.

Return type:

bool

Open the audio device associated with the ring buffer. Does not perform any setup on the device. You must open the device before acquiring the ring buffer.

do_pause() virtual

Returns:

True if the device could be paused, False on error.

MT safe.

Return type:

bool

Pause processing samples from the ringbuffer.

do_release() virtual

Returns:

True if the device could be released, False on error.

MT safe.

Return type:

bool

Free the resources of the ringbuffer.

do_resume() virtual

Return type:

bool

resume processing of samples after pause

do_start() virtual

Returns:

True if the device could be started, False on error.

MT safe.

Return type:

bool

Start processing samples from the ringbuffer.

do_stop() virtual

Returns:

True if the device could be stopped, False on error.

MT safe.

Return type:

bool

Stop processing samples from the ringbuffer.