docs/design/draft-klass.txt

   1 Element Klass definition
   2 ------------------------
   3
   4 Purpose
   5 ~~~~~~~
   6
   7 Applications should be able to retrieve elements from the registry of existing
   8 elements based on specific capabilities or features of the element.
   9
  10 A playback application might want to retrieve all the elements that can be
  11 used for visualisation, for example, or a video editor might want to select
  12 all video effect filters.
  13
  14 The topic of defining the klass of elements should be based on use cases.
  15
  16 A list of classes that are used in a installation can be generated using:
  17 gst-inspect-0.10 -a | grep -ho Class:.* | cut -c8- | sed "s/\//\\n/g" | sort | uniq
  18
  19 Proposal
  20 ~~~~~~~~
  21
  22 The GstElementDetails contains a field named klass that is a pointer to a
  23 string describing the element type.
  24
  25 In this document we describe the format and contents of the string. Elements
  26 should adhere to this specification although that is not enforced to allow
  27 for wild (application specific) customisation.
  28
  29 1) string format
  30
  31     <keyword>['/'<keyword]*
  32
  33   The string consists of an _unordered_ list of keywords separated with a '/'
  34   character. While the / suggests a hierarchy, this is _not_ the case.
  35
  36 2) keyword categories
  37
  38  - functional
  39
  40    Categories are base on _intended usage_ of the element. Some elements
  41    might have other side-effects (especially for filers/effects). The purpose
  42    is to list enough keywords so that applications can do meaningfull filtering,
  43    not to completely describe the functionality, that is expressed in caps etc..
  44
  45    * Source        : produces data
  46    * Sink          : consumes data
  47    * Filter        : filters/transforms data, no modification on the data is
  48                      intended (although it might be unavoidable). The
  49                      filter can decide on input and output caps independently
  50                      of the stream contents (GstBaseTransform).
  51    * Effect        : applies an effect to some data, changes to data are
  52                      intended. Examples are colorbalance, volume. These
  53                      elements can also be implemented with GstBaseTransform.
  54    * Demuxer       : splits audio, video, ... from a stream
  55    * Muxer         : interleave audio, video, ... into one stream, this is
  56                      like mixing but without losing or degrading each separate
  57                      input stream. The reverse operation is possible with a
  58                      Demuxer that reproduces the exact same input streams.
  59    * Decoder       : decodes encoded data into a raw format, there is typically
  60                      no relation between input caps and output caps. The output
  61                      caps are defined in the stream data. This separates the
  62                      Decoder from the Filter and Effect.
  63    * Encoder       : encodes raw data into an encoded format.
  64    * Mixer         : combine audio, video, .. this is like muxing but with
  65                      applying some algorithm so that the individual streams
  66                      are not extractable anymore, there is therefore no
  67                      reverse operation to mixing. (audio mixer, video mixer, ...)
  68    * Converter     : convert audio into video, text to audio, ... The converter
  69                      typically works on raw types only. The source media type
  70                      is listed first.
  71    * Analyzer      : reports about the stream contents.
  72    * Control       : controls some aspect of a hardware device
  73    * Extracter     : extracts tags/headers from a stream
  74    * Formatter     : adds tags/headers to a stream
  75    * Connector     : allows for new connections in the pipeline. (tee, ...)
  76    * ...
  77
  78  - Based on media type
  79
  80    Purpose is to make a selection for elements operating on the different
  81    types of media. An audio application must be able to filter out the
  82    elements operating on audio, for example.
  83
  84    * Audio         : operates on audio data
  85    * Video         : operates on video data
  86    * Image         : operates on image data. Usually this media type can also
  87                      be used to make a video stream in which case it is added
  88                      together with the Video media type.
  89    * Text          : operates on text data
  90    * Metadata      : operates on metadata
  91    * ...
  92
  93  - Extra features
  94
  95    The purpose is to further specialize the element, mostly for
  96    application specific needs.
  97
  98    * Network       : element is used in networked situations
  99    * Protocol      : implements some protocol (RTSP, HTTP, ...)
 100    * Payloader     : encapsulate as payload (RTP, RDT,.. )
 101    * Depayloader   : strip a payload (RTP, RDT,.. )
 102    * RTP           : intended to be used in RTP applications
 103    * Device        : operates on some hardware device (disk, network,
 104                      audio card, video card, usb, ...)
 105    * Visualisation : intended to be used for audio visualisation
 106    * Debug         : intended usage is more for debugging purposes.
 107
 108  - Categories found, but not yet in one of the above lists
 109
 110    * Bin           : playbin, decodebin, bin, pipeline
 111    * Codec         : lots of decoders, encoder, demuxers
 112                      should be removed?
 113    * Generic       : should be removed?
 114    * File          : like network, should go to Extra?
 115    * Editor        : gnonlin, textoverlays
 116    * DVD, GDP, LADSPA, Parser, Player, Subtitle, Testing, ...
 117
 118 3) suggested order:
 119
 120    <functional>[/<media type>]*[/<extra...>]*
 121
 122 4) examples:
 123
 124    apedemux         : Extracter/Metadata
 125    audiotestsrc     : Source/Audio
 126    autoaudiosink    : Sink/Audio/Device
 127    cairotimeoverlay : Mixer/Video/Text
 128    dvdec            : Decoder/Video
 129    dvdemux          : Demuxer
 130    goom             : Converter/Audio/Video
 131    id3demux         : Extracter/Metadata
 132    udpsrc           : Source/Network/Protocol/Device
 133    videomixer       : Mixer/Video
 134    ffmpegcolorspace : Filter/Video             (intended use to convert video with as little
 135                                                 visible change as possible)
 136    vertigotv        : Effect/Video             (intended use is to change the video)
 137    volume           : Effect/Audio             (intended use is to change the audio data)
 138    vorbisdec        : Decoder/Audio
 139    vorbisenc        : Encoder/Audio
 140    oggmux           : Muxer
 141    adder            : Mixer/Audio
 142    videobox         : Effect/Video
 143    alsamixer        : Control/Audio/Device
 144    audioconvert     : Filter/Audio
 145    audioresample    : Filter/Audio
 146    xvimagesink      : Sink/Video/Device
 147    navseek          : Filter/Debug
 148    decodebin        : Decoder/Demuxer
 149    level            : Filter/Analyzer/Audio
 150    tee              : Connector/Debug
 151
 152  5) open issues:
 153
 154    - how to differencial physical devices from logical ones?
 155      autoaudiosink    : Sink/Audio/Device
 156      alsasink         : Sink/Audio/Device
 157
 158 Use cases
 159 ~~~~~~~~~
 160
 161 - get a list of all elements implementing a video effect (pitivi):
 162
 163    klass.contains (Effect & Video)
 164
 165 - get list of muxers (pitivi):
 166
 167    klass.contains (Muxer)
 168
 169 - get list of video encoders (pitivi):
 170
 171    klass.contains (Encoder & video)
 172
 173 - Get a list of all audio/video visualisations (totem):
 174
 175    klass.contains (Visualisation)
 176
 177 - Get a list of all decoders/demuxer/metadata parsers/vis (playbin):
 178
 179    klass.contains (Visualisation | Demuxer | Decoder | (Extractor & Metadata))
 180
 181 - Get a list of elements that can capture from an audio device (gst-properties):
 182
 183    klass.contains (Source & Audio & Device)
 184
 185     * filters out audiotestsrc, since it is not a device
 186
 187