mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-04-26 03:56:16 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs: Gram and nit fixes for part-buffering.txt

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2013-10-14 05:39:19 -07:00
parent 52810aa6ee
commit 06a79347f3
1 changed files with 27 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
docs/design/part-buffering.txt
View file

@ -6,7 +6,7 @@ core that can be used by plugins and applications.
The purpose of buffering is to accumulate enough data in a pipeline so that The purpose of buffering is to accumulate enough data in a pipeline so that
playback can occur smoothly and without interruptions. It is typically done playback can occur smoothly and without interruptions. It is typically done
when reading from a (slow) and non-live network source but can also be used for when reading from a (slow) non-live network source but can also be used for
live sources. live sources.
We want to be able to implement the following features: We want to be able to implement the following features:
@ -41,12 +41,12 @@ Some use cases:
the sinks. the sinks.
- When the high watermark is hit, a BUFFERING message with 100% will be - When the high watermark is hit, a BUFFERING message with 100% will be
posted, which instructs the application to continue playback. posted, which instructs the application to continue playback.
- When during playback, the low watermark is hit, the queue will start posting - When the low watermark is hit during playback, the queue will start posting
BUFFERING messages again, making the application PAUSE the pipeline again BUFFERING messages again, making the application PAUSE the pipeline again
until the high watermark is hit again. This is called the rebuffering until the high watermark is hit again. This is called the rebuffering
stage. stage.
- during playback, the queue level will fluctuate between the high and the - During playback, the queue level will fluctuate between the high and
low watermark as a way to compensate for network irregularities. low watermarks as a way to compensate for network irregularities.
This buffering method is usable when the demuxer operates in push mode. This buffering method is usable when the demuxer operates in push mode.
Seeking in the stream requires the seek to happen in the network source. Seeking in the stream requires the seek to happen in the network source.
@ -63,14 +63,14 @@ Some use cases:
file file
In this case, we know the server is streaming a fixed length file to the In this case, we know the server is streaming a fixed length file to the
client. The application can choose to download the file on disk. The buffer client. The application can choose to download the file to disk. The buffer
element will provide a push or pull based srcpad to the demuxer to navigate in element will provide a push or pull based srcpad to the demuxer to navigate in
the downloaded file. the downloaded file.
This mode is only suitable when the client can determine the length of the This mode is only suitable when the client can determine the length of the
file on the server. file on the server.
In this case, buffering messages will be emited as usual when the requested In this case, buffering messages will be emitted as usual when the requested
range is not within the downloaded area + buffersize. The buffering message range is not within the downloaded area + buffersize. The buffering message
will also contain an indication that incremental download is being performed. will also contain an indication that incremental download is being performed.
This flag can be used to let the application control the buffering in a more This flag can be used to let the application control the buffering in a more
@ -96,7 +96,7 @@ Some use cases:
This mode is suitable for all live streams. This mode is suitable for all live streams.
As with the incremental download mode, buffering messages are emited along As with the incremental download mode, buffering messages are emitted along
with an indication that timeshifting download is in progress. with an indication that timeshifting download is in progress.
@ -106,7 +106,7 @@ Some use cases:
the playback elements. This latency can be introduced by a queue (such as a the playback elements. This latency can be introduced by a queue (such as a
jitterbuffer) or by other means (in the audiosink). jitterbuffer) or by other means (in the audiosink).
Buffering messages can be emited in those live pipelines as well and serve as Buffering messages can be emitted in those live pipelines as well and serve as
an indication to the user of the latency buffering. The application usually an indication to the user of the latency buffering. The application usually
does not react to these buffering messages with a state change. does not react to these buffering messages with a state change.
@ -115,7 +115,7 @@ Messages
~~~~~~~~ ~~~~~~~~
A GST_MESSAGE_BUFFERING must be posted on the bus when playback temporarily A GST_MESSAGE_BUFFERING must be posted on the bus when playback temporarily
stops to buffer and when buffering finishes. When percentage field in the stops to buffer and when buffering finishes. When the percentage field in the
BUFFERING message is 100, buffering is done. Values less than 100 mean that BUFFERING message is 100, buffering is done. Values less than 100 mean that
buffering is in progress. buffering is in progress.
@ -131,24 +131,23 @@ are added to the buffering message:
"buffering-mode", GST_TYPE_BUFFERING_MODE, "buffering-mode", GST_TYPE_BUFFERING_MODE,
enum { "stream", "download", "timeshift", "live" } enum { "stream", "download", "timeshift", "live" }
- gives the buffering mode in use. See above for an explanation of the - Buffering mode in use. See above for an explanation of the
different modes of buffering. This field can be used to let the different alternatives. This field can be used to let the
application have more control over the buffering process. application have more control over the buffering process.
"avg-in-rate", G_TYPE_INT "avg-in-rate", G_TYPE_INT
- gives the average input buffering speed in bytes/second. -1 is unknown. - Average input buffering speed in bytes/second. -1 is unknown.
This is the average number of bytes per second that is received on the This is the average number of bytes per second that is received on the
buffering element input (sink) pads. It is a measurement of the network buffering element input (sink) pads. It is a measurement of the network
speed in most cases. speed in most cases.
"avg-out-rate", G_TYPE_INT "avg-out-rate", G_TYPE_INT
- gives the average consumption speed in bytes/second. -1 is unknown. - Average consumption speed in bytes/second. -1 is unknown.
This is the average number of bytes per second that is consumed by the This is the average number of bytes per second that is consumed by the
downstream element of the buffering element. downstream element of the buffering element.
"buffering-left", G_TYPE_INT64 "buffering-left", G_TYPE_INT64
- gives the estimated time that bufferring will take in milliseconds. - Estimated time that buffering will take in milliseconds. -1 is unknown.
-1 unknown.
This is measured based on the avg-in-rate and the filled level of the This is measured based on the avg-in-rate and the filled level of the
queue. The application can use this hint to update the GUI about the queue. The application can use this hint to update the GUI about the
estimated remaining time that buffering will take. estimated remaining time that buffering will take.
@ -156,36 +155,37 @@ are added to the buffering message:
Application Application
~~~~~~~~~~~ ~~~~~~~~~~~
While data is buffered, the pipeline should remain in the PAUSED state. It is While data is buffered the pipeline should remain in the PAUSED state. It is
also possible that more data should be buffered while the pipeline is PLAYING, also possible that more data should be buffered while the pipeline is PLAYING,
in which case the pipeline should be PAUSED until the buffering finished. in which case the pipeline should be PAUSED until the buffering finishes.
BUFFERING messages can be posted while the pipeline is prerolling. The BUFFERING messages can be posted while the pipeline is prerolling. The
application should not set the pipeline to PLAYING before a BUFFERING message application should not set the pipeline to PLAYING before a BUFFERING message
with 100 percent value is received, which might only happen after the pipeline with a 100 percent value is received, which might only happen after the pipeline
prerolled. prerolls.
An exception is made for live pipelines. The application may not change An exception is made for live pipelines. The application may not change
the state of a live pipeline when a buffering message is received. Usually these the state of a live pipeline when a buffering message is received. Usually these
buffering messages contain the "buffering-mode" = "live". buffering messages contain the "buffering-mode" = "live".
The buffering message can also instruct the application to switch to a periodical The buffering message can also instruct the application to switch to a
BUFFERING query instead to more precisely control the buffering process. The periodical BUFFERING query instead, so it can more precisely control the
application can, for example, choose to not act on the BUFFERING message with buffering process. The application can, for example, choose not to act on the
100 percent fill level to resume playback but instead use the estimated download BUFFERING complete message (buffer-percent = 100) to resume playback but use
time to resume playback to get uninterrupted playback. the estimated download time instead, resuming playback when it has determined
that it should be able to provide uninterrupted playback.
Buffering Query Buffering Query
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
In addition to the BUFFERING messages posted by the buffering elements we want In addition to the BUFFERING messages posted by the buffering elements, we want
to be able to query the same information from the application. We also want to to be able to query the same information from the application. We also want to
be able to present the user with information about the downloaded range in the be able to present the user with information about the downloaded range in the
file so that the GUI can react on it. file so that the GUI can react on it.
In addition to all the fields present in the buffering message, the BUFFERING In addition to all the fields present in the buffering message, the BUFFERING
query contains the following field, which indicate the available downloaded query contains the following field, which indicates the available downloaded
range in a specific format and the estimated time to complete: range in a specific format and the estimated time to complete:
"busy", G_TYPE_BOOLEAN "busy", G_TYPE_BOOLEAN
@ -205,7 +205,7 @@ range in a specific format and the estimated time to complete:
- gives the estimated download time in milliseconds. -1 unknown. - gives the estimated download time in milliseconds. -1 unknown.
When the size of the downloaded file is known, this value will contain When the size of the downloaded file is known, this value will contain
the latest estimate of the remaining download time. This value is usualy the latest estimate of the remaining download time. This value is usually
only filled for the "download" buffering mode. The application can use only filled for the "download" buffering mode. The application can use
this information to estimate the amount of remaining time to download the this information to estimate the amount of remaining time to download the
complete file. complete file.