Extract a thumbnail from a video with FFmpeg

Put -ss before -i, then -frames:v 1 and -q:v 2 for a sharp JPEG: ffmpeg -ss 65 -i in.mp4 -frames:v 1 -q:v 2 out.jpg. That grabbed frame 1560, exactly 1:05.000. Every command below ran on a clip with the frame number burned in, so each picture shows which frame you get.

At a time Re-encode

You know the moment you want. Exact to the frame and only decodes from the keyframe before it.

ffmpeg -ss 65 -i in.mp4 -frames:v 1 -q:v 2 out.jpg

One 1280x546 JPEG of frame 1560, exactly 1:05.000.

Frame
1560, 1:05.000
Resolution
1280x546
Run time
166 ms
Output
162 KB
Representative Re-encode

You want a frame that looks typical of a stretch of video, not a fixed moment.

ffmpeg -ss 60 -i in.mp4 -vf thumbnail=240 -frames:v 1 -q:v 2 out.jpg

Frame 1488 (1:02.000), the dragon on the roof. The filter scored all 240 frames of the window and kept the one closest to their average.

Picked
frame 1488, 1:02.000
Scored
240 frames
Run time
245 ms
Output
169 KB

Proof

The frame each command grabbed

Timecode and frame number are burned into the bottom left of the test clip, so each picture is its own receipt.
-ss 65 -i in.mp4 -frames:v 1 The frame you asked for
Frame grabbed with -ss 65 before -i: timecode 1:05.000, frame 1560
frame 1560 Exactly 1:05.000. The same command with -ss after -i wrote the same file, byte for byte.
-vf thumbnail, defaults Only looked at the first 4 seconds
Frame picked by the thumbnail filter with default settings: frame 2, a dark shot from the opening
frame 2 The filter scores batches of 100 frames. With -frames:v 1 you get the pick of the first batch, here 0:00.083 in a dark interior.
-ss 60, thumbnail=240 A typical frame of the window
Frame picked by thumbnail=240 starting at 1:00: frame 1488, the dragon on a rooftop
frame 1488 Seek to the stretch you care about and size the batch to cover it: 240 frames is 10 s at 24 fps.
-q:v 2 vs -q:v 31 31 shows blocks in hair and skin
The same crop of frame 1560 saved at -q:v 2 on the left and -q:v 31 on the right
162 KB vs 23 KB Same frame, same crop. Left -q:v 2, right -q:v 31, shown at full size.
-sseof -1, -update 1 The very last frame
Last frame of the clip grabbed with -sseof: timecode 1:59.958, frame 2879
frame 2879 Frame 2879 of 2880. -sseof -1 starts one second from the end and -update 1 keeps overwriting the file, so the last frame wins.

Footage: Sintel, © Blender Foundation, CC BY 3.0. Timecode added by us.

Run it

Run it on Rendobar

Send the same command from your code. The job fetches each input from its URL and returns the output file's URL when it finishes.

job.ts
import { createClient } from "@rendobar/sdk";
const rb = createClient({ apiKey: process.env.RENDOBAR_API_KEY });
const job = await rb.jobs.run({
type: "ffmpeg",
inputs: {
"in.mp4": "https://cdn.rendobar.com/examples/video-thumbnail/in.mp4",
},
params: {
command: "ffmpeg -ss 65 -i in.mp4 -frames:v 1 -q:v 2 out.jpg",
},
});
console.log(job.output.file.url);

Install with npm i @rendobar/sdk. jobs.run() submits and waits, so it returns the finished job in one call.

terminal
curl https://api.rendobar.com/jobs \
-H "Authorization: Bearer $RENDOBAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "ffmpeg",
"inputs": {
"in.mp4": "https://cdn.rendobar.com/examples/video-thumbnail/in.mp4"
},
"params": {
"command": "ffmpeg -ss 65 -i in.mp4 -frames:v 1 -q:v 2 out.jpg"
}
}'

Returns immediately with a job id. Poll GET /jobs/{id} or register a webhook rather than blocking on the request.

Every variant

Pick the command for your case

