屏幕录制

android.display.video 数据源会记录 trace 采集期间每个物理屏幕 显示的内容。Perfetto 将帧作为编码后的视频流存储在 trace 中,UI 会 添加每个屏幕的时间线 track,在浏览器中解码它们。你可以悬停在 track 上预览帧、像播放视频一样回放帧,以及点击任意帧将其与下方的 track 对齐。

它会录制屏幕的实际内容,因此任何包含此内容的 trace 都是敏感的:它精确地显示了屏幕上的内容。在 userdebug(debuggable)设备上,它可以开箱即用。在 user(production)build 上,它默认被禁用,必须先用一个 system property 解锁 — 参见 user build 的前提条件。

本指南涵盖:

工作原理及成本

在数据源启用期间,设备将每个屏幕显示的内容编码为视频流并存储在 trace 中 — 屏幕每次变化产生一帧 — UI 在浏览器中将其解码回来。 这有两方面成本:

当数据源关闭时,零成本。

采集屏幕视频

有三种方式开启屏幕视频采集,从最简单到最多控制。在 user build 上,还需要先设置一个每次启动只需设置一次的 property — 参见下方的前提条件。

user build 的前提条件

在 userdebug(debuggable)设备上,屏幕视频采集开箱即用,你可以跳过此步骤。在 user(production)build 上,它默认被禁用:首先通过 ADB 设置一个 system property 来解锁。

adb shell setprop debug.tracing_video_allowed true

此 property 不是持久化的 — 下次重启时会被清除。设备重启后,你必须再次设置它才能采集屏幕视频。一旦设置,以下任何方式都可以采集:设备端开关、录制页面或原始配置。

在设备上,使用 System Tracing

System Tracing 应用在 Trace settings 下有一个 Record display video 开关。启用它,然后像往常一样录制 trace — 采集会自动包含 在内。这是在你手中的设备上最快的方式 — 无需编写配置。

System Tracing 应用的 Trace 设置中启用的 "Record display video" 开关,描述为 "Captures encoded display frames (adds encoder overhead, can cause jank, and records screen contents)"。

从录制页面

打开 Perfetto UI 录制页面,在 Android probes 下找到 Display video frames,然后启用它。这会使用 producer 的默认设置将 android.display.video 数据源添加到生成的配置中。

Perfetto 录制页面,侧边栏选中 "Android apps & svcs";"Display video frames" probe 位于 probe 列表中,关闭状态,标题为 "Captures what each display showed during the trace."

从原始 trace 配置

要获得完全控制,自行编写配置。启用 android.display.video, 并添加 display_video_config 来设置质量和大小。不带选项时, 每个屏幕使用设备的默认设置:

data_sources { config { name: "android.display.video" } }

添加 display_video_config 来调优采集。每个字段都是可选的; 未设置或为零的字段使用 producer 默认值。

