image2 demuxer documentation deficiencies

[Jim DeLaHunt]

Summary of the bug: The documentation of the image2 demuxer fails to mention two significant aspects of its operation. Also, the examples are missing an important class of usage.

How to reproduce: Using web browser, visit ​http://ffmpeg.org/ffmpeg-all.html#image2-1 . This is section "20 Demuxers", subsection "20.9 image2". The corresponding source code is in doc/demuxers.texi line 329.

Problem 1. The documentation does not mention image2 does not work with input in gif format.

It state this limitation clearly.

It should also help the user find workarounds. This could be text in the image2 section, or in the examples, or in an FAQ. Two workarounds are: 1. convert the input still images to some other format e.g. png, and 2. generate the animated GIF using the concat filter instead of image2.

% ls -lF blue_[0-9].gif
-rw-r--r--  1 myuser  staff  1303  6 Jan 21:04 blue_1.gif
-rw-r--r--  1 myuser  staff  1379  6 Jan 21:05 blue_2.gif

% ffmpeg -f image2 -i blue_%d.gif  -y animated_blue_12.gif
ffmpeg version 3.4.1 Copyright (c) 2000-2017 the FFmpeg developers
  built with Apple LLVM version 8.0.0 (clang-800.0.42.1)
  configuration: --prefix=/opt/local --enable-swscale --enable-avfilter --enable-avresample
--enable-libmp3lame --enable-libvorbis --enable-libopus --enable-librsvg --enable-libtheora
--enable-libopenjpeg --enable-libmodplug --enable-libvpx --enable-libsoxr --enable-libspeex
--enable-libass --enable-libbluray --enable-lzma --enable-gnutls --enable-fontconfig --enable-libfreetype
--enable-libfribidi --disable-indev=jack --enable-opencl --disable-outdev=xv --enable-audiotoolbox
--enable-videotoolbox --enable-sdl2 --mandir=/opt/local/share/man --enable-shared --enable-pthreads
--cc=/usr/bin/clang --arch=x86_64 --enable-x86asm --enable-libx265 --enable-gpl --enable-postproc
--enable-libx264 --enable-libxvid
  libavutil      55. 78.100 / 55. 78.100
  libavcodec     57.107.100 / 57.107.100
  libavformat    57. 83.100 / 57. 83.100
  libavdevice    57. 10.100 / 57. 10.100
  libavfilter     6.107.100 /  6.107.100
  libavresample   3.  7.  0 /  3.  7.  0
  libswscale      4.  8.100 /  4.  8.100
  libswresample   2.  9.100 /  2.  9.100
  libpostproc    54.  7.100 / 54.  7.100
[image2 @ 0x7ff99080ba00] Could not find codec parameters for stream 0 (Video: none, none): unknown codec
Consider increasing the value for the 'analyzeduration' and 'probesize' options
Input #0, image2, from 'blue_%d.gif':
  Duration: 00:00:00.08, start: 0.000000, bitrate: N/A
    Stream #0:0: Video: none, none, 25 tbr, 25 tbn, 25 tbc
Stream mapping:
  Stream #0:0 -> #0:0 (? (?) -> gif (native))
Decoder (codec none) not found for input stream #0:0

Here's the same error, when the destination is a different video format than animated gif. This makes me believe that the problem is the input format, not output format.

% ffmpeg -f image2 -i blue_%d.gif animated_blue_12.mp4
ffmpeg version 3.4.1 Copyright (c) 2000-2017 the FFmpeg developers
  built with Apple LLVM version 8.0.0 (clang-800.0.42.1)
  configuration: --prefix=/opt/local --enable-swscale --enable-avfilter --enable-avresample --enable-libmp3lame --enable-libvorbis --enable-libopus --enable-librsvg --enable-libtheora --enable-libopenjpeg --enable-libmodplug --enable-libvpx --enable-libsoxr --enable-libspeex --enable-libass --enable-libbluray --enable-lzma --enable-gnutls --enable-fontconfig --enable-libfreetype --enable-libfribidi --disable-indev=jack --enable-opencl --disable-outdev=xv --enable-audiotoolbox --enable-videotoolbox --enable-sdl2 --mandir=/opt/local/share/man --enable-shared --enable-pthreads --cc=/usr/bin/clang --arch=x86_64 --enable-x86asm --enable-libx265 --enable-gpl --enable-postproc --enable-libx264 --enable-libxvid
  libavutil      55. 78.100 / 55. 78.100
  libavcodec     57.107.100 / 57.107.100
  libavformat    57. 83.100 / 57. 83.100
  libavdevice    57. 10.100 / 57. 10.100
  libavfilter     6.107.100 /  6.107.100
  libavresample   3.  7.  0 /  3.  7.  0
  libswscale      4.  8.100 /  4.  8.100
  libswresample   2.  9.100 /  2.  9.100
  libpostproc    54.  7.100 / 54.  7.100
