YUVTools Tutorial: Batch Converting and Inspecting YUV FilesYUVTools is a lightweight, command-line oriented toolkit for working with raw YUV video data: converting between YUV formats, inspecting pixel values and structure, extracting planes, and preparing raw video for encoding or analysis. This tutorial walks through typical workflows: identifying YUV formats, batch-converting files, inspecting content and metadata, extracting frames and planes, and troubleshooting common issues. Examples use YUVTools commands and demonstrate integration into simple scripts for automated processing.
What is YUV and why use YUVTools?
YUV is a family of color spaces commonly used in video processing and compression. It separates luminance (Y) from chrominance (U and V), which matches human vision sensitivity and enables effective chroma subsampling. Raw YUV files (often with extensions like .yuv or .raw) are uncompressed pixel dumps and lack container metadata, so tools that interpret and manipulate these files must be told the resolution, pixel format (e.g., YUV420p, YUV422p), bit depth, and plane order.
YUVTools focuses on raw YUV workflows. It’s useful when:
- converting between YUV pixel formats (e.g., 4:2:0 ↔ 4:4:4),
- preparing test vectors for encoders,
- extracting individual planes for analysis,
- verifying bit-depth and packing,
- batch-processing many raw files quickly in pipelines.
Installing YUVTools
YUVTools may be distributed as a small binary or as part of a repository with source code. Typical installation methods:
- Download prebuilt binaries for your OS and add to PATH.
- Build from source (requires a C/C++ compiler and build tools).
- Use package managers if available (rare for niche tools).
Verify installation:
yuvtools --help Expected output shows available commands and flags.
Understanding formats and parameters
Because raw YUV files contain no header, you must specify:
- Width and height (e.g., 1920×1080)
- Pixel format (common: YUV420p / I420, YUV422p, YUV444p)
- Bit depth (8, 10, or higher) and packing (packed vs planar)
- Plane order (Y U V or Y V U) — I420 uses Y U V.
Common formats:
- YUV420p (I420): Y plane full resolution; U and V subsampled by 2×2.
- YUV422p: U and V subsampled horizontally by 2.
- YUV444p: No subsampling; full chroma resolution.
- Packed formats (less common in raw dumps): YUY2, UYVY.
Example flags (names vary by YUVTools version):
- –width 1920 –height 1080
- –format yuv420p
- –depth 10 –packed=none
Inspecting a YUV file
YUVTools provides commands to print file summary, hex/dump ranges, and display basic statistics per plane.
-
Get a summary (frame count, size per frame):
yuvtools info --width 1280 --height 720 --format yuv420p input.yuv -
Show basic per-plane stats (min, max, mean):
yuvtools stats --width 1280 --height 720 --format yuv420p input.yuv -
Dump first frame Y plane as ASCII (for spot-checking):
yuvtools dump --width 640 --height 480 --format yuv420p --plane Y --frame 0 input.yuv | head -n 20
Output helps confirm whether the file matches expected dimensions and chroma layout. If pixel values look clipped or noise is high, re-check bit depth and packing.
Visualizing frames
While YUVTools is text/CLI-focused, it integrates with display tools to visualize frames:
- Convert a frame to PPM/PGM or PNG and open with an image viewer.
- Pipe output into ffmpeg or ImageMagick.
Convert a single frame to PNG:
yuvtools extract --width 1920 --height 1080 --format yuv420p --frame 10 --out-frame frame10.yuv input.yuv # then convert to PNG using ffmpeg ffmpeg -f rawvideo -pix_fmt yuv420p -s 1920x1080 -i frame10.yuv -frames:v 1 frame10.png Extracting planes and frames
Extracting planes is useful for analysis or feature extraction.
Extract U plane of frame 0:
yuvtools plane --width 1280 --height 720 --format yuv420p --plane U --frame 0 input.yuv -o frame0_U.raw Extract a range of frames to separate files (many YUVTools builds support frame-range):
yuvtools extract --width 640 --height 360 --format yuv420p --start 0 --end 29 --out-pattern frame_%04d.yuv clip.yuv Batch converting many files
Automate conversion across a directory. Example: convert multiple raw 10-bit YUV420p files to 8-bit YUV420p and change resolution or pack format.
Bash loop example:
mkdir -p converted for f in *.yuv; do base=$(basename "$f" .yuv) yuvtools convert --width 1920 --height 1080 --format yuv420p --depth 10 --out-format yuv420p --out-depth 8 "$f" -o "converted/${base}_8bit.yuv" done Parallelize using GNU parallel for speed:
ls *.yuv | parallel -j8 'yuvtools convert --width 1920 --height 1080 --format yuv420p --depth 10 --out-format yuv420p --out-depth 8 {} -o converted/{/.}_8bit.yuv' Include error checking: verify output frame size matches expectations and that commands exit with zero status.
Converting between chroma subsampling formats
Convert 4:2:0 to 4:4:4 (upsample chroma) or 4:4:4 to 4:2:0 (downsample with filtering):
Upsample:
yuvtools convert --width 1280 --height 720 --in-format yuv420p --out-format yuv444p input420.yuv -o output444.yuv Downsample with a specified filter:
yuvtools convert --width 1280 --height 720 --in-format yuv444p --out-format yuv420p --chroma-filter lanczos input444.yuv -o output420.yuv Check for artifacting after resampling; prefer bicubic/lanczos for quality, nearest for speed.
Handling different bit depths and packing
10-bit and 12-bit raw files may be packed (e.g., 10-bit packed into 16-bit words or into a tight 10-bit stream). YUVTools often supports flags for input bit depth and packing schemes.
Example converting 10-bit packed to 8-bit planar:
yuvtools convert --width 3840 --height 2160 --in-format yuv420p --in-depth 10 --in-packed packed10 --out-format yuv420p --out-depth 8 big10_packed.yuv -o small8.yuv If values look wrong (strange bands, weird negatives), try different packing options or inspect raw hex to deduce packing.
Scripting robust pipelines
Useful checks in scripts:
- Validate filesize against expected: filesize % frame_size == 0 and frames = filesize / frame_size
- Use temporary directories and atomic moves to avoid partial outputs
- Log processed filenames and errors
Example check and process snippet:
width=1920; height=1080; pixfmt=yuv420p framesize=$(( width*height + 2*(width/2)*(height/2) )) # for 4:2:0, adjust for other formats for f in *.yuv; do size=$(stat -c%s "$f") if (( size % framesize != 0 )); then echo "Size mismatch: $f" continue fi yuvtools convert --width $width --height $height --format $pixfmt "$f" -o processed/"$f" done Common pitfalls and troubleshooting
- Wrong resolution: Causes scrambled frames; always confirm width/height.
- Incorrect format: Mis-specified chroma subsampling yields color distortions.
- Bit-depth mismatch: Leads to clipping or strange value ranges.
- Packed vs planar confusion: Produces garbage if wrong.
- Endianness issues on nonstandard files.
Use yuvtools info/stats first to detect obvious mismatches.
Integration with other tools
- ffmpeg: for encoding, decoding, and visualization; use yuvtools to prepare or verify raw data before ffmpeg processing.
- Python (numpy): read raw planes for custom analysis.
- ImageMagick: convert small extracted frames to common image formats.
Example Python read (conceptual):
import numpy as np w,h=1280,720 with open('frame0.yuv','rb') as f: Y=np.fromfile(f, dtype=np.uint8, count=w*h).reshape((h,w)) U=np.fromfile(f, dtype=np.uint8, count=(w//2)*(h//2)).reshape((h//2,w//2)) V=np.fromfile(f, dtype=np.uint8, count=(w//2)*(h//2)).reshape((h//2,w//2)) Example end-to-end workflow
-
Inspect file to determine dimensions and format: yuvtools info –width 3840 –height 2160 –format yuv420p bigfile.yuv
-
Extract a single frame to visually verify: yuvtools extract –frame 5 –width 3840 –height 2160 –format yuv420p bigfile.yuv -o frame5.yuv ffmpeg -f rawvideo -s 3840×2160 -pix_fmt yuv420p -i frame5.yuv -vframes 1 frame5.png
-
Batch convert to 8-bit and 4:2:0 with chroma filtering: see batch script above.
-
Run stats to ensure value ranges are valid: yuvtools stats –width 3840 –height 2160 –format yuv420p converted/*.yuv
Conclusion
YUVTools is a practical utility for anyone working with raw YUV video: testing encoder inputs, preparing datasets, and inspecting low-level pixel data. The key to success is carefully specifying format parameters (dimensions, chroma layout, bit depth, packing) and validating outputs with stats and sample visual checks. Use scripting and parallelization for large datasets, and combine YUVTools with ffmpeg and Python for flexible end-to-end pipelines.
Leave a Reply