GI.GstBase.Objects.BaseSrc

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 baseSrcSetFormat method. The currently set format determines the format of the internal Segment and any EventTypeSegment events. The default format for BaseSrc is FormatBytes.

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

• The format is set to FormatBytes (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 FormatBytes:

• BaseSrcClass.is_seekable() returns True.
• BaseSrcClass.query() can convert all supported seek formats to the internal format as set with baseSrcSetFormat.
• 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 baseSrcSetLive 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 StateChangeReturnNoPreroll.

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 baseSrcWaitPlaying 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:

C code

static void
my_element_class_init (GstMyElementClass *klass)
{
  GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
  // srctemplate should be a #GstStaticPadTemplate 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 <[e-mail]>");
}

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 MessageTypeSegmentDone on the bus). This can typically be done with the elementSendEvent 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.

Exported types

newtype BaseSrc

Memory-managed wrapper type.

Constructors

BaseSrc (ManagedPtr BaseSrc)

Instances

GObject BaseSrc

Defined in GI.GstBase.Objects.BaseSrc

Methods

gobjectType :: IO GType

HasParentTypes BaseSrc

Defined in GI.GstBase.Objects.BaseSrc

type ParentTypes BaseSrc

Defined in GI.GstBase.Objects.BaseSrc

type ParentTypes BaseSrc = Element ': (Object ': (Object ': ([] :: [Type])))

class (GObject o, IsDescendantOf BaseSrc o) => IsBaseSrc o

Type class for types which can be safely cast to BaseSrc, for instance with toBaseSrc.

Instances

(GObject o, IsDescendantOf BaseSrc o) => IsBaseSrc o

Defined in GI.GstBase.Objects.BaseSrc

toBaseSrc :: (MonadIO m, IsBaseSrc o) => o -> m BaseSrc

Cast to BaseSrc, for types for which this is known to be safe. For general casts, use castTo.

noBaseSrc :: Maybe BaseSrc

A convenience alias for Nothing :: Maybe BaseSrc.

Methods

getAllocator

baseSrcGetAllocator

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: a BaseSrc

-> m (Allocator, AllocationParams)

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

Unref the allocator after usage.

getBlocksize

baseSrcGetBlocksize

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: the source

-> m Word32

Returns: the number of bytes pushed with each buffer.

Get the number of bytes that src will push out with each buffer.

getBufferPool

baseSrcGetBufferPool

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: a BaseSrc

-> m BufferPool

Returns: the instance of the BufferPool used by the src; unref it after usage.

No description available in the introspection data.

getDoTimestamp

baseSrcGetDoTimestamp

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: the source

-> m Bool

Returns: True if the base class will automatically timestamp outgoing buffers.

Query if src timestamps outgoing buffers based on the current running_time.

isAsync

baseSrcIsAsync

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: base source instance

-> m Bool

Returns: True if src is operating in async mode.

Get the current async behaviour of src. See also baseSrcSetAsync.

isLive

baseSrcIsLive

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: base source instance

-> m Bool

Returns: True if element is in live mode.

Check if an element is in live mode.

newSeamlessSegment

baseSrcNewSeamlessSegment

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: The source

-> Int64

start: The new start value for the segment

-> Int64

stop: Stop value for the new segment

-> Int64

time: The new time value for the start of the new segment

-> m Bool

Returns: True if preparation of the seamless segment succeeded.

Prepare a new seamless segment for emission downstream. This function must only be called by derived sub-classes, and only from the 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 baseSrcSetFormat

queryLatency

baseSrcQueryLatency

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: the source

-> m (Bool, Bool, Word64, Word64)

Returns: True if the query succeeded.

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

This function is mostly used by subclasses.

setAsync

baseSrcSetAsync

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: base source instance

-> Bool

async: new async mode

-> m ()

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.

setAutomaticEos

baseSrcSetAutomaticEos

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: base source instance

-> Bool

automaticEos: automatic eos

-> m ()

If automaticEos 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 FormatTime, BaseSrc will send an EOS when a buffer outside of the currently configured segment is pushed if automaticEos is True. Since 1.16, if automaticEos is False an EOS will be pushed only when the BaseSrc.create implementation returns FlowReturnEos.

Since: 1.4

setBlocksize

baseSrcSetBlocksize

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: the source

-> Word32

blocksize: the new blocksize in bytes

-> m ()

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.

setCaps

baseSrcSetCaps

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: a BaseSrc

-> Caps

caps: a Caps

-> m Bool

Returns: True if the caps could be set

Set new caps on the basesrc source pad.

setDoTimestamp

baseSrcSetDoTimestamp

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: the source

-> Bool

timestamp: enable or disable timestamping

-> m ()

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

setDynamicSize

baseSrcSetDynamicSize

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: base source instance

-> Bool

dynamic: new dynamic size mode

-> m ()

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.

setFormat

baseSrcSetFormat

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: base source instance

-> Format

format: the format to use

-> m ()

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 < StatePaused.

setLive

baseSrcSetLive

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: base source instance

-> Bool

live: new live-mode

-> m ()

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.

startComplete

baseSrcStartComplete

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

basesrc: base source instance

-> FlowReturn

ret: a FlowReturn

-> m ()

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

startWait

baseSrcStartWait

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

basesrc: base source instance

-> m FlowReturn

Returns: a FlowReturn.

Wait until the start operation completes.

submitBufferList

baseSrcSubmitBufferList

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: a BaseSrc

-> BufferList

bufferList: a BufferList

-> m ()

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 FlowReturnOk 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.

Since: 1.14

waitPlaying

baseSrcWaitPlaying

Arguments

:: (HasCallStack, MonadIO m, IsBaseSrc a)

=> a

src: the src

-> m FlowReturn

Returns: FlowReturnOk if src is PLAYING and processing can continue. Any other return value should be returned from the create vmethod.

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 FlowReturnOk) or the processing must be stopped due to a state change to READY or a FLUSH event (in which case this function returns FlowReturnFlushing).

