argent-screen-recording

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

1. Tools

1. 工具

```
screen-recording-start
```
— start capturing the screen of a booted device to a video file. Frames come from the same simulator-server backend that
```
screenshot
```
and the interaction tools already use, and are encoded live to h264 mp4 (constant 30 fps, device-native resolution).
```
screen-recording-stop
```
— stop the capture, finalize the container, and retrieve the video as a downloadable artifact (
```
video.hostPath
```
for co-located clients).

One recording per device at a time; different devices can record concurrently. Recording does not disturb anything else reading the device — a preview window can stay open on the same screen.

```
screen-recording-start
```
— 开始将已启动设备的屏幕捕获为视频文件。画面来自与
```
screenshot
```
和交互工具相同的simulator-server后端，并实时编码为h264格式的mp4文件（恒定30帧/秒，设备原生分辨率）。
```
screen-recording-stop
```
— 停止捕获，完成容器封装，并将视频作为可下载工件返回（对于本地客户端，可通过
```
video.hostPath
```
获取）。

同一时间每个设备仅支持一个录制任务；不同设备可同时进行录制。录制操作不会干扰设备上的其他读取操作——预览窗口可在同一屏幕保持开启状态。

2. Critical: never leave a recording running

2. 重要提示：切勿让录制持续运行

A recording does not stop itself before its

timeLimitSeconds

cap, so a forgotten one keeps capturing until the cap fires — holding the recording session, wasting disk, and delaying the video you are waiting on (and with

trimStatic: false

it comes back padded with dead air). Two safety nets exist — use both:

Set yourself a reminder the moment the recording starts. You know the expected capture length (the interaction you are about to drive). Immediately after
```
screen-recording-start
```
returns, schedule a wake-up for that expected end time using whatever your harness provides — a built-in reminder/wakeup or scheduled-task tool if you have one, otherwise a background shell running
```
sleep <expected-seconds>
```
whose completion notification pulls you back. When it fires, call
```
screen-recording-stop
```
. Do not rely on remembering.
Read the tool-result notes. While a recording is running, every argent tool result carries a
```
NOTE:
```
reminding you it is still going and how to stop it. If the note says the recording already ended (time limit hit), still call
```
screen-recording-stop
```
— that is what hands you the file.

录制不会在达到

timeLimitSeconds

上限前自动停止，因此被遗忘的录制会一直捕获直到触发上限——这会占用录制会话资源、浪费磁盘空间，并延迟你等待的视频生成（若设置

trimStatic: false

，视频还会被无画面的空白内容填充）。现有两个安全保障措施，请同时使用：

录制启动后立即设置提醒。你清楚预期的捕获时长（即即将执行的交互操作时长）。在
```
screen-recording-start
```
返回结果后，立即通过你的工具集提供的功能设置预期结束时间的提醒——若有内置提醒/唤醒或定时任务工具则优先使用，否则可运行一个后台shell执行
```
sleep <预期秒数>
```
，待其完成后触发通知唤回你。提醒触发时，调用
```
screen-recording-stop
```
。切勿依赖记忆。
查看工具结果提示。录制运行期间，每个Argent工具的结果都会附带
```
NOTE:
```
提示，提醒你录制仍在进行以及停止方法。若提示显示录制已因时间限制结束，仍需调用
```
screen-recording-stop
```
——这是获取视频文件的必要操作。

3. Workflow

3. 工作流程

Ensure the target device is booted and the app is in the state you want the video to open on (
```
list-devices
```
,
```
launch-app
```
,
```
argent-device-interact
```
).
Call
```
screen-recording-start
```
with
```
udid
```
and a
```
timeLimitSeconds
```
slightly above the expected interaction length (default 180, max 600). Taps and swipes are drawn into the video by default (see the touch-visualizer note below); pass
```
showTouches: false
```
for a clean raw-screen capture.
Set the end-of-recording reminder described in §2 — this step is not optional.
Drive the interaction to capture: gestures, navigation, typing (
```
argent-device-interact
```
). Prefer
```
run-sequence
```
for tight multi-step interactions so tool-call latency does not pad the video.
Call
```
screen-recording-stop
```
with the same
```
udid
```
. It returns
```
{ video, durationMs, wallClockMs?, trimmedMs?, warning? }
```
;
```
video
```
is an artifact whose resolved path points at the durably-saved file (see below). The video is already final when stop returns (the watermark is stamped during capture, not in a second pass), so stop takes well under a second.
Check
```
warning
```
: it reports cap-triggered stops, early encoder exits, a dropped frame stream, and possibly-truncated containers. Verify the file plays (or at least has a sane size) before presenting it to the user.