[image2 @ 0x7f9ba4808000] Could not find codec parameters for stream 0 (Video: none, none): unknown codec
Consider increasing the value for the 'analyzeduration' and 'probesize' options
Input #0, image2, from 'blue_%d.gif':
  Duration: 00:00:00.08, start: 0.000000, bitrate: N/A
    Stream #0:0: Video: none, none, 25 tbr, 25 tbn, 25 tbc
Stream mapping:
  Stream #0:0 -> #0:0 (? (?) -> h264 (libx264))
Decoder (codec none) not found for input stream #0:0

Here's the same operation, accomplished with inputs of format png instead of gif:

% ffmpeg -f image2 -i blue_%d.png animated_blue_12_from_png.gif
ffmpeg version 3.4.1 Copyright (c) 2000-2017 the FFmpeg developers
  built with Apple LLVM version 8.0.0 (clang-800.0.42.1)
  configuration: --prefix=/opt/local --enable-swscale --enable-avfilter --enable-avresample --enable-libmp3lame --enable-libvorbis --enable-libopus --enable-librsvg --enable-libtheora --enable-libopenjpeg --enable-libmodplug --enable-libvpx --enable-libsoxr --enable-libspeex --enable-libass --enable-libbluray --enable-lzma --enable-gnutls --enable-fontconfig --enable-libfreetype --enable-libfribidi --disable-indev=jack --enable-opencl --disable-outdev=xv --enable-audiotoolbox --enable-videotoolbox --enable-sdl2 --mandir=/opt/local/share/man --enable-shared --enable-pthreads --cc=/usr/bin/clang --arch=x86_64 --enable-x86asm --enable-libx265 --enable-gpl --enable-postproc --enable-libx264 --enable-libxvid
  libavutil      55. 78.100 / 55. 78.100
  libavcodec     57.107.100 / 57.107.100
  libavformat    57. 83.100 / 57. 83.100
  libavdevice    57. 10.100 / 57. 10.100
  libavfilter     6.107.100 /  6.107.100
  libavresample   3.  7.  0 /  3.  7.  0
  libswscale      4.  8.100 /  4.  8.100
  libswresample   2.  9.100 /  2.  9.100
  libpostproc    54.  7.100 / 54.  7.100
Input #0, image2, from 'blue_%d.png':
  Duration: 00:00:00.08, start: 0.000000, bitrate: N/A
    Stream #0:0: Video: png, pal8(pc), 212x318, 25 tbr, 25 tbn, 25 tbc
Stream mapping:
  Stream #0:0 -> #0:0 (png (native) -> gif (native))
Press [q] to stop, [?] for help
Output #0, gif, to 'animated_blue_12_from_png.gif':
  Metadata:
    encoder         : Lavf57.83.100
    Stream #0:0: Video: gif, pal8, 212x318, q=2-31, 200 kb/s, 25 fps, 100 tbn, 25 tbc
    Metadata:
      encoder         : Lavc57.107.100 gif
frame=    2 fps=0.0 q=-0.0 Lsize=       3kB time=00:00:00.05 bitrate= 423.8kbits/s speed=9.25x    
video:2kB audio:0kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 44.596069%

Here's the same operation, accomplished with the concat filter:

% ffmpeg -i blue_1.gif -i blue_2.gif -filter_complex "[0:v][1:v] concat=n=2:v=1:a=0" -y animated_blue_12.gif 
ffmpeg version 3.4.1 Copyright (c) 2000-2017 the FFmpeg developers
  built with Apple LLVM version 8.0.0 (clang-800.0.42.1)
  configuration: --prefix=/opt/local --enable-swscale --enable-avfilter --enable-avresample --enable-libmp3lame --enable-libvorbis --enable-libopus --enable-librsvg --enable-libtheora --enable-libopenjpeg --enable-libmodplug --enable-libvpx --enable-libsoxr --enable-libspeex --enable-libass --enable-libbluray --enable-lzma --enable-gnutls --enable-fontconfig --enable-libfreetype --enable-libfribidi --disable-indev=jack --enable-opencl --disable-outdev=xv --enable-audiotoolbox --enable-videotoolbox --enable-sdl2 --mandir=/opt/local/share/man --enable-shared --enable-pthreads --cc=/usr/bin/clang --arch=x86_64 --enable-x86asm --enable-libx265 --enable-gpl --enable-postproc --enable-libx264 --enable-libxvid
  libavutil      55. 78.100 / 55. 78.100
  libavcodec     57.107.100 / 57.107.100
  libavformat    57. 83.100 / 57. 83.100
  libavdevice    57. 10.100 / 57. 10.100
  libavfilter     6.107.100 /  6.107.100
  libavresample   3.  7.  0 /  3.  7.  0
  libswscale      4.  8.100 /  4.  8.100
  libswresample   2.  9.100 /  2.  9.100
  libpostproc    54.  7.100 / 54.  7.100
Input #0, gif, from 'blue_1.gif':
  Duration: N/A, bitrate: N/A
    Stream #0:0: Video: gif, bgra, 212x318, 10 tbr, 100 tbn, 100 tbc
