docs/random/wtay/messages

   1 problem
   2 -------
   3
   4 Since gstreamer uses a hierarchical pipeline layout individual elements
   5 can be inside N levels of containers (bins). Elements can also produce
   6 interesting information for the user app or for its parent.
   7
   8 Consider the mp3parse element that could detect id3 tags in the stream.
   9 One way to let the app know about those tags is by emitting a signal. The
  10 problem with this signal is that the app has to perform a g_signal_connect
  11 on this element. This might not always be possible/feasable because
  12 the APP might not know about the mp3parse element (eg. an autoplugged
  13 pipeline or a compound object). The app could instrospect each element
  14 in the pipeline and look for known properties/signals to connect to,
  15 but that looks a bit ugly IMO.
  16
  17 Signal proxying is also not very feasable because signals are tied to
  18 class instances.
  19
  20 let's take the following use case:
  21
  22  - the user autoplugs an mpeg1 pipeline
  23
  24  - the autoplugged pipeline most likely contains an mpegdemuxer, an mp3
  25    decoder, mpegdecoder etc.
  26
  27  - the mpegdemuxer knows the (average) bitrate of the stream.
  28
  29  - the mpegdecoder knows the framerate of the stream
  30
  31  - the mp3 decoder has some neat stuff too (bitrate, layer etc..)
  32
  33 how are we going to get all those properties to the app? each element
  34 could fire a signal with the data. It the app were able to connect to
  35 every signal in each element this would work somewhat.
  36
  37
  38 Requirements
  39 ------------
  40
  41 The application can listen to an abritrary bin in the pipeline to collect
  42 information about that bins children. The app can listen on the top
  43 level bin to collect all of the elements messages.
  44
  45 The data sent out by the elements must not be limited to a fixed set of
  46 messages; it must be extensible.
  47
  48
  49 proposed solution
  50 -----------------
  51
  52 We propose another way of propagating these element messages to the
  53 application.
  54
  55 An element can send a message to its parent using a
  56 gst_element_send_message (element, message). The message would be of type
  57 GstMessage and would be similar to a GstEvent type (maybe even the same).
  58
  59 The message would contain GstProps, which can be anything (a string, an
  60 int, a range etc..). It would also contain the originator of the message.
  61
  62 The parent would just simply accept the message (and do something with it)
  63 or the default handler would just forward the message to its parent etc..
  64
  65 The message would bubble up the pipeline. When an element doesn't have
  66 a parent, the message is converted to a GSignal. The signal ("message")
  67 would just forward the message to any listening apps.
  68
  69 The app can then use the originator field of the message to find out
  70 where it came from, possibly using the elementfactories klass field to
  71 find out what type of plugin created this message.
  72
  73 For an autoplugged mpeg1 pipeline the following messages could be
  74 signalled to the app:
  75
  76 element klass        element      property      value
  77                      name
  78
  79 stream/mpeg/demuxer: (mpegdemux) "bitrate",   GST_PROPS_INT (1000000)
  80 stream/mpeg/demuxer: (mpegdemux) "type",      GST_PROPS_STRING ("mpeg1")
  81 video/mpeg/decoder:  (mpeg2dec)  "type",      GST_PROPS_STRING ("mpeg1")
  82 video/mpeg/decoder:  (mpeg2dec)  "frame_rate",GST_PROPS_INT (25)
  83 video/mpeg/decoder:  (mpeg2dec)  "size",      GST_PROPS_LIST (
  84                                                  GST_PROPS_INT (320),
  85                                                  GST_PROPS_INT (200)
  86                                                )
  87 audio/mp3/decoder:   (mad)       "layer",     GST_PROPS_INT (2)
  88 audio/mp3/decoder:   (mad)       "bitrate",   GST_PROPS_INT (128000)
  89 audio/mp3/decoder:   (mad)       "channels",  GST_PROPS_INT (2)
  90
  91 other possibilities:
  92
  93 video/render/X:     (xvideosink) "frames_dropped", GST_PROPS_INT (4)
  94 video/render/X:     (xvideosink) "frames_shown",   GST_PROPS_INT (254)
  95 video/mpeg/decoder: (mpeg2dec)   "frames_dropped", GST_PROPS_INT (2)
  96 video/avi/demuxer:  (avidemux)   "codec",          GST_PROPS_FOURCC ("DIVX")
  97
  98 or
  99
 100 video/mpeg/decoder: (mpeg2dec)  "state_changed", GST_PROPS_INT (GST_STATE_PAUSED)
 101
 102 or even
 103
 104 audio/render/oss:    (osssink)  "master_clock", GST_PROPS_OBJECT (osssink_clock)
 105 ....
 106
 107 or even even:
 108
 109 input/file/filesrc:  (filesrc)  "here_i_am", GST_PROPS_STRING ("alive and kicking")
 110
 111
 112 With standard naming conventions for the element klass type and the
 113 messages ids, the player can easily create an info dialog to show various
 114 properties of the stream.
 115
 116 The benefits are that we don't need to define N-thousand methods on
 117 elements, the messages can be anything and we don't have to use the
 118 heavyweight GObject signals in the core library.
 119
 120
 121 what about?
 122 -----------
 123
 124 - Threads? do we queue events and let the top half collect the messages
 125   or do we send them to the app in the thread context?
 126
 127 - do we need a similar system for core functionalities (clocks, states,
 128   ...) or do we define methods for those?
 129
 130
 131