Use ffmpeg-utils Syntax Without Guessing at Sizes, Times and Layouts

By the end of this guide you will be able to read and write the compact values shared by FFmpeg tools: durations, video sizes, frame rates, ratios, colours and audio channel layouts. The examples use the installed FFmpeg 8.0.1 binary and take about 10 minutes to try.

Before you start

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.

Checkpoint 1: keep FFmpeg's 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.

Checkpoint 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 -

Look for 25 fps and time=00:00:00.20 in the output. The command reads the local now date keyword as the current time where a date value is accepted. Date and time values are local time unless they end in Z, which means UTC. That distinction matters in scripts running on machines with different time zones.

Checkpoint 3: use named video sizes and rates

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.

Checkpoint 4: set colours and transparency

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. If alpha is omitted, it defaults to opaque. 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.

Be careful with the shell: # begins a comment in many unquoted shell contexts. Quote a filter containing a hash colour, or use the equivalent 0xRRGGBB spelling.

Checkpoint 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 gives 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.

Ratios and expression values

Ratios accept either an expression or numerator:denominator. The undefined ratio is 0:0. Infinite, such as 1:0, and negative ratios are 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 and safe recovery

• Wrong parser: 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 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.