openscreen-demo

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Make a demo video with OpenScreen

使用 OpenScreen 制作 demo 视频

You produce a short MP4 that shows one feature, zooms on the action and carries its message in on-screen callouts. You do the whole job through OpenScreen's MCP tools: record, edit, export, look. It ends one of two ways:

A pull request video: 10 to 30 s, showing the change a pull request makes, attached to that pull request so reviewers watch it in place (step 8).
A launch demo: 20 to 60 s, 1080p, with a post drafted for X (step 9). Nothing is ever posted without the user's explicit yes.

你将制作一段简短的 MP4，展示一个功能、放大操作画面，并通过屏幕标注传达核心信息。整个任务都通过 OpenScreen 的 MCP 工具完成：录制、编辑、导出、查看。最终采用以下两种交付方式之一：

Pull request 视频： 10 至 30 秒，展示 pull request 带来的变更，并将其附加到该 pull request，让审阅者可以就地观看（步骤 8）。
发布 demo： 20 至 60 秒，1080p，并为 X 起草帖子（步骤 9）。未经用户明确同意，绝不会发布任何内容。

1. Set up OpenScreen

1. 配置 OpenScreen

You need the tools

startRecording

stopRecording

exportVideo

and

getFrames

. Both of OpenScreen's MCP servers have them: the one the app serves (AI settings → MCP server), and

openscreen mcp

, set up below. If you have them, go to step 2. Otherwise set OpenScreen up, once per machine, doing only what is missing.

The app. Its executable is the MCP server:

OS	Executable
Windows	`%LOCALAPPDATA%\Programs\Openscreen\Openscreen.exe` , or `C:\Program Files\Openscreen\Openscreen.exe` . The Microsoft Store version: `openscreen` on the PATH once its release ships the execution alias ( `where openscreen` ); before that, `app\Openscreen.exe` under `(Get-AppxPackage EtienneLescot.OpenScreen).InstallLocation` (in PowerShell). That path carries the version: register it again after a Store update. Never wrap it in a `powershell -Command` launcher: PowerShell swallows the server's input after the first message
macOS	`/Applications/Openscreen.app/Contents/MacOS/Openscreen`
Linux	`openscreen` on the PATH, or the AppImage

Check every location in the table before you call OpenScreen missing: the Store version is the one most often overlooked. Run

"<executable>" help

: it must list

mcp

. If the app is missing, or too old to list it, offer to install the latest release, and do it only once the user agrees:

Find the installer for this machine in the latest release of
```
getopenscreen/openscreen
```
:
```
gh release view --repo getopenscreen/openscreen --json assets
```
, or https://github.com/getopenscreen/openscreen/releases/latest.
- macOS:
```
Openscreen-macOS-Apple-Silicon-<version>.dmg
```
  , or
```
-Intel-
```
  (check
```
uname -m
```
  ). Mount it, copy
```
Openscreen.app
```
  to
```
/Applications
```
  , unmount it.
- Windows: the
```
Openscreen.Setup.<version>.exe
```
  installer, run with
```
/S /currentuser
```
  for a silent install for the current user.
- Linux: the
```
.deb
```
  ,
```
.rpm
```
  or
```
.pacman
```
  for the distribution, or the
```
.AppImage
```
  made executable.
Check
```
help
```
again. If even the latest release does not list
```
mcp
```
, this OpenScreen feature is not released yet: say so and stop.

The MCP server. Add it to the agent, then the tools load in the next session:

Claude Code:

claude mcp add openscreen -- "<executable>" mcp

Codex:

codex mcp add openscreen -- "<executable>" mcp

Cursor and others: a stdio server with the executable as
```
command
```
and
```
["mcp"]
```
as
```
args
```
.

Permissions.

macOS: the app that runs the agent needs, in System Settings → Privacy & Security, the Screen Recording permission to record at all, and the Accessibility permission for OpenScreen to record the pointer's clicks and shapes. Without Accessibility a take driven with the real mouse gets no zoom on its clicks: grant it, or hand the clicks over with
```
setPointerTrack
```
as for a scripted take.
Linux: the desktop's picker opens on every recording, and the user chooses the window.

