gstbase.base_parse

Module for [BaseParse] class

class BaseParse BaseParseGidBuilder BaseParseGidBuilderImpl

Types 3

This base class is for parser elements that process data and splits it into separate audio/video/whatever frames.

It provides for:

provides one sink pad and one source pad
handles state changes
can operate in pull mode or push mode
handles seeking in both modes
handles events (SEGMENT/EOS/FLUSH)
handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT)
handles flushing

The purpose of this base class is to provide the basic functionality of a parser and share a lot of rather complex code.

Description of the parsing mechanism:

Set-up phase

#GstBaseParse calls #GstBaseParseClass::start to inform subclass

that data processing is about to start now.

#GstBaseParse class calls #GstBaseParseClass::set_sink_caps to

inform the subclass about incoming sinkpad caps. Subclass could already set the srcpad caps accordingly, but this might be delayed until calling [gstbase.base_parse.BaseParse.finishFrame] with a non-queued frame.

At least at this point subclass needs to tell the #GstBaseParse class

how big data chunks it wants to receive (minimum frame size ). It can do this with [gstbase.base_parse.BaseParse.setMinFrameSize].

#GstBaseParse class sets up appropriate data passing mode (pull/push)

and starts to process the data.

Parsing phase

#GstBaseParse gathers at least min_frame_size bytes of data either

by pulling it from upstream or collecting buffers in an internal #GstAdapter.

A buffer of (at least) min_frame_size bytes is passed to subclass

with #GstBaseParseClass::handle_frame. Subclass checks the contents and can optionally return #GST_FLOW_OK along with an amount of data to be skipped to find a valid frame (which will result in a subsequent DISCONT). If, otherwise, the buffer does not hold a complete frame, #GstBaseParseClass::handle_frame can merely return and will be called again when additional data is available. In push mode this amounts to an additional input buffer (thus minimal additional latency), in pull mode this amounts to some arbitrary reasonable buffer size increase.

Of course, [gstbase.base_parse.BaseParse.setMinFrameSize] could also be used if a very specific known amount of additional data is required. If, however, the buffer holds a complete valid frame, it can pass the size of this frame to [gstbase.base_parse.BaseParse.finishFrame].

If acting as a converter, it can also merely indicate consumed input data while simultaneously providing custom output data. Note that baseclass performs some processing (such as tracking overall consumed data rate versus duration) for each finished frame, but other state is only updated upon each call to #GstBaseParseClass::handle_frame (such as tracking upstream input timestamp).

