Write ffmpeg-utils Values Without Guessing

This guide covers the compact values ffmpeg tools share: durations, sizes, frame rates, ratios, colours and channel layouts. By the end you will read and write them with confidence instead of copying a value from a forum post and hoping. The examples use the installed FFmpeg 8.0.1 binary and take about 10 minutes to try.

Install FFmpeg and check which executable your shell will run:

command -v ffmpeg
ffmpeg -version | head -n 1

This guide was checked with FFmpeg 8.0.1. The local ffmpeg-utils(1) manpage comes from the Ubuntu ffmpeg package version 7:6.1.1-3ubuntu5+esm13, so small differences between builds are possible. The syntax described here is the shared libavutil syntax, not a list of options accepted by every individual filter.

1. Keep FFmpeg's two quoting layers separate

FFmpeg's own parser treats a backslash as an escape character and single quotes as a quoting mechanism. Unquoted leading and trailing spaces are discarded. Your shell parses the command first, so a value can pass through two parsers before FFmpeg sees it.

For example, this filter gives the colour value to FFmpeg as one shell argument:

ffmpeg -hide_banner -f lavfi \
  -i "color=c='Crime d\\'Amour':s=320x240:d=0.1" \
  -f null -

That example is deliberately awkward because the value contains a quote. For ordinary filter values, use double quotes around the whole filter expression when the shell needs to protect punctuation:

ffmpeg -hide_banner -f lavfi \
  -i "color=c=red:s=320x240:d=0.1" -f null -

Do not copy a backslash from a shell example into a configuration file without checking the second parser. If a value contains spaces, quotes or backslashes, test the exact form in the tool that will consume it. The FFmpeg source tree also provides tools/ffescape for generating escaped strings, but it is not part of the installed runtime command.

2. Express durations precisely

A duration can be written as HH:MM:SS, with an optional fractional part, or as seconds with an optional s, ms or us suffix. A leading minus sign makes it negative. These are equivalent ways to describe short intervals:

0.2
200ms
200000us
00:00:00.200

The compact form is useful in filters and input options. This command generates five PAL-rate frames, because d=0.2 is a duration and r=pal is a frame-rate abbreviation:

ffmpeg -hide_banner -f lavfi \
  -i "color=c=black:s=320x240:r=pal:d=0.2" \
  -f null -

3. Use named video sizes and rates correctly

Video sizes accept explicit widthxheight values or recognised abbreviations. For example, hd720 means 1280x720, while pal as a video rate means 25 frames per second. A size abbreviation is not a frame-rate abbreviation, even when both use familiar broadcast names:

ffmpeg -hide_banner -f lavfi \
  -i "testsrc2=s=hd720:r=pal:d=0.2" -f null -

The verification line should identify a 1280x720 video stream at 25 fps. Prefer explicit dimensions when a downstream service has a strict contract. Names such as 4k and uhd2160 are not interchangeable: the manpage defines them as 4096x2160 and 3840x2160 respectively.

Do not use a size name to imply an aspect ratio without checking its dimensions. vga is 640x480, whereas nhd is 640x360. Both have 640 pixels of width but different shapes.

4. Set colours and transparency without losing them to the shell

Colour names are matched without regard to case. Hex colours may start with 0x or # and contain six hexadecimal digits, with an optional alpha component after @. Alpha is opacity: 0.0 is fully transparent and 1.0 is fully opaque, and it defaults to opaque when omitted. The special value random chooses a random colour:

ffmpeg -hide_banner -f lavfi \
  -i "[email protected]:s=320x240:r=25:d=0.1" \
  -f null -

The command should complete successfully and report a 320x240 stream. The null output verifies that the expression was parsed, but it does not make transparency visible; for a visual check, write to a format and inspect it with a viewer that preserves an alpha channel.

5. Describe audio channels explicitly

Channel layouts describe where channels belong, not just how many channels exist. mono expands to FC; stereo expands to FL+FR; and 5.1 expands to front left, front right, front centre, low frequency, back left and back right. Side and back layouts are different, so choose the one your source and receiver expect:

ffmpeg -hide_banner -f lavfi \
  -i "sine=frequency=440:duration=0.2" \
  -ac 2 -channel_layout stereo -f null -

For a custom arrangement, join channel identifiers with plus signs, for example FL@Left+FR@Right to give the two channels custom names. The manpage also documents numeric forms such as 2c, which asks for the default layout for two channels, and 2C, which asks for an unknown layout with two channels. The trailing letter is required by current syntax; old examples that omit it are obsolete.

6. Handle ratios and expressions

Ratios accept either an expression or numerator:denominator. The undefined ratio is 0:0. Infinite ratios, such as 1:0, and negative ratios are both considered valid by the parser, so an application that needs a finite positive value must validate the result itself.

FFmpeg's expression evaluator supports +, -, *, / and ^, plus unary signs and functions such as abs(), min() and max(). A semicolon joins two expressions and returns the value of the second after evaluating the first. Quote expressions containing shell metacharacters and keep them in the option's intended field.

Common traps

• Wrong parser blamed. A shell may remove quotes before FFmpeg sees them. Print or log the final argument list in a script, then test it with a short null output.
• Wrong abbreviation. pal is 720x576 as a video size but 25/1 as a video rate. Check which field is being populated.
• Wrong audio shape. 5.1 and 5.1(side) have the same channel count but different positions. Confirm the target's channel order.
• Unexpected file changes. The examples write only to FFmpeg's null muxer. If you replace -f null - with a filename, check that it does not already exist. FFmpeg may prompt before overwriting; stop with Ctrl-C if the target is wrong, then remove only a file you have positively identified.