-r output option misguiding documentation

[Ilya Basin]

Summary of the bug:

doc/ffmpeg.texi:As an output option, duplicate or drop input frames to achieve constant output

In fact, that sounds more like the description of the fps filter. What '-r' option actually does, is set the declared fps of a video stream without actually duplicating frames (it may drop frames though).

The following example produces a 2-second 4fps video and uses '-r 120'. The demuxer says: '120 fps', but prints only 8 frames with proper PTS.

$ ffmpeg -y -f lavfi -i testsrc=s=720x576:r=4:d=2 -r 120 -pix_fmt yuv422p -vcodec rawvideo -f matroska - 2>/dev/null | ffmpeg -f matroska -i - -vf "showinfo" -f null x
ffmpeg version N-72058-g3ecc063 Copyright (c) 2000-2015 the FFmpeg developers
  built with gcc 4.9.2 (GCC)
  configuration: --disable-static --enable-shared --enable-gpl --enable-version3 --disable-w32threads --enable-avisynth --enable-bzlib --enable-fontconfig --enable-frei0r --enable-gnutls --enable-iconv --enable-libass --enable-libbluray --enable-libbs2b --enable-libcaca --enable-libdcadec --enable-libfreetype --enable-libgme --enable-libgsm --enable-libilbc --enable-libmodplug --enable-libmp3lame --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libopenjpeg --enable-libopus --enable-librtmp --enable-libschroedinger --enable-libsoxr --enable-libspeex --enable-libtheora --enable-libtwolame --enable-libvidstab --enable-libvo-aacenc --enable-libvo-amrwbenc --enable-libvorbis --enable-libvpx --enable-libwavpack --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxavs --enable-libxvid --enable-lzma --enable-decklink --enable-zlib
  libavutil      54. 23.101 / 54. 23.101
  libavcodec     56. 38.100 / 56. 38.100
  libavformat    56. 33.100 / 56. 33.100
  libavdevice    56.  4.100 / 56.  4.100
  libavfilter     5. 16.101 /  5. 16.101
  libswscale      3.  1.101 /  3.  1.101
  libswresample   1.  1.100 /  1.  1.100
  libpostproc    53.  3.100 / 53.  3.100
Input #0, matroska,webm, from 'pipe:':
  Metadata:
    ENCODER         : Lavf56.33.100
  Duration: N/A, start: 0.000000, bitrate: N/A
    Stream #0:0: Video: rawvideo (Y42B / 0x42323459), yuv422p, 720x576, SAR 1:1 DAR 5:4, 120 fps, 120 tbr, 1k tbn, 1k tbc (default)
    Metadata:
      ENCODER         : Lavc56.38.100 rawvideo
[Parsed_showinfo_0 @ 0000000002a03f20] config in time_base: 1/1000, frame_rate: 120/1
[Parsed_showinfo_0 @ 0000000002a03f20] config out time_base: 0/0, frame_rate: 0/0
Output #0, null, to 'x':
  Metadata:
    encoder         : Lavf56.33.100
    Stream #0:0: Video: rawvideo (Y42B / 0x42323459), yuv422p, 720x576 [SAR 1:1 DAR 5:4], q=2-31, 200 kb/s, 120 fps, 120 tbn, 120 tbc (default)
    Metadata:
      encoder         : Lavc56.38.100 rawvideo
Stream mapping:
  Stream #0:0 -> #0:0 (rawvideo (native) -> rawvideo (native))
