YUV裸流查看器实战：帧切分、stride对齐与颜色排查

简介：YUV_Viewer 是一款面向图像处理、视频编码学习者与开发者的 YUV 数据查看工具，主要用于打开并显示采集到的 YUV422 与 YUV420 图像文件，帮助读者直观核对原始数据效果、调试视频处理算法并观察两种色度采样格式的差异；前者两相邻像素共享色度分量，后者进一步降低色度分辨率，适合在实验中对照理解。压缩包共 16 个文件，约 553KB，内含 h 与 cpp 源码、yuv 样本数据、exe 可执行程序，以及 vcproj、sln 工程配置和 txt 说明文档，既可直接运行，也便于研读实现。已有 381 人学习下载。借助随包源码与样例，读者可梳理 YUV 文件的读取、显示与色彩空间转换流程，并参考亮度、对比度、缩放、像素测量等功能的实现，用于视频编码实验、图像质量检查和二次开发入门，可作为课程设计、算法验证与采集数据核验的辅助工具。

1. 为什么裸 YUV 值得单独做个查看器：从「能打开」到「看得对」

拿到一段后缀是.yuv的文件，双击打不开，拖进播放器只显示黑屏，用十六进制编辑器看又是一大片没有边界的数据——这是查看YUV文件时最常见的第一个跟头。反直觉的地方在于：能显示不等于看得对，宽高、像素格式、stride 任意一个参数填错，画面都能“看起来有图像”，但颜色、边缘和帧序已经错了。YUV_Viewer 这类工具的价值不是多一个播放器，而是把裸数据缺少的头信息显式摆到参数面板上，让你用已知图案把显示链路校准。适合做图像算法、编解码、摄像头调试的人。

2. 拆开显示链路：I420、NV12、YUYV 的帧切分与 stride 对齐

2.1 YUV 文件的「三无」本质：无头、无宽高、无帧率

YUV 裸流和 MP4、MKV 这类容器文件最大的区别，是它没有文件头。没有 magic number，没有宽高字段，没有帧率，也没有色彩矩阵标记。文件里只有按某种排列堆起来的 Y、U、V 字节。查看器打开文件时，第一件事不是“解码”，而是按你给的参数把字节流切成帧，再把 YUV 转成 RGB 显示出来。

这意味着一个很现实的后果：同一段文件，用 1920×1080 的 I420 去读，和用 1280×720 的 NV12 去读，都能出图。前者可能是对的，后者可能只是“看起来像一张图”。如果宽高填错，画面会斜切、重复、比例失真；如果格式填错，颜色会整体偏绿、偏紫，或者把亮度当成色度。YUV_Viewer 的界面通常会把 width、height、format、frame count、offset、stride 这几个参数摆出来，不是为了让你多填几步，而是因为裸流本来就没有这些信息，必须由外部补上。

我一般会先确认三件事：这段流是不是纯 YUV，有没有自定义头；宽高是不是偶数，尤其是 4:2:0；文件大小能不能被单帧大小整除。三件事对上了，再谈颜色准不准。否则后面调色彩矩阵都是白费力气。

2.2 从 planar 到 packed：I420/NV12/YV12/YUYV 的排布差异

YUV 的格式名字很多，但落到字节排列上，先分两大类：planar 和 packed。planar 是把 Y 存成一块，U 存成一块，V 存成一块；packed 是把 Y、U、V 交错在同一个像素组里。查看器如果只支持其中一种，另一种就会被读成花屏，或者出现很规律的斜纹。

最容易混淆的是 I420 和 YV12：两者都是三平面，区别只是 U、V 平面的先后顺序。NV12 和 NV21 也一样，都是 Y 平面后面跟一个交错平面，区别是 UV 还是 VU。很多“颜色发绿”的现场，不是色彩矩阵错了，而是把 NV12 当成了 NV21，或者把 I420 当成了 YV12。先切格式，再看颜色，顺序不能反。

packed 格式的坑在另一个地方：它的“每像素字节数”不是 1.5，而是 2。把 YUYV422 当成 I420 读，第一帧还能勉强看出轮廓，第二帧开始就完全错位，因为帧大小算少了。查看器如果支持格式下拉框，切换一次就能验证；如果不支持，只能靠脚本先转成它认识的格式。

