Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (inaki@blueleaf.cc) |
Safe Haskell | None |
Language | Haskell2010 |
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
() returnsTrue
.
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
() returnsTrue
.BaseSrcClass
.query
() can convert all supported seek formats to the internal format as set withbaseSrcSetFormat
.BaseSrcClass
.do_seek
() is implemented, performs the seek and returnsTrue
.
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 <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
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.
Synopsis
- newtype BaseSrc = BaseSrc (ManagedPtr BaseSrc)
- class (GObject o, IsDescendantOf BaseSrc o) => IsBaseSrc o
- toBaseSrc :: (MonadIO m, IsBaseSrc o) => o -> m BaseSrc
- noBaseSrc :: Maybe BaseSrc
- baseSrcGetAllocator :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m (Allocator, AllocationParams)
- baseSrcGetBlocksize :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m Word32
- baseSrcGetBufferPool :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m BufferPool
- baseSrcGetDoTimestamp :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m Bool
- baseSrcIsAsync :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m Bool
- baseSrcIsLive :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m Bool
- baseSrcNewSeamlessSegment :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Int64 -> Int64 -> Int64 -> m Bool
- baseSrcQueryLatency :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m (Bool, Bool, Word64, Word64)
- baseSrcSetAsync :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- baseSrcSetAutomaticEos :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- baseSrcSetBlocksize :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Word32 -> m ()
- baseSrcSetCaps :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Caps -> m Bool
- baseSrcSetDoTimestamp :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- baseSrcSetDynamicSize :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- baseSrcSetFormat :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Format -> m ()
- baseSrcSetLive :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- baseSrcStartComplete :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> FlowReturn -> m ()
- baseSrcStartWait :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m FlowReturn
- baseSrcSubmitBufferList :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> BufferList -> m ()
- baseSrcWaitPlaying :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m FlowReturn
- constructBaseSrcBlocksize :: IsBaseSrc o => Word32 -> IO (GValueConstruct o)
- getBaseSrcBlocksize :: (MonadIO m, IsBaseSrc o) => o -> m Word32
- setBaseSrcBlocksize :: (MonadIO m, IsBaseSrc o) => o -> Word32 -> m ()
- constructBaseSrcDoTimestamp :: IsBaseSrc o => Bool -> IO (GValueConstruct o)
- getBaseSrcDoTimestamp :: (MonadIO m, IsBaseSrc o) => o -> m Bool
- setBaseSrcDoTimestamp :: (MonadIO m, IsBaseSrc o) => o -> Bool -> m ()
- constructBaseSrcNumBuffers :: IsBaseSrc o => Int32 -> IO (GValueConstruct o)
- getBaseSrcNumBuffers :: (MonadIO m, IsBaseSrc o) => o -> m Int32
- setBaseSrcNumBuffers :: (MonadIO m, IsBaseSrc o) => o -> Int32 -> m ()
- constructBaseSrcTypefind :: IsBaseSrc o => Bool -> IO (GValueConstruct o)
- getBaseSrcTypefind :: (MonadIO m, IsBaseSrc o) => o -> m Bool
- setBaseSrcTypefind :: (MonadIO m, IsBaseSrc o) => o -> Bool -> m ()
Exported types
Memory-managed wrapper type.
Instances
GObject BaseSrc Source # | |
Defined in GI.GstBase.Objects.BaseSrc gobjectType :: IO GType | |
HasParentTypes BaseSrc Source # | |
Defined in GI.GstBase.Objects.BaseSrc | |
type ParentTypes BaseSrc Source # | |
Defined in GI.GstBase.Objects.BaseSrc |
class (GObject o, IsDescendantOf BaseSrc o) => IsBaseSrc o Source #
Instances
(GObject o, IsDescendantOf BaseSrc o) => IsBaseSrc o Source # | |
Defined in GI.GstBase.Objects.BaseSrc |
Methods
getAllocator
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m BufferPool | Returns: the instance of the |
No description available in the introspection data.
getDoTimestamp
baseSrcGetDoTimestamp Source #
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m Bool | Returns: |
Query if src
timestamps outgoing buffers based on the current running_time.
isAsync
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m Bool | Returns: |
Get the current async behaviour of src
. See also baseSrcSetAsync
.
isLive
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m Bool | Returns: |
Check if an element is in live mode.
newSeamlessSegment
baseSrcNewSeamlessSegment Source #
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Int64 |
|
-> Int64 |
|
-> Int64 |
|
-> m Bool | Returns: |
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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m (Bool, Bool, Word64, Word64) | Returns: |
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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Bool |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Bool |
|
-> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Word32 |
|
-> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Caps |
|
-> m Bool | Returns: |
Set new caps on the basesrc source pad.
setDoTimestamp
baseSrcSetDoTimestamp Source #
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Bool |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Bool |
|
-> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Format |
|
-> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Bool |
|
-> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m FlowReturn | Returns: a |
Wait until the start operation completes.
submitBufferList
baseSrcSubmitBufferList Source #
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> 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
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m FlowReturn | Returns: |
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) Source #
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 Source #
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 () Source #
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) Source #
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 Source #
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 () Source #
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) Source #
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 Source #
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 () Source #
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) Source #
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 Source #
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 () Source #
Set the value of the “typefind
” property.
When overloading is enabled, this is equivalent to
set
baseSrc [ #typefind:=
value ]