BaseSrc

class BaseSrc(**properties: Any)

Superclasses: Element, Object, InitiallyUnowned, Object

Subclasses: PushSrc

This is a generic base class for source elements. The following types of sources are supported:

random access sources like files

seekable sources

live sources

The source can be configured to operate in any Format with the set_format() method. The currently set format determines the format of the internal Segment and any %GST_EVENT_SEGMENT events. The default format for BaseSrc is %GST_FORMAT_BYTES.

BaseSrc always supports push mode scheduling. If the following conditions are met, it also supports pull mode scheduling:

The format is set to %GST_FORMAT_BYTES (default).

BaseSrcClass::is_seekable returns True.

If all the conditions are met for operating in pull mode, BaseSrc is automatically seekable in push mode as well. The following conditions must be met to make the element seekable in push mode when the format is not %GST_FORMAT_BYTES:

BaseSrcClass::is_seekable returns True.
BaseSrcClass::query can convert all supported seek formats to the internal format as set with set_format().
BaseSrcClass::do_seek is implemented, performs the seek and returns
True.

When the element does not meet the requirements to operate in pull mode, the offset and length in the BaseSrcClass::create method should be ignored. It is recommended to subclass PushSrc instead, in this situation. If the element can operate in pull mode but only with specific offsets and lengths, it is allowed to generate an error when the wrong values are passed to the BaseSrcClass::create function.

BaseSrc has support for live sources. Live sources are sources that when paused discard data, such as audio or video capture devices. A typical live source also produces data at a fixed rate and thus provides a clock to publish this rate. Use set_live() to activate the live source mode.

A live source does not produce data in the PAUSED state. This means that the BaseSrcClass::create method will not be called in PAUSED but only in PLAYING. To signal the pipeline that the element will not produce data, the return value from the READY to PAUSED state will be %GST_STATE_CHANGE_NO_PREROLL.

A typical live source will timestamp the buffers it creates with the current running time of the pipeline. This is one reason why a live source can only produce data in the PLAYING state, when the clock is actually distributed and running.

Live sources that synchronize and block on the clock (an audio source, for example) can use wait_playing() when the BaseSrcClass::create function was interrupted by a state change to PAUSED.

The BaseSrcClass::get_times method can be used to implement pseudo-live sources. It only makes sense to implement the BaseSrcClass::get_times function if the source is a live source. The BaseSrcClass::get_times function should return timestamps starting from 0, as if it were a non-live source. The base class will make sure that the timestamps are transformed into the current running_time. The base source will then wait for the calculated running_time before pushing out the buffer.

For live sources, the base class will by default report a latency of 0. For pseudo live sources, the base class will by default measure the difference between the first buffer timestamp and the start time of get_times and will report this value as the latency. Subclasses should override the query function when this behaviour is not acceptable.

There is only support in BaseSrc for exactly one source pad, which should be named “src”. A source implementation (subclass of BaseSrc) should install a pad template in its class_init function, like so:

static void
my_element_class_init (GstMyElementClass *klass)
{
  GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
  // srctemplate should be a :obj:`~gi.repository.Gst.StaticPadTemplate` with direction
  // ``%GST_PAD_SRC`` and name "src"
  gst_element_class_add_static_pad_template (gstelement_class, &srctemplate);

  gst_element_class_set_static_metadata (gstelement_class,
     "Source name",
     "Source",
     "My Source element",
     "The author <my.sink``my``.email>");
}

Controlled shutdown of live sources in applications

Applications that record from a live source may want to stop recording in a controlled way, so that the recording is stopped, but the data already in the pipeline is processed to the end (remember that many live sources would go on recording forever otherwise). For that to happen the application needs to make the source stop recording and send an EOS event down the pipeline. The application would then wait for an EOS message posted on the pipeline’s bus to know when all data has been processed and the pipeline can safely be stopped.

An application may send an EOS event to a source element to make it perform the EOS logic (send EOS event downstream or post a %GST_MESSAGE_SEGMENT_DONE on the bus). This can typically be done with the send_event() function on the element or its parent bin.

