From e0e4bf4bdb01a8da8ae4f47f67c5bd56826efb82 Mon Sep 17 00:00:00 2001 From: "Reynaldo H. Verdejo Pinochet" Date: Sat, 24 Dec 2016 00:15:21 -0800 Subject: [PATCH] design: live-source: improve grammar and add missing markup --- markdown/design/live-source.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/markdown/design/live-source.md b/markdown/design/live-source.md index dc12d1de1e..dbb7373cce 100644 --- a/markdown/design/live-source.md +++ b/markdown/design/live-source.md @@ -3,13 +3,13 @@ A live source is a source that cannot be arbitrarily `PAUSED` without losing data. -A live source such as an element capturing audio or video need to be +A live source such as an element capturing audio or video, needs to be handled in a special way. It does not make sense to start the dataflow in the `PAUSED` state for those devices as the user might wait a long time -between going from `PAUSED` to PLAYING, making the previously captured +between going from `PAUSED` to `PLAYING`, making the previously captured buffers irrelevant. -A live source therefore only produces buffers in the PLAYING state. This +A live source therefore only produces buffers in the `PLAYING` state. This has implications for sinks waiting for a buffer to complete the preroll state since such a buffer might never arrive. @@ -18,36 +18,36 @@ the bin/pipeline that this element will not be able to produce data in the `PAUSED` state. `NO_PREROLL` should be returned for both READY→PAUSED and PLAYING→PAUSED. -When performing a get\_state() on a bin with a non-zero timeout value, +When performing a `get_state()` on a bin with a non-zero timeout value, the bin must be sure that there are no live sources in the pipeline -because else the get\_state() function would block on the sinks. +because otherwise, the `get_state()` function would block on the sinks. -A gstbin therefore always performs a zero timeout get\_state() on its +A gstbin therefore always performs a zero timeout `get_state()` on its elements to discover the `NO_PREROLL` (and ERROR) elements before performing a blocking wait. ## Scheduling -Live sources will not produce data in the paused state. They block in -the getrange function or in the loop function until they go to PLAYING. +Live sources will not produce data in the `PAUSED` state. They block in +the `get_range()` function or in the loop function until they go to PLAYING. ## Latency -The live source timestamps its data with the time of the clock at the -time the data was captured. Normally it will take some time to capture -the first sample of data and the last sample. This means that when the +The live source timestamps its data with the time of the clock when +the data was captured. Normally, it will take some time to capture +the first sample of data and the last one. This means that when the buffer arrives at the sink, it will already be late and will be dropped. -The latency is the time it takes to construct one buffer of data. This -latency is exposed with a `LATENCY` query. +The latency is the time it takes to construct one buffer of data and it's +exposed with a `LATENCY` query. See [latency](design/latency.md) ## Timestamps -Live sources always timestamp their buffers with the running\_time of +Live sources always timestamp their buffers with the `running_time` of the pipeline. This is needed to be able to match the timestamps of different live sources in order to synchronize them. This is in contrast to non-live sources, which timestamp their buffers -starting from running\_time 0. +starting from `running_time` 0.