Where the file lands (durable, not scratch). Unlike most argent artifacts (which live in a disposable temp cache the OS reclaims), a finished recording is saved durably on the client into

<project>/.argent/recordings/

— the project being the nearest ancestor of the client's working directory with a

.git

package.json

.argent

, or

~/.argent/recordings/

when the client isn't inside a project. This holds even for a remote

argent link

tool-server: the mp4 is written on the client host, not the server. The saved name is

screen-recording-<device>-<timestamp>.mp4

; if that name is already taken the new file lands beside it as

… (2).mp4

rather than overwriting. Because these files persist in the working tree, mention the path to the user (and note that they are untracked — add them to

.gitignore

or clean them up if they shouldn't be committed).

Static-frame trimming (on by default). Stretches where the screen does not change are collapsed: the first second of each still stretch is kept so pauses read naturally, then unchanged frames are dropped until something moves again (a change of even a couple of pixels counts). So you can leave a recording running across slow steps, waits, or thinking time without padding the clip with dead air — a 40-second session with 5 seconds of real activity comes back as a ~5-7 second video. When trimming removed anything, stop also returns

wallClockMs

(real elapsed time) and

trimmedMs

(how much was cut);

durationMs

is always the length of the video you actually get. Pass

trimStatic: false

screen-recording-start

when you want a faithful real-time recording (e.g. to measure how long something took on screen).

Touch visualizer (on by default). Every interaction argent drives is drawn straight into the video: a pulse marks each tap, a fading comet trail follows swipes and drags, and paired markers show the two contact points of a pinch or rotate. This makes a recording self-explanatory — a viewer can see where each gesture landed rather than watching the UI react to an invisible finger. It is rendered by simulator-server into the frame stream (nothing is composited host-side), so it costs nothing extra and never appears in a

screenshot

. Pass

showTouches: false

screen-recording-start

to record the raw screen with no overlay (e.g. when capturing exactly what the user would see). If simulator-server cannot enable it, the recording still succeeds and stop returns a

warning

saying touches are not shown.

确保目标设备已启动，且应用处于你希望视频开篇的状态（可使用
```
list-devices
```
、
```
launch-app
```
、
```
argent-device-interact
```
工具）。
调用
```
screen-recording-start
```
，传入
```
udid
```
和略长于预期交互时长的
```
timeLimitSeconds
```
（默认180秒，最大600秒）。默认情况下，点击和滑动操作会被绘制到视频中（见下方触控可视化提示）；若要捕获纯净的原始屏幕画面，可传入
```
showTouches: false
```
。
设置第2节所述的录制结束提醒——此步骤为必填项。
执行需捕获的交互操作：手势、导航、输入（使用
```
argent-device-interact
```
）。对于多步紧密衔接的交互，优先使用
```
run-sequence
```
，避免工具调用延迟导致视频内容冗余。
使用相同的
```
udid
```
调用
```
screen-recording-stop
```
。返回结果为
```
{ video, durationMs, wallClockMs?, trimmedMs?, warning? }
```
；
```
video
```
为工件，其解析路径指向持久保存的文件（见下文说明）。停止操作返回时视频已完成最终处理（水印在捕获过程中添加，无需二次处理），因此停止操作耗时不到1秒。
检查
```
warning
```
字段：它会报告因上限触发的停止、编码器提前退出、帧流丢失以及可能的容器截断情况。在将文件交付给用户前，需验证文件可正常播放（或至少文件大小合理）。

文件存储位置（持久化，而非临时存储）。与大多数Argent工件（存储在操作系统会回收的临时缓存中）不同，完成的录制会被持久保存到客户端的

<project>/.argent/recordings/

目录下——这里的project指客户端工作目录最近的包含

.git

package.json

.argent

文件的父目录；若客户端不在项目目录内，则存储到

~/.argent/recordings/

。即使使用远程

argent link

工具服务器，mp4文件仍会写入客户端主机，而非服务器。保存的文件名为

screen-recording-<device>-<timestamp>.mp4

；若该名称已存在，新文件会以

… (2).mp4

的形式保存在同一目录下，而非覆盖原有文件。由于这些文件会保留在工作目录中，需向用户告知路径（并注意这些文件未被追踪——若不应提交到版本库，需将其添加到

.gitignore

或进行清理）。

静态帧裁剪（默认开启）。屏幕无变化的时段会被压缩：每个静止时段的前1秒会被保留以保证停顿效果自然，之后的无变化帧会被丢弃，直到画面再次变动（哪怕只有几个像素的变化也会触发）。因此，你可以在缓慢操作、等待或思考期间保持录制运行，而不会让视频被空白内容填充——一个40秒的会话若只有5秒的实际操作，最终生成的视频时长约为5-7秒。若裁剪操作生效，停止操作还会返回

wallClockMs

（实际耗时）和

trimmedMs

（裁剪掉的时长）；

durationMs

始终为最终得到的视频时长。若需要忠实的实时录制（例如测量屏幕上某操作的耗时），可在调用

screen-recording-start

时传入

trimStatic: false

。

触控可视化（默认开启）。Argent执行的每一次交互都会直接绘制到视频中：脉冲标记每个点击操作，渐隐的彗尾跟随滑动和拖拽操作，成对标记则显示捏合或旋转的两个接触点。这让录制内容具备自解释性——观看者可以看到每个手势的落点，而非仅观察UI对隐形操作的响应。它由simulator-server渲染到帧流中（无需在主机端合成），因此不会产生额外开销，也不会出现在

screenshot

截图中。若要录制无叠加层的原始屏幕画面（例如捕获用户实际看到的内容），可在调用

screen-recording-start

时传入

showTouches: false

。若simulator-server无法启用该功能，录制仍会成功，但停止操作会返回

warning

提示触控未显示。

4. Platform notes and limits

4. 平台说明与限制

What can be recorded: anything simulator-server drives — iOS simulators, Android emulators, and physical Android devices. The only length limit is
```
timeLimitSeconds
```
(max 600).
The timeline is paced to a steady 30 fps: a device only emits a frame when its screen changes, so captured frames are re-paced onto a fixed timeline rather than bunching up. With static-frame trimming off (
```
trimStatic: false
```
) that timeline is wall-clock accurate — a completely still screen still comes back as a full-length video (compressing to almost nothing) and
```
durationMs
```
matches the time you actually recorded. With trimming on (the default, see §3) still stretches past the grace window are collapsed, so
```
durationMs
```
is the trimmed video length and
```
wallClockMs
```
carries the real elapsed time.
Android: records at the device's native resolution; secure screens (DRM, some password fields) come out black.
Unsupported: tvOS simulators, physical iPhones, Chromium apps, Vega/Fire TV, and remote (
```
remote:
```
-prefixed) simulators — none of them expose a readable frame stream. For a single still frame use
```
screenshot
```
; for a replayable interaction script use
```
argent-create-flow
```
instead of a video.
ffmpeg is required: it is the encoder, so
```
screen-recording-start
```
fails up front with an install hint if it is missing (
```
brew install ffmpeg
```
). It is resolved from
```
PATH
```
plus the usual Homebrew prefixes.
Watermark: the Argent logo + "By @swmansion" is stamped bottom-left while encoding, faint (20% opacity) and per-pixel contrast-matched to the background (light logo over dark UI, dark logo over light UI). On by default — turn it off with
```
argent disable video-watermark
```
(re-enable with
```
argent enable video-watermark
```
). The flag is read when the recording starts.

可录制内容：simulator-server可驱动的所有内容——iOS模拟器、Android模拟器和物理Android设备。唯一的时长限制为
```
timeLimitSeconds
```
（最大600秒）。
时间线稳定保持30帧/秒：设备仅在屏幕变化时输出帧，因此捕获的帧会被重新调整到固定时间线，而非集中出现。关闭静态帧裁剪（
```
trimStatic: false
```
）时，时间线与实际时间完全一致——完全静止的屏幕仍会生成完整时长的视频（压缩后体积极小），且
```
durationMs
```
与实际录制时长一致。开启裁剪时（默认设置，见第3节），超过缓冲窗口的静止时段会被压缩，因此
```
durationMs
```
为裁剪后的视频时长，
```
wallClockMs
```
为实际耗时。
Android平台：以设备原生分辨率录制；安全屏幕（DRM、部分密码输入框）会显示为黑色。
不支持的场景：tvOS模拟器、物理iPhone、Chromium应用、Vega/Fire TV以及远程（前缀为
```
remote:
```
）模拟器——这些设备均不提供可读的帧流。若仅需单张静态截图，可使用
```
screenshot
```
；若需可回放的交互脚本，可使用
```
argent-create-flow
```
替代视频录制。
需安装ffmpeg：它是编码器，因此若未安装
```
ffmpeg
```
，
```
screen-recording-start
```
会直接失败并给出安装提示（
```
brew install ffmpeg
```
）。程序会从
```
PATH
```
以及常用的Homebrew前缀路径中查找
```
ffmpeg
```
。
水印：编码过程中会在左下角添加Argent标志 + "By @swmansion"的水印，透明度为20%，且会根据背景进行逐像素对比度匹配（深色UI上显示浅色标志，浅色UI上显示深色标志）。默认开启——可通过
```
argent disable video-watermark
```
关闭（通过
```
argent enable video-watermark
```
重新开启）。该设置会在录制启动时读取。