2.3 帧切分与 stride 对齐：最容易看错的两行参数

裸 YUV 的帧切分看起来简单：算出单帧字节数，然后按这个大小往后读。真正容易翻车的是 stride。逻辑宽度是 1920，不代表每一行只占 1920 字节。摄像头、编码器、GPU 纹理经常把行对齐到 16、32、64 甚至 256 字节，多出来的部分叫 padding。你按 1920 去切，第一行就偏了，后面每一行都会跟着偏，画面就会出现斜切或者右侧重复。

我通常用下面这个函数先核对帧大小，参数不多，但每个都对应一个现场问题：

def frame_size(width, height, fmt, y_stride=None, uv_stride=None): """返回单帧字节数；stride 默认等于逻辑宽度。""" y_stride = y_stride or width uv_stride = uv_stride or (width // 2) fmt = fmt.lower() if fmt in ("i420", "yv12", "nv12", "nv21"): # 4:2:0：Y 占满，UV 各占 1/4；stride 可能大于逻辑宽高 y_size = y_stride * height uv_size = uv_stride * (height // 2) return y_size + uv_size * 2 if fmt in ("yuyv", "yuy2", "uyvy"): # packed 4:2:2：每 2 个像素占 4 字节 return y_stride * height * 2 if fmt == "yuv444": return y_stride * height * 3 raise ValueError(f"unsupported format: {fmt}")

width和height是逻辑分辨率，也就是你希望在查看器里看到的画面大小；y_stride是 Y 平面每一行实际占用的字节数；uv_stride是 UV 平面每一行实际占用的字节数。4:2:0 的 UV 平面宽高都是 Y 的一半，所以默认uv_stride取width // 2。如果采集端给的是 2048 对齐，那y_stride要填 2048，uv_stride也要按实际对齐值填，不能继续用 960。

有了帧大小，切帧就是顺序读：

def iter_frames(path, width, height, fmt, y_stride=None, uv_stride=None, limit=None): size = frame_size(width, height, fmt, y_stride, uv_stride) with open(path, "rb") as f: index = 0 while True: buf = f.read(size) if len(buf) < size: break yield index, buf index += 1 if limit and index >= limit: break

这段代码里，size必须和文件实际排布一致，否则f.read(size)每次都会从错误的位置开始。limit只用于快速看前几帧，不参与帧大小计算。如果文件带自定义头，比如某些设备会在前面加几十字节的私有信息，就要在打开文件后先seek(offset)，或者在读取时跳过offset。查看器里的 offset 参数就是干这个的，不是用来“微调颜色”的。

3. 把 YUV_Viewer 跑起来：依赖、启动参数与第一帧验证

3.1 运行环境与依赖清单

如果拿到的是打包好的可执行文件，直接运行即可，依赖部分可以跳过。如果拿到的是源码，先看入口脚本和requirements.txt，不要急着全局装包。我一般会新建一个虚拟环境，把依赖隔离在项目目录里，避免和系统里的其他版本打架。

python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install -r requirements.txt

这段命令做三件事：创建虚拟环境、激活环境、安装依赖。source那一行在 Windows 上不适用，换成注释里的激活脚本。虚拟环境的好处是，查看器依赖的数组库和图像库版本不会污染其他项目。装完之后先跑一次入口脚本的--help或者直接启动界面，确认没有报缺库，再开始填参数。

常见依赖一般包括数值数组库、图像读写库，如果查看器带界面，还会有 GUI 框架。检查方式不是看版本号，而是看能不能 import：

python -c "import numpy, PIL; print('deps ok')"

能打印deps ok就说明基础链路通了。如果报ModuleNotFoundError，先回到requirements.txt看包名，不要凭记忆猜。

3.2 参数怎么填：宽高、格式、偏移与帧数

查看器打开文件时，参数面板里最关键的几项如下。不同资源的字段名可能略有差异，认准含义即可：

帧数不要手填，先算。公式是(文件大小 - offset) // 单帧大小。余数如果不为 0，要么 offset 不对，要么帧大小算错，要么文件尾部有附加信息。下面这段脚本可以在打开查看器之前先跑一遍：

import os w, h = 1920, 1080 frame_size = w * h * 3 // 2 path = "clip.yuv" size = os.path.getsize(path) print("frame_size", frame_size) print("frames", size // frame_size) print("tail bytes", size % frame_size)

frame_size是按 I420 紧密排列算的，tail bytes是除不尽的余数。余数为 0 不代表格式一定对，但余数很大时一定有问题。比如 1920×1080 的 I420 单帧是 3110400 字节，文件大小除以它余了几百字节，先怀疑 offset，再怀疑格式。查看器里如果显示的总帧数和这个脚本算出来的差一帧，通常是最后一帧不完整被丢掉了，不一定是工具 bug。

3.3 用一张已知色卡验证颜色顺序

填完参数不要直接拿业务流看，先用一张自己生成的已知图案验证。灰度阶梯图可以同时验证宽高、帧切分和 Y 平面；UV 四象限图可以验证 U、V 顺序。先看灰度，再看颜色，排查范围会小很多。

import numpy as np w = h = 16 y = np.zeros((h, w), dtype=np.uint8) for i, val in enumerate([16, 81, 145, 235]): y[:, i * 4:(i + 1) * 4] = val u = np.full((h // 2, w // 2), 128, dtype=np.uint8) v = np.full((h // 2, w // 2), 128, dtype=np.uint8) with open("gray_16x16_i420.yuv", "wb") as f: f.write(y.tobytes()) f.write(u.tobytes()) f.write(v.tobytes())

这段代码生成一个 16×16 的 I420 文件，Y 平面是四根竖条，灰度从暗到亮，U、V 都置为 128，也就是中性色度。用查看器打开时，宽高填 16 和 16，格式选 I420，帧数 1。正常应该看到四根竖条从左到右变亮。如果竖条变成横条，宽高填反了；如果竖条带颜色，说明 UV 不是中性值，或者格式不是 I420。

再用四象限验证 U、V 顺序：

y = np.full((h, w), 128, dtype=np.uint8) u = np.full((h // 2, w // 2), 128, dtype=np.uint8) v = np.full((h // 2, w // 2), 128, dtype=np.uint8) u[:h // 4, :w // 4] = 192 # 左上：提高 Cb，偏蓝 v[:h // 4, w // 4:w // 2] = 192 # 右上：提高 Cr，偏红 u[h // 4:h // 2, :w // 4] = 64 # 左下：降低 Cb，偏黄 v[h // 4:h // 2, w // 4:w // 2] = 64 # 右下：降低 Cr，偏青 with open("uv_16x16_i420.yuv", "wb") as f: f.write(y.tobytes()) f.write(u.tobytes()) f.write(v.tobytes())

打开后看四个象限的冷暖方向：左上偏蓝、右上偏红、左下偏黄、右下偏青。如果左上出现红色而不是蓝色，说明 U、V 平面接反了，优先检查是不是把 I420 当成了 YV12，或者把 NV12 当成了 NV21。这个测试图不依赖具体色彩矩阵，只看方向，足够判断顺序。

4. 批量看序列与导出：帧索引、PNG 对比和测试流生成

4.1 帧索引、播放与步进

单帧看对了，接下来才是序列。查看器一般会提供帧索引、上一帧、下一帧、播放和暂停。帧索引从 0 开始还是从 1 开始，不同工具不一样，但文件偏移一定按 0 算。比如界面显示第 10 帧，实际 seek 的偏移是9 × frame_size。这一点在写脚本核对时很容易差一帧，表现就是“查看器里第 10 帧和脚本导出的第 10 帧对不上”。

我习惯先用脚本把某一帧的 Y 平面单独导出来，和查看器里看到的亮度对一遍。Y 平面不涉及 UV 转换，出问题最容易定位：

import numpy as np from PIL import Image def read_i420_y(path, width, height, index): frame_size = width * height * 3 // 2 with open(path, "rb") as f: f.seek(index * frame_size) y = np.frombuffer(f.read(width * height), dtype=np.uint8) return y.reshape(height, width) y = read_i420_y("clip.yuv", 1920, 1080, 10) Image.fromarray(y, mode="L").save("clip_frame010_y.png")

seek(index * frame_size)把文件指针移到目标帧开头，read(width * height)只读 Y 平面，reshape(height, width)还原成图像。这里没有处理 stride，所以只适用于紧密排列的 I420。如果采集端有行对齐，要先按y_stride * height读，再切片取前width列。导出的灰度图可以用来检查边缘、纹理和块效应，不受颜色转换干扰。

4.2 导出 PNG 与对比截图

查看器里看到的颜色是转换后的结果，真正要定位问题时，最好把 Y 平面和 UV 平面分开看。Y 平面看结构和噪声，UV 平面看色度块和颜色溢出。很多编码问题在 RGB 截图里不明显，回到 YUV 平面反而一眼能看出来。

如果是两段流对比，比如原始流和编码后解码流，不要只靠肉眼切换。可以用 Y 平面算 PSNR，先给一个数值结论，再用查看器看差异区域：

import numpy as np def psnr(a, b): mse = np.mean((a.astype(np.float32) - b.astype(np.float32)) ** 2) if mse == 0: return 99.0 return 10 * np.log10(255 ** 2 / mse) # a、b 是同一帧的 Y 平面，形状一致 # print(psnr(a, b))

a和b必须是同一帧、同一分辨率、同一裁剪范围。PSNR 高不代表颜色一定对，但 PSNR 突然掉到很低，说明这一帧的结构已经偏了，先查帧对齐，再查格式。查看器负责“看”，脚本负责“给数”，两边对得上才靠谱。

4.3 用脚本批量生成测试流

业务流不方便反复试参数时，自己生成一段已知运动的测试流更直接。下面这段代码生成 30 帧 I420，每帧一个白色方块横向移动，背景是深灰。用查看器步进时，方块应该逐帧右移，不应该跳帧、回退或者出现残影。

import numpy as np w, h, n = 320, 240, 30 with open("moving_square_i420.yuv", "wb") as f: for i in range(n): y = np.full((h, w), 16, dtype=np.uint8) x = (i * 8) % (w - 40) y[80:160, x:x + 40] = 235 u = np.full((h // 2, w // 2), 128, dtype=np.uint8) v = np.full((h // 2, w // 2), 128, dtype=np.uint8) f.write(y.tobytes()) f.write(u.tobytes()) f.write(v.tobytes())

w、h是分辨率，n是帧数，x是方块左上角横坐标，i * 8控制每帧移动 8 像素。方块大小是 40×80，所以取模用w - 40，避免越界。这个流只有亮度变化，UV 保持中性，适合验证帧切分和播放顺序。如果查看器里方块移动方向反了，先看帧索引是不是递减；如果方块边缘出现绿色或紫色，说明 UV 被误读了，回到格式设置。

5. 避坑与排查：颜色发绿、画面斜切、帧数不对的五个现场

5.1 现象：整体偏绿或偏紫，肤色明显不对

现象很直观：人脸发绿，天空发紫，或者画面整体像蒙了一层色纸。原因通常是 U、V 顺序错了，常见于 NV12 和 NV21 互换、I420 和 YV12 互换。另一种原因是色彩矩阵或量化范围不匹配，比如把 limited range 当成 full range，表现更多是对比度发灰，而不是色相跑偏。

解决顺序是先格式、后矩阵。用上一节的 UV 四象限图，确认左上是不是蓝色、右上是不是红色。如果方向反了，切换格式，不要先调饱和度。方向对了但肤色仍偏，再检查查看器有没有 BT.601 / BT.709 的选项，以及 limited / full 的选项。很多现场把“颜色不对”全归咎于矩阵，实际上第一步的平面顺序就错了。

5.2 现象：画面斜切、右侧重复，边缘有规律噪点

现象是图像像被斜着推了一段，右边出现一条重复的竖条，或者每一行都向右错一点。原因几乎都是 stride 不等于 width，但查看器按 width 切行。采集端为了对齐，可能把 1920 的行宽补到 2048，你按 1920 去读，每一行都会少读 128 字节，下一行就从错误的位置开始。

解决办法是填真实 stride，或者先用工具把流重排成紧密排列。重排时注意 UV 平面的 stride 也要一起处理，不能只改 Y。一个快速判断方法是看画面斜切的角度是否固定：固定斜切通常是 stride 问题，随机花屏更像是格式或帧大小问题。如果查看器没有 stride 输入框，就先转成紧密排列的 I420 再看，不要在原始流上硬调。

5.3 现象：只能看第一帧，步进就花屏或错位

第一帧正常，点下一帧就错位，说明单帧大小算错了。常见原因有三个：宽高是奇数，但按 4:2:0 算；把 YUYV422 当成了 I420；把 10bit 数据当成了 8bit。4:2:0 要求宽高都能被 2 整除，奇数宽度会让 UV 平面大小出现半个像素，不同工具的处理方式还不一样，很容易错位。

解决时先跑帧大小脚本，看文件大小能不能被单帧大小整除。余数很大，就换一个格式再算一次。比如同一段文件按 I420 算余 100 字节，按 YUYV422 算余 0，那它大概率是 packed 格式。不要忽略“最后一帧不完整”的情况，有些文件尾部带附加信息，查看器会丢掉最后一点数据，帧数看起来少一帧，但不影响前面的帧。

5.4 现象：10bit 文件发灰，高光一片白，暗部并阶

10bit 的 YUV 经常不是按 10bit 紧凑存储，而是每个分量放在 16bit 容器里，低 2 位补零或者放低位数据。查看器如果按 8bit 读，会把这些字节当成亮度，画面就会发灰、对比度异常，细节像被压平。另一种情况是字节序反了，读出来的值忽大忽小。

先看原始值的范围：

import numpy as np raw = np.frombuffer(open("clip_10bit.yuv", "rb").read(), dtype="<u2") print(raw.min(), raw.max())

如果最大值在 1023 附近，说明是 10bit 存在 16bit 容器里；如果最大值到 65535，可能是 16bit 数据或者字节序不对。查看器如果有 10bit / 16bit 选项，直接选；没有的话，读入后右移 2 位再显示。注意右移前不要做饱和裁剪，否则高光会提前截断。

5.5 现象：大文件一打开就卡死，内存飙高

几 GB 的 YUV 一次性读进内存，界面很容易卡死。原因不是文件太大，而是读取方式太粗。查看器如果每次都把整个文件读成字节数组，再切片显示，内存占用会随着文件大小线性上涨。解决方式是内存映射或者按帧读取，只保留当前帧和前后几帧缓存。

import mmap with open("clip.yuv", "rb") as f: mm = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ) frame = mm[index * frame_size:(index + 1) * frame_size]

mmap把文件映射到虚拟内存，读取时按页加载，不会一次性占满物理内存。frame是当前帧的字节切片，用完就可以释放。如果查看器本身不支持内存映射，至少避免在步进时重复打开文件，把文件句柄和帧大小缓存起来，也能减少卡顿。

6. 进阶用法：用参考流和哈希把查看器接进调试链

查看器最容易停在“看一眼，觉得没问题”这一步。真正省时间的做法，是把它接进一条固定检查链：先用参考流确认参数，再用哈希定位第一帧差异，最后才用肉眼看看差异区域。

我通常先用常见视频工具生成一段已知参数的参考 YUV，再用下面的脚本算每一帧的哈希。原始流和解码流逐帧对比，第一个哈希不同的帧就是问题起点，不用从第 1 帧开始盲看到第 300 帧。

import hashlib def frame_md5(path, frame_size, index): with open(path, "rb") as f: f.seek(index * frame_size) return hashlib.md5(f.read(frame_size)).hexdigest() frame_size = 1920 * 1080 * 3 // 2 print(frame_md5("ref.yuv", frame_size, 0)) print(frame_md5("out.yuv", frame_size, 0))

frame_size必须先按真实格式算对，index从 0 开始。两个哈希一致，说明这一帧字节级相同；不一致再回到查看器里看 Y 平面和 UV 平面，判断是亮度偏了还是色度偏了。哈希不告诉你“哪里错”，但能告诉你“从哪一帧开始错”，这比肉眼找帧快得多。

我的固定检查链是：先算帧大小和尾部余数，再用灰度阶梯图验证宽高和格式，再用 UV 四象限验证平面顺序，最后用参考流哈希定位第一帧差异。从那以后我每次拿到新的 YUV 流都强制走一遍，不再靠“看起来差不多”下结论。希望帮到你。

本文还有配套的精品资源，点击获取