Skip to content

uridecodebin: Add properties and documentation for better control over buffering

Submitted by Carlos Rafael Giani

Link to original bug (#762125)

Description

Created attachment 321347
uridecodebin patch for enhanced buffering control

Currently, there are only two properties for controlling the buffering: buffer-size and buffer-duration. Properties for the low/high percentage thresholds are missing. Also, the default value for buffer-size and buffer-duration is -1, which means "automatic/default". It is not obvious what this exactly means, and relies on hardcoded internal values.

Furthermore, buffer-duration conflates two distinct concepts: its value is used both for bitrate-based and for input data rate based buffer size estimation. As a result, a buffer-duration value of for example 5 seconds can either mean a buffer size of bitrate5 seconds , or in case of slow connections, in-data-rate5 seconds, whichever is lower. In many cases, it is desirable to use only one of these two estimations.

The exact way how buffering behaves, how the properties work, and how it should be used is not documented.

This is the first version of a patch that deprecates buffer-size and buffer-duration in favor of three new properties: max-buffer-size, max-buffering-duration, and buffer-estimate-duration.

The new properties work as follows:

  • max-buffer-size: The upper limit for the buffer size, in bytes; this value is passed to the internal queue/decodebin as the "max-size-bytes" property; default value is 10 MB
  • max-buffering-duration: The in-data-rate*duration estimate mentioned above; this value is passed to the internal queue/decodebin as the "max-size-time" property, but it is not used for bitrate based estimations; default value is 0 (= disables data rate based estimates)
  • buffer-estimate-duration: The bitrate*duration estimate mentioned above; this value is not passed to the internal queue, and used only if a bitrate tag is encountered; default value is 6.5 seconds

Out of these three, the lowest size (in bytes) is picked.

The patch also makes it possible to set these property during playback; the buffer size will be readjusted on the fly.

Properties for low/high percentage are also introduced. Default values are: low 5%, high 5%. Together with the default values for the other three properties, this means buffering messages will reach 100% once 1.5 seconds are buffered. During playback, if the source can deliver data faster than realtime, additional 5 second can be buffered on the fly. This makes streaming playback more robust against network bandwidth drops without having to let the user wait too long for buffering to finish.

gtkdoc documentation for how to use these new properties and how configuring buffer size works is also added.

Also, a new "will-post-buffering" signal is added. This is emitted whenever uridecodebin sets the "use-buffering" property of an internal queue to TRUE. This is useful for applications to let them know that they should not switch to PLAYING just yet, because buffering messages will be posted soon. This prevents the possibility that the PLAYING state is reached, playback goes on briefly, and then the application receives the first BUFFERING message, and pauses playback again.

In subsequent patches, playbin could also get these new properties (they'd be forwarded to uridecodebin just like buffer-size and buffer-duration are now), and the new signal. Another planned addition is a "current-buffer-level" property; however, this first requires a patch for multiqueue, since it doesn't have any property like that (queue2 does have "current-level-bytes"). Also, several parsers such as flacparse, wavparse, aiffparse have been found to not push bitrate tags downstream, and therefore also require patching to further improve buffering behavior.

Patch 321347, "uridecodebin patch for enhanced buffering control":
0001-uridecodebin-Add-properties-and-signals-for-better-c.patch