Hand over to the next session. Write the user's request, and anything already decided, to

openscreen-demo-plan.md

in the working directory. Then ask the user to start a new session and say continue the OpenScreen demo. In that session, read the file and carry on from step 2.

The tools are missing right after the plugin or the server is added: an agent loads its MCP servers when a session starts. Say so in plain words and hand over as above, with the storyboard in the file if you have made one. Never stand in for the missing tools by driving OpenScreen's window with computer use or a mouse tool: it takes over the user's mouse and screen while they may be working.

你需要

startRecording

、

stopRecording

、

exportVideo

和

getFrames

工具。OpenScreen 的两个 MCP 服务器都提供这些工具：应用提供的服务器（AI settings → MCP server），以及下文配置的

openscreen mcp

。如果已有这些工具，请转到步骤 2。否则，每台机器只需配置一次 OpenScreen，并且仅执行缺失的部分。

应用。 其可执行文件就是 MCP 服务器：

操作系统	可执行文件
Windows	`%LOCALAPPDATA%\Programs\Openscreen\Openscreen.exe` ，或 `C:\Program Files\Openscreen\Openscreen.exe` 。Microsoft Store 版本：待其发行版提供 execution alias 后， `openscreen` 会位于 PATH 上（ `where openscreen` ）；在此之前，使用 PowerShell 中 `(Get-AppxPackage EtienneLescot.OpenScreen).InstallLocation` 下的 `app\Openscreen.exe` 。该路径包含版本号：Store 更新后需要重新注册。绝不要使用 `powershell -Command` 启动器包装它：PowerShell 会在收到第一条消息后吞掉服务器的输入。
macOS	`/Applications/Openscreen.app/Contents/MacOS/Openscreen`
Linux	PATH 上的 `openscreen` ，或 AppImage

在认定 OpenScreen 缺失之前，检查表格中的每个位置：最常被忽略的是 Store 版本。运行

"<executable>" help

：输出中必须列出

mcp

。如果应用缺失，或版本过旧而无法列出

mcp

，应提议安装最新版本，并且只有在用户同意后才执行：

在
```
getopenscreen/openscreen
```
的最新发行版中查找适用于这台机器的安装包：
```
gh release view --repo getopenscreen/openscreen --json assets
```
，或访问 https://github.com/getopenscreen/openscreen/releases/latest。
- macOS：
```
Openscreen-macOS-Apple-Silicon-<version>.dmg
```
  或
```
-Intel-
```
  （检查
```
uname -m
```
  ）。挂载镜像，将
```
Openscreen.app
```
  复制到
```
/Applications
```
  ，然后卸载镜像。
- Windows：
```
Openscreen.Setup.<version>.exe
```
  安装程序，使用
```
/S /currentuser
```
  为当前用户静默安装。
- Linux： 适用于该发行版的
```
.deb
```
  、
```
.rpm
```
  或
```
.pacman
```
  ，或赋予
```
.AppImage
```
  执行权限。
再次检查
```
help
```
。如果即使最新版本也未列出
```
mcp
```
，说明此 OpenScreen 功能尚未发布：如实告知并停止。

MCP 服务器。 将其添加到 agent 中，随后工具会在下一会话加载：

Claude Code：

claude mcp add openscreen -- "<executable>" mcp

Codex：

codex mcp add openscreen -- "<executable>" mcp

Cursor 和其他工具： 使用该可执行文件作为
```
command
```
，并以
```
["mcp"]
```
作为
```
args
```
，配置一个 stdio 服务器。

权限。

macOS： 运行 agent 的应用需要授予相应权限。在“系统设置”→“隐私与安全性”中授予屏幕录制（Screen Recording）权限，才能开始录制；授予辅助功能（Accessibility）权限，OpenScreen 才能记录指针点击和标记。没有 Accessibility 权限时，使用真实鼠标驱动的录制片段在点击处不会自动缩放：应授予该权限，或像脚本录制一样通过
```
setPointerTrack
```
移交点击轨迹。
Linux： 每次录制时都会打开桌面的选择器，由用户选择窗口。