After the EOS has been sent to the element, the application should wait for an EOS message to be posted on the pipeline’s bus. Once this EOS message is received, it may safely shut down the entire pipeline.

Methods

class BaseSrc

get_allocator() → tuple[Allocator, AllocationParams]

Lets BaseSrc sub-classes to know the memory allocator used by the base class and its params.

Unref the allocator after usage.

get_blocksize() → int: Get the number of bytes that src will push out with each buffer.

get_buffer_pool() → BufferPool | None

get_do_timestamp() → bool: Query if src timestamps outgoing buffers based on the current running_time.

is_async() → bool: Get the current async behaviour of src. See also set_async().

negotiate() → bool

Negotiates src pad caps with downstream elements. Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again if BaseSrcClass::negotiate fails.

Do not call this in the BaseSrcClass::fill vmethod. Call this in BaseSrcClass::create or in BaseSrcClass::alloc, before any buffer is allocated.

Added in version 1.18.

new_seamless_segment(start: int, stop: int, time: int) → bool

Prepare a new seamless segment for emission downstream. This function must only be called by derived sub-classes, and only from the BaseSrcClass::create function, as the stream-lock needs to be held.

The format for the new segment will be the current format of the source, as configured with set_format()

Deprecated since version 1.18: Use new_segment()

Parameters:

start – The new start value for the segment
stop – Stop value for the new segment
time – The new time value for the start of the new segment

new_segment(segment: Segment) → bool

Prepare a new segment for emission downstream. This function must only be called by derived sub-classes, and only from the BaseSrcClass::create function, as the stream-lock needs to be held.

The format for the segment must be identical with the current format of the source, as configured with set_format().

The format of src must not be %GST_FORMAT_UNDEFINED and the format should be configured via set_format() before calling this method.

Added in version 1.18.

Parameters:: segment – a pointer to a Segment

query_latency() → tuple[bool, bool, int, int]

Query the source for the latency parameters. live will be True when src is configured as a live source. min_latency and max_latency will be set to the difference between the running time and the timestamp of the first buffer.

This function is mostly used by subclasses.

set_async(async_: bool) → None

Configure async behaviour in src, no state change will block. The open, close, start, stop, play and pause virtual methods will be executed in a different thread and are thus allowed to perform blocking operations. Any blocking operation should be unblocked with the unlock vmethod.

Parameters:: async

set_automatic_eos(automatic_eos: bool) → None

If automatic_eos is True, src will automatically go EOS if a buffer after the total size is returned. By default this is True but sources that can’t return an authoritative size and only know that they’re EOS when trying to read more should set this to False.

When src operates in %GST_FORMAT_TIME, BaseSrc will send an EOS when a buffer outside of the currently configured segment is pushed if automatic_eos is True. Since 1.16, if automatic_eos is False an EOS will be pushed only when the BaseSrcClass::create implementation returns %GST_FLOW_EOS.

Added in version 1.4.

Parameters:: automatic_eos – automatic eos

set_blocksize(blocksize: int) → None

Set the number of bytes that src will push out with each buffer. When blocksize is set to -1, a default length will be used.

Parameters:: blocksize – the new blocksize in bytes

set_caps(caps: Caps) → bool

Set new caps on the basesrc source pad.

Parameters:: caps – a Caps

set_do_timestamp(timestamp: bool) → None

Configure src to automatically timestamp outgoing buffers based on the current running_time of the pipeline. This property is mostly useful for live sources.

Parameters:: timestamp – enable or disable timestamping

set_dynamic_size(dynamic: bool) → None

If not dynamic, size is only updated when needed, such as when trying to read past current tracked size. Otherwise, size is checked for upon each read.

Parameters:: dynamic – new dynamic size mode

set_format(format: Format) → None

Sets the default format of the source. This will be the format used for sending SEGMENT events and for performing seeks.

If a format of GST_FORMAT_BYTES is set, the element will be able to operate in pull mode if the BaseSrcClass::is_seekable returns True.

This function must only be called in states < %GST_STATE_PAUSED.

Parameters:: format – the format to use

set_live(live: bool) → None

If the element listens to a live source, live should be set to True.

