[FFmpeg-devel] [PATCH] doc: extend -ss documentation.

[Lou Logan]

On Thu, 15 Nov 2012 13:50:21 +0100, Nicolas George wrote:

> Specify seeking inaccuracy and direction, timestamps adjustment, and
> multiple -ss interaction in the reference documentation.
> Re-explain it with different words in the FAQ.
> 
> Signed-off-by: Nicolas George <nicolas.george at normalesup.org>
> ---
>  doc/faq.texi    |   29 +++++++++++++++++++++++++++++
>  doc/ffmpeg.texi |   14 +++++++++++++-
>  2 files changed, 42 insertions(+), 1 deletion(-)

Good idea. I have only one comment below.

> diff --git a/doc/faq.texi b/doc/faq.texi
> index a7b34b1..f4613e3 100644
> --- a/doc/faq.texi
> +++ b/doc/faq.texi
> @@ -410,6 +410,35 @@ point acceptable for your tastes. The most common options to do that are
>  @option{-qscale} and @option{-qmax}, but you should peruse the documentation
>  of the encoder you chose.
>  
> + at section Should @option{-ss} go before or after @option{-i}?
> +
> +Most options to @command{ffmpeg} apply to the next input or output file. If
> +you put @option{-ss} before @option{-i}, it applies to the input file; if
> +you put it after, it applies to the output file that probably comes later on
> +the command line, unless there is a second @option{-i}.
> +
> +If applied to the input, the @option{-ss} option performs a seek. This is
> +usually very fast, but not very accurate because it is only possible to seek
> +to a keyframe. Also, with some formats or protocols, it may be very
> +inaccurate or just not work at all.
> +
> +If applied to the output, the @option{-ss} option causes @command{ffmpeg} to
> +skip the frames until the requested time. This is rather slow, because all
> +previous frames need to be decoded, but this is completely accurate.
> +
> +Both options can be combined. In that case, the time for the output
> + at option{-ss} is relative to the exact time requested on the input
> + at option{-ss}. If you are working with a format and protocol that support
> +seeking correctly, it can be used to do fast and accurate seeking:
> +
> + at example
> +ffmpeg -ss 0:01:00 -i input.mkv -ss 0 output
> + at end example
> +
> +will seek to a point slightly before 1 minute and start decoding with
> +negative timestamps; the frames are then skipped until the timestamps reach
> +0, at exactly one minute.
> +
>  @chapter Development
>  
>  @section Are there examples illustrating how to use the FFmpeg libraries, particularly libavcodec and libavformat?
> diff --git a/doc/ffmpeg.texi b/doc/ffmpeg.texi
> index d39ad22..cbd7e67 100644
> --- a/doc/ffmpeg.texi
> +++ b/doc/ffmpeg.texi
> @@ -266,11 +266,23 @@ Stop writing the output after its duration reaches @var{duration}.
>  Set the file size limit, expressed in bytes.
>  
>  @item -ss @var{position} (@emph{input/output})
> +
>  When used as an input option (before @code{-i}), seeks in this input file to
> - at var{position}. When used as an output option (before an output filename),
> + at var{position}. This is fast but possibly inaccurate because it can only
> +seek to key-frames. Also, not all protocols/formats support accurate
> +seeking, or seeking at all. If seeking to exact time is not possible, it
> +will try to a keyframe before the requested position. By default, the

"will try to a keyframe". Seems to be missing a verb.