docs/random/wtay/messages

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