[FFmpeg-devel] [PATCH] avformat: add some documentation about seeking

[wm4]

On Tue, 13 May 2014 18:20:26 -0700
Aman Gupta <ffmpeg at tmm1.net> wrote:

> Signed-off-by: Aman Gupta <ffmpeg at tmm1.net>
> ---
>  libavformat/avformat.h | 21 +++++++++++++++++++++
>  1 file changed, 21 insertions(+)
> 
> diff --git a/libavformat/avformat.h b/libavformat/avformat.h
> index 7d2db6a..f4b6ba0 100644
> --- a/libavformat/avformat.h
> +++ b/libavformat/avformat.h
> @@ -169,6 +169,27 @@
>   * longer needed.
>   *
>   * @section lavf_decoding_seek Seeking
> + * @{
> + * Instead of reading each frame successively with av_read_frame(), you may seek
> + * around the stream with av_seek_frame() and read frames at specific locations.
> + * By default, seeking will jump forward to the closest keyframe near the given
> + * timestamp in the given stream. Use AVSEEK_FLAG_ANY to seek to non-keyframes,
> + * or AVSEEK_FLAG_BACKWARD to jump backwards in the stream.

It should say something like: if AVSEEK_FLAG_BACKWARD is set, and the
target time is not a key frame, the demuxer will seek to the keyframe
_before_ the target time. If unset, it will seek to a keyframe _after_
the target time.

> + * Here's a simple example that quickly processes all keyframes by seeking over
> + * intermediate frames:
> + * @code
> + * while (av_read_frame(ic, &pkt) == 0) {
> + *     if (pkt.flags & AV_PKT_FLAG_KEY)
> + *         process(pkt);
> + *
> + *     // seek forward to the next keyframe in this stream
> + *     av_seek_frame(ic, pkt.stream_index, pkt.dts, 0);
> + * }
> + * @endcode

That seems to be a strange example. Is AV_PKT_FLAG_KEY even correctly
set in all situations? (AFAIK it's not.)

> + *
> + * If you're decoding incoming packets with avcodec_decode_*, make sure to flush
> + * your decoder's buffers after each seek with avcodec_flush_buffers().
>   * @}
>   *
>   * @defgroup lavf_encoding Muxing