Subclass is also responsible for setting the buffer metadata (e.g. buffer timestamp and duration, or keyframe if applicable). (although the latter can also be done by #GstBaseParse if it is appropriately configured, see below). Frame is provided with timestamp derived from upstream (as much as generally possible), duration obtained from configuration (see below), and offset if meaningful (in pull mode).

Note that #GstBaseParseClass::handle_frame might receive any small amount of input data when leftover data is being drained (e.g. at EOS).

As part of finish frame processing, just prior to actually pushing

the buffer in question, it is passed to #GstBaseParseClass::pre_push_frame which gives subclass yet one last chance to examine buffer metadata, or to send some custom (tag) events, or to perform custom (segment) filtering.

During the parsing process #GstBaseParseClass will handle both srcpad

and sinkpad events. They will be passed to subclass if #GstBaseParseClass::sink_event or #GstBaseParseClass::src_event implementations have been provided.

Shutdown phase

#GstBaseParse class calls #GstBaseParseClass::stop to inform the

subclass that data parsing will be stopped.

Subclass is responsible for providing pad template caps for source and sink pads. The pads need to be named "sink" and "src". It also needs to set the fixed caps on srcpad, when the format is ensured (e.g. when base class calls subclass' #GstBaseParseClass::set_sink_caps function).

This base class uses [gst.types.Format.Default] as a meaning of frames. So, subclass conversion routine needs to know that conversion from [gst.types.Format.Time] to [gst.types.Format.Default] must return the frame number that can be found from the given byte position.

#GstBaseParse uses subclasses conversion methods also for seeking (or otherwise uses its own default one, see also below).

Subclass @start and @stop functions will be called to inform the beginning and end of data processing.

Things that subclass need to take care of:

Provide pad templates
Fixate the source pad caps when appropriate
Inform base class how big data chunks should be retrieved. This is

done with [gstbase.base_parse.BaseParse.setMinFrameSize] function.

Examine data chunks passed to subclass with

#GstBaseParseClass::handle_frame and pass proper frame(s) to [gstbase.base_parse.BaseParse.finishFrame], and setting src pad caps and timestamps on frame.

Provide conversion functions
Update the duration information with [gstbase.base_parse.BaseParse.setDuration]
Optionally passthrough using [gstbase.base_parse.BaseParse.setPassthrough]
Configure various baseparse parameters using

[gstbase.base_parse.BaseParse.setAverageBitrate], [gstbase.base_parse.BaseParse.setSyncable] and [gstbase.base_parse.BaseParse.setFrameRate].

In particular, if subclass is unable to determine a duration, but

parsing (or specs) yields a frames per seconds rate, then this can be provided to #GstBaseParse to enable it to cater for buffer time metadata (which will be taken from upstream as much as possible). Internally keeping track of frame durations and respective sizes that have been pushed provides #GstBaseParse with an estimated bitrate. A default #GstBaseParseClass::convert (used if not overridden) will then use these rates to perform obvious conversions. These rates are also used to update (estimated) duration at regular frame intervals.

Methods

GType _getGType()

GType _gType() @property

BaseParse self()Returns `this`, for use in `with` statements.

BaseParseGidBuilder builder()Get builder for [gstbase.base_parse.BaseParse] Returns: New builder object

bool disablePassthrough() @propertyGet `disablePassthrough` property. Returns: If set to true, baseparse will unconditionally force parsing of the incoming data. This can be required in the rare cases where the incoming side-data (c...

void disablePassthrough(bool propval) @propertySet `disablePassthrough` property. Params: propval = If set to true, baseparse will unconditionally force parsing of the incoming data. This can be required in the rare cases where the incoming sid...

bool addIndexEntry(ulong offset, gst.types.ClockTime ts, bool key, bool force)Adds an entry to the index associating offset to ts. It is recommended to only add keyframe entries. force allows to bypass checks, such as whether the stream is (upstream) seekable, another entr...

bool convertDefault(gst.types.Format srcFormat, long srcValue, gst.types.Format destFormat, out long destValue)Default implementation of #GstBaseParseClass::convert.

void drain()Drains the adapter until it is empty. It decreases the minframesize to match the current adapter size and calls chain method until the adapter is emptied or chain returns with error.

gst.types.FlowReturn finishFrame(gstbase.base_parse_frame.BaseParseFrame frame, int size)Collects parsed data and pushes it downstream. Source pad caps must be set when this is called.

void mergeTags(gst.tag_list.TagList tags, gst.types.TagMergeMode mode)Sets the parser subclass's tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with [gstbase.base_parse.BaseParse.mergeTags].

gst.types.FlowReturn pushFrame(gstbase.base_parse_frame.BaseParseFrame frame)Pushes the frame's buffer downstream, sends any pending events and does some timestamp and segment handling. Takes ownership of frame's buffer, though caller retains ownership of frame.

void setAverageBitrate(uint bitrate)Optionally sets the average bitrate detected in media (if non-zero), e.g. based on metadata, as it will be posted to the application.

void setDuration(gst.types.Format fmt, long duration, int interval)Sets the duration of the currently playing media. Subclass can use this when it is able to determine duration and/or notices a change in the media duration. Alternatively, if interval is non-zero ...

void setFrameRate(uint fpsNum, uint fpsDen, uint leadIn, uint leadOut)If frames per second is configured, parser can take care of buffer duration and timestamping. When performing segment clipping, or seeking to a specific location, a corresponding decoder might nee...

void setHasTimingInfo(bool hasTiming)Set if frames carry timing information which the subclass can (generally) parse and provide. In particular, intrinsic (rather than estimated) time can be obtained following a seek.

void setInferTs(bool inferTs)By default, the base class might try to infer PTS from DTS and vice versa. While this is generally correct for audio data, it may not be otherwise. Sub-classes implementing such formats should dis...

void setLatency(gst.types.ClockTime minLatency, gst.types.ClockTime maxLatency)Sets the minimum and maximum (which may likely be equal) latency introduced by the parsing process. If there is such a latency, which depends on the particular parsing of the format, it typically c...

void setMinFrameSize(uint minSize)Subclass can use this function to tell the base class that it needs to be given buffers of at least min_size bytes.

void setPassthrough(bool passthrough)Set if the nature of the format or configuration does not allow (much) parsing, and the parser should operate in passthrough mode (which only applies when operating in push mode). That is, incoming...

void setPtsInterpolation(bool ptsInterpolate)By default, the base class will guess PTS timestamps using a simple interpolation (previous timestamp + duration), which is incorrect for data streams with reordering, where PTS can go backward. Su...

void setSyncable(bool syncable)Set if frame starts can be identified. This is set by default and determines whether seeking based on bitrate averages is possible for a format/stream.

void setTsAtOffset(size_t offset)This function should only be called from a handle_frame implementation.

Constructors

this(void * ptr, Flag!"Take" take)

classBaseParseGidBuilderImpl(T) : gst.element.ElementGidBuilderImpl!T

Methods

T disablePassthrough(bool propval)Set `disablePassthrough` property. Params: propval = If set to true, baseparse will unconditionally force parsing of the incoming data. This can be required in the rare cases where the incoming sid...

classBaseParseGidBuilder : BaseParseGidBuilderImpl!BaseParseGidBuilder

Fluent builder for [gstbase.base_parse.BaseParse]

Methods

BaseParse build()