Element Packaging

It is possible to make more elements available to the Streamer by adding modules to the /usr/lib/streamer directory of the boot image. When a Streamer process starts, it will load all modules in this directory automatically, and examine them to see what elements are available and what properties they have.

Modules

Modules are shared libraries exporting a function called GetModule() that returns a pointer to a ILoadableModule C structure. The ILoadableModule structure contains several function pointers. The functions are used to retrieve the name of the module and the number of classes available in the module. There is also a function to get a pointer to a factory for each class in the module. The factories implement the IModuleClassFactory interface with function pointers, the same way as the ILoadableModule struct.

The class factory contains functions to get information about the class and to create and destroy objects of the class.

Element Modules

The general module system described above is used specifically for elements to create element descriptors. Each class factory in a module is used to create and destroy descriptors describing a specific element. Actually, since element descriptors have static state only, in most cases the CreateObject() function does not create an element descriptor object but rather returns a pointer to a static object and the DestroyObject() function does nothing in that case.

The element descriptors are C++ objects implementing the IElementDescriptor interface. See the Element Descriptor section below for detailed information about the descriptors.

The other functions in the class factory are fairly simple to implement. For element modules they should be implemented the same way for all elements:

Element Descriptors

The element descriptors are ordinary C++ classes implementing the IElementDescriptor interface. The interface is used by the Streamer to create instances of the described element and if the element is a source element the interface is queried to know whether the source can handle URIs that the Streamer is requested to open.

Another purpose of the descriptor is to provide the Streamer core with all the properties of the element. Properties are used to decide what element to create when an output is opened by another element.

Element Properties

The properties of an element are described with an IElementDescriptor::TProperties structure. These properties include the element name and the type of element (source, intermediate or sink). The supported input data formats (the syntax and semantics of the actual stream data carried in the segments) are described with a format expression in the form of a NULL-terminated character string. The output data formats produced by the element are described with the same kind of format expression. See the Format Expression Syntax section for more information.

The number of output formats an element is able to produce may be greater than the number of open output pads the element has at every moment of time. For example, a framing element should have only one pad open at a time but the output format will be different depending on the content of the stream.

The input and output format expressions are used by the Streamer to decide what element to add to the pipeline when an output pad is opened. If there are several suitable elements the one with the highest priority property will be chosen.

However, input and output formats are not enough information for the Streamer core to know what elements to use. The metadata needed by elements must be guaranteed, and therefore information about which metadata that each element use, produce and consume must be specified in the properties. The information on metadata is stored in an array of IElementDescriptor::TMetadataInfo structures, each containing the name of a metadata parameter, the type of the parameter and information about the input and output characteristics for that specific element.

The input may be Produced (the parameter is produced in this element), Optional (the parameter is not required in the element, but the element will perform better if it is available) or Required (the parameter must be available in the stream).

The output on the other hand may be Committed (the metadata is committed to all output pads), Destroyed (the metadata is destroyed) or Published (the parameter is published on the blackboard and the metadata destroyed).

Note! The combination of input Produced and output Destroyed is not allowed. If the Streamer finds an element descriptor with this illegal combination the element will be ignored and not used when constructing the pipeline.

Metadata parameters can be of two distinct types, Momentary or Continual. Momentary parameters are valid only at a specific position in the stream, e.g. a parameter indicating the beginning of a packet or a parameter indicating the time. Continual parameters on the other hand describe a state that is valid until the parameter gets another value, e.g. information about what audio tracks are available or the current playback mode. Only the producer of metadata should indicate what type the parameter is.

Note! If the input is Optional or Required the type must be "Not Produced". If the input is Produced the type must be Momentary or Continual. If the Streamer finds an element descriptor with illegal type/input combination the element will be ignored and not used when constructing the pipeline.

Metadata committed to an element that is not specified in the metadata list is assumed to just pass through the element, i.e. it is committed to all pads by intermediate elements and published on the blackboard by sink elements.

Assuming that the metadata information is correctly specified in the element descriptors, it is possible for the Streamer to deduce what parameters that will be available in the pipeline. This makes it possible for the Streamer to choose elements that produce necessary metadata for other elements later in the chain. It is vital that the information provided in the element properties are correct since the pipeline will not be correctly built otherwise.

Traits

In addition to the properties it is possible to indicate that an element has special traits by letting the the HasTrait() function in the descriptor return true for certain strings.

These are the interesting traits that the descriptor might be asked for:

In later versions of the Streamer other traits might be added. If the element is queried for unknown traits it should always return false.