A live source will not produce data in the PAUSED state and will therefore not be able to participate in the PREROLL phase of a pipeline. To signal this fact to the application and the pipeline, the state change return value of the live source will be GST_STATE_CHANGE_NO_PREROLL.

Parameters:: live – new live-mode

start_complete(ret: FlowReturn) → None

Complete an asynchronous start operation. When the subclass overrides the start method, it should call start_complete() when the start operation completes either from the same thread or from an asynchronous helper thread.

Parameters:: ret – a FlowReturn

start_wait() → FlowReturn: Wait until the start operation completes.

submit_buffer_list(buffer_list: BufferList) → None

Subclasses can call this from their create virtual method implementation to submit a buffer list to be pushed out later. This is useful in cases where the create function wants to produce multiple buffers to be pushed out in one go in form of a BufferList, which can reduce overhead drastically, especially for packetised inputs (for data streams where the packetisation/chunking is not important it is usually more efficient to return larger buffers instead).

Subclasses that use this function from their create function must return %GST_FLOW_OK and no buffer from their create virtual method implementation. If a buffer is returned after a buffer list has also been submitted via this function the behaviour is undefined.

Subclasses must only call this function once per create function call and subclasses must only call this function when the source operates in push mode.

Added in version 1.14.

Parameters:: buffer_list – a BufferList

wait_playing() → FlowReturn

If the BaseSrcClass::create method performs its own synchronisation against the clock it must unblock when going from PLAYING to the PAUSED state and call this method before continuing to produce the remaining data.

This function will block until a state change to PLAYING happens (in which case this function returns %GST_FLOW_OK) or the processing must be stopped due to a state change to READY or a FLUSH event (in which case this function returns %GST_FLOW_FLUSHING).

Properties

class BaseSrc

props.blocksize: int

props.do_timestamp: bool

props.num_buffers: int

props.typefind: bool

Virtual Methods

class BaseSrc

do_alloc(offset: int, size: int) → tuple[FlowReturn, Buffer]

Ask the subclass to allocate an output buffer with offset and size, the default implementation will use the negotiated allocator.

Parameters:

offset
size

do_create(offset: int, size: int) → tuple[FlowReturn, Buffer]

Ask the subclass to create a buffer with offset and size, the default implementation will call alloc if no allocated buf is provided and then call fill.

Parameters:

offset
size

do_decide_allocation(query: Query) → bool

Parameters:: query

do_do_seek(segment: Segment) → bool

Parameters:: segment

do_event(event: Event) → bool

Parameters:: event

do_fill(offset: int, size: int, buf: Buffer) → FlowReturn

Parameters:

offset
size
buf

do_fixate(caps: Caps) → Caps

Called if, in negotiation, caps need fixating.

Parameters:: caps

do_get_caps(filter: Caps | None = None) → Caps

Called to get the caps to report.

Parameters:: filter

do_get_size() → tuple[bool, int]: Get the total size of the resource in the format set by set_format().

do_get_times(buffer: Buffer) → tuple[int, int]

Given buffer, return start and end time when it should be pushed out. The base class will sync on the clock using these times.

Parameters:: buffer

do_is_seekable() → bool

do_negotiate() → bool

Negotiates src pad caps with downstream elements. Unmarks GST_PAD_FLAG_NEED_RECONFIGURE in any case. But marks it again if BaseSrcClass::negotiate fails.

Do not call this in the BaseSrcClass::fill vmethod. Call this in BaseSrcClass::create or in BaseSrcClass::alloc, before any buffer is allocated.

Added in version 1.18.

do_prepare_seek_segment(seek: Event, segment: Segment) → bool

Parameters:

seek
segment

do_query(query: Query) → bool

Parameters:: query

do_set_caps(caps: Caps) → bool

Set new caps on the basesrc source pad.

Parameters:: caps – a Caps

do_start() → bool

do_stop() → bool

do_unlock() → bool

do_unlock_stop() → bool

Fields

class BaseSrc

blocksize

can_activate_push

clock_id

element

is_live

live_cond

live_lock

live_running

need_newsegment

num_buffers

num_buffers_left

pending_seek

priv

random_access

running

segment

srcpad

typefind