Tidy up the FFmpeg syntax


Is it possible to tidy up the FFmpeg syntax? At present, there over-quoting which makes the output difficult to read. I realize that over-quoting may have been a safety measure internal to the code, but this leads to a rather messy command output.

I propose the following Topaz FFmpeg Style Guide which should work across bash, zsh, PowerShell and Windows cmd. In the same way as Google publishes a Style Guide for Shell, Topaz could define a [Style Guide for FFmpeg].

  • Native FFmpeg options need not be quoted when passed to FFmpeg.
  • Numbers need not be quoted
  • String-types should be single quoted.
  • Filenames should be double quoted to allow for shell expansion.
  • Complete filtergraphs should be double quoted, which allows for named pads such as [out], while allowing individual inner-strings to be single quoted. It also avoids extra levels of escaping within expressions within the filtergraph.
  • Prefer FFmpeg named strings over integer indexes, eg -color_primaries 'bt709' rather than "-color_primaries" "2". This avoids the user from having to cross-reference FFmpeg command-line help and online documentation to identify what “2” means. This is more convenient for the user.
  • Prefer verbose options over shorthand options, eg codec:v 'prores_videotoolbox' rather than "-c:v" "prores_videotoolbox" since this explains to the user what the option is, rather than requiring cross-reference. FFmpeg has been trying to make options more verbose. To an inexperienced user, -c:v could means codec, it could mean compression. Verbose code is good code.
  • Prefer FFmpeg’s enumerated strings for video size and frame rates.
  • flags should be preceded with a '+flag1' where the flag appends to defaults, eg -movflags '+use_metadata_tags+write_colr', otherwise FFmpeg’s default flags are ignored.

Current output from Topaz…

$ ffmpeg "-hide_banner" "-i" "${infile}" "-sws_flags" "spline+accurate_rnd+full_chroma_int" "-color_trc" "2" "-colorspace" "2" "-color_primaries" "2" "-filter_complex" "tvai_fi=model=chf-3:slowmo=1:rdt=-0.000001:fps=29.97:device=-1:vram=1:instances=1,tvai_up=model=ahq-12:scale=0:w=1920:h=1080:device=-1:vram=1:instances=1,scale=w=1920:h=1080:flags=lanczos:threads=0" "-c:v" "prores_videotoolbox" "-profile:v" "hq" "-pix_fmt" "p210le" "-allow_sw" "1" "-map_metadata" "0" "-movflags" "use_metadata_tags+write_colr " "-map_metadata:s:v" "0:s:v" "-map_metadata:s:a" "0:s:a" "-c:a" "copy" "-metadata" "videoai=Slowmo 100% and framerate changed to 29.97 using chf-3. Enhanced using ahq-12. Changed resolution to 1920x1080" "${outfile}"

Would become the more readable syntax of…

$ ffmpeg -hide_banner -i "${infile}" -sws_flags 'spline+accurate_rnd+full_chroma_int' -color_trc 'bt709' -colorspace 'bt709' -color_primaries 'bt709' -filter_complex "tvai_up=model='ahq-12':scale=0:w=1920:h=1080:device=-1:vram=1:instances=1,scale=width=1920:height=1080:flags='lanczos':threads=0" -codec:v 'prores_videotoolbox' -profile:v 'hq' -pix_fmt:v 'p210le' -allow_sw 1 -map_metadata:g 0 -movflags '+use_metadata_tags+write_colr' -map_metadata:s:v '0:s:v' -map_metadata:s:a '0:s:a' -codec:a 'copy' -metadata 'videoai=Slowmo 100% and framerate changed to 29.97 using chf-3. Enhanced using ahq-12. Changed resolution to 1920x1080' "${outfile}"

With the above syntax optimizations and proposed Topaz FFmpeg Style Guide:

  • Topaz Community Forum markup will then lint and syntax highlight the command.
  • shellcheck and Github Flavored Markup will lint and syntax highlight correctly.
  • More readable code for the user.
  • It provides distinction between keys and values.

The above would not be a functional change, but a stylistic change making the output of Topaz more readable for the end user.

I appreciate that ffmpeg-python has a structured output which will quote everything, but that is less relevant since Topaz’ output is focused on shells such as bash/zsh/PowerShell/cmd rather than Python.

Do any community members have any syntax best practice that could be added to an overall FFmpeg Style Guide to propose to Topaz?

Good suggestion - voted!

You can also vote once yourself even though you created the topic.

1 Like

As a CLi user I second this Idea :100: