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.
  48    - during playback, the queue level will fluctuate between the high and the
  49      low watermark as a way to compensate for network irregularities.
  50
  51   This buffering method is usable when the demuxer operates in push mode.
  52   Seeking in the stream requires the seek to happen in the network source.
  53   It is mostly desirable when the total duration of the file is not know, such
  54   as in live streaming or when efficient seeking is not possible/required.
  55
  56  * Incremental download
  57
  58    +---------+     +---------+     +-------+
  59    | httpsrc |     | buffer  |     | demux |
  60    |        src - sink      src - sink     ....
  61    +---------+     +----|----+     +-------+
  62                         V
  63                        file
  64
  65   In this case, we know the server is streaming a fixed length file to the
  66   client. The application can choose to download the file on disk. The buffer
  67   element will provide a push or pull based srcpad to the demuxer to navigate in
  68   the downloaded file.
  69
  70   This mode is only suitable when the client can determine the length of the
  71   file on the server.
  72
  73   In this case, buffering messages will be emited as usual when the requested
  74   range is not within the downloaded area + buffersize. The buffering message
  75   will also contain an indication that incremental download is being performed.
  76   This flag can be used to let the application control the buffering in a more
  77   intelligent way, using the BUFFERING query, for example.
  78
  79   The application can use the BUFFERING query to get the estimated download time
  80   and match this time to the current/remaining playback time to control when
  81   playback should start to have a non-interupted playback experience.
  82
  83
  84  * Timeshifting
  85
  86    +---------+     +---------+     +-------+
  87    | httpsrc |     | buffer  |     | demux |
  88    |        src - sink      src - sink     ....
  89    +---------+     +----|----+     +-------+
  90                         V
  91                     file-ringbuffer
  92
  93   In this mode, a fixed size ringbuffer is kept to download the server content.
  94   This allows for seeking in the buffered data. Depending on the size of the
  95   buffer one can seek further back in time.
  96
  97   This mode is suitable for all live streams.
  98
  99   As with the incremental download mode, buffering messages are emited along
 100   with an indication that timeshifting download is in progress.
 101
 102
 103  * Live buffering
 104
 105   In live pipelines we usually introduce some latency between the capture and
 106   the playback elements. This latency can be introduced by a queue (such as a
 107   jitterbuffer) or by other means (in the audiosink).
 108
 109   Buffering messages can be emited in those live pipelines as well and serve as
 110   an indication to the user of the latency buffering. The application usually
 111   does not react to these buffering messages with a state change.
 112
 113
 114 Messages
 115 --------
 116
 117 A GST_MESSAGE_BUFFERING must be posted on the bus when playback temporarily
 118 stops to buffer and when buffering finishes. When percentage field in the
 119 BUFFERING message is 100, buffering is done. Values less than 100 mean that
 120 buffering is in progress.
 121
 122 The BUFFERING message should be intercepted and acted upon by the application.
 123 The message contains at least one field that is sufficient for basic
 124 functionality:
 125
 126   "buffer-percent", G_TYPE_INT, between 0 and 100
 127
 128 Several more clever ways of dealing with the buffering messages can be used when
 129 in incremental or timeshifting download mode. For this purpose additional fields
 130 are added to the buffering message:
 131
 132   "buffering-mode", GST_TYPE_BUFFERING_MODE,
 133                    enum { "none", "stream", "download", "timeshift", "live" }
 134       - gives the buffering mode in use. See above for an explanation of the
 135         different modes of buffering.
 136
 137   "avg-in-rate", G_TYPE_INT
 138       - gives the average input buffering speed in bytes/second. -1 is unknown.
 139
 140         This is the average number of bytes per second that is received on the
 141         buffering element input (sink) pads. If is a measurement of the network
 142         speed in most cases.
 143
 144   "avg-out-rate", G_TYPE_INT
 145       - gives the average consumption speed in bytes/second. -1 is unknown.
 146
 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_INT
 151       - gives the estimated time that bufferring will take in milliseconds.
 152         -1 unknown.
 153
 154       This is measured based on the avg-in-rate and the filled level of the
 155       queue. The application can use this hint to update the gui while buffering.
 156
 157   "estimated-time", G_TYPE_INT
 158       - gives the estimated download time in milliseconds. -1 unknown.
 159
 160       When the size of the downloaded file is known, this value will contain
 161       the latest estimate of the remaining download time. This value is usualy
 162       only filled for the "download" buffering mode.
 163
 164
 165 Application
 166 -----------
 167
 168 While data is buffered, the pipeline should remain in the PAUSED state. It is
 169 also possible that more data should be buffered while the pipeline is PLAYING,
 170 in which case the pipeline should be PAUSED until the buffering finished.
 171
 172 BUFFERING messages can be posted while the pipeline is prerolling. The
 173 application should not set the pipeline to PLAYING before a BUFFERING message
 174 with 100 percent value is received, which might only happen after the pipeline
 175 prerolled.
 176
 177 An exception is made for live pipelines. The application may not change
 178 the state of a live pipeline when a buffering message is received. Usually these
 179 buffering messages contain the "buffering-mode" = "live".
 180
 181 The buffering message can also instruct the application to switch to a periodical
 182 BUFFERING query instead to more precisely control the buffering process. The
 183 application can, for example, choose to not act on the BUFFERING message with
 184 100 percent fill level to resume playback but instead use the estimated download
 185 time to resume playback to get uninterrupted playback.
 186
 187
 188 Buffering Query
 189 ---------------
 190
 191 In addition to the BUFFERING messages posted by the buffering elements we want
 192 to be able to query the same information from the application. We also want to
 193 be able to present the user with information about the downloaded range in the
 194 file so that the GUI can react on it.
 195
 196 In addition to all the fields present in the buffering message, the BUFFERING
 197 query contains the following field, which indicate the available downloaded
 198 range in a specific format:
 199
 200   "format", GST_TYPE_FORMAT
 201     - the format of the "start" and "stop" values below
 202
 203   "start", G_TYPE_INT64, -1 unknown
 204     - the start position of the available data
 205
 206   "stop", G_TYPE_INT64, -1 unknown
 207     - the stop position of the available data
 208
 209 For the "download" and "timeshift" buffering-modes, the start and stop positions
 210 specify the ranges where efficient seeking in the downloaded media is possible.
 211 Seeking outside of these ranges might be slow or not at all possible.
 212
 213 For the "stream" and "live" mode the start and stop values describe the oldest
 214 and newest item (expressed in "format") in the buffer.
 215
 216
 217 Defaults
 218 --------
 219
 220 Some defaults for common elements:
 221
 222 A GstBaseSrc with random access replies to the BUFFERING query with:
 223
 224   "buffer-percent" = 100
 225   "buffering-mode" = "none"
 226   "avg-in-rate" = -1
 227   "avg-out-rate" = -1
 228   "buffering-left" = 0
 229   "estimated-time" = 0
 230   "format" = GST_FORMAT_BYTES
 231   "start" = 0
 232   "stop" = the total filesize
 233
 234 A GstBaseSrc in push mode replies to the BUFFERING query with:
 235
 236   "buffer-percent" = 100
 237   "buffering-mode" = "none"
 238   "avg-in-rate" = -1
 239   "avg-out-rate" = -1
 240   "buffering-left" = 0
 241   "estimated-time" = 0
 242   "format" = a valid GST_TYPE_FORMAT
 243   "start" = current position
 244   "stop" = current position
 245