In -filter_complex, commas chain filters, semicolons separate chains and [labels] wire them together; a 2x2 grid from one 1080p input takes 5 chains. ReelSDK bills $0.02 per compute minute, so that grid cost under 1.2 cents for a 10-second clip.

ffmpeg -filter_complex explained

Reach for it when a job has more than one input or output. Below are 4 graphs that run on ffmpeg 8.1, plus 3 errors and their fixes; ReelSDK's API takes each graph as one string in args, with no shell quoting to fight.

GuidesUpdated

grid
ffmpeg -i in.mp4 -filter_complex "[0:v]scale=960:540,split=4[a][b][c][d];[b]hue=s=0[gray];[c]gblur=sigma=12[soft];[d]edgedetect=mode=colormix[edges];[a][gray][soft][edges]xstack=inputs=4:layout=0_0|w0_0|0_h0|w0_h0[grid]" \
  -map "[grid]" -map 0:a -c:v libx264 -crf 20 -preset veryfast -c:a copy -movflags +faststart grid.mp4

split=4 makes four copies of the scaled stream; three get a filter each, and xstack places all four by layout. -map picks the labelled result and the original audio.

Variations

The other commands you will need

  1. Picture in picture

    [1:v] is the video of the second input. It is scaled to 480 px high and laid over the first, 40 px from the bottom right corner; W and w are the widths of the two layers.

    picture in picture
    ffmpeg -i in.mp4 -i clip.mp4 -filter_complex "[1:v]scale=-2:480[small];[0:v][small]overlay=W-w-40:H-h-40:shortest=1[v]" \
      -map "[v]" -map 0:a -c:v libx264 -crf 20 -preset veryfast -c:a copy -movflags +faststart pip.mp4
  2. Music under the original sound

    An audio-only graph. normalize=0 keeps each input at the level you set; amix scales them down otherwise. The video is copied, so it takes a fraction of a second.

    audio mix
    ffmpeg -i in.mp4 -i music.mp3 -filter_complex "[1:a]volume=0.25[bed];[0:a][bed]amix=inputs=2:duration=first:normalize=0[mix]" \
      -map 0:v -map "[mix]" -c:v copy -c:a aac -movflags +faststart mixed.mp4
  3. A mirror with split

    With no output label, the last chain's result goes to the output file on its own. Here the frame and its flipped copy sit side by side at 3840x1080.

    mirror
    ffmpeg -i in.mp4 -filter_complex "[0:v]split[l][r];[r]hflip[m];[l][m]hstack" \
      -an -c:v libx264 -crf 20 -preset veryfast -movflags +faststart mirror.mp4

The flags

The pieces of a filtergraph

The pieces of a filtergraph
FlagWhat it doesUsed here
split=4Copies a stream so several chains can read it; asplit for audioGrid, mirror
xstackPlaces its inputs on one canvas by layoutGrid
overlayDraws the second input over the first at x and yPicture in picture
[0:v]The video of the first input; [1:a] is the audio of the secondAll four
[soft]A link label: one chain's output, another chain's inputGrid
,Passes frames to the next filter in the same chainGrid, audio mix
;Ends one chain and starts the nextAll four
-map "[grid]"Sends a labelled output, or an input stream like 0:a, to the fileGrid, picture in picture, audio mix

Sources: ffmpeg filters: filtergraph syntax, ffmpeg documentation: complex filtergraphs, checked November 2026.

Reading a graph

Cut the grid graph at its semicolons and you get 5 chains. The first reads input 0's video, scales it to 960x540 and splits it into four labelled copies. The next three each take one copy and apply one filter. The last feeds all four into xstack and names the result [grid].

Input streams like [0:v] can be read more than once, but a link label like [soft] connects exactly two ends: one chain writes it, one chain reads it. That is why the grid needs split to feed four filters.

Three errors and their fixes

"Filter 'split' has output 1 (b) unconnected": you made a label and nothing reads it. Map it with -map "[b]", feed it to a filter, or drop it.

"Simple and complex filtering cannot be used together for the same stream.": an output fed by -filter_complex also got a -vf. Move that filter into the graph.

"Stream specifier 'a' in filtergraph description ... matches no streams.": a label was read twice. Add a split and read each copy once.

On the API

args takes up to 1000 strings of up to 8192 characters each, so long graphs fit. Two things get a 400 before the job starts: -filter_complex_script, which loads the graph from a file, and the movie filter, which opens a file from inside the graph. The answer says "add the file as another -i instead".

So every file goes in inputs and gets an -i; a job takes up to 50 inputs and 1 to 20 outputs. See pricing for the per-minute rate.

Without installing ffmpeg

The same command as one API call

The graph goes in args as one string. Each string in the array reaches ffmpeg as one argument and no shell parses it, so shell quoting rules don't apply; the graph's own quotes stay as they are. Each job runs ffmpeg 8.1 on a fresh machine at $0.02 per compute minute, billed per second; this one finished in about 34 seconds and cost under 1.2 cents.

terminalTry it
curl "https://api.reelsdk.com/v1/ffmpeg?wait=60" \
  -H "Authorization: Bearer $REELSDK_KEY" \
  --json '{
    "inputs": {
      "in.mp4": "https://api.reelsdk.com/f/lib/demo/landscape.mp4"
    },
    "args": [
      "-i", "in.mp4", "-filter_complex",
      "[0:v]scale=960:540,split=4[a][b][c][d];[b]hue=s=0[gray];[c]gblur=sigma=12[soft];[d]edgedetect=mode=colormix[edges];[a][gray][soft][edges]xstack=inputs=4:layout=0_0|w0_0|0_h0|w0_h0[grid]",
      "-map", "[grid]", "-map", "0:a", "-c:v", "libx264", "-crf", "20",
      "-preset", "veryfast", "-c:a", "copy", "-movflags", "+faststart",
      "grid.mp4"
    ],
    "outputs": ["grid.mp4"]
  }'
grid.mp4 from the API: one input split into 4 tiles.Input: 1920x1080 input

FAQ

Questions, answered

What is the difference between -vf and -filter_complex?

-vf runs one chain on one stream. -filter_complex takes any number of inputs and outputs and wires them with labels. You can't use both on the same output stream.

How do I use the same input twice in a filtergraph?

Copy it with split for video or asplit for audio, for example [0:v]split=2[a][b], and read each label once.

What does 'has output 1 (b) unconnected' mean?

The graph creates the label [b] and nothing reads it. Map it with -map "[b]", use it in another chain, or remove it.

Can I load the filtergraph from a file on the API?

No, -filter_complex_script gets a 400. Send the graph as one string in args instead; each string can be up to 8192 characters.

Ready to build?

Ship video from your app today

Your first $0.50 is free, and one key covers every endpoint.

Moonlit lake with a lit cabin under the mountains