GstAudio.AudioRingBuffer

g GObject.InitiallyUnowned GObject.InitiallyUnowned Gst.Object Gst.Object GObject.InitiallyUnowned->Gst.Object GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned GstAudio.AudioRingBuffer GstAudio.AudioRingBuffer Gst.Object->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_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)

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)[source]
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)[source]
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)[source]
Parameters:
Returns:

True if the caps could be parsed.

Return type:

bool

Parse caps into spec.

acquire(spec)[source]
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)[source]
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)[source]
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)[source]
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()[source]

Fill the ringbuffer with silence.

MT safe.

close_device()[source]
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)[source]
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.

accum:accumulator for rate conversion.

Return type:

(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)[source]
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()[source]
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 transfered 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 transfered to the ringbuffer.

device_is_open()[source]
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()[source]
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()[source]
Returns:True if the device is active.
Return type:bool

Check if self is activated.

MT safe.

is_flushing()[source]
Returns:True if the device is flushing.
Return type:bool

Check if self is flushing.

MT safe.

may_start(allowed)[source]
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()[source]
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()[source]
Returns:True if the device could be paused, False on error.

MT safe.

Return type:bool

Pause processing samples from the ringbuffer.

prepare_read()[source]
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)[source]
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()[source]
Returns:True if the device could be released, False on error.

MT safe.

Return type:bool

Free the resources of the ringbuffer.

samples_done()[source]
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)[source]
Parameters:

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)[source]
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_flushing(flushing)[source]
Parameters:flushing (bool) – the new mode

Set the ringbuffer to flushing mode or normal mode.

MT safe.

set_sample(sample)[source]
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)[source]
Parameters:
  • readseg (int) –
  • timestamp (int) –
start()[source]
Returns:True if the device could be started, False on error.

MT safe.

Return type:bool

Start processing samples from the ringbuffer.

stop()[source]
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

Fill the ringbuffer with silence.

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.

accum:accumulator for rate conversion.

Return type:

(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 transfered 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 transfered 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
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.