移交给下一会话。 将用户请求以及已经确定的所有事项写入工作目录中的

openscreen-demo-plan.md

。然后请用户启动新会话并说“继续 OpenScreen demo”。在新会话中，读取该文件并从步骤 2 继续执行。

刚添加 plugin 或服务器后，工具仍会显示为缺失：agent 会在会话启动时加载 MCP 服务器。要用直白的话说明这一点，并按上述方式移交；如果已经制作了故事板，也将其写入文件。绝不能通过 computer use 或 mouse tool 代替缺失的工具来操控 OpenScreen 窗口：用户可能正在工作，而这类工具会接管其鼠标和屏幕。

2. Plan before recording

2. 先规划，再录制

Write a storyboard and show it to the user in a few lines, then carry on unless they object.

One message. What should a viewer remember after 3 seconds? The first beat shows the result, not a setup screen.
Launch demo: 3 to 6 beats, 20 to 60 seconds. Each beat is one action and one callout of 6 words or fewer. X autoplays muted, so the callouts carry the story, not a voice.
Pull request video: 1 to 3 beats, 10 to 30 seconds. Show what the change does, not the whole product: the new behavior, or the bug no longer happening. The pull request text explains the rest, so one short callout per beat is enough.
Realistic data. Seed the app with believable content. No real customer data, secrets, tokens or personal notifications on screen.

编写 storyboard，并用几行文字展示给用户；除非用户提出异议，否则继续执行。

一个核心信息。 观众在 3 秒后应该记住什么？第一段应展示结果，而不是设置界面。
发布 demo：3 至 6 个节点，20 至 60 秒。 每个节点包含一个操作和一条不超过 6 个字的标注。X 会静音自动播放，因此应通过标注而非旁白来传达故事。
Pull request 视频：1 至 3 个节点，10 至 30 秒。 展示变更带来的效果，而不是整个产品：新行为，或问题不再发生。Pull request 文本会解释其余内容，因此每个节点只需一条简短标注。
真实数据。 为应用填充可信的内容。屏幕上不得出现真实的客户数据、机密信息、token 或个人通知。

3. Set the stage

3. 搭建场景

Start the app and open it on the starting state of the first beat.
Give it one clean window of about 1600×1000. For a web app, open it in an app window without browser chrome:
```
chrome --app=http://localhost:3000 --window-size=1600,1000 --user-data-dir=<temp folder>
```
. Its title is the page's
```
<title>
```
.
Call
```
listSources
```
and pick a unique part of the window's title.
Only the app on screen. No browser toolbar, address bar, local file path, user name, bookmark bar, translation prompt or notification in the recorded window. Recording one window keeps the rest of the desktop out.

启动应用，并打开至第一个节点的起始状态。
为应用准备一个约 1600×1000 的独立干净窗口。对于 Web 应用，在不带浏览器 chrome 的应用窗口中打开：
```
chrome --app=http://localhost:3000 --window-size=1600,1000 --user-data-dir=<temp folder>
```
。窗口标题就是页面的
```
<title>
```
。
调用
```
listSources
```
，并选择窗口标题中一个独特的内容。
屏幕上只能有应用本身。 录制的窗口中不得出现浏览器工具栏、地址栏、本地文件路径、用户名、书签栏、翻译提示或通知。仅录制该窗口会将桌面其他内容排除在外。

4. Record

4. 录制

```
startRecording
```
with
```
window
```
. It returns once capture has started. Connected to the server in the app, the take goes through OpenScreen's recording bar: the editor closes, the bar counts down, and
```
stopRecording
```
opens the take in the editor. Pass
```
camera
```
only when the user wants to appear on screen: the webcam then shows as a picture-in-picture. Pass
```
microphone: true
```
when the user narrates: without it the take has no voice, and nothing to caption.
Play the storyboard. Move deliberately, and pause about one second after each result appears.

stopRecording

with a

title

. Keep what it returns:

projectId

checkpointId

videoPath

recordingStartedAt

How you drive the app decides the cursor.

