Stream remote media to FFmpeg using cURL

Tim Koschützki

Co-founder · Berlin, Germany ·

In this post, we fetch remote video data with cURL and process it with FFmpeg without saving the input video locally. By piping data directly into FFmpeg, you can extract frames, analyze scene changes, or generate dynamic thumbnails as the video is being streamed.

Overview

When working with media, efficiency is key. Combining cURL and FFmpeg into a seamless pipeline allows you to fetch remote media data and process it on the fly. This guide assumes you're using FFmpeg 6.0+ and cURL 7.81.0+ for optimal compatibility and features.

The examples use Bash and MP4 files prepared for sequential reading, with their moov metadata before the media data (“faststart”). A pipe cannot seek backward: ordinary MP4 files with metadata at the end can fail even after the entire download. When the layout is unknown, give the HTTP URL directly to FFmpeg so it can seek with range requests, or download to a local file first.

Setting up the pipeline

Here's how to set up a pipeline that extracts frames from a remote video stream. This command fetches the video using cURL and pipes it to FFmpeg for processing:

set -euo pipefail
mkdir thumbnails
curl -fsSL "https://example.com/path/to/video.mp4" | \
ffmpeg -nostdin -n -f mp4 -i pipe:0 \
  -vf "fps=1" \
  -frame_pts 1 \
  -v error \
  -stats \
  thumbnails/thumbnail_%03d.jpg

Explanation

-f mp4 specifies the input format explicitly
pipe:0 tells FFmpeg to read from standard input
-frame_pts 1 uses each output frame’s PTS as the filename number, in the output time base
-v error shows only error messages
-stats displays progress information
set -o pipefail makes a failed download fail the pipeline
mkdir thumbnails requires a new directory, protecting images from earlier runs

Advanced uses

The basic pipeline can be extended for more complex tasks:

Scene Change Detection: Use FFmpeg's scene detection capabilities with proper thresholds:

set -euo pipefail
mkdir scenes
curl -fsSL "https://example.com/path/to/video.mp4" | \
ffmpeg -nostdin -n -f mp4 -i pipe:0 \
  -filter_complex "select='gt(scene,0.3)',metadata=print:file=scenes/time.txt" \
  -fps_mode vfr \
  -frame_pts 1 \
  scenes/scene_%03d.jpg

This command detects scene changes with a 0.3 threshold and outputs frame timestamps to scenes/time.txt for further analysis.

Real-time Analysis: Process video streams with optimized settings:

set -euo pipefail
mkdir analysis-frames
curl -fsSL "https://example.com/path/to/video.mp4" | \
ffmpeg -nostdin -n -f mp4 -i pipe:0 \
  -vf "scale=640:-1,fps=5" \
  -v warning \
  -vcodec ppm \
  analysis-frames/frame_%05d.ppm

This example scales the video, reduces the frame rate, and saves PPM frames for an analysis program to consume.

Troubleshooting

Common issues and solutions:

Network Issues: Retry downloads into a file before processing. Retrying a transfer that is already piped into a decoder can mix data from multiple attempts:
```
set -euo pipefail
mkdir download
curl --retry 3 --retry-delay 2 -fsSL \
  "https://example.com/path/to/video.mp4" -o download/input.mp4
```
Slow Processing: Lower the resolution or frame rate. FFmpeg’s muxing and input packet queues do not fix an input container that needs seeking.
Format Detection: Use -f mp4 before -i pipe:0 only for MP4 input. Forcing a demuxer does not recover missing metadata or make a pipe seekable.

Performance considerations

For optimal performance:

Scale down video resolution for analysis when full resolution isn't needed
Use appropriate frame rates for your use case
Consider hardware acceleration where available
Monitor system resources and adjust parameters accordingly

Note that real-time analysis capabilities depend on input format, processing power, and network bandwidth. For high-resolution streams, consider reducing the processing load by lowering the analysis framerate or using a scaled-down version of the input.

Conclusion

The combination of cURL and FFmpeg provides a powerful toolkit for real-time media processing. This approach offers flexibility and efficiency for various video analysis tasks. At Transloadit, we use similar techniques in our media processing pipeline to deliver fast and reliable results.