data_sources { config { name: "android.display.video" display_video_config { scale: 0.5 format: FORMAT_H264 key_frame_interval_secs: 2 bitrate_bps: 8000000 # 8 Mbps max_stream_size_bytes: 67108864 # 64 MiB per display } } }
选项 描述
scale 采集前应用于每个屏幕分辨率的比例因子,例如 0.5 为一半大小或 0.25 为四分之一。较低的比例意味着更少的编码器负载和更小的 trace,但会牺牲细节。
format FORMAT_H264(默认)或 FORMAT_HEVC。HEVC 在相同质量下产生更小的流,但设备必须支持 HEVC 编码才能采集,浏览器必须支持 HEVC 解码才能预览。
key_frame_interval_secs 关键帧的发射频率。较小的值使定位更流畅但增大 trace;较大的值更紧凑但拖拽较慢。
bitrate_bps 目标编码器 bitrate,单位为 bit/s。Trace 大小大致等于 bitrate × 时长,因此这在固定分辨率下权衡质量与大小(与 scale 不同,后者会降低分辨率)。未设置时,设备使用默认值。
max_stream_size_bytes 每个屏幕的发送字节数上限。当屏幕达到上限时,其流被拆除(记录大小上限错误),而非无限增长。未设置时,设备默认每屏幕 256 MiB 的上限。

大小限制

屏幕视频每屏幕限制为 256 MiB,在两个独立的位置强制执行:

在长会话或高分辨率下,视频因此可能在 trace 结束之前停止。这两个限制 都源自保存流的存储成本,而非根本性约束。如果它们妨碍到你,请在跟踪 issue 上评论和点赞以便进行优先级排序: perfetto#6609。

查看屏幕视频

时间线 Track

包含屏幕视频的 trace 会显示一个 Video Frames 分组,每个屏幕有 一个 track(对于手机,通常是一个 Built-in Screen)。Track 上的 每个 slice 是一个采集的帧,标有帧号。该编号仅是采集帧的顺序计数器 — 与帧时间线中的 vsync ID 无关。与产生该帧的 SurfaceFlinger composite 相关联的帧,会改标为该 composite 的 vsync ID (例如 vsync 123456);参见将帧关联到帧时间线。

Perfetto 时间线,顶部固定了 "Video Frames" 分组的 "Built-in Screen" track — 一行彩色 slice,标注为 Frame 30、Frame 57 等 — 位于 CPU 调度 track 之上。

悬停预览帧

沿 track 移动指针即可预览帧。光标下的帧被解码并显示为该行上方的 缩略图,因此你可以拖拽寻找想要的帧。

沿 video-frames track 滑动光标;光标下帧的解码缩略图随之在行上方移动,随光标移动而更新。

回放

点击一个帧打开其详情。面板左侧显示帧号和时间戳,右侧显示解码的 Preview,页眉中有播放控件:上一帧、播放/暂停、下一帧和播放速度 选择器。按下播放,采集内容像视频一样播放:预览逐帧前进,时间线选择 也随之前进,因此 UI 其余部分始终保持与屏幕上内容对齐。使用上一帧/ 下一帧按钮逐帧前进,或更改速度选择器以更慢(最低 0.1×)或更快 (最高 2×)地回放。

回放屏幕视频采集,video-frames track 固定在顶部:详情面板中解码的预览从设置屏幕前进到启动器,同时帧号和时间戳更新。

从命令行导出为 .mp4

python/tools/trace_video_conv.py 使用 ffmpeg 的 libav 将 trace 中捕获的视频提取为 .mp4(编码后的帧按原样复制,不会重新编码)。它需要 PyAV 包(pip install av),另外使用 --compare 以及处理需要填充无帧间隙的片段时还需要 PATH 中有 ffmpeg;trace_processor 会自动下载,或传递 --trace-processor 以使用本地构建。

# 列出 trace 中的视频流。 python3 python/tools/trace_video_conv.py TRACE.perfetto-trace --list # 将整个视频转换为 .mp4。 python3 python/tools/trace_video_conv.py TRACE.perfetto-trace -o out.mp4 # 剪辑到时间范围(trace ts,纳秒),或剪辑到查询选择的任何内容 # (查询返回 `ts` 列,以及可选的 `dur`)。 python3 python/tools/trace_video_conv.py TRACE.perfetto-trace -o clip.mp4 --start <ts> --end <ts> python3 python/tools/trace_video_conv.py TRACE.perfetto-trace -o clip.mp4 \ --query "SELECT ts, dur FROM slice WHERE name = 'my_cuj'" # 慢动作(0.5x)或 2 倍快放。 python3 python/tools/trace_video_conv.py TRACE.perfetto-trace -o out.mp4 --speed 0.5 # 两个 trace 并排,每个都带标题(默认为文件名)。 python3 python/tools/trace_video_conv.py before.perfetto-trace --compare after.perfetto-trace \ -o compare.mp4 --title Before --title2 After
选项 描述
-o, --output 输出 .mp4 路径。
--list 列出 trace 的视频流并退出。
--display-id 用于多显示器 trace 时选择哪个流。
--start, --end 剪辑到时间范围,单位为 trace ts 纳秒。
--query 剪辑到 SQL 查询选择的区域(返回 ts,可选 dur)。
--speed 输出播放速度:2 = 两倍速,0.5 = 慢动作。
--compare 第二个 trace,放在右侧进行并排比较。
--display-id2 用于 --compare trace 的流选择。
--start2, --end2 剪辑 --compare trace 的时间范围。
--query2 剪辑 --compare trace 的 SQL 选择区域。
--title, --title2 第一个和第二个视频的标题(默认:文件名)。
--trace-processor 本地 trace_processor 构建路径(否则会自动下载)。

将帧关联到帧时间线

每个采集的帧都可以关联到产生它的 SurfaceFlinger composite,并经由它 关联到该 vsync 的帧时间线。这个 关联来自 SurfaceFlinger 的 android.surfaceflinger.virtualdisplay 数据源:它为每个排队到虚拟显示器的 composite 发出一个 packet,其中带有 该 composite 的 vsync ID 以及打在所排队 buffer 上的呈现时间。编码器 通常会把该呈现时间原样传递为帧的呈现时间,因此 trace_processor 将两者 匹配,并把 vsync ID 存入 __intrinsic_video_frames 的 frame_timeline_vsync_id 列。

在采集的同时启用它,并一起启用这些关联所指向的帧时间线:

data_sources { config { name: "android.display.video" } } data_sources { config { name: "android.surfaceflinger.virtualdisplay" } } data_sources { config { name: "android.surfaceflinger.frametimeline" } }

虚拟显示器数据源仅在设备的 SurfaceFlinger 启用了 com.android.graphics.surfaceflinger.flags.virtual_display_composite_tracing flag 时才可用。若未启用,帧仍会照常采集,但保持未关联状态。

在 UI 中,已关联的帧在视频 track 上标有其 vsync ID。视频帧的详情会显示 Frame timeline vsync id,它链接到帧时间线上的 SurfaceFlinger DisplayFrame,并列出被合成到其中的各个应用帧,每个都链接到对应应用的 帧。反方向地,当某个 vsync 产生了一个已采集的帧时,在 Actual Timeline track 上选择一个 slice 会显示一个 Display video 小节, 其中带有 Jump to video frame 链接。

当没有 composite 具有该帧的呈现时间时(例如因为编码器调整了时间戳), 或者当具有不同 vsync ID 的 composite 共享同一呈现时间时,该帧保持未 关联。android_video_vsync_composite_unmatched 统计项统计没有匹配视频 帧的 composite,而 android_video_vsync_present_time_ambiguous 统计 映射到相互冲突的 vsync ID 且匹配到了某个帧的呈现时间。composite packet 中的 display ID 是 SurfaceFlinger 为虚拟显示器分配的 ID,与 视频流的 display ID 无关,因此呈现时间是这一匹配可以使用的唯一键。