How to Read Raw YUV Video from Stdin in FFmpeg

Piping raw YUV video data into FFmpeg via standard input (stdin) allows you to process or encode uncompressed video streams generated on the fly by other programs. Because raw YUV contains no container headers, timestamps, or metadata, FFmpeg cannot automatically detect the stream's properties. To process the data successfully, you must explicitly declare the input format, pixel format, dimensions, and frame rate before defining standard input as the source.

The Required Input Parameters

When reading raw video, the order of parameters matters. Input-specific options must appear before -i - (which specifies stdin as the input file).

The required flags are:

  • -f rawvideo: Tells FFmpeg to use the raw video demuxer instead of attempting to autodetect a container format.
  • -pix_fmt <format>: Specifies the exact chroma subsampling layout (e.g., yuv420p, yuv422p, yuv444p, nv12).
  • -s <width>x<height> (or -video_size <width>x<height>): Sets the frame dimensions in pixels.
  • -r <fps> (or -framerate <fps>): Specifies the frame rate of the incoming stream.
  • -i - (or -i pipe:0): Directs FFmpeg to read data from stdin.

Basic Command Syntax

The general structure of the command is:

cat input.yuv | ffmpeg -f rawvideo -pix_fmt yuv420p -s 1920x1080 -r 30 -i - output.mp4

In a real-world scenario, you will typically pipe data directly from an application, camera capture tool, or script rather than using cat:

./generate_stream | ffmpeg -f rawvideo -pix_fmt yuv420p -s 1280x720 -r 60 -i - -c:v libx264 -preset fast -crf 22 output.mp4

Parameter Breakdown

  • Pixel Format (-pix_fmt): Raw YUV files are simple byte dumps. If you specify yuv420p when the data is actually nv12 or yuv422p, the output will show incorrect colors, tearing, or green artifacts. Always match the exact byte layout of your source.
  • Resolution (-s): FFmpeg calculates frame boundaries by multiplying the width, height, and the byte size per pixel derived from -pix_fmt. If the resolution does not match the incoming byte stream precisely, the video will desynchronize and appear slanted or corrupt.
  • Frame Rate (-framerate): Unlike container formats that store timestamps for each frame, raw data relies on this value to generate proper presentation timestamps (PTS) for encoding.

Handling Planar vs. Semi-Planar YUV

Ensure your -pix_fmt flag matches the planar structure of your raw data:

  • yuv420p: Planar format where all Y samples appear first, followed by all U samples, then all V samples.
  • nv12: Semi-planar format where all Y samples appear first, followed by interleaved U and V samples. This format is commonly output by hardware encoders and decoders.
  • yuv422p: Planar 4:2:2 format often used in professional capture cards.

Run ffmpeg -pix_fmts to view the complete list of supported pixel formats if you are working with less common bit depths (such as 10-bit yuv420p10le).