To create a preview from a delivered video, choose a timestamp within that file, extract one decoded frame, and verify the resulting image before attaching it to your application. A successful process exit alone is not enough: a timestamp beyond the available video may produce no image.
This tutorial uses a local video and FFmpeg. It is a downstream processing example, not a claim that Tornado API exposes a custom thumbnail timestamp parameter.
Decide what the preview should represent
A source-platform thumbnail and a frame extracted from your delivered video serve different purposes. A source thumbnail may include designed artwork or text. A local frame shows imagery from the artifact your application will use. Neither automatically identifies the most representative moment.
For a clip library, use a timestamp relative to the delivered clip, not the original full-length source. A five-second offset in a thirty-second clip is different from five seconds into the original recording. Store the artifact identity and requested offset together so a replacement file does not silently inherit an unrelated preview.
Start with a deliberately chosen timestamp. Opening titles, fades and black frames can make zero seconds a poor choice. For automated selection, review a small bounded set of candidates against your product requirements instead of promising that a fixed offset always yields a useful image.
Extract one frame from a local video
This command requests a frame at one second into a local file whose timeline starts at zero:
ffmpeg -nostdin -v error -n -i ./video.mkv -ss 1 -map 0:V:0 -frames:v 1 -update 1 ./preview.png
The capital V selects video while excluding attached pictures and cover art; 0:V:0 selects the first matching video stream in input zero. If the file has several actual video streams, inspect them and choose the intended one rather than assuming the first is appropriate.
-ss after the input discards decoded content until the requested timestamp. -frames:v 1 limits output to one video frame. -update 1 uses the output image filename directly. -n avoids overwriting an existing file. These options are described in the FFmpeg command reference and image2 muxer documentation.
This is a clear baseline command, not a throughput benchmark. Decoding up to the offset can be expensive for long inputs. Evaluate input-side seeking separately if you need faster extraction, with representative files and correctness checks. Do not assume a requested time corresponds to an exact frame boundary in every file.
The example does not resize the frame. If your interface needs a small thumbnail, add a deliberate scaling policy and verify its output. Avoid stretching a portrait source to fit a landscape card; the aspect-ratio guide covers presentation without distortion. HDR, rotation metadata and unusual pixel aspect ratios also deserve representative visual tests before adopting a general preview pipeline.
Confirm that an image was actually produced
Run the command in an application-controlled temporary directory with a fresh output path. Check its return code, then require a nonempty output file that an image decoder can read. Verify dimensions and the expected image type before moving the result into durable storage.
A stale preview.png is not proof of success. With overwrite protection enabled, an old file may remain untouched. Associate validation with the current attempt, and promote only its validated output. The atomic download guide explains the same temporary-file handoff principle for downloaded media.
Handle these outcomes explicitly:
- No video stream: use an audio placeholder or mark the item as having no video preview.
- Timestamp outside available frames: choose another approved offset or return a controlled no-preview result.
- Decoder failure: retain a concise diagnostic and inspect the input rather than accepting a partial output.
- Valid but unhelpful image: select another candidate; technical validity does not establish editorial quality.
Use a worker deadline and resource limits. Avoid unbounded retries over arbitrary timestamps. Do not interpolate untrusted filenames into shell command strings; production code should pass an argument list to its process runner.
Connect the preview to your Tornado workflow
Wait for the media result, download the delivered file, and validate it before extracting a frame. The public job status reference describes an optional thumbnail_url. Its availability does not establish that it represents your chosen timestamp, and this guide makes no guarantee that every source provides one.
If a job produces a clip, apply the requested offset to that delivered clip. Keep the preview record linked to the correct job and artifact, with the selection policy used. Check delivered duration to avoid choosing obviously out-of-range offsets, while still verifying extraction output afterward.
What was verified locally
The command was exercised against a synthetic two-second video: red imagery followed by blue imagery. The test checks that the requested one-second preview is a decodable blue frame with the fixture's dimensions. It also checks overwrite preservation, an out-of-range timestamp and an audio-only input.
That fixture does not prove behavior for every codec, timestamp layout, source platform or HDR conversion. No paid API job or live-media benchmark was used. Test representative permitted files before relying on the preview in a production application.
To put delivery and downstream validation together, build your first Tornado media workflow, then add preview extraction as a separate, observable processing step.