mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2025-01-19 05:45:58 +00:00
Code Issues 1 Projects Releases Wiki Activity

design/buffering: improve formatting and fix other minor issues

Browse source 
- Promote use-cases to their own section. Add markup as needed
- Add missing markup to figures, code blocks and other keywords
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2016-12-20 21:22:59 -08:00
parent 849985ba7e
commit 2fda0e1314
1 changed files with 41 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
markdown/design/buffering.md
View file

@ -25,14 +25,16 @@ timeshifting.
- the possibility for the application to do more complex buffering - the possibility for the application to do more complex buffering
Some use cases: ## Some use cases
- Stream buffering: ### Stream buffering
```
+---------+ +---------+ +-------+ +---------+ +---------+ +-------+
| httpsrc | | buffer | | demux | | httpsrc | | buffer | | demux |
| src - sink src - sink .... | src - sink src - sink ....
+---------+ +---------+ +-------+ +---------+ +---------+ +-------+
```
In this case we are reading from a slow network source into a buffer element In this case we are reading from a slow network source into a buffer element
(such as queue2). (such as queue2).
@ -63,15 +65,16 @@ Seeking in the stream requires the seek to happen in the network source.
It is mostly desirable when the total duration of the file is not known, such It is mostly desirable when the total duration of the file is not known, such
as in live streaming or when efficient seeking is not possible/required. as in live streaming or when efficient seeking is not possible/required.
- Incremental download ### Incremental download
```
+---------+ +---------+ +-------+ +---------+ +---------+ +-------+
| httpsrc | | buffer | | demux | | httpsrc | | buffer | | demux |
| src - sink src - sink .... | src - sink src - sink ....
+---------+ +----|----+ +-------+ +---------+ +----|----+ +-------+
V V
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 to 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
@ -90,14 +93,16 @@ The application can use the `BUFFERING` query to get the estimated download time
and match this time to the current/remaining playback time to control when and match this time to the current/remaining playback time to control when
playback should start to have a non-interrupted playback experience. playback should start to have a non-interrupted playback experience.
- Timeshifting ### Timeshifting
```
+---------+ +---------+ +-------+ +---------+ +---------+ +-------+
| httpsrc | | buffer | | demux | | httpsrc | | buffer | | demux |
| src - sink src - sink .... | src - sink src - sink ....
+---------+ +----|----+ +-------+ +---------+ +----|----+ +-------+
V V
file-ringbuffer file-ringbuffer
```
In this mode, a fixed size ringbuffer is kept to download the server content. In this mode, a fixed size ringbuffer is kept to download the server content.
This allows for seeking in the buffered data. Depending on the size of the This allows for seeking in the buffered data. Depending on the size of the
@ -108,7 +113,7 @@ This mode is suitable for all live streams.
As with the incremental download mode, buffering messages are emitted 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.
- Live buffering ### Live buffering
In live pipelines we usually introduce some latency between the capture and In live pipelines we usually introduce some latency between the capture and
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
@ -129,7 +134,7 @@ The `BUFFERING` message should be intercepted and acted upon by the
application. The message contains at least one field that is sufficient application. The message contains at least one field that is sufficient
for basic functionality: for basic functionality:
* **`buffer-percent`**, G_TYPE_INT: between 0 and 100 * **`buffer-percent`**, `G_TYPE_INT`: between 0 and 100
Several more clever ways of dealing with the buffering messages can be Several more clever ways of dealing with the buffering messages can be
used when in incremental or timeshifting download mode. For this purpose used when in incremental or timeshifting download mode. For this purpose
@ -140,16 +145,16 @@ additional fields are added to the buffering message:
alternatives. This field can be used to let the application have more control alternatives. This field can be used to let the application have more control
over the buffering process. over the buffering process.
* **`avg-in-rate`**, G_TYPE_INT: Average input buffering speed in bytes/second. * **`avg-in-rate`**, `G_TYPE_INT`: Average input buffering speed in bytes/second.
-1 is unknown. This is the average number of bytes per second that is received -1 is unknown. 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 on the 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: Average consumption speed in bytes/second. -1 * **`avg-out-rate`**, `G_TYPE_INT`: Average consumption speed in bytes/second. -1
is unknown. This is the average number of bytes per second that is consumed by is unknown. This is the average number of bytes per second that is consumed by
the downstream element of the buffering element. the downstream element of the buffering element.
* **`buffering-left`**, G_TYPE_INT64: Estimated time that buffering will take * **`buffering-left`**, `G_TYPE_INT64`: Estimated time that buffering will take
in milliseconds. -1 is unknown. This is measured based on the avg-in-rate and in milliseconds. -1 is unknown. 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 the filled level of the queue. The application can use this hint to update the
GUI about the estimated remaining time that buffering will take. GUI about the estimated remaining time that buffering will take.
@ -190,36 +195,38 @@ In addition to all the fields present in the buffering message, the
available downloaded range in a specific format and the estimated time available downloaded range in a specific format and the estimated time
to complete: to complete:
* **`busy`**, G_TYPE_BOOLEAN: if buffering was busy. This flag allows the * **`busy`**, `G_TYPE_BOOLEAN`: if buffering was busy. This flag allows the
application to pause the pipeline by using the query only. application to pause the pipeline by using the query only.
* **`format`**, GST_TYPE_FORMAT: the format of the "start" and "stop" values * **`format`**, `GST_TYPE_FORMAT`: the format of the "start" and "stop" values
below below
* **`start`**, G_TYPE_INT64, -1 unknown: the start position of the available * **`start`**, `G_TYPE_INT64`, -1 unknown: the start position of the available
data. If there are multiple ranges, this field contains the start position of data. If there are multiple ranges, this field contains the start position of
the currently downloading range. the currently downloading range.
* **`stop`**, G_TYPE_INT64, -1 unknown: the stop position of the available * **`stop`**, `G_TYPE_INT64`, -1 unknown: the stop position of the available
data. If there are multiple ranges, this field contains the stop position of data. If there are multiple ranges, this field contains the stop position of
the currently downloading range. the currently downloading range.
* **`estimated-total`**, G_TYPE_INT64: gives the estimated download time in * **`estimated-total`**, `G_TYPE_INT64`: gives the estimated download time in
milliseconds. -1 unknown. When the size of the downloaded file is known, this milliseconds. -1 unknown. When the size of the downloaded file is known, this
value will contain the latest estimate of the remaining download time of the value will contain the latest estimate of the remaining download time of the
currently downloading range. This value is usually only filled for the currently downloading range. This value is usually only filled for the
"download" buffering mode. The application can use this information to estimate "download" buffering mode. The application can use this information to estimate
the amount of remaining time to download till the end of the file. the amount of remaining time to download till the end of the file.
* **`buffering-ranges`**, G_TYPE_ARRAY of GstQueryBufferingRange: contains * **`buffering-ranges`**, `G_TYPE_ARRAY` of `GstQueryBufferingRange`: contains
optionally the downloaded areas in the format given above. One of the ranges optionally the downloaded areas in the format given above. One of the ranges
contains the same start/stop position as above: contains the same start/stop position as above:
```
typedef struct typedef struct
{ {
gint64 start; gint64 start;
gint64 stop; gint64 stop;
} GstQueryBufferingRange; } GstQueryBufferingRange;
```
For the `download` and `timeshift` buffering-modes, the start and stop For the `download` and `timeshift` buffering-modes, the start and stop
positions specify the ranges where efficient seeking in the downloaded positions specify the ranges where efficient seeking in the downloaded
@ -233,7 +240,7 @@ oldest and newest item (expressed in `format`) in the buffer.
Some defaults for common elements: Some defaults for common elements:
A GstBaseSrc with random access replies to the `BUFFERING` query with: A `GstBaseSrc` with random access replies to the `BUFFERING` query with:
"buffer-percent" = 100 "buffer-percent" = 100
"buffering-mode" = "stream" "buffering-mode" = "stream"
@ -246,7 +253,7 @@ A GstBaseSrc with random access replies to the `BUFFERING` query with:
"estimated-total" = 0 "estimated-total" = 0
"buffering-ranges" = NULL "buffering-ranges" = NULL
A GstBaseSrc in push mode replies to the `BUFFERING` query with: A `GstBaseSrc` in push mode replies to the `BUFFERING` query with:
"buffer-percent" = 100 "buffer-percent" = 100
"buffering-mode" = "stream" "buffering-mode" = "stream"