openscreen-demo

使用 OpenScreen 制作演示视频

制作一段简短的 MP4 视频，展示一项功能，放大操作画面，并通过屏幕标注传达其信息。你可以通过 OpenScreen 的 MCP 工具完成整个流程：录制、编辑、导出、查看。最终有两种成品：

• **拉取请求视频：**时长 10 到 30 s，展示拉取请求带来的更改，并附在该拉取请求中，方便审核者直接观看（第 8 步）。
• **发布演示视频：**时长 20 到 60 s，分辨率为 1080p，并拟好一篇发布到 X 的帖子（第 9 步）。未经用户明确同意，绝不会发布任何内容。

1. 设置 OpenScreen

你需要 startRecording、stopRecording、exportVideo 和 getFrames 工具。OpenScreen 的两个 MCP 服务都提供这些工具：应用提供的服务（AI settings → MCP server），以及下文设置的 openscreen mcp。如果你已拥有这些工具，请转到第 2 步。否则，请在每台机器上设置一次 OpenScreen，只执行尚未完成的步骤。

应用。 它的可执行文件就是 MCP 服务：

OS	可执行文件
Windows	%LOCALAPPDATA%\Programs\Openscreen\Openscreen.exe，或 C:\Program Files\Openscreen\Openscreen.exe。Microsoft Store 版本：发布执行别名后，可通过 PATH 中的 openscreen 调用（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。如果应用缺失，或版本过旧而未列出该项，请提出安装最新版本；只有用户同意后才安装：

1. 在 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。
2. 再次检查 help。如果最新版本仍未列出 mcp，说明此 OpenScreen 功能尚未发布：请告知用户并停止。

MCP 服务。 将其添加到 Agent，然后这些工具会在下一个会话中加载：

• Claude Code： claude mcp add openscreen -- "<executable>" mcp
• Codex： codex mcp add openscreen -- "<executable>" mcp
• Cursor 及其他客户端： 添加一个 stdio 服务，将可执行文件设为 command，并将 ["mcp"] 设为 args。

权限。

• macOS： 运行 Agent 的应用需要在“系统设置”→“隐私与安全性”中获得“屏幕录制”权限才能录制；还需要“辅助功能”权限，才能让 OpenScreen 录制指针的点击和形状。没有“辅助功能”权限时，使用真实鼠标操作的录制片段中，点击处不会缩放：请授予此权限，或像脚本录制片段那样使用 setPointerTrack 移交点击操作。
• Linux： 每次录制都会打开桌面选择器，由用户选择窗口。

交接给下一个会话。 将用户的请求以及已确定的事项写入工作目录中的 openscreen-demo-plan.md。然后请用户启动新会话，并说 继续 OpenScreen 演示。在该会话中，读取此文件并从第 2 步继续。

刚添加插件或服务后，工具不会立即出现：Agent 会在会话启动时加载 MCP 服务。请用简单明白的话说明这一点，并按上述方式交接；如果已制作分镜脚本，也要写入文件。切勿通过计算机操作或鼠标工具来操作 OpenScreen 窗口，以此代替缺失的工具：这会接管用户的鼠标和屏幕，而用户可能正在工作。

2. 录制前先规划

先写好分镜，并用几行内容展示给用户，然后继续操作，除非用户提出异议。

• 一句话。 观众看 3 秒后应该记住什么？第一个镜头展示结果，而不是设置界面。
• 发布演示：3 到 6 个镜头，20 到 60 秒。 每个镜头包含一个操作和一条不超过 6 个字的提示。X 会自动静音播放，因此故事要靠提示来传达，而不是靠旁白。
• 拉取请求视频：1 到 3 个镜头，10 到 30 秒。 展示改动的效果，而不是整个产品：展示新的行为，或不再发生的错误。拉取请求文本会解释其余内容，因此每个镜头配一条简短提示即可。
• 使用真实感数据。 为应用填入看起来可信的内容。屏幕上不要出现真实客户数据、机密、令牌或个人通知。

3. 设置场景

• 启动应用，并将其打开到第一个镜头的起始状态。
• 打开一个整洁的窗口，大小约为 1600×1000。对于 Web 应用，可在没有浏览器边框的应用窗口中打开：chrome --app=http://localhost:3000 --window-size=1600,1000 --user-data-dir=<temp folder>。窗口标题就是页面的 <title>。
• 调用 listSources，并选取窗口标题中的独特部分。
• 屏幕上只显示应用。 录制窗口中不要出现浏览器工具栏、地址栏、本地文件路径、用户名、书签栏、翻译提示或通知。录制单个窗口可让桌面其他部分不出现在画面中。

4. 录制

1. 使用 window 调用 startRecording。开始采集后，该调用便会返回。在应用中连接到服务后，录制过程会通过 OpenScreen 的录制栏进行：编辑器关闭，录制栏倒计时，然后 stopRecording 会在编辑器中打开这段录制。只有用户想要出现在画面中时才传入 camera：此时网络摄像头画面会以画中画形式显示。用户要进行旁白时传入 microphone: true：否则录制没有语音，也就没有内容可加字幕。
2. 按分镜操作。动作要从容，并在每个结果出现后暂停约 1 秒。
3. 使用 title 调用 stopRecording。保留其返回值：projectId、checkpointId、videoPath、recordingStartedAt。

