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.
  10
  11  Some use cases:
  12
  13    +---------+     +--------+     +-------+
  14    | httpsrc |     | buffer |     | demux |
  15    |        src - sink     src - sink     ....
  16    +---------+     +--------+     +-------+
  17
  18   In this case we are reading from a slow network source into a buffer element
  19   (such as queue).
  20
  21   The buffer element has a low and high watermark expressed in bytes. The
  22   buffer uses the watermarks as follows:
  23
  24    - The buffer element will not produce data on the src pad until the high
  25      watermark is hit. While accumulating data in the buffer, progress is
  26      reported by posting BUFFERING messages.
  27    - The source will stop to produce data on the src pad when the low watermark
  28      is hit.
  29
  30
  31 Messages
  32 --------
  33
  34 A GST_MESSAGE_BUFFERING must be posted on the bus when playback temporarily
  35 stops to buffer and when buffering finishes. When percentage field in the
  36 BUFFERING message is 100, buffering is done. Values less than 100 mean that
  37 buffering is in progress.
  38
  39 The BUFFERING message should be intercepted and acted upon by the application.
  40
  41
  42 Application
  43 -----------
  44
  45 While data is buffered, the pipeline should remain in the PAUSED state. It is
  46 also possible that more data should be buffered while the pipeline is PLAYING,
  47 in which case the pipeline should be PAUSED until the buffering finished.
  48
  49 BUFFERING messages can be posted while the pipeline is prerolling. The
  50 application should not set the pipeline to PLAYING before a BUFFERING message
  51 with 100 percent value is received, which might only happen after the pipeline
  52 prerolled.
  53
  54
  55 Buffering Query
  56 ---------------
  57
  58 It is possible to query the amount of buffering performed in the pipeline, which
  59 is defined as the amount of data made available at the source. This amount is
  60 expressed in some GstFormat and is usually compared to the duration or position
  61 of the media stream in the same GstFormat.
  62
  63 The buffering query should return the following information:
  64
  65  - format
  66  - position
  67  - duration
  68
  69 The format is of lesser importance, the ratio of position versus duration can be
  70 used to calculate the percentage of available media. It should also be possible
  71 for the application to calculate the expected time when the complete file will
  72 be buffered.
  73
  74
  75
  76 Incremental download
  77 --------------------
  78
  79