Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
This is a generic base class for source elements. The following types of sources are supported: <itemizedlist> <listitem><para>random access sources like files</para></listitem> <listitem><para>seekable sources</para></listitem> <listitem><para>live sources</para></listitem> </itemizedlist>
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:
<itemizedlist>
<listitem><para>The format is set to FormatBytes
(default).</para>
</listitem>
<listitem><para>BaseSrcClass
.is_seekable
() returns True
.</para>
</listitem>
</itemizedlist>
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
:
<itemizedlist>
<listitem><para>
BaseSrcClass
.is_seekable
() returns True
.
</para></listitem>
<listitem><para>
BaseSrcClass
.query
() can convert all supported seek formats to the
internal format as set with baseSrcSetFormat
.
</para></listitem>
<listitem><para>
BaseSrcClass
.do_seek
() is implemented, performs the seek and returns
True
.
</para></listitem>
</itemizedlist>
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>"); }
<refsect2> <title>Controlled shutdown of live sources in applications</title> <para> 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. </para> </refsect2>
- newtype BaseSrc = BaseSrc (ManagedPtr BaseSrc)
- class GObject o => IsBaseSrc o
- toBaseSrc :: IsBaseSrc o => o -> IO BaseSrc
- noBaseSrc :: Maybe BaseSrc
- data BaseSrcGetAllocatorMethodInfo
- baseSrcGetAllocator :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m (Allocator, AllocationParams)
- data BaseSrcGetBlocksizeMethodInfo
- baseSrcGetBlocksize :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m Word32
- data BaseSrcGetBufferPoolMethodInfo
- baseSrcGetBufferPool :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m BufferPool
- data BaseSrcGetDoTimestampMethodInfo
- baseSrcGetDoTimestamp :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m Bool
- data BaseSrcIsAsyncMethodInfo
- baseSrcIsAsync :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m Bool
- data BaseSrcIsLiveMethodInfo
- baseSrcIsLive :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m Bool
- data BaseSrcNewSeamlessSegmentMethodInfo
- baseSrcNewSeamlessSegment :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Int64 -> Int64 -> Int64 -> m Bool
- data BaseSrcQueryLatencyMethodInfo
- baseSrcQueryLatency :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m (Bool, Bool, Word64, Word64)
- data BaseSrcSetAsyncMethodInfo
- baseSrcSetAsync :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- data BaseSrcSetAutomaticEosMethodInfo
- baseSrcSetAutomaticEos :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- data BaseSrcSetBlocksizeMethodInfo
- baseSrcSetBlocksize :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Word32 -> m ()
- data BaseSrcSetCapsMethodInfo
- baseSrcSetCaps :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Caps -> m Bool
- data BaseSrcSetDoTimestampMethodInfo
- baseSrcSetDoTimestamp :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- data BaseSrcSetDynamicSizeMethodInfo
- baseSrcSetDynamicSize :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- data BaseSrcSetFormatMethodInfo
- baseSrcSetFormat :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Format -> m ()
- data BaseSrcSetLiveMethodInfo
- baseSrcSetLive :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> Bool -> m ()
- data BaseSrcStartCompleteMethodInfo
- baseSrcStartComplete :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> FlowReturn -> m ()
- data BaseSrcStartWaitMethodInfo
- baseSrcStartWait :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m FlowReturn
- data BaseSrcWaitPlayingMethodInfo
- baseSrcWaitPlaying :: (HasCallStack, MonadIO m, IsBaseSrc a) => a -> m FlowReturn
- data BaseSrcBlocksizePropertyInfo
- baseSrcBlocksize :: AttrLabelProxy "blocksize"
- constructBaseSrcBlocksize :: IsBaseSrc o => Word32 -> IO (GValueConstruct o)
- getBaseSrcBlocksize :: (MonadIO m, IsBaseSrc o) => o -> m Word32
- setBaseSrcBlocksize :: (MonadIO m, IsBaseSrc o) => o -> Word32 -> m ()
- data BaseSrcDoTimestampPropertyInfo
- baseSrcDoTimestamp :: AttrLabelProxy "doTimestamp"
- constructBaseSrcDoTimestamp :: IsBaseSrc o => Bool -> IO (GValueConstruct o)
- getBaseSrcDoTimestamp :: (MonadIO m, IsBaseSrc o) => o -> m Bool
- setBaseSrcDoTimestamp :: (MonadIO m, IsBaseSrc o) => o -> Bool -> m ()
- data BaseSrcNumBuffersPropertyInfo
- baseSrcNumBuffers :: AttrLabelProxy "numBuffers"
- constructBaseSrcNumBuffers :: IsBaseSrc o => Int32 -> IO (GValueConstruct o)
- getBaseSrcNumBuffers :: (MonadIO m, IsBaseSrc o) => o -> m Int32
- setBaseSrcNumBuffers :: (MonadIO m, IsBaseSrc o) => o -> Int32 -> m ()
- data BaseSrcTypefindPropertyInfo
- baseSrcTypefind :: AttrLabelProxy "typefind"
- 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
GObject BaseSrc Source # | |
IsObject BaseSrc Source # | |
IsElement BaseSrc Source # | |
IsObject BaseSrc Source # | |
IsBaseSrc BaseSrc Source # | |
((~) * info (ResolveBaseSrcMethod t BaseSrc), MethodInfo * info BaseSrc p) => IsLabel t (BaseSrc -> p) Source # | |
((~) * info (ResolveBaseSrcMethod t BaseSrc), MethodInfo * info BaseSrc p) => IsLabelProxy t (BaseSrc -> p) Source # | |
HasAttributeList * BaseSrc Source # | |
type AttributeList BaseSrc Source # | |
type SignalList BaseSrc Source # | |
Methods
getAllocator
data BaseSrcGetAllocatorMethodInfo Source #
((~) * signature (m (Allocator, AllocationParams)), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcGetAllocatorMethodInfo a signature Source # | |
:: (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
data BaseSrcGetBlocksizeMethodInfo Source #
((~) * signature (m Word32), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcGetBlocksizeMethodInfo a signature Source # | |
:: (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
data BaseSrcGetBufferPoolMethodInfo Source #
((~) * signature (m BufferPool), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcGetBufferPoolMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m BufferPool | Returns: the instance of the |
No description available in the introspection data.
getDoTimestamp
data BaseSrcGetDoTimestampMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcGetDoTimestampMethodInfo a signature Source # | |
baseSrcGetDoTimestamp Source #
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m Bool | Returns: |
Query if src
timestamps outgoing buffers based on the current running_time.
isAsync
data BaseSrcIsAsyncMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcIsAsyncMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m Bool | Returns: |
Get the current async behaviour of src
. See also baseSrcSetAsync
.
isLive
data BaseSrcIsLiveMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcIsLiveMethodInfo a signature Source # | |
:: (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
data BaseSrcSetAsyncMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcSetAsyncMethodInfo a signature Source # | |
:: (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
data BaseSrcSetAutomaticEosMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcSetAutomaticEosMethodInfo a signature Source # | |
baseSrcSetAutomaticEos Source #
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Bool |
|
-> m () |
setBlocksize
data BaseSrcSetBlocksizeMethodInfo Source #
((~) * signature (Word32 -> m ()), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcSetBlocksizeMethodInfo a signature Source # | |
:: (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
data BaseSrcSetCapsMethodInfo Source #
((~) * signature (Caps -> m Bool), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcSetCapsMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> Caps |
|
-> m Bool | Returns: |
Set new caps on the basesrc source pad.
setDoTimestamp
data BaseSrcSetDoTimestampMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcSetDoTimestampMethodInfo a signature Source # | |
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
data BaseSrcSetDynamicSizeMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcSetDynamicSizeMethodInfo a signature Source # | |
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
data BaseSrcSetFormatMethodInfo Source #
((~) * signature (Format -> m ()), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcSetFormatMethodInfo a signature Source # | |
:: (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
data BaseSrcSetLiveMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcSetLiveMethodInfo a signature Source # | |
:: (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
data BaseSrcStartCompleteMethodInfo Source #
((~) * signature (FlowReturn -> m ()), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcStartCompleteMethodInfo a signature Source # | |
:: (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
data BaseSrcStartWaitMethodInfo Source #
((~) * signature (m FlowReturn), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcStartWaitMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsBaseSrc a) | |
=> a |
|
-> m FlowReturn | Returns: a |
Wait until the start operation completes.
waitPlaying
data BaseSrcWaitPlayingMethodInfo Source #
((~) * signature (m FlowReturn), MonadIO m, IsBaseSrc a) => MethodInfo * BaseSrcWaitPlayingMethodInfo a signature Source # | |
:: (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
data BaseSrcBlocksizePropertyInfo Source #
baseSrcBlocksize :: AttrLabelProxy "blocksize" Source #
constructBaseSrcBlocksize :: IsBaseSrc o => Word32 -> IO (GValueConstruct o) Source #
doTimestamp
data BaseSrcDoTimestampPropertyInfo Source #
baseSrcDoTimestamp :: AttrLabelProxy "doTimestamp" Source #
constructBaseSrcDoTimestamp :: IsBaseSrc o => Bool -> IO (GValueConstruct o) Source #
numBuffers
data BaseSrcNumBuffersPropertyInfo Source #
baseSrcNumBuffers :: AttrLabelProxy "numBuffers" Source #
constructBaseSrcNumBuffers :: IsBaseSrc o => Int32 -> IO (GValueConstruct o) Source #
typefind
data BaseSrcTypefindPropertyInfo Source #
baseSrcTypefind :: AttrLabelProxy "typefind" Source #
constructBaseSrcTypefind :: IsBaseSrc o => Bool -> IO (GValueConstruct o) Source #