docs/design/part-buffering.txt

   1 Buffering
   2 ---------
   3
   4 This document outlines the buffering policy used in the GStreamer
   5 core that can be used by plugins and applications.
   6
   7 The purpose of buffering is to accumulate enough data in a pipeline so that
   8 playback can occur smoothly and without interruptions. It is typically done
   9 when reading from a (slow) and non-live network source but can also be used for
  10 live sources.
  11
  12 We want to be able to implement the following features:
  13
  14  - buffering up to a specifc amount of data, in memory, before starting playback
  15    so that network fluctuations are minimized.
  16  - download of the network file to a local disk with fast seeking in the
  17    downloaded data. This is similar to the quicktime/youtube players.
  18  - caching of semi-live streams to a local, on disk, ringbuffer with seeking in
  19    the cached area. This is similar to tivo-like timeshifting.
  20  - progress report about the buffering operations
  21  - easy (backward compatible) application notification of buffering
  22  - the possibility for the application to do more complex buffering
  23
  24 Some use cases:
  25
  26  * Stream buffering:
  27
  28    +---------+     +---------+     +-------+
  29    | httpsrc |     | buffer  |     | demux |
  30    |        src - sink      src - sink     ....
  31    +---------+     +---------+     +-------+
  32
  33   In this case we are reading from a slow network source into a buffer element
  34   (such as queue2).
  35
  36   The buffer element has a low and high watermark expressed in bytes. The
  37   buffer uses the watermarks as follows:
  38
  39    - The buffer element will post BUFFERING messages until the high watermark
  40      is hit. This instructs the application to keep the pipeline PAUSED, which
  41      will eventually block the srcpad from pushing while data is prerolled in
  42      the sinks.
  43    - When the high watermark is hit, a BUFFERING message with 100% will be
  44      posted, which instructs the application to continue playback.
  45    - When during playback, the low watermark is hit, the queue will start posting
  46      BUFFERING messages again, making the application PAUSE the pipeline again
  47      until the high watermark is hit again. This is called the rebuffering
  48      stage.
  49    - during playback, the queue level will fluctuate between the high and the
  50      low watermark as a way to compensate for network irregularities.
  51
  52   This buffering method is usable when the demuxer operates in push mode.
  53   Seeking in the stream requires the seek to happen in the network source.
  54   It is mostly desirable when the total duration of the file is not know, such
  55   as in live streaming or when efficient seeking is not possible/required.
  56
  57  * Incremental download
  58
  59    +---------+     +---------+     +-------+
  60    | httpsrc |     | buffer  |     | demux |
  61    |        src - sink      src - sink     ....
  62    +---------+     +----|----+     +-------+
  63                         V
  64                        file
  65
  66   In this case, we know the server is streaming a fixed length file to the
  67   client. The application can choose to download the file on disk. The buffer
  68   element will provide a push or pull based srcpad to the demuxer to navigate in
  69   the downloaded file.
  70
  71   This mode is only suitable when the client can determine the length of the
  72   file on the server.
  73
  74   In this case, buffering messages will be emited as usual when the requested
  75   range is not within the downloaded area + buffersize. The buffering message
  76   will also contain an indication that incremental download is being performed.
  77   This flag can be used to let the application control the buffering in a more
  78   intelligent way, using the BUFFERING query, for example.
  79
  80   The application can use the BUFFERING query to get the estimated download time
  81   and match this time to the current/remaining playback time to control when
  82   playback should start to have a non-interupted playback experience.
  83
  84
  85  * Timeshifting
  86
  87    +---------+     +---------+     +-------+
  88    | httpsrc |     | buffer  |     | demux |
  89    |        src - sink      src - sink     ....
  90    +---------+     +----|----+     +-------+
  91                         V
  92                     file-ringbuffer
  93
  94   In this mode, a fixed size ringbuffer is kept to download the server content.
  95   This allows for seeking in the buffered data. Depending on the size of the
  96   buffer one can seek further back in time.
  97
  98   This mode is suitable for all live streams.
  99
 100   As with the incremental download mode, buffering messages are emited along
 101   with an indication that timeshifting download is in progress.
 102
 103
 104  * Live buffering
 105
 106   In live pipelines we usually introduce some latency between the capture and
 107   the playback elements. This latency can be introduced by a queue (such as a
 108   jitterbuffer) or by other means (in the audiosink).
 109
 110   Buffering messages can be emited in those live pipelines as well and serve as
 111   an indication to the user of the latency buffering. The application usually
 112   does not react to these buffering messages with a state change.
 113
 114
 115 Messages
 116 ~~~~~~~~
 117
 118 A GST_MESSAGE_BUFFERING must be posted on the bus when playback temporarily
 119 stops to buffer and when buffering finishes. When percentage field in the
 120 BUFFERING message is 100, buffering is done. Values less than 100 mean that
 121 buffering is in progress.
 122
 123 The BUFFERING message should be intercepted and acted upon by the application.
 124 The message contains at least one field that is sufficient for basic
 125 functionality:
 126
 127   "buffer-percent", G_TYPE_INT, between 0 and 100
 128
 129 Several more clever ways of dealing with the buffering messages can be used when
 130 in incremental or timeshifting download mode. For this purpose additional fields
 131 are added to the buffering message:
 132
 133   "buffering-mode", GST_TYPE_BUFFERING_MODE,
 134                    enum { "stream", "download", "timeshift", "live" }
 135       - gives the buffering mode in use. See above for an explanation of the
 136         different modes of buffering. This field can be used to let the
 137         application have more control over the buffering process.
 138
 139   "avg-in-rate", G_TYPE_INT
 140       - gives the average input buffering speed in bytes/second. -1 is unknown.
 141         This is the average number of bytes per second that is received on the
 142         buffering element input (sink) pads. It is a measurement of the network
 143         speed in most cases.
 144
 145   "avg-out-rate", G_TYPE_INT
 146       - gives the average consumption speed in bytes/second. -1 is unknown.
 147         This is the average number of bytes per second that is consumed by the
 148         downstream element of the buffering element.
 149
 150   "buffering-left", G_TYPE_INT64
 151       - gives the estimated time that bufferring will take in milliseconds.
 152         -1 unknown.
 153         This is measured based on the avg-in-rate and the filled level of the
 154         queue. The application can use this hint to update the GUI about the
 155         estimated remaining time that buffering will take.
 156
 157 Application
 158 ~~~~~~~~~~~
 159
 160 While data is buffered, the pipeline should remain in the PAUSED state. It is
 161 also possible that more data should be buffered while the pipeline is PLAYING,
 162 in which case the pipeline should be PAUSED until the buffering finished.
 163
 164 BUFFERING messages can be posted while the pipeline is prerolling. The
 165 application should not set the pipeline to PLAYING before a BUFFERING message
 166 with 100 percent value is received, which might only happen after the pipeline
 167 prerolled.
 168
 169 An exception is made for live pipelines. The application may not change
 170 the state of a live pipeline when a buffering message is received. Usually these
 171 buffering messages contain the "buffering-mode" = "live".
 172
 173 The buffering message can also instruct the application to switch to a periodical
 174 BUFFERING query instead to more precisely control the buffering process. The
 175 application can, for example, choose to not act on the BUFFERING message with
 176 100 percent fill level to resume playback but instead use the estimated download
 177 time to resume playback to get uninterrupted playback.
 178
 179
 180 Buffering Query
 181 ~~~~~~~~~~~~~~~
 182
 183 In addition to the BUFFERING messages posted by the buffering elements we want
 184 to be able to query the same information from the application. We also want to
 185 be able to present the user with information about the downloaded range in the
 186 file so that the GUI can react on it.
 187
 188 In addition to all the fields present in the buffering message, the BUFFERING
 189 query contains the following field, which indicate the available downloaded
 190 range in a specific format and the estimated time to complete:
 191
 192   "busy", G_TYPE_BOOLEAN
 193     - if buffering was busy. This flag allows the application to pause the
 194       pipeline by using the query only.
 195
 196   "format", GST_TYPE_FORMAT
 197     - the format of the "start" and "stop" values below
 198
 199   "start", G_TYPE_INT64, -1 unknown
 200     - the start position of the available data
 201
 202   "stop", G_TYPE_INT64, -1 unknown
 203     - the stop position of the available data
 204
 205   "estimated-total", G_TYPE_INT64
 206     - gives the estimated download time in milliseconds. -1 unknown.
 207
 208     When the size of the downloaded file is known, this value will contain
 209     the latest estimate of the remaining download time. This value is usualy
 210     only filled for the "download" buffering mode. The application can use
 211     this information to estimate the amount of remaining time to download the
 212     complete file.
 213
 214 For the "download" and "timeshift" buffering-modes, the start and stop positions
 215 specify the ranges where efficient seeking in the downloaded media is possible.
 216 Seeking outside of these ranges might be slow or not at all possible.
 217
 218 For the "stream" and "live" mode the start and stop values describe the oldest
 219 and newest item (expressed in "format") in the buffer.
 220
 221
 222 Defaults
 223 ~~~~~~~~
 224
 225 Some defaults for common elements:
 226
 227 A GstBaseSrc with random access replies to the BUFFERING query with:
 228
 229   "buffer-percent" = 100
 230   "buffering-mode" = "stream"
 231   "avg-in-rate" = -1
 232   "avg-out-rate" = -1
 233   "buffering-left" = 0
 234   "format" = GST_FORMAT_BYTES
 235   "start" = 0
 236   "stop" = the total filesize
 237   "estimated-total" = 0
 238
 239 A GstBaseSrc in push mode replies to the BUFFERING query with:
 240
 241   "buffer-percent" = 100
 242   "buffering-mode" = "stream"
 243   "avg-in-rate" = -1
 244   "avg-out-rate" = -1
 245   "buffering-left" = 0
 246   "format" = a valid GST_TYPE_FORMAT
 247   "start" = current position
 248   "stop" = current position
 249   "estimated-total" = -1
 250
 251
 252 Buffering strategies
 253 ~~~~~~~~~~~~~~~~~~~~
 254
 255  Buffering strategies are specific implementations based on the buffering
 256  message and query described above.
 257
 258  Most strategies have to balance buffering time versus maximal playback
 259  experience.
 260
 261  * simple buffering
 262
 263    NON-live pipelines are kept in the paused state while buffering messages with
 264    a percent < 100% are received.
 265
 266    This buffering strategy relies on the buffer size and low/high watermarks of
 267    the element. It can work with a fixed size buffer in memory or on disk.
 268
 269    The size of the buffer is usually expressed in a fixed amount of time units
 270    and the estimated bitrate of the upstream source is used to convert this time
 271    to bytes.
 272
 273    All GStreamer applications must implement this strategy. Failure to do so
 274    will result in starvation at the sink.
 275
 276  * no-rebuffer strategy
 277
 278    This strategy tries to buffer as much data as possible so that playback can
 279    continue without any further rebuffering.
 280
 281    This strategy is initially similar to simple buffering, the difference is in
 282    deciding on the condition to continue playback. When a 100% buffering message
 283    has been received, the application will not yet start the playback but it will
 284    start a periodic buffering query, which will return the estimated amount of
 285    buffering time left. When the estimated time left is less than the remaining
 286    playback time, playback can continue.
 287
 288    This strategy requires a unlimited buffer size in memory or on disk, such as
 289    provided by elements that implement the incremental download buffering mode.
 290
 291    Usually, the application can choose to start playback even before the
 292    remaining buffer time elapsed in order to more quickly start the playback at
 293    the expense of a possible rebuffering phase.
 294
 295  * Incremental rebuffering
 296
 297    The application implements the simple buffering strategy but with each
 298    rebuffering phase, it increases the size of the buffer.
 299
 300    This strategy has quick, fixed time startup times but incrementally longer
 301    rebuffering times if the network is slower than the media bitrate.
 302
 303
 304
 305
 306
 307
 308