操作应用的方式决定光标的呈现。

• 真实鼠标（计算机使用功能，或任何能移动实际指针的工具）：OpenScreen 会记录指针、绘制清晰的光标，并自动放大点击位置（参见下文的 放大操作位置）。如果你的鼠标工具无法在应用窗口中点击（例如，有些工具只能读取浏览器），请改用脚本操作。
• 脚本（Playwright、CDP）：屏幕指针不会移动，因此录制中没有光标，也不会放大。在脚本运行时记录每个操作：at 为 Date.now()，x 和 y 是操作位置相对于窗口的比例，点击时 click 为 true。stopRecording 后将日志传给 setPointerTrack；其说明会提供从页面坐标换算的公式。使用脚本也能获得最干净的录制：每次运行的时序相同，不会迟疑。

已有视频无需录制：使用其绝对路径 videoPath 调用 createProject，即可将其整理为项目，并像 stopRecording 一样返回 projectId 和 checkpointId。在第 5 步中将其作为录制内容检查，包括其 videoPath，然后从第 6 步继续。

5. 检查录制内容

对 videoPath 调用 getFrames，获取约 6 帧。窗口对吗？有没有显示任何隐私信息？每个镜头都发生了吗？如果没有，就重新录制：重新录制的成本低于剪辑修复。

6. 剪辑

使用文档工具时，始终提供 projectId。先用 getCurrentDocument 读取项目：其中的备注会说明哪些时间使用录制内容的秒数，哪些使用编辑器标尺上的时间。

统一时钟。 所有效果都按标尺上的秒数放置，并使用 getFrames 和 projectId 查看结果；两者采用相同的秒数。不要从导出文件读取时间：剪切或加速会使其时间与标尺不再一致。

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

其余部分保持原样：背景、内边距、阴影和光标样式都已选好，效果美观。用户要求更换样式时，使用 setEditorSettings 设置背景、画框、摄像头布局、光标和音量；getCurrentDocument 会在 settings 下显示当前值，settingsContext.inactive 会指出哪些设置目前不会产生任何变化。

7. 导出和检查

1. 使用 projectId 和绝对路径调用 exportVideo：先将 demo/demo.mp4 等路径解析为相对于当前工作目录的路径，因为应用中的服务不接受相对路径。为拉取请求视频传入 quality: "medium"（720p），以减小文件体积。对于 GIF（例如 README 中使用的 GIF），将路径以 .gif 结尾，并传入 gifSize: "small"（480p）。
2. 在各个节拍对应的时间标尺秒数处，使用 projectId 调用 getFrames。编辑时，你可以在导出前调用它：如果没有当前导出，它会渲染导出时会显示的帧。
3. 检查每一帧：
   • 每个标注是否清晰易读，且没有遮挡操作？
   • 每个缩放是否都聚焦在发生变化的内容上？
   • 是否有黑帧、被截断的文字或残留的初始设置画面？
4. 修复项目并重新导出，直到效果合适为止。

绝不要将视频提交到代码仓库：视频应放在拉取请求或帖子中，而不是代码里。

8. 将视频附加到拉取请求

仅限用户要求添加视频的拉取请求，或你在本任务中为用户创建的拉取请求。

1. 检查文件大小。 GitHub 免费方案的仓库最多可上传 10 MB 的视频，付费方案最多可上传 100 MB。超过限制时，缩短某个节拍或加快播放速度，然后重新导出。

2. 在文件中撰写视频说明，例如 demo/pr-video.md：用一行说明视频展示的内容，然后单独用一段放置视频，这样 GitHub 才会显示播放器而不是链接：

   **Demo:** the export dialog now remembers the last format.
   
   ![](demo/pr-video.mp4)
   

3. 使用 gh 附加视频，版本需为 2.99.0 或更高（gh --version）。gh 会上传文件，并用文件的 URL 替换路径。你需要拥有仓库的推送权限。

   • 对于现有拉取请求，作为评论发布：gh pr comment <number> --body-file demo/pr-video.md --attach demo/pr-video.mp4
   • 对于你正在创建的拉取请求，将相同的两行放入其正文，并向 gh pr create 传入 --attach demo/pr-video.mp4。

4. **如果使用较旧版本的 gh，**请让用户更新它。在 GitHub Enterprise Server 上，gh 完全无法附加文件，此时不要使用 --attach。这两种情况下，都应使用能够在拉取请求页面的评论框中附加文件的浏览器工具；否则，将文件和要粘贴的文本交给用户，让他们自行添加。

5. 报告评论或拉取请求的 URL。

9. 发布到 X

1. 撰写帖子。 最多 280 个字符：先写吸引人的开场，再说明视频内容，然后添加链接（如有）。标签最多一个或两个。
2. 检查 X 的限制。 对于未开通 Premium 的账号，视频必须为 MP4，时长不超过 2 分 20 秒，大小不超过 512 MB。导出的视频符合要求。
3. 征求用户同意。 展示帖子文本、视频路径和一帧画面，并明确询问用户是否同意。用户在较早步骤中说“看起来不错”不算同意。
4. 仅在用户同意后发布。 使用能够在 https://x.com/compose/post 的编辑框中附加文件的浏览器工具，或者使用用户已配置的 X API。如果无法附加文件，就将文本和文件交给用户。
5. 报告帖子的 URL。

出现问题时

• **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。