Input #1, gif, from 'blue_2.gif':
  Duration: N/A, bitrate: N/A
    Stream #1:0: Video: gif, bgra, 212x318, 10 tbr, 100 tbn, 100 tbc
Stream mapping:
  Stream #0:0 (gif) -> concat:in0:v0
  Stream #1:0 (gif) -> concat:in1:v0
  concat -> Stream #0:0 (gif)
Press [q] to stop, [?] for help
Output #0, gif, to 'animated_blue_12.gif':
  Metadata:
    encoder         : Lavf57.83.100
    Stream #0:0: Video: gif, bgr8, 212x318, q=2-31, 200 kb/s, 10 fps, 100 tbn, 10 tbc (default)
    Metadata:
      encoder         : Lavc57.107.100 gif
frame=    2 fps=0.0 q=-0.0 Lsize=       1kB time=00:00:00.11 bitrate= 102.7kbits/s speed=24.9x    
video:1kB audio:0kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 137.310928%

Problem 2. Documentation doesn't mention that input file pattern of %d usually implies -f image2.

The examples, in section "20.9.1 Examples" at ​http://ffmpeg.org/ffmpeg-all.html#Examples-6, have three variations on:

ffmpeg -framerate 10 -i 'img-%03d.jpeg' out.mkv

Note that the invocation does not include -f image2. Apparently, use of a pattern in the input file name implies the image2 demuxer to ffmpeg. (See ffmpeg-user post ​http://ffmpeg.org/pipermail/ffmpeg-user/2018-January/038454.html .)

The documentation for image2 should mention that patterns imply image2 format, so the -f image2 option is optional in some cases. It would be good to read the corresponding code and be clear about just how optional the -f image2 notation is.

Also, the examples which omit the -f image2 notation should point out that they do so, and explain why it still works. The reader should not have to scratch their head and try the example to understand why it works. Instead, the documentation should document it.

Problem 3. Examples are missing an important class of usage.

Presently there are 3 examples. All omit the -f image2 notation. There should be some examples that include this notation. Preferably, these new examples should do something different than the existing examples, and show a case where the -f image2 notation is required, and cannot be inferred.

[Carl Eugen Hoyos]

The ticket is invalid since it claims to report more than one issue.
I will try to explain shortly why the issues cannot be fixed, feel free to continue the discussion on the user mailing list.

Replying to jdlh:

Problem 1. The documentation does not mention image2 does not work with input in gif format.

It also doesn't mention that the image2 demuxer does not support apng files.

Problem 2. Documentation doesn't mention that input file pattern of %d usually implies -f image2.

No other demuxer support %d but %d does not imply image2, file suffixes do. It is not part of the API which file suffixes imply the image2 demuxer, we try to update the list whenever we become aware of new use-cases (but we have removed file suffixes from the list in the past, for example gif).

Problem 3. Examples are missing an important class of usage.

Presently there are 3 examples. All omit the -f image2 notation.

But you did not provide a use-case where -f image2 was needed: Such use cases of course exist but it will be difficult (or actually impossible) to add examples for every possible use-case.

[Jim DeLaHunt]

This response shows one of the reasons why the ffmpeg project has poor documentation. This ticket points out deficiencies in the documentation. The developer's response does not refute the deficiencies. It does not improve the actual documentation. Yet the developer closes the ticket. Thus the project will lose visibility that this part of the documentation is deficient.

To respond to cehoyos' comments one by one:

"The ticket is invalid since it claims to report more than one issue." The deficiency is with one contiguous part of the documentation, in doc/demuxers.txi, lines 329:462. The deficiency has multiple aspects. The efficient way to fix it is to improve that section of documentation, addressing all the aspects at once. Thus I think a single ticket is appropriate.

However, if it's really important to have one ticket for each aspect, I can break this ticket into multiple tickets. I have low confidence that those tickets will be respected any better.

Problem 1: "It also doesn't mention that the image2 demuxer does not support apng files." All this does is say there is a further deficiency. It does not refute the claim that the lack of mention of GIF is a deficiency. A ticket should stay open to track the deficiency, namely the variance in image2 behaviour by formats and file extensions.

Problem 2: "No other demuxer support %d but %d does not imply image2, file suffixes do. It is not part of the API which file suffixes imply the image2 demuxer, we try to update the list whenever we become aware of new use-cases (but we have removed file suffixes from the list in the past, for example gif)." This does not refute the claim that the documentation is deficient. It just suggests a better explanation for the documentation to include. A ticket should stay open to track the deficiency, namely when and how the nature of the input makes explicitly specifying -f image2 optional.

Problem 3: "But you did not provide a use-case where -f image2 was needed…" This does not refute the claim that the examples are missing an important class of usage. At the very least, one of the existing examples should have -f image2 added, and there should be text added to the examples without -f image2 pointing out that it is options for those examples.

"it will be difficult (or actually impossible) to add examples for every possible use-case." This ticket does not call for "every possible use-case", just for doing better than the examples do now. Don't exaggerate.