Each one ran on the same input. The line under it is what came out. Run times are the best of three runs with FFmpeg 8.0 on one desktop machine, so read them as relative.

  1. Grab the first frame

    Re-encode
    ffmpeg -i in.mp4 -frames:v 1 -q:v 2 out.jpg

    Frame 0, 0:00.000. Without -ss FFmpeg starts at the beginning, so no select filter is needed.

    103 ms run 38 KB

  2. Grab the last frame

    Re-encode
    ffmpeg -sseof -1 -i in.mp4 -update 1 -q:v 2 out.jpg

    Frame 2879, 1:59.958, the last of 2880. You never need the duration.

    187 ms run 94 KB

  3. Grab a frame at hh:mm:ss.ms

    Re-encode
    ffmpeg -ss 00:01:05.5 -i in.mp4 -frames:v 1 -q:v 2 out.jpg

    Frame 1572, 1:05.500. -ss takes seconds or hh:mm:ss with a fraction.

    156 ms run 163 KB

  4. Grab frame number 1560

    Re-encode
    ffmpeg -i in.mp4 -vf "select=eq(n\,1560)" -frames:v 1 -q:v 2 out.jpg

    The same file as -ss 65, byte for byte. n counts from 0, and FFmpeg decodes every frame before it.

    525 ms run 162 KB

  5. Grab a small thumbnail, 320 wide

    Re-encode
    ffmpeg -ss 65 -i in.mp4 -frames:v 1 -vf scale=320:-2 -q:v 2 out.jpg

    320x136, 17 KB. -2 keeps the height even. scale=320:-1 gave 320x137.

    146 ms run 17 KB

  6. Save it as PNG

    Re-encode
    ffmpeg -ss 65 -i in.mp4 -frames:v 1 out.png

    Lossless, 903 KB, 5.6 times the -q:v 2 JPEG. -q:v does nothing for PNG.

    184 ms run 903 KB

  7. Save it as WebP

    Re-encode
    ffmpeg -ss 65 -i in.mp4 -frames:v 1 out.webp

    71 KB at the encoder's default quality of 75. -quality 80 gave 89 KB.

    190 ms run 71 KB

Gotchas

Where it goes wrong

-ss before -i or after it?

Before. Both give the exact frame when the output is an image, because FFmpeg decodes and discards everything before your time either way. The difference is where it starts decoding.

ffmpeg -i in.mp4 -ss 65 -frames:v 1 -q:v 2 out.jpg

Frame 1560, the same 161,860 bytes as -ss 65 before -i. After -i, FFmpeg decoded all 1560 frames to get there. Before -i, it jumped to the keyframe at frame 1440 and decoded from there.

On a long video the gap grows with the timestamp. A frame at 1:30:00 after -i means decoding an hour and a half of video first.

What -q:v value should I use for a JPEG?

-q:v runs from 2 (best) to 31 (worst). Here is the 1:05 frame at each setting:

  • -q:v 2: 162 KB. -q:v 1 wrote the same file, byte for byte, so 2 is the real top.
  • -q:v 5: 88 KB.
  • -q:v 10: 51 KB.
  • -q:v 31: 23 KB, with visible blocks in the hair and skin.
  • No -q:v at all: 68 KB. FFmpeg's default JPEG is softer than most people expect.

Use 2 for a poster or a frame you will edit, 5 for a page thumbnail. The proof above shows the same crop at 2 and 31.

Why does the thumbnail filter pick a frame from the first few seconds?

It works in batches. thumbnail reads 100 frames, keeps the one whose colour histogram is closest to the batch average, and moves to the next batch. Stop after one frame and you get the winner of the first 100 frames, which here was frame 2 of a dark opening shot.

Seek to where the good material is and set the batch to the length you want judged:

ffmpeg -ss 60 -i in.mp4 -vf thumbnail=240 -frames:v 1 -q:v 2 out.jpg

Frame 1488, the dragon on the roof.

Judging the whole clip in one batch did not help. fps=1,thumbnail=120 picked frame 2819, the middle of a crossfade between two shots. The average of a whole film is rarely a good picture.

Why do I get "Cannot write more than one file with the same name"?

Your command makes more than one frame and the output is a single file name. FFmpeg 8.0 stops with this error. Add -frames:v 1, or -update 1 if you want the last frame to win.

A common cause is two -vf options. FFmpeg keeps only the last one, so a select in the first is silently dropped. This command is from a highly voted answer on the first-frame question:

ffmpeg -i in.mp4 -vf "select=eq(n\,0)" -vf scale=320:-2 -q:v 3 out.jpg

FFmpeg warned that only -filter:v scale=320:-2 would be used, then failed with the error above. Put both filters in one -vf, separated by a comma, and add -frames:v 1.

Related: Extract frames, Contact sheet, Trim a video, MP4 to GIF.

Your command. Our infrastructure.

Bring your own commands. Run them on scalable CPU and GPU infrastructure, and pay only for compute time.