[FFmpeg-trac] #6950(documentation:new): image2 demuxer documentation deficiencies

FFmpeg trac at avcodec.org
Sun Jan 7 22:34:47 EET 2018


#6950: image2 demuxer documentation deficiencies
-------------------------------------+-------------------------------------
             Reporter:  jdlh         |                     Type:  defect
               Status:  new          |                 Priority:  normal
            Component:               |                  Version:
  documentation                      |  unspecified
             Keywords:               |               Blocked By:
             Blocking:               |  Reproduced by developer:  0
Analyzed by developer:  0            |
-------------------------------------+-------------------------------------
 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.

--
Ticket URL: <https://trac.ffmpeg.org/ticket/6950>
FFmpeg <https://ffmpeg.org>
FFmpeg issue tracker


More information about the FFmpeg-trac mailing list