3.2 element%

8.16.0.1

class
element% : class?

The basic building block for any GStreamer media pipeline. Elements are like a black box: something goes in, and something else will come out the other side. For example, a decoder element would take in encoded data and would output decoded data. A muxer element would take in several different media streams and combine them into one. Elements are linked via pads.

method
(send an-element add-pad pad) → boolean?
pad : (is-a?/c pad%)

Adds pad to an-element. Returns #t if the pad could be added, #f otherwise. This method can fail when a pad with the same name already existed or pad already had another parent.

method
(send an-element get-compatible-pad pad
[ caps])
→ (or/c (is-a?/c pad%) #f)
pad : (is-a?/c pad%)
caps : (or/c caps? #f) = #f

Look for an unlinked pad to which pad can link. When caps are present, they are used as a filter for the link. Returns a pad% to which a link could be made, or #f if one cannot be found.

method
(send an-element get-compatible-pad-template compattempl)
→ (or/c pad-template? #f)
compattempl : pad-template?

Retrieves a pad template from an-element that is compatible with compattempl. Pads from compatible templates can be linked together.

method
(send an-element get-request-pad name)
→ (or/c (is-a?/c pad%) #f)
name : string?

Retrieves a pad from an-element by name. This version only retrieves request pads. Returns #f if a pad could not be found.

method
(send an-element get-static-pad name)
→ (or/c (is-a?/c pad%) #f)
name : string?

Retrieves a pad from an-element by name. This version only retrieves already-existing (i.e. static) pads. Returns #f if a pad could not be found.

method
(send an-element link dest) → boolean?
dest : (is-a?/c element%)

Links an-element to dest in that direction, looking for existing pads that aren’t yet linked or requesting new pads if necessary. Returns #t if the elements could be linked, #f otherwise.

method
(send an-element unlink dest) → void?
dest : (is-a?/c element%)

Unlinks all source pads of an-element with all sink pads of the dest element to which they are linked.

method
(send an-element link-many element ...+) → boolean?
element : (is-a?/c element%)

Chains together a series of elements, using link. The elements must share a common bin parent.

method
(send an-element link-pads srcpadname
dest
destpadname) → boolean?
  srcpadname : (or/c string? #f)
  dest : (is-a?/c element%)
  destpadname : (or/c string? #f)

Links the two named pads of an-element and dest. If both elements have different parents, the link fails. Both srcpadname and destpadname could be #f, in which acase any pad will be selected. Returns #t if the pads could be linked, #f otherwise.

method
(send an-element link-pads-filtered srcpadname
dest
destpadname
filter) → boolean?
  srcpadname : (or/c string? #f)
  dest : (is-a?/c element%)
  destpadname : (or/c string? #f)
  filter : (or/c caps? #f)

Equivalent to link-pads, but if filter is present and not #f, the link will be constrained by the specified set of caps.

method
(send an-element link-filtered dest filter) → boolean?
dest : (is-a?/c element%)
filter : (or/c caps? #f)

Equivalent to link, but if filter is present and not #f, the link will be constrained by the specified set of caps.

method
(send an-element set-context context) → void?
context : context?

Sets the context of an-element to context.

method
(send an-element get-context type) → (or/c context? #f)
type : string?

Gets the context with the type from an-element or #f one is not present.

method
(send an-element get-contexts) → (listof context?)

Gets the contexts set on an-element.

method
(send an-element get-factory) → (is-a?/c element-factory%)

Retrieves the factory that was used to create an-element.

method
(send an-element set-state state)
→ (one-of/c 'failure 'success 'async 'no-preroll)
state : (one-of/c 'void-pending 'null 'ready 'paused 'playing)

Sets the state of an-element. If the method returns 'async, the element will perform the remainder of the state change asynchronously in another thread, in which case an application can use get-state to await the completion of the state change.

method
(send an-element get-state [timeout])
→
(one-of/c 'failure 'success 'async 'no-preroll)
(one-of/c 'void-pending 'null 'ready 'paused 'playing)
(one-of/c 'void-pending 'null 'ready 'paused 'playing)
timeout : clock-time? = clock-time-none

Gets the state of an-element. For elements that performed an 'async state change as a result of set-state, this method call will block up to the specified timeout for the state change to complete.

This method returns three values.

The first returned value is the result of most recent state change, i.e. 'success if the element has no more pending state and the last state change succeeded, 'async if the element is still performing a state change, 'no-preroll if the element successfully changed its state but is not able to provide data yet, or 'failure if the last state change failed.

The second return value is the current state of the element.

The third return value is the pending state of the element, i.e. what the next state will be when the result of the state change is 'async.

method
(send an-element post-message message) → boolean?
message : message?

Posts message on an-element’s bus. Returns #t if the message was successfully posted, #f otherwise.

method
(send an-element send-event event) → boolean?
event : event?

Sends an event to an-element. Returns #t if the event was handled, #f otherwise.

method
(send an-element play!)
→ (one-of/c 'failure 'success 'async 'no-preroll)

Shorthand equivalent to calling set-state on an-element with 'playing.

method
(send an-element pause!)
→ (one-of/c 'failure 'success 'async 'no-preroll)

Shorthand equivalent to calling set-state on an-element with 'paused.

method
(send an-element stop!)
→ (one-of/c 'failure 'success 'async 'no-preroll)

Shorthand equivalent to calling set-state on an-element with 'null.

procedure
(element/c factoryname) → flat-contract?
factoryname : string?

Accepts a string factoryname and returns a flat contract that recognizes elements created by a factory of that name.

procedure
(parse/launch description) → (or/c (is-a?/c element%) #f)
description : string?

Create a new element based on command line syntax, where description is a command line describing a pipeline. Returns #f if an element could not be created.

class
element-factory% : class?

superclass: gst-object%

Element factories are used to create instances of element%.

method
(send an-element-factory create [name]) → (is-a?/c element%)
name : (or/c string? #f) = #f
Creates a new instance of element% of the type defined by an-element-factory. It will be given the name supplied, or if name is #f, a unique name will be created for it.
method
(send an-element-factory get-metadata)
→ (hash/c symbol? any/c)
Returns a hash of an-element-factory metadata e.g. author, description, etc.

procedure
(element-factory%-find name)
→ (or/c (is-a?/c element-factory%) #f)
name : string?

Search for an element factory of name. Returns #f if the factory could not be found.

procedure
(element-factory%-make factoryname
[ name
#:class factory%])
→ (or/c (is-a?/c element%) #f)
  factoryname : string?
  name : (or/c string? #f) = #f
  factory% : (subclass?/c element%) = element%

Create a new element of the type defined by the given factoryname. The element’s name will be given the name if supplied, otherwise the element will receive a unique name. The returned element will be an instance of factory% if provided.

Returns #f if an element was unable to be created.

3.2.2 Events🔗ℹ

An event in GStreamer is a small structure to describe notification signals that can be passed up and down a pipeline. Events can move both upstream and downstream, notifying elements of stream states. Send an event through a pipeline with send-event.

procedure
(event? v) → boolean?
v : any/c

Returns #t if v is a GStreamer event, #f otherwise.

procedure
(event-type ev)
→
(one-of/c 'unknown 'flush-start 'flush-stop 'stream-start 'caps 'segment
          'stream-collection 'tag 'buffersize 'sink-message 'stream-group-done
          'eos 'toc 'protection 'segment-done 'gap 'qos 'seek 'navigation
          'latency 'step 'reconfigure 'toc-select 'select-streams
          'custom-upstream 'custom-downstream 'custom-downstream-oob
          'custom-downstream-sticky 'custom-both 'custom-both-oob)
  ev : event?

Gets the type of event for ev.

procedure
(event-seqnum ev) → exact-integer?
ev : event?

Retrieve the sequence number of ev.

Events have ever-incrementing sequence numbers. Sequence numbers are typically used to indicate that an event corresponds to some other set of messages or events.

Events and messages share the same sequence number incrementor; two events or messages will never have the same sequence number unless that correspondence was made explicitly.

procedure
(make-eos-event) → event?

Create a new EOS (end-of-stream) event.

The EOS event will travel down to the sink elements in the pipeline which will then post an eos-message? on the bus after they have finished playing any buffered data.

The EOS event itself will not cause any state transitions of the pipeline.

3.2.3 Contexts🔗ℹ

A GStreamer context is a container used to store contexts that can be shared between multiple elements. Applications will set a context on an element (or a pipeline) with set-context.

procedure
(context? v) → boolean?
v : any/c

Returns #t if v is a context, #f otherwise.

procedure
(context-type context) → string?
context : context?

Gets the type of context, which is just a string that describes what the context contains.

procedure
(context-has-type? context type) → boolean?
context : context?
type : string?

Returns #t if context has a context type of type, #f otherwise.

procedure
(context-persistent? context) → boolean?
context : context?

Returns #t if context is persistent, that is the context will be kept by the element even if it reaches a 'null state. Otherwise returns #f.

procedure
(make-context type key value [persistent?]) → context?
  type : string?
  key : string?
  value : any/c
  persistent? : boolean? = #f

Create a context of type that maps key to value.

procedure
(context-ref context key) → (or/c any/c #f)
context : context?
key : string?

Retrieves the value of context mapped to key, or #f if no value is found.

1	Getting Started
2	Broadcasting
3	GStreamer
4	GObject Introspection

3.1	Using GStreamer
3.2	element%
3.3	bin%
3.4	bus%
3.5	pad%
3.6	clock%
3.7	device%
3.8	Capabilities
3.9	Buffers
3.10	Common Elements
3.11	Base Support