docs/random/phonon-gst

   1 Phonon backend
   2 --------------
   3
   4  The phonon design is based around forming graphs using 3 basic components:
   5
   6  - a source component that generates raw audio/video/subtitle data, aka
   7    MediaObject.
   8  - an effect component that applies effects to raw audio/video known as
   9    AudioPath/VideoPath respectively. Subtitles are routed to a VideoPath
  10  - output components that render audio or video called AudioOutput and
  11    VideoOutput.
  12
  13   there is also a special input object that allows for feeding raw data in the
  14   pipeline and specialized sinks to retrieve audio samples and video frames from
  15   the pipeline.
  16
  17  A typical graph or a source that produces an audio and a video stream that
  18  need to be played. The VideoPath and AudioPath typically contain no filters
  19  in this case:
  20
  21                      +----+  +---
  22                      | FX |  | ...
  23                      +----+  +---
  24                        V       V
  25                       +-----------+      +-------------+
  26                 ----->| VideoPath |----->| VideoOutput |
  27                 |     +-----------+      +-------------+
  28     +-------------+
  29     | MediaObject |
  30     +-------------+
  31                 |     +-----------+      +-------------+
  32                 +---->| AudioPath |----->| AudioOutput |
  33                       +-----------+      +-------------+
  34                        ^       ^
  35                      +----+  +---
  36                      | FX |  | ...
  37                      +-+--+  +---
  38
  39    - This is very similar to a regular gstreamer playback pipeline.
  40
  41   A typical graph of playing and crosfading two sources:
  42
  43                           +--------+
  44                           | volume |
  45                           +--------+
  46                               V
  47      +-------------+    +-----------+
  48      | MediaObject |--->| AudioPath |\
  49      +-------------+    +-----------+ \     +-------------+
  50                                        ---->| AudioOutput |
  51      +-------------+    +-----------+ /     +-------------+
  52      | MediaObject |--->| AudioPath |/
  53      +-------------+    +-----------+
  54                               ^
  55                           +--------+
  56                           | volume |
  57                           +--------+
  58
  59   - As soon as two audio paths are connected to one sink, the input signals are
  60     mixed before sending them to the sink. The mixing is typically done in the
  61     audio sink by an element such as adder.
  62
  63   Other types of graphs are possible too:
  64
  65                         +-----------+
  66                        /| AudioPath |\
  67      +-------------+  / +-----------+ \     +-------------+
  68      | MediaObject |--                 ---->| AudioOutput |
  69      +-------------+  \ +-----------+ /     +-------------+
  70                        \| AudioPath |/
  71                         +-----------+
  72
  73   - This graph sends the same out data to 2 effect filter graphs and then mixes
  74     it to an audio output. The splitting of the graph typically happens with a
  75     tee element after the media object.
  76
  77
  78 Questions
  79 ---------
  80
  81  1) do the following chains run
  82
  83     - synchronized with a shared clock?
  84
  85      +-------------+    +-----------+    +-------------+
  86      | MediaObject |--->| AudioPath |--->| AudioOutput |
  87      +-------------+    +-----------+    +-------------+
  88
  89      +-------------+    +-----------+    +-------------+
  90      | MediaObject |--->| VideoPath |--->| VideoOutput |
  91      +-------------+    +-----------+    +-------------+
  92
  93     - no API to set both MediaObjects atomically to play so it is assumed that
  94       the playback starts and follows the rate of the global clock as soon as
  95       the MediaObject is set to play. This makes unconnected chains run as if
  96       they were in different GstPipelines.
  97
  98  2) Threading:
  99
 100    - Can signals be emitted from any thread?
 101    - what operations are permited from a signal handler?
 102
 103  3) Error reporting
 104
 105    - How does error reporting work?
 106      * an audio/video device/port is busy.
 107      * a fatal decoding error occurred.
 108      * a media type is not supported
 109
 110
 111 General
 112 -------
 113
 114  - Setting up KDE and Phonon build environment
 115  - Testing, identifying test applications, building test cases
 116  - Asking questions to Phonon maintainers/designers
 117
 118 Essential classes
 119 -----------------
 120
 121 These classes are essential to implement a backend and should be implemented
 122 first.
 123
 124 Phonon::BackendCapabilities
 125
 126   Mostly exposes features in the registry like available decoders and effects.
 127
 128 Phonon::Factory
 129
 130   Entry point for the GStreamer backend. Provides methods to create instances of
 131   object from our backed.
 132
 133
 134 Simple playback
 135 ---------------
 136
 137 The following classes need to be implemented in order to have simple playback
 138 capabilities from the backend.
 139
 140 Phonon::AudioOutput
 141
 142   - Wrapper around audiosinks. Also needs provision for rate and format
 143     conversions.
 144   - Mixing capabilities in the case when 2 audio paths are routed to it.
 145
 146  Notes:
 147
 148   * is the volume related to the device or to the connection to the device.
 149
 150 Phonon::VideoWidget
 151
 152   - Wrapper around videosinks. Also needs provision for colorspace and size
 153     conversions.  Extends QWidget and probably needs to hook into the XOverlay
 154     stuff to draw in the QT widget.  Supports fullscreen mode with a switch.
 155
 156   - Needs mixing capabilities in the case when 2 video paths are routed to it.
 157
 158 Phonon::AbstractMediaProducer
 159
 160   - contains stream selection
 161   - play/pause/stop
 162   - seeking
 163   - periodically performs tick callbacks.
 164
 165 Phonon::MediaObject:
 166
 167   - The object that decodes the media into raw audio/video/subtitle.
 168     This object will use the GStreamer decodebin element to perform the
 169     typefinding and decoding.
 170
 171 Phonon::AudioPath/Phonon::VideoPath
 172
 173   - Simple container for audio/video effect plugins.
 174   - Handles adding/removing of effects, making sure that the streaming is not
 175     interrupted and the formats are all compatible.
 176
 177
 178 Effect support
 179 --------------
 180
 181 Phonon::Visualization
 182
 183   Connects an AudioPath to a VideoWidget and allows for selection of a
 184   visualisation plugin.
 185
 186 Phonon::AudioEffect/Phonon::VideoEffect
 187
 188   Base classes
 189
 190 Phonon::VolumeFaderEffect
 191
 192   Allows fade-in and fade-out with a configurable curve and time. Needs
 193   GstController.
 194
 195 Phonon::BrightnessControl
 196
 197   Controls the brightness of video.
 198
 199
 200 Playlist support
 201 ----------------
 202
 203 Phonon::MediaQueue:
 204
 205   ?? don't know yet where this fits in.
 206
 207
 208 Capture
 209 -------
 210
 211 Phonon::AvCapture
 212
 213   Synchronized audio and video capture.
 214
 215 Phonon::AudioWriter
 216
 217   Compress audio.
 218
 219
 220 Advanced features
 221 -----------------
 222
 223 Phonon::ByteStream
 224
 225   Feed raw data into the pipeline. Used for streaming network access.
 226
 227  Implementation:
 228
 229   Possibly a specialized source element connected to a decodebin.
 230
 231  Notes:
 232
 233   * Phonon::ByteStream::writeData
 234    - can it block?
 235
 236   * Phonon::ByteStream::setStreamSeekable
 237    - If called before starting the ByteStream, decodebin might operate in pull
 238      based mode when supported. Else the source is activated in push mode.
 239    - If called after starting ByteStream, the Phonon::ByteStream::seekStream
 240      signal can be called for push-based seekable streams.
 241
 242   * Can the signals be emitted from a streaming thread?
 243
 244
 245 Phonon::AudioDataOutput/Phonon::VideoDataOutput/
 246
 247   Receive raw audio/video data from the pipeline. Used to allow applications to
 248   deal with the raw data themselves.
 249
 250  Implementation:
 251
 252   Possibly a specialized sink element.
 253
 254  Notes :
 255
 256   * Phonon::AudioDataOutput::dataReady
 257     - can this be emitted from the streaming threads?
 258
 259   * Phonon::AudioDataOutput::endOfMedia
 260     - can this be emitted from the streaming threads?
 261     - We need to grab this EOS message synchronously from the bus.
 262     - should be emitted _before_ sending the last dataReady. This means we need
 263       to cache at least one dataReady.
 264
 265   * Phonon::AudioDataOutput::setDataSize
 266     - can this be a _suggested_ data size or does every callback need to be of
 267       this size?
 268
 269