Real mouse (computer-use, or any tool that moves the actual pointer): OpenScreen records the pointer, draws a clean cursor and already zooms on the clicks (see Zoom on the action below). If your mouse tool cannot click in the app's window (some only read browsers, for one), drive it from a script instead.
A script (Playwright, CDP): the screen pointer never moves, so the take has no cursor and no zoom. In the script, log every action as it runs:
```
at
```
is
```
Date.now()
```
,
```
x
```
and
```
y
```
are the action's position as fractions of the window,
```
click
```
is true for a click. Hand the log to
```
setPointerTrack
```
after
```
stopRecording
```
; its description gives the formula from a page's coordinates. A script also gives the cleanest take: same timing on every run, no hesitation.

A video you already have needs no recording:

createProject

with its absolute

videoPath

lays it out as a project, and returns a

projectId

and a

checkpointId

stopRecording

does. Check it as a take in step 5, its

videoPath

included, then go on from step 6.

以
```
window
```
模式调用
```
startRecording
```
。捕获开始后，该调用就会返回。连接到应用内的服务器时，录制会经过 OpenScreen 的录制栏：编辑器关闭，录制栏开始倒计时，然后
```
stopRecording
```
会在编辑器中打开该录制片段。仅当用户希望出镜时传入
```
camera
```
：此时摄像头画面会以画中画形式显示。用户需要旁白时传入
```
microphone: true
```
：不传则录制片段没有声音，也没有可供添加字幕的内容。
按照 storyboard 演示。操作时保持从容，每个结果出现后暂停约 1 秒。

使用标题调用

stopRecording

。保留其返回内容：

projectId

、

checkpointId

、

videoPath

、

recordingStartedAt

。

驱动应用的方式决定视频中的光标效果。

真实鼠标（computer-use，或任何能够移动实际指针的工具）：OpenScreen 会记录指针、绘制清晰的光标，并自动在点击处缩放（参见下文“对操作进行缩放”）。如果鼠标工具无法点击应用窗口（例如有些工具只能读取浏览器），则改用脚本驱动。
脚本（Playwright、CDP）：屏幕指针不会移动，因此录制片段中没有光标，也没有缩放。在脚本运行期间记录每个操作：
```
at
```
为
```
Date.now()
```
，
```
x
```
和
```
y
```
为操作位置相对于窗口的比例，
```
click
```
在发生点击时为 true。完成
```
stopRecording
```
后，将日志交给
```
setPointerTrack
```
；其描述中给出了根据页面坐标计算的公式。脚本也能生成最干净的录制片段：每次运行的节奏一致，没有犹豫造成的停顿。

已有视频无需重新录制：使用其绝对

videoPath

调用

createProject

，即可将其作为项目进行编排，并像

stopRecording

一样返回

projectId

和

checkpointId

。在步骤 5 中像检查录制片段一样检查它，其中包括

videoPath

，然后从步骤 6 继续。

5. Check the take

5. 检查录制片段

getFrames

on the

videoPath

, about 6 frames. Is it the right window? Is anything private visible? Did every beat happen? If not, record again: a new take costs less than a fix in editing.

对

videoPath

调用

getFrames

，大约检查 6 帧。是否是正确的窗口？是否暴露了隐私信息？每个节点是否都发生了？如果没有，请重新录制：新录制片段的成本低于在编辑阶段修复问题。

6. Edit

6. 编辑

Use the document tools, always with the

projectId

. Read the project first with

getCurrentDocument

: its notes say which times are in the recording's seconds and which on the editor's ruler.

One clock. Place every effect in ruler seconds, and look at the result with

getFrames

and the

projectId

, which takes the same seconds. Never read times off the exported file: a cut or a speed-up shifts its clock away from the ruler.

