Video Thumbnails
PreviewProxy can extract a thumbnail frame from video files using ffmpeg, and then process that frame through the normal transform pipeline.
Requirements
ffmpeg must be installed and accessible. By default, PreviewProxy looks for ffmpeg and ffprobe on the system PATH. You can override the locations with environment variables:
| Variable | Description |
|---|---|
FFMPEG_PATH | Path to the ffmpeg binary |
FFPROBE_PATH | Path to the ffprobe binary |
Supported Video Sources
Any URL that resolves to a video file can be used as the source:
| Source | Format |
|---|---|
| HTTP | http://example.com/video.mp4 |
| HTTPS | https://example.com/video.mp4 |
| S3 | s3:/bucket/path/video.mp4 |
| Local | local:/path/to/video.mp4 |
| Alias | mycdn:/path/to/video.mp4 |
seek Parameter
The seek parameter controls which frame to extract from the video. If seek is not specified, the first frame is used.
| Value | Effect |
|---|---|
5.0 | Absolute: seek to 5 seconds from the start |
0.5r | Relative: seek to 50% of total duration (requires ffprobe) |
auto | Automatically seek to the middle of the video (requires ffprobe) |
ffprobe is required for relative (r) and auto seek modes. PreviewProxy defaults to looking for ffprobe in the same directory as ffmpeg.
Examples
Extract a thumbnail at the midpoint, resized to 640px wide in WebP format:
/w=640,webp,seek:auto/https://example.com/video.mp4
Extract a thumbnail at 5 seconds:
/seek:5.0/https://example.com/video.mp4
Extract a thumbnail at 25% of total duration from an S3 source, resized to 320px wide:
/w=320,seek:0.25r/s3:/videos/clip.mp4
Processing Pipeline
Once the frame is extracted by ffmpeg, it is passed through the standard PreviewProxy transform pipeline. This means you can apply resize, format conversion, quality settings, and any other supported transforms to the extracted frame in the same request.