演示到宣传短片：Screen Studio 风格网页应用演示

webapp-screencast

您编排录制内容，webapp-screencast 负责录制和编辑。输出：OUT/<name>.mp4（1920×1080，60 fps）以及一张海报 .jpg 图片。所有内容都是您编写的文件（scenario.py、plan.py）和一个 CLI 命令。 始终使用 --json 参数（在子命令之前）调用 CLI：标准输出为一个 JSON 对象（ok、error、路径、时长、警告）；进度信息输出到标准错误。退出码 0 表示成功，1 表示步骤失败，2 表示输入错误。

API 和计划键值说明：reference.md。在编写 scenario.py / plan.py 之前请先阅读该文件。

0. 环境设置（每台机器只需一次）

webapp-screencast --json doctor

如果缺少 webapp-screencast：执行 pip install git+https://github.com/dr-osmanovich/webapp-screencast.git （如果项目有虚拟环境，请使用该虚拟环境），然后执行 python -m playwright install chromium。 doctor 命令会列出每个失败的检查项及其修复方法。渲染需要 Node 22+ 和 ffmpeg。

1. 了解应用（开始录制前）

• 找到应用的本地运行方式（README、package.json 脚本、Makefile、docker-compose）及其 URL。 纯静态文件夹可以由 webapp-screencast 本身提供服务（make --serve DIR）。
• 在仓库中找到 演示/种子数据和测试账户（fixtures、种子脚本、.env.example）。 绝对不要录制生产环境、真实客户或患者数据，也不要录制真实凭据。如果没有安全的演示数据，请停止并询问用户。
• 了解如何 重置状态（种子/重置脚本、清除 localStorage）。每次录制都从干净状态开始。
• 选取 3-5 个关键点来展示价值：吸引点 → 操作 → 结果 → 一个细节 → 结束。录制 15-30 秒的片段。
• 阅读实际组件以获取稳定的选择器（id、data-testid、角色）。不要猜测。

2. 搭建脚手架和编写脚本

webapp-screencast --json init video/ --base-url http://127.0.0.1:3000 --title "产品名称"

编写 video/scenario.py：CONFIG，可选的 login(page, cfg) 和 prepare(page, cfg)，以及 run(take, page)。以下规则可减少重录次数：

• 在每个关键点使用 take.mark("name")；对所有需要被镜头或标注框选中的元素使用 take.box("name", selector)（或 click(..., name=)）。始终先标记 hook，最后标记 end。
• 在操作后使用 page.wait_for_selector(...) 等待应用响应，然后使用 take.hold(0.3–0.8)。
• 在 take.type(...) 之前将鼠标指针移离文本区域；以 25-35 的 cps（每秒字符数）速度输入。
• 在 prepare() 中隐藏提示框、Cookie 横幅、开发者覆盖层；关闭侧面板。
• 原生的 title= 工具提示在无头模式下不会渲染——请改用计划中的 callout。

3. 录制和检查

webapp-screencast --json record video/scenario.py --out video/out/footage [--base-url URL]
webapp-screencast --json inspect video/out/footage

检查繁忙关键点的 peak_fps 是否 ≥ 50（macOS 上可能更低 → GPU 标志问题，请参阅参考文档），并确保您计划的所有标记都存在。选择器失败会通过标准错误输出 Playwright 错误：修正场景脚本后重新录制——录制片段的成本很低（≈ 关键点时长 + 10 秒）。

4. 规划、合成、审视

使用 inspect 输出的标记和框（永远不要硬编码秒数）编写 video/plan.py： 跟随操作的镜头片段（关键点处缩放 1.4-1.7 倍，场景之间恢复为 1.0 倍），每个关键点添加一个简短字幕（每个词至少 0.3 秒，无重叠），以及介绍/结束卡片。

webapp-screencast --json compose video/plan.py --footage video/out/footage --out video/out/composition
webapp-screencast --json snapshot video/out/composition --at 1,5,9,14 --out video/out/stills

修正所有 warnings 条目。查看截图（读取 PNG 图片或缩略图）：文本可读，镜头对准操作，没有裁剪，字幕不覆盖其描述的内容。仅通过 compose + snapshot 迭代修改 plan.py——无需重新录制。

5. 渲染和交付

渲染大约每 20 秒片段需要 4-5 分钟（M1 芯片上）——建议在后台运行并同时输出日志文件。

webapp-screencast --json render video/out/composition --out video/out/video.mp4
webapp-screencast --json poster video/out/video.mp4 --at 9.0

确认 JSON 输出中显示 fps: 60 和预期的时长。交付 mp4 和海报文件路径。 在 .gitignore 中添加 out/ 目录；提交 scenario.py + plan.py，以便在 UI 更改后可以重新生成视频。

当场景脚本和计划已经完善时，可以使用一键命令： webapp-screencast --json make video/scenario.py video/plan.py --out video/out --base-url URL --poster-at 9 （静态网站使用 --serve DIR，添加 --skip-render 可在检查后停止）。

配合 /brag（或其他启动视频技能）

Brag 决定故事内容；webapp-screencast 提供真实录制的素材。

1. 运行 brag 自己的规划：概念、基调、关键点、标题、文案。在其构建截图场景之前停止。
2. 将 brag 的关键点转换为 scenario.py 中的标记（每个关键点一个标记）并录制。
3. 将 brag 的文案放入 plan.py：吸引点 → intro.title，关键点说明 → subtitles，收尾语/行动号召 → outro；将 brag 的基调映射为 look（精致 → graphite/ocean、活泼 → sunset/violet，强调色 = 应用 CSS 中的品牌颜色）。
4. 按上述步骤合成、截图、渲染到 brag 的输出文件夹中；然后让 brag 编写分享文案。 目前仅支持 16:9 横向格式；如果 brag 要求纵向格式，请说明并渲染为横向格式。