Format first:
```
setAspectRatio
```
for where the video will be shown,
```
16:9
```
for X. Do it before placing text.
Cut dead time: the setup at the start, the stop at the end, any wait. Use
```
addTrims
```
, or
```
addSpeed
```
to fast-forward a wait instead of cutting it.
Zoom on the action: clicks close in time and on screen share one zoom, and the first 2.5 s stay wide. Check them, then add or move zooms with
```
addZooms
```
and
```
setZoom
```
where a result deserves its own. Hold a zoom at least 1.5 s. After a cut that removed some,
```
addAutoZooms
```
plans them again on the clicks left, clear of the zooms still there.
Frame the app: when the take shows more than the app,
```
setClipRange
```
with a
```
cropRegion
```
crops the clip to it.
Callouts: one
```
addAnnotation
```
per beat, short, placed clear of the action. Text sits on the output frame and stays put when the picture zooms. Use its look for hierarchy: a large title with
```
animation: "typewriter"
```
, step callouts with
```
animation: "pop"
```
. An arrow,
```
type: "figure"
```
, points at a control the text names.
```
setAnnotation
```
moves or restyles one.
Hide what is private: an email address, a token or a name that shows on screen gets
```
addAnnotation
```
with
```
type: "blur"
```
over the span it is visible. Its x, y, width and height are percent of the recording's picture, not of the frame, so it stays on what it hides when a zoom moves the picture. Check it with
```
getFrames
```
.
An effect no setting offers (a ripple on each click, a glitch on a cut, a color grade): read the resource
```
openscreen://effects/contract
```
, then write it as WGSL with
```
addEffect
```
. It reads the clicks and the pointer already placed on the frame. Code that does not compile comes back with the compiler's error at your line: fix it and call again. The result gives a cost tier; keep heavy effects to short spans. Check the effect with
```
getFrames
```
at the moments it acts.
Music or a voiceover:
```
importMedia
```
with the file's absolute path adds it to the project's media, then
```
addAudio
```
plays it over a span.
```
removeMedia
```
takes back a file the timeline no longer uses.
Name:
```
setProjectInfo
```
renames the project, if the
```
title
```
given to
```
stopRecording
```
no longer fits.
Captions, for a narrated take (
```
startRecording
```
with
```
microphone: true
```
):
1. ```
transcribe
```
  with the
```
projectId
```
  . Whisper runs on this machine and can take a minute; a take has no transcript before this.
2. ```
setCaptionSettings
```
  with
```
enabled: true
```
  and a
```
style
```
  , plus
```
anchorV
```
  ,
```
insetY
```
  or
```
maxWordsPerLine
```
  if the callouts need room.
3. To caption in another language:
```
getCaptionTranslationUnits
```
  with the
```
language
```
  , translate each unit yourself as a whole phrase, store them with
```
putCaptionTranslation
```
  , then
```
setCaptionSettings
```
  with that
```
language
```
  .
4. ```
getCaptions
```
  reads it all back. The export burns the captions in. A misheard name is fixed with
```
setWordText
```
  (or
```
setVocabulary
```
  , then
```
transcribe
```
  again with the
```
language
```
  ), a flubbed phrase cut with
```
getTranscriptWords
```
  and
```
removeWords
```
  .
Undo:
```
restoreCheckpoint
```
with the
```
checkpointId
```
takes the project back to the raw take in one step. It also puts back the take's own pointer track, undoing any
```
setPointerTrack
```
made since.
Open in the app: while OpenScreen is running, your edits go through it, so a project the user has open in its editor changes there live and they can undo each edit. If an edit is refused as "open in the OpenScreen editor", the app did not answer: retry once, then ask the user to close the project there or restart OpenScreen.

Keep the rest as it is: the background, padding, shadow and cursor style are chosen to look good. When the user asks for a different look,

setEditorSettings

sets it (background, frame, camera layout, cursor, volume);

getCurrentDocument

shows the current values under

settings

, and

settingsContext.inactive

says which ones would change nothing right now.

使用文档工具，并始终传入

projectId

。先通过

getCurrentDocument

读取项目：其 notes 会说明哪些时间对应录制中的秒数，哪些对应编辑器标尺上的时间。

统一时间基准。 将所有效果放在标尺秒数上，并通过

projectId

调用

getFrames

查看结果，两者使用相同的秒数。绝不要从导出文件中读取时间：剪辑或加速会让文件时间偏离标尺。

