企业官网建设流程全解析

• 音视频
• 移动开发

本文围绕 ExoPlayer 仓库中 testdata/src/test/assets/media/bitmap/sample_mp4_first_frame/electrical_colors/README.md 所声明的色彩空间约定展开，解释"期望首帧（expected first frame）"测试资产为何必须遵循 SMPTE 170M（即 BT.601 电信号颜色）编码，以及它如何被 Transformer 与 effect 模块的像素测试用作 golden 参照。读完本文，你将理解 Android 媒体管线中COLOR_TRANSFER_SDR_VIDEO的含义、电信号颜色与线性 RGB 的区别，并掌握为像素测试生成和更新 golden 图片的完整流程。

一、像素测试与"期望首帧"机制

在 ExoPlayer 的视频帧处理（VideoFrameProcessing）链路中，Transformer 负责把一组Effect应用到输入视频上并输出新文件。为了验证这些效果在像素层面是否正确，仓库采用了一种"golden 文件比对"测试策略：

1. 取一段已知内容的 SDR 测试视频，仅处理其第一帧；
2. 用DefaultVideoFrameProcessor渲染出实际输出帧；
3. 将实际帧与预先固化下来的"期望首帧"图片逐像素比对，计算平均绝对像素差（average pixel absolute difference），并断言其不超过阈值。

这套机制的入口是 library/effect/src/androidTest/java/com/google/android/exoplayer2/effect/DefaultVideoFrameProcessorPixelTest.java，其类注释明确写道：期望图片取自模拟器，因此在不同模拟器或真机上测试可能失败，必要时需调大 testutils/src/main/java/com/google/android/exoplayer2/testutil/BitmapPixelTestUtil.java 中的MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE（默认值为1f，即平均每个像素通道的绝对差不超过 1）。

而 testdata/src/test/assets/media/bitmap/README.md 则对这批资产的来源做了总述：它们是 Transformer 转换后的期望首帧，用于像素测试中对帧操作产出的验证。

二、为什么必须是 SMPTE 170M 颜色

关联文档 electrical_colors/README.md 的核心声明只有一句话：该目录下所有图片都处于SMPTE 170M 颜色（即 BT.601 色彩标准下的电信号颜色），并对照 AndroidMediaFormat文档中的COLOR_TRANSFER_SDR_VIDEO常数。

拆解这句话，它实际上锁定了三层色彩信息：

这一点在 library/common/src/main/java/com/google/android/exoplayer2/video/ColorInfo.java 中可以找到旁证：仓库为常见 SDR 视频定义了SDR_BT709_LIMITED = (COLOR_SPACE_BT709, COLOR_RANGE_LIMITED, COLOR_TRANSFER_SDR)，并注释其为"常见的 SDR 视频颜色格式"。而像素测试使用的输入源 testdata/src/test/assets/media/mp4/sample.mp4 在 library/transformer/src/androidTest/java/com/google/android/exoplayer2/transformer/AndroidTestUtil.java 中被描述为 H.264（avc1.64001F）、1080×720、29.97fps 的标准 SDR 视频，其色彩特性与 BT.601/BT.709 类 SDR 约定一致。

为什么必须在文档中显式声明这一点？因为像素比对是逐字节敏感的：同一帧画面若以线性 RGB 存储，其像素值会与电信号存储完全不同（前者做了电光逆变换，值普遍偏暗且分布在低端）。如果不固定 golden 文件的色彩编码，测试将既无法跨设备复现，也无法与 OpenGL 管线输出的数据对齐。

三、electrical 与 linear：两套 golden 集的对照

在sample_mp4_first_frame目录下并排放着两套语义不同的 golden 集，这正是理解本文档的关键背景：

• electrical_colors/：全部文件为SMPTE 170M 电信号颜色（COLOR_TRANSFER_SDR_VIDEO），即视频解码/编码链路中的原生表示；
• linear_colors/README.md：对应目录下所有文件为Linear RGB（COLOR_TRANSFER_LINEAR），即 OpenGL 着色器内部进行光照计算时所处的线性工作空间。

ExoPlayer 的 OpenGL 处理管线在内部会做"解码电信号 → 线性空间 → 效果计算 → 编码电信号"的转换，因此针对不同环节的像素测试必须使用匹配的 golden 色彩表示。linear_colors中存放的图片（如grayscale.png、invert.png、rotate_hue_by_60_degrees.png等）验证的是着色器在线性空间内的数值行为；而electrical_colors中存放的图片验证的是管线最终输出（回到电信号编码后）与参考实现的吻合度。

两套 README 都只有一句话，但恰恰是这种"一句话约定"保证了两个目录下数百 MB 的测试资产在解码语义上不会发生歧义。

四、golden 文件在源码中的实际引用

electrical_colors目录中的图片被多个测试类直接引用，可以在源码中逐一验证其角色：