[Parsed_showinfo_0 @ 0000000002a03f20] n:   0 pts:      0 pts_time:0       pos:      618 fmt:yuv422p sar:1/1 s:720x576 i:P iskey:1 type:I checksum:8B0AA2CB plane_checksum:[87271B24 F6292B83 9D3A5C24] mean:[126 129 126] stdev:[71.4 70.2 72.6]
[null @ 0000000002a02be0] Encoder did not produce proper pts, making some up.
[Parsed_showinfo_0 @ 0000000002a03f20] n:   1 pts:    250 pts_time:0.25    pos:   830081 fmt:yuv422p sar:1/1 s:720x576 i:P iskey:1 type:I checksum:5C15AB10 plane_checksum:[C538A9E0 3585795C 479987C5] mean:[126 129 126] stdev:[71.4 70.2 72.7]
[Parsed_showinfo_0 @ 0000000002a03f20] n:   2 pts:    500 pts_time:0.5     pos:  1659545 fmt:yuv422p sar:1/1 s:720x576 i:P iskey:1 type:I checksum:B10C5D37 plane_checksum:[9A6BC88B 93E6BB84 18B8D90A] mean:[126 129 126] stdev:[71.4 70.1 72.8]
[Parsed_showinfo_0 @ 0000000002a03f20] n:   3 pts:    750 pts_time:0.75    pos:  2489009 fmt:yuv422p sar:1/1 s:720x576 i:P iskey:1 type:I checksum:8D290D16 plane_checksum:[F3FAE338 28B7FC3F AEDA2D81] mean:[125 129 126] stdev:[71.4 70.0 72.9]
[Parsed_showinfo_0 @ 0000000002a03f20] n:   4 pts:   1000 pts_time:1       pos:  3318473 fmt:yuv422p sar:1/1 s:720x576 i:P iskey:1 type:I checksum:11BC56BD plane_checksum:[B4839897 9F273F08 9A537F0F] mean:[124 129 126] stdev:[71.3 69.9 72.9]
[Parsed_showinfo_0 @ 0000000002a03f20] n:   5 pts:   1250 pts_time:1.25    pos:  4147937 fmt:yuv422p sar:1/1 s:720x576 i:P iskey:1 type:I checksum:1A09A329 plane_checksum:[ADA1817E F1454629 5FF1DB73] mean:[124 129 126] stdev:[71.2 69.9 73.0]
[Parsed_showinfo_0 @ 0000000002a03f20] n:   6 pts:   1500 pts_time:1.5     pos:  4977401 fmt:yuv422p sar:1/1 s:720x576 i:P iskey:1 type:I checksum:F5CF596F plane_checksum:[27E9F6FA 831823A8 7D483EBE] mean:[124 129 126] stdev:[71.3 70.0 73.0]
[Parsed_showinfo_0 @ 0000000002a03f20] n:   7 pts:   1750 pts_time:1.75    pos:  5806865 fmt:yuv422p sar:1/1 s:720x576 i:P iskey:1 type:I checksum:22CD0DB6 plane_checksum:[816D6A3D 14230294 6028A0D6] mean:[125 129 127] stdev:[71.4 70.0 72.9]
frame=    8 fps=0.0 q=0.0 Lsize=N/A time=00:00:01.75 bitrate=N/A
video:1kB audio:0kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: unknown

Please fix the doc.

[Carl Eugen Hoyos]

The relevant output would be the one of ffmpeg -i output.mkv, FFmpeg's matroska muxer supports variable frame rate, so it is not necessary to actually write the duplicated frames to the output file. Please compare with a muxer that does not support vfr like mov or use -vsync cfr to force the actual frame duplication.

[Ilya Basin]

Replying to cehoyos:

The relevant output would be the one of ffmpeg -i output.mkv, FFmpeg's matroska muxer supports variable frame rate, so it is not necessary to actually write the duplicated frames to the output file. Please compare with a muxer that does not support vfr like mov or use -vsync cfr to force the actual frame duplication.

Then how about we write something like this:

As an output option, set the declared video stream fps. Together with the chosen '-vsync' method this affects duplicating or dropping frames.

Let them go and read the description of -vsync instead of duplicating it here.

P.S.
Tested with mov: by default it really duplicates frames, but I did the opposite to your advice and applied -vsync vfr, which produced a vfr mov. So it does support vfr!

Found a cfr-only container: yuv4mpegpipe.

[Carl Eugen Hoyos]

Replying to basinilya:

Tested with mov: by default it really duplicates frames, but I did the opposite to your advice and applied -vsync vfr, which produced a vfr mov. So it does support vfr!

No, it produces an invalid output file because you requested it.