先设置格式： 使用
```
setAspectRatio
```
设置视频的展示位置；用于 X 时选择
```
16:9
```
。应在放置文字之前完成。
剪掉无效时间： 剪掉开头的设置过程、结尾的停顿以及所有等待。使用
```
addTrims
```
，或使用
```
addSpeed
```
快进等待时段，而不是直接剪掉。
对操作进行缩放： 时间相近且屏幕位置接近的点击共用一次缩放，前 2.5 秒保持全景。先检查这些点击，再使用
```
addZooms
```
和
```
setZoom
```
添加或移动缩放，让值得单独呈现的结果拥有自己的缩放。每次缩放至少保持 1.5 秒。剪辑移除部分点击后，
```
addAutoZooms
```
会根据剩余点击重新规划缩放，并避开仍然存在的缩放区域。
裁剪应用画面： 当录制片段显示的内容超出应用本身时，使用
```
setClipRange
```
并设置
```
cropRegion
```
，将片段裁剪到应用区域。
标注： 每个节点添加一条
```
addAnnotation
```
，内容应简短并避开操作区域。文字位于输出画面上，画面缩放时仍会保持位置不变。通过标注样式建立视觉层级：大标题使用
```
animation: "typewriter"
```
，步骤标注使用
```
animation: "pop"
```
。使用
```
type: "figure"
```
的箭头指向文字所命名的控件。
```
setAnnotation
```
可移动或重新设置单个标注的样式。
隐藏隐私信息： 屏幕上出现的邮箱地址、token 或姓名，应在对应显示时间段内使用
```
type: "blur"
```
的
```
addAnnotation
```
加以遮盖。其 x、y、width 和 height 是相对于录制画面而非输出帧的百分比，因此画面缩放、移动时仍会准确遮住目标。使用
```
getFrames
```
检查效果。
设置中没有相应选项的效果（例如每次点击产生涟漪、剪辑时出现故障效果或色彩分级）：读取资源
```
openscreen://effects/contract
```
，然后使用
```
addEffect
```
以 WGSL 编写。该效果会读取已放置在画面上的点击和指针信息。如果代码无法编译，返回结果会指出编译器错误所在的行：修复后再次调用。返回结果还会给出 cost tier；将高开销效果限制在较短时间段内。使用
```
getFrames
```
检查效果生效时刻的画面。
音乐或旁白： 使用文件的绝对路径调用
```
importMedia
```
，将其添加到项目媒体中，然后使用
```
addAudio
```
在指定时间段内播放。时间线不再使用的文件可通过
```
removeMedia
```
移除。
名称： 如果传给
```
stopRecording
```
的
```
title
```
已不再适用，使用
```
setProjectInfo
```
重命名项目。
旁白录制片段的字幕（使用
```
microphone: true
```
调用
```
startRecording
```
）：
1. 使用
```
projectId
```
  调用
```
transcribe
```
  。Whisper 在本机运行，可能需要约一分钟；在此之前，录制片段没有转录文本。
2. 调用
```
setCaptionSettings
```
  ，设置
```
enabled: true
```
  和一种
```
style
```
  ；如果标注需要更多空间，还可设置
```
anchorV
```
  、
```
insetY
```
  或
```
maxWordsPerLine
```
  。
3. 要生成其他语言的字幕：使用
```
language
```
  调用
```
getCaptionTranslationUnits
```
  ，将每个单元作为完整短语自行翻译，使用
```
putCaptionTranslation
```
  保存翻译，然后使用该
```
language
```
  调用
```
setCaptionSettings
```
  。
4. 使用
```
getCaptions
```
  读取全部字幕。导出时，字幕会直接烧录到画面中。使用
```
setWordText
```
  可以修正识别错误的人名；也可以先使用
```
setVocabulary
```
  ，再使用
```
language
```
  调用
```
transcribe
```
  重新转录。说错的短语可以使用
```
getTranscriptWords
```
  和
```
removeWords
```
  剪掉。