• DefaultVideoFrameProcessorPixelTest.java：以original.png作为"无效果处理"的期望输出（noEffects_matchesGoldenFile），以scale_wide.png、translate_right.png、rotate_then_translate.png、rotate45_then_scale2w.png、crop_then_aspect_ratio.png、increase_brightness.png、grayscale_then_increase_red_channel.png等验证具体效果链；
• PresentationPixelTest.java：引用aspect_ratio_scale_to_fit_narrow/wide.png、aspect_ratio_scale_to_fit_with_crop_*.png、aspect_ratio_stretch_to_fit_*.png等，验证Presentation效果下不同宽高比策略的输出；
• DefaultVideoFrameProcessorTextureOutputPixelTest.java：引用original.png（SDR）、original_hdr10.png、original_hlg10.png，验证纹理输出路径下 SDR 与 HDR 输入的期望帧；
• ToneMapHdrToSdrUsingOpenGlPixelTest.java：配合media/mp4下的 HDR10/HLG 素材（hdr10-720p.mp4、hlg-1080p.mp4），以original_hdr10.png、original_hlg10.png验证 HDR 到 SDR 的色调映射结果。

这解释了electrical_colors目录中图片命名高度多样化的原因：rotate90.png、rotate_45_scale_to_fit.png、overlay_bitmap_default.png、overlay_bitmap_anchored.png、overlay_text_translate.png、request_output_height.png、tone_map_pq_to_sdr.png等 30 余张图片，恰好一一对应测试矩阵中的每一种效果组合，是"期望输出"的直接证据。

五、色彩转换链：sRGB 输入如何变成电信号输出

值得单独说明的是srgb_to_electrical_original.png与srgb_to_electrical_media3test.png两张特殊图片。它们被 DefaultVideoFrameProcessorMultipleTextureOutputPixelTest.java 使用：该测试以queueInputBitmap的方式把位图（Bitmap）直接送入帧处理器，而位图的色彩空间按 testdata/src/test/assets/media/bitmap/input_images/README.md 的约定是sRGB（IEC 61966-2-1，对应COLOR_TRANSFER_SRGB全范围）。

于是这里发生了一次关键的跨空间转换：sRGB 全范围位图 → 渲染 → 电信号（BT.601/BT.709 limited）输出。srgb_to_electrical_*两张 golden 文件正是用来断言这条转换链的数值正确性。从源码结构看，这印证了文档约定的真实用途：golden 文件的色彩空间声明，本质上定义了"输入色彩空间 → 输出色彩空间"这条转换链的终点，任何一端不明确，比对都失去意义。

六、如何生成与更新 golden 文件

testdata/src/test/assets/media/bitmap/README.md 给出了在本地重新生成"期望"资产的标准流程，共三步：

1. 启动与预提交（presubmit）环境一致的模拟器，要求 API level 33、x86 架构，例如：

   crow --device generic_phone --api_level 33 --arch x86

2. 运行对应的像素测试，测试失败时会把实际输出位图保存到设备缓存目录；
3. 从设备拉取生成的文件到 assets 目录，例如将rotate90的实际输出更新为新的期望文件：

   adb pull \ /sdcard/Android/data/com.google.android.exoplayer2.effect.test/cache/drawFrame_rotate90.png \ testdata/src/test/assets/media/bitmap/sample_mp4_first_frame/electrical_colors/rotate90.png

需要强调的是：由于 golden 图片来自特定模拟器，跨设备比对天然存在渲染差异。BitmapPixelTestUtil为此提供了两档阈值——同设备标准MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE（1.0）与跨设备放宽阈值MAXIMUM_AVERAGE_PIXEL_ABSOLUTE_DIFFERENCE_DIFFERENT_DEVICE（含 FP16 变体），后者用于纹理输出、HDR 色调映射等渲染路径差异较大的测试。若在非标准模拟器上运行失败，正确做法是参考 README 所述"增大阈值或检查保存的输出位图"，而不是盲目修改 golden 文件。

七、总结：一份两行 README 背后的工程约定

electrical_colors/README.md虽只有一句话，却是整套像素测试体系的"色彩契约"：

• 对测试作者：它规定新提交的 golden 图片必须以 SMPTE 170M（COLOR_TRANSFER_SDR_VIDEO）编码，与linear_colors的线性 RGB 集明确区分，避免两类资产混用导致比对失真；
• 对测试运行：它与 AndroidTestUtil.java 中定义的 SDR 输入素材格式、ColorInfo.java 中COLOR_TRANSFER_SDR等常量相互印证，构成"输入格式 + 色彩空间 + 期望输出"的完整闭环；
• 对阅读者：理解 BT.601/BT.709 电信号颜色与线性 RGB 的区别，是调试 OpenGL 视频效果（亮度、对比度、HSL、LUT、色调映射）数值偏差的前提。

当你下次看到某个像素测试因"平均像素绝对差超标"而失败时，不妨先回到这份 README：确认比对双方的色彩空间契约是否一致——很多时候，问题不在效果算法，而在颜色约定。

• 音视频
• 移动开发