dam

dam — Block and/or filter stream

Properties

Types and Values

typedef GstEntransDam

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GstObject
            ╰── GstElement
                ╰── GstBaseTransform
                    ╰── GstEntransDam

Description

Special-purpose element that enables a "cutting" muxing pipeline. This is used for transcoding purposes where it is not desired to mux the entire original stream into a new stream, but only selected parts of it. The desired parts in such a scenario are selected depending on segment-mode property:

  • using regular seek-events (segment-mode or seek-mode); an initial flushing seek followed by a number of segmenting seeks and finally concluded with a normal seek. The element then drops buffers that are out of the selected segment range, to compensate for some elements not doing so (yes, there are such ...). The usual end-of-segment messages (or final EOS) allow the 'application' to pass from one segment to the next.

  • cut-mode: allowing only a certain range of buffers to pass where the range is specified by gst time (starting from 0). When using counts, such times are then converted to either a frame count or a sample count and compared with the corresponding count of the incoming data (using the format info supplied by the caps) (so buffer timestamps are disregarded). Alternatively, buffer timestamps can be used to decide on clipping.

In addition, audio data can optionally be clipped to sample precision when deciding based on buffer timestamps (it is always done so when clipping based on counts).

The element can also be requested to send an eos event, so that streaming can be cleanly completed, and e.g. muxers can complete EOS-actions.

Usage

This element is (likely) essentially in a muxing pipeline whenever only a part of the input is selected, even when using segments. The functionality to drop out-of-segment data is typically present in (base)sinks, so this usually happens transparently in a playing pipeline. However, in a muxing pipeline, a filesink can and should clearly have no impact on this; so it is up to the rest of pipeline to perform this dropping. Failing to do so would not only result in too much and unwanted data, but will probably even block the muxing pipeline (in a collectpads instance), due to (typically) an imbalance (in volume and timestamps) in video and audio data. It might be noted that more recently, however, modern encoder elements (e.g. based on baseclasses) also take care of such dropping, which somewhat alleviates the need for this element (but neither does it have any adverse effects).

Similarly, modern encoder elements filter some upstream (stream scoped) tags that are not relevant for newly encoded data. Alternatively, the drop-tags property can be set to a comma-separated list of (substring matched) tags that should be filtered out of passing tag events (global or stream scope). While its depends on the encoding/transcoding scenario, a typically useful value is "bitrate,encoder,codec,container"

In case of a demuxer element involved in providing input, it should be separated from it by means of queue (or other thread boundary).

The sequence of events/operation is roughly as follows.

  • The element starts up and announces its existence by posting a message on the bus. This should be detected (synchronously) by the application using it, which should block pads to prevent data flowing through prior to setup being completed.

  • This setup (typically happening when all relevant pads have blocked) consists of setting the proper "mode", and providing section info in case of cut-mode. After this, streaming can be continued by (optionally) performing seek and (typically) unblocking pads. The element then performs as described above, depending on mode, and either the last normal seek will give rise to EOS, or the element generates EOS when having passed all data for the last section.


Element Information

plugin

entrans

author

Mark Nauwelaerts <mnauw@users.sourceforge.net>

class

Generic

Functions

Types and Values

GstEntransDam

typedef GstDam GstEntransDam;

Property Details

The “begin-count” property

  “begin-count”              gint64

Begin of section in frames.

Flags: Write

Allowed values: >= G_MAXULONG

Default value: -1


The “begin-time” property

  “begin-time”               guint64

Begin of section in time.

Flags: Write

Default value: 0


The “drop-tags” property

  “drop-tags”                gchar *

Drop matching tag events.

Flags: Read / Write

Default value: ""


The “end-count” property

  “end-count”                gint64

End of section in frames.

Flags: Write

Allowed values: >= G_MAXULONG

Default value: -1


The “end-time” property

  “end-time”                 guint64

End of section in time.

Flags: Write

Default value: 0


The “force-eos” property

  “force-eos”                gboolean

Force End-Of-Stream.

Flags: Write

Default value: TRUE


The “framerate” property

  “framerate”                gchar *

Framerate discovered in stream and used for cutting and stamping.

Flags: Read

Default value: "1/1"


The “handle-query” property

  “handle-query”             gboolean

Respond to position query.

Flags: Read / Write

Default value: FALSE


The “precision” property

  “precision”                gboolean

Precision filter, slicing (audio) buffers if needed.

Flags: Read / Write

Default value: FALSE


The “samplerate” property

  “samplerate”               gint

Samplerate discovered in stream and used for cutting and stamping.

Flags: Read

Allowed values: >= 0

Default value: 0


The “samplewidth” property

  “samplewidth”              gint

Width of a sample as deduced from stream and used for cutting and stamping.

Flags: Read

Allowed values: >= 0

Default value: 0


The “save-section” property

  “save-section”             gboolean

Commit current section info for processing.

Flags: Write

Default value: TRUE


The “section” property

  “section”                  gint

Current filtered section.

Flags: Read

Allowed values: >= G_MAXULONG

Default value: -1


The “segment-mode” property

  “segment-mode”             gboolean

Control and filter flow based on segments and seeks.

Flags: Read / Write

Default value: TRUE


The “use-count” property

  “use-count”                gboolean

Filter flow based on byte or frame count.

Flags: Read / Write

Default value: TRUE