撤销： 使用
```
checkpointId
```
调用
```
restoreCheckpoint
```
，可一步将项目恢复到原始录制片段。它也会恢复该片段自带的指针轨迹，撤销此后通过
```
setPointerTrack
```
所做的更改。
在应用中打开： OpenScreen 运行时，你的编辑会通过 OpenScreen 执行，因此用户在编辑器中打开的项目会实时发生变化，用户可以逐项撤销编辑。如果编辑被拒绝并提示“open in the OpenScreen editor”，说明应用没有响应：重试一次，然后请用户关闭该项目或重启 OpenScreen。

其余设置保持不变：背景、内边距、阴影和光标样式已经过预设，能够呈现良好效果。当用户要求不同的视觉效果时，使用

setEditorSettings

进行设置（背景、边框、摄像头布局、光标、音量）；

getCurrentDocument

会在

settings

下显示当前值，

settingsContext.inactive

则会指出当前哪些设置不会产生任何变化。

7. Export and review

7. 导出与审查

```
exportVideo
```
with the
```
projectId
```
and an absolute path: resolve, say,
```
demo/demo.mp4
```
against your working directory first, since the server in the app refuses a relative path. For a pull request video, pass
```
quality: "medium"
```
(720p) to keep the file small. For a GIF (a README, say), end the path in
```
.gif
```
and pass
```
gifSize: "small"
```
(480p).
```
getFrames
```
with the
```
projectId
```
, at the ruler seconds of your beats. While you edit, you can call it before exporting: without a current export it renders the frames the export would show.
Check every frame:
- Is each callout readable and clear of the action?
- Is each zoom on the thing that changes?
- Are there black frames, cut-off text or a leftover setup screen?
Fix the project and export again until it holds.

Never commit the video to the repository: it goes into the pull request or the post, not the code.

使用
```
projectId
```
和绝对路径调用
```
exportVideo
```
：先以当前工作目录解析诸如
```
demo/demo.mp4
```
的路径，因为应用内的服务器会拒绝相对路径。对于 pull request 视频，传入
```
quality: "medium"
```
（720p），以减小文件大小。如果需要 GIF（例如用于 README），让路径以
```
.gif
```
结尾，并传入
```
gifSize: "small"
```
（480p）。
使用
```
projectId
```
调用
```
getFrames
```
，检查各节点对应的标尺秒数。编辑期间，也可以在导出前调用：没有当前导出文件时，它会呈现导出后将要显示的画面。
检查每一帧：
- 每条标注是否清晰可读，并避开操作区域？
- 每次缩放是否对准了发生变化的内容？
- 是否存在黑帧、文字被截断或残留的设置界面？
修复项目并重新导出，直到效果合格。

绝不要将视频提交到代码仓库：它应放入 pull request 或帖子中，而不是代码中。

8. Attach it to the pull request

8. 附加到 pull request

Only to a pull request the user asked for a video on, or one you open for them in this task.

Check the size. GitHub takes videos up to 10 MB in a repository on a free plan, 100 MB on a paid one. Over the limit, cut or speed up a beat and export again.
Write the text around it in a file, say
```
demo/pr-video.md
```
: one line saying what the video shows, then the video alone in its own paragraph, so GitHub shows a player and not a link:
markdown
```
**Demo:** the export dialog now remembers the last format.

![](demo/pr-video.mp4)
```
Attach it with
gh
, version 2.99.0 or later (
```
gh --version
```
).
```
gh
```
uploads the file and puts its URL in place of the path. You need push access to the repository.
- On an existing pull request, as a comment:
```
gh pr comment <number> --body-file demo/pr-video.md --attach demo/pr-video.mp4
```
- On a pull request you are opening: put the same two lines in its body, and pass
```
--attach demo/pr-video.mp4
```
  to
```
gh pr create
```
  .
With an older
gh
, ask the user to update it. On GitHub Enterprise Server, where
```
gh
```
cannot attach files at all, skip
```
--attach
```
. In both cases, use a browser tool that can attach a file to the comment box on the pull request's page, or else give the user the file and the text to drop in themselves.
Report the comment's or the pull request's URL.

仅用于用户明确要求添加视频的 pull request，或本任务中代用户新建的 pull request。

