屏幕录制
android.display.video 数据源会记录 trace 采集期间每个物理屏幕 显示的内容。Perfetto 将帧作为编码后的视频流存储在 trace 中,UI 会 添加每个屏幕的时间线 track,在浏览器中解码它们。你可以悬停在 track 上预览帧、像播放视频一样回放帧,以及点击任意帧将其与下方的 track 对齐。
它会录制屏幕的实际内容,因此任何包含此内容的 trace 都是敏感的:它精确地显示了屏幕上的内容。在 userdebug(debuggable)设备上,它可以开箱即用。在 user(production)build 上,它默认被禁用,必须先用一个 system property 解锁 — 参见 user build 的前提条件。
本指南涵盖:
- 工作原理及成本 — 帧如何进入 trace,以及对设备的开销。
- 采集屏幕视频:首先在
userbuild 上设置 property, 然后三种开启方式 — 设备端开关、录制页面以及可完全控制质量和大小的原始配置。 - 查看屏幕视频:时间线 track、 悬停预览帧以及保持时间线同步地回放采集内容。
- 将帧关联到帧时间线: 将每个采集的帧与产生它的 SurfaceFlinger vsync 匹配。
工作原理及成本
在数据源启用期间,设备将每个屏幕显示的内容编码为视频流并存储在 trace 中 — 屏幕每次变化产生一帧 — UI 在浏览器中将其解码回来。 这有两方面成本:
- 编码器和 CPU 开销。在 trace 运行期间,编码帧使用设备的视频 编码器。在繁忙的屏幕上这会增加负载,并可能干扰你正在测量的时序。
- Trace 大小。视频流随分辨率和屏幕变化量而增长;下面的
scale和max_stream_size_bytes选项可以控制其大小上限。
当数据源关闭时,零成本。
采集屏幕视频
有三种方式开启屏幕视频采集,从最简单到最多控制。在 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 — 采集会自动包含 在内。这是在你手中的设备上最快的方式 — 无需编写配置。

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

从原始 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
max_stream_size_bytes: 67108864
}
}
}| 选项 | 描述 |
|---|---|
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,在两个独立的位置强制执行:
- 在设备端,
max_stream_size_bytes限制每个流的发送量(默认 256 MiB; 达到限制时记录大小上限错误)。 - 独立地,trace_processor 在加载 trace 时丢弃每个流超过 256 MiB 的 任何帧,因此仅提高设备端上限不会在 UI 中获得更多帧。
在长会话或高分辨率下,视频因此可能在 trace 结束之前停止。这两个限制 都源自保存流的存储成本,而非根本性约束。如果它们妨碍到你,请在跟踪 issue 上评论和点赞以便进行优先级排序: perfetto#6609。
查看屏幕视频
时间线 Track
包含屏幕视频的 trace 会显示一个 Video Frames 分组,每个屏幕有
一个 track(对于手机,通常是一个 Built-in Screen)。Track 上的
每个 slice 是一个采集的帧,标有帧号。该编号仅是采集帧的顺序计数器
— 与帧时间线中的 vsync ID 无关。与产生该帧的 SurfaceFlinger
composite 相关联的帧,会改标为该 composite 的 vsync ID
(例如 vsync 123456);参见将帧关联到帧时间线。

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

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

从命令行导出为 .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 无关,因此呈现时间是这一匹配可以使用的唯一键。