[FFmpeg-user] Unclear Instructions for Sending Commands to Filtergraphs

[Santanu Biswas]

The feature to send commands to filters in filtergraphs is barely even
documented.
https://ffmpeg.org/ffmpeg-filters.html#Changing-options-at-runtime-with-a-command

But, what commands a filter supports is (almost) well documented.

At runtime too, it does a poor job at providing quick reference.
https://github.com/FFmpeg/FFmpeg/blob/master/fftools/ffmpeg.c#L3537

        fprintf(stderr, "\nEnter command: <target>|all <time>|-1
<command>[ <argument>]\n");

baffled me a lot in the command-line, even though I'm using FFmpeg for
five years. How are people even supposed to infer all this mess? The
syntax is ambigious. And, looking source code I figured out,
parenthesis should've been used to isolate possible options.

Also,
https://github.com/FFmpeg/FFmpeg/blob/master/fftools/ffmpeg.c#L3539

        set_tty_echo(1);

doesn't work with Windows console therefore makes it hard to type. IMO
readline should be used instead of own techniques as there might be
errors while typing.

Even though I managed to send a command to multiple filters (i.e
afreqshift, rubberband), it returns (-38) all the time, according to
avfilter_graph_send_command() that is an error. Further verifying the
meaning of (-38), av_strerror() reports, "Function not implemented." I
check if that is really the case or not. But,
https://github.com/FFmpeg/FFmpeg/blob/master/libavfilter/af_afreqshift.c#L383
tells me otherwise.

        $ ffmpeg -f lavfi -i 'sine,afreqshift,rubberband' -f null -
        ffmpeg version n5.1.2 Copyright (c) 2000-2022 the FFmpeg developers
          built with gcc 12.2.1 (GCC) 20230111
          configuration: --prefix=/usr --disable-debug
--disable-static --disable-stripping --enable-amf --enable-avisynth
--enable-cuda-llvm --enable-lto --enable-fontconfig --enable-gmp
--enable-gnutls --enable-gpl --enable-ladspa --enable-libaom
--enable-libass --enable-libbluray --enable-libbs2b --enable-libdav1d
--enable-libdrm --enable-libfreetype --enable-libfribidi
--enable-libgsm --enable-libiec61883 --enable-libjack --enable-libmfx
--enable-libmodplug --enable-libmp3lame --enable-libopencore_amrnb
--enable-libopencore_amrwb --enable-libopenjpeg --enable-libopus
--enable-libpulse --enable-librav1e --enable-librsvg
--enable-librubberband --enable-libsoxr --enable-libspeex
--enable-libsrt --enable-libssh --enable-libsvtav1 --enable-libtheora
--enable-libv4l2 --enable-libvidstab --enable-libvmaf
--enable-libvorbis --enable-libvpx --enable-libwebp --enable-libx264
--enable-libx265 --enable-libxcb --enable-libxml2 --enable-libxvid
--enable-libzimg --enable-nvdec --enable-nvenc --enable-opencl
--enable-opengl --enable-shared --enable-version3 --enable-vulkan
          libavutil      57. 28.100 / 57. 28.100
          libavcodec     59. 37.100 / 59. 37.100
          libavformat    59. 27.100 / 59. 27.100
          libavdevice    59.  7.100 / 59.  7.100
          libavfilter     8. 44.100 /  8. 44.100
          libswscale      6.  7.100 /  6.  7.100
          libswresample   4.  7.100 /  4.  7.100
          libpostproc    56.  6.100 / 56.  6.100
        Input #0, lavfi, from 'sine,afreqshift,rubberband':
          Duration: N/A, start: 0.000000, bitrate: 1411 kb/s
          Stream #0:0: Audio: pcm_f32le, 44100 Hz, mono, flt, 1411 kb/s
        Stream mapping:
          Stream #0:0 -> #0:0 (pcm_f32le (native) -> pcm_s16le (native))
        Press [q] to stop, [?] for help
        Output #0, null, to 'pipe:':
          Metadata:
            encoder         : Lavf59.27.100
          Stream #0:0: Audio: pcm_s16le, 44100 Hz, mono, s16, 705 kb/s
            Metadata:
              encoder         : Lavc59.37.100 pcm_s16le
        size=N/A time=00:01:44.96 bitrate=N/A speed= 105x
        Enter command: <target>|all <time>|-1 <command>[ <argument>]
        afreqshift -1 shift 100^M
        Command reply for stream 0: ret:-38 res:
        size=N/A time=00:08:53.51 bitrate=N/A speed=13.5x
        video:0kB audio:45953kB subtitle:0kB other streams:0kB global
headers:0kB muxing overhead: unknown
        Exiting normally, received signal 2.