Properties

blocksize

No description available in the introspection data.

constructBaseSrcBlocksize :: IsBaseSrc o => Word32 -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “blocksize” property. This is rarely needed directly, but it is used by new.

getBaseSrcBlocksize :: (MonadIO m, IsBaseSrc o) => o -> m Word32

Get the value of the “blocksize” property. When overloading is enabled, this is equivalent to

get baseSrc #blocksize

setBaseSrcBlocksize :: (MonadIO m, IsBaseSrc o) => o -> Word32 -> m ()

Set the value of the “blocksize” property. When overloading is enabled, this is equivalent to

set baseSrc [ #blocksize := value ]

doTimestamp

No description available in the introspection data.

constructBaseSrcDoTimestamp :: IsBaseSrc o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “do-timestamp” property. This is rarely needed directly, but it is used by new.

getBaseSrcDoTimestamp :: (MonadIO m, IsBaseSrc o) => o -> m Bool

Get the value of the “do-timestamp” property. When overloading is enabled, this is equivalent to

get baseSrc #doTimestamp

setBaseSrcDoTimestamp :: (MonadIO m, IsBaseSrc o) => o -> Bool -> m ()

Set the value of the “do-timestamp” property. When overloading is enabled, this is equivalent to

set baseSrc [ #doTimestamp := value ]

numBuffers

No description available in the introspection data.

constructBaseSrcNumBuffers :: IsBaseSrc o => Int32 -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “num-buffers” property. This is rarely needed directly, but it is used by new.

getBaseSrcNumBuffers :: (MonadIO m, IsBaseSrc o) => o -> m Int32

Get the value of the “num-buffers” property. When overloading is enabled, this is equivalent to

get baseSrc #numBuffers

setBaseSrcNumBuffers :: (MonadIO m, IsBaseSrc o) => o -> Int32 -> m ()

Set the value of the “num-buffers” property. When overloading is enabled, this is equivalent to

set baseSrc [ #numBuffers := value ]

typefind

No description available in the introspection data.

constructBaseSrcTypefind :: IsBaseSrc o => Bool -> IO (GValueConstruct o)

Construct a GValueConstruct with valid value for the “typefind” property. This is rarely needed directly, but it is used by new.

getBaseSrcTypefind :: (MonadIO m, IsBaseSrc o) => o -> m Bool

Get the value of the “typefind” property. When overloading is enabled, this is equivalent to

get baseSrc #typefind

setBaseSrcTypefind :: (MonadIO m, IsBaseSrc o) => o -> Bool -> m ()

Set the value of the “typefind” property. When overloading is enabled, this is equivalent to

set baseSrc [ #typefind := value ]