检查大小。 免费方案下，GitHub 允许仓库中的视频最大为 10 MB；付费方案下为 100 MB。如果超出限制，删减或加速某个节点，然后重新导出。
编写视频周围的文字。 将其写入文件，例如
```
demo/pr-video.md
```
：先用一行说明视频展示的内容，然后让视频单独占据一个段落，这样 GitHub 会显示播放器，而不是普通链接：
markdown
```
**Demo：** 导出对话框现在会记住上次使用的格式。

![](demo/pr-video.mp4)
```
使用
gh
附加视频。需要 2.99.0 或更高版本（
```
gh --version
```
）。
```
gh
```
会上传文件，并将文件路径替换为其 URL。你需要拥有该仓库的推送权限。
- 对于现有 pull request，以评论形式添加：
```
gh pr comment <number> --body-file demo/pr-video.md --attach demo/pr-video.mp4
```
- 对于正在创建的 pull request，将同样的两行内容放入正文，并向
```
gh pr create
```
  传入
```
--attach demo/pr-video.mp4
```
  。
如果
gh
版本较旧，请用户更新。对于无法附加文件的 GitHub Enterprise Server，跳过
```
--attach
```
。在这两种情况下，都应使用能够在 pull request 页面的评论框中附加文件的浏览器工具；否则，将文件和文字提供给用户自行添加。
报告评论或 pull request 的 URL。

9. Post on X

9. 发布到 X

Write the post. At most 280 characters: the hook first, then what it does, then the link if there is one. One or two hashtags at most.
Check X's limits. The video must be an MP4 of at most 2 min 20 s and 512 MB for an account without Premium. The export fits.
Ask the user. Show the post text, the video path and one frame, and ask for an explicit yes. A "looks good" given to an earlier step is not one.
Post, after the yes only. Use a browser tool that can attach a file to the composer at https://x.com/compose/post, or the X API if the user has set one up. If you cannot attach a file, give the user the text and the file instead.
Report the post's URL.

编写帖子。 最多 280 个字符：先写吸引点，再说明功能，最后附上链接（如果有）。最多使用一两个 hashtag。
检查 X 的限制。 对于未订阅 Premium 的账户，视频必须为 MP4 格式，时长不超过 2 分 20 秒，大小不超过 512 MB。导出的视频符合要求。
询问用户。 展示帖子文字、视频路径和一帧画面，并请求明确同意。用户在较早步骤中说的“看起来不错”不算作此次同意。
仅在获得同意后发布。 使用能够在 https://x.com/compose/post 的编辑器中附加文件的浏览器工具，或使用用户已配置的 X API。如果无法附加文件，则将帖子文字和视频文件提供给用户。
报告帖子的 URL。

When it goes wrong

出现问题时

The recording did not start
: the window title did not match, or capture is not permitted. Check
```
listSources
```
and the permissions in step 1.
Recording, exporting or an edit refused, naming MCP edits: you are connected to the server in the app, which records, exports and edits only once the user allows it. Ask them to turn on MCP edits under AI settings → MCP server.
No cursor in the video: the app was driven by a script. See step 4.
transcribe
fails with
no-audio
: the take was recorded with neither
```
microphone
```
nor
```
systemAudio
```
. Record again with one of them.
No zoom on an early click: the first 2.5 s stay wide on purpose. Start the first action after that.
unknown flag: --attach
:
```
gh
```
is older than 2.99.0. See step 8.

The recording did not start
：窗口标题不匹配，或未允许捕获。检查
```
listSources
```
以及步骤 1 中的权限。
录制、导出或编辑被拒绝并提示 MCP edits： 当前连接的是应用内的服务器，只有在用户允许后，它才会执行录制、导出和编辑。请用户在 AI settings → MCP server 中开启 MCP edits。
视频中没有光标： 应用由脚本驱动。参见步骤 4。
transcribe
失败并报告
no-audio
：录制片段既未启用
```
microphone
```
，也未启用
```
systemAudio
```
。请使用其中之一重新录制。
早期点击没有缩放： 前 2.5 秒会刻意保持全景。请在此时之后再开始第一个操作。
unknown flag: --attach
：
```
gh
```
版本低于 2.99.0。参见步骤 8。