Web Demo Video Synthesis

核心原则

1. 先锁定文案，再执行技术流水线。
2. 语音必须按段生成（每段独立可重试，可定位失败）。

3. timeline.json

   是全链路主键：录屏、音频编排、字幕都基于它。
4. 录屏阶段输出“无字幕母带”，字幕在最终合成阶段统一烧录。
5. 禁止静默降级：缺参数、schema 错误、时序冲突必须直接报错。

网页演示设计偏好（默认建议）

• 结构优先“每页一主题”：一段旁白对应一个完整页面/板块，讲完再翻页，避免“一屏塞满全部信息”。
• 默认视觉方向：白色/米色背景 + 轻松活泼但有科技感的点缀色（青绿/天蓝/暖橙），减少沉重暗色与“AI 味”紫色方案。
• 保持高信息密度与可读性平衡：标题醒目、正文简洁、层次清晰、每页有明确视觉重心。
• 尽量做成“多媒体网页 demo”而不是纯文字卡片：图表（折线/柱状/环形/热力）、指标卡、动效（数字跳动/进度条/光扫）、图片/插画、轻量交互（hover/选项切换）都会让录屏成片更像“真实产品演示”，显著降低“AI 味”。
• 对外发布前至少做一次“竖屏真机视角”复核：确认翻页节奏、字幕安全区、关键视觉元素不被裁切。

文案与读音（中文 TTS 经验）

中文配音（例如阿里云 ISI

zhida

）时，如果旁白里出现大量英文/缩写/口语拼接，容易出现“读不对/怪口音”，建议做如下处理（这是内容层面的修复，优先于换 TTS 引擎）：

• 把关键术语改成中文：例如把

  workspace

  写成“工作空间”，把

  retry

  写成“重试”。
• 避免容易读错的短词组合：例如把“重配音”写成“重新配音”（更自然，也更不容易误读）。
• 对必须保留的英文缩写，尽量在第一次出现时给出中文解释：例如 “TTS（text-to-speech，文本转语音）”。

依赖与安装（独立发布必需）

该 skill 可单独拷贝发布，但需要安装运行依赖：

• python3

  （建议 3.10+）
  • 需要的 Python 包：

    requests

  • 录屏与后期合成不依赖 Python 的 GUI

• node

  （建议 18+）+

  npm

  • 需要 Node 包：

    playwright

  • 需要安装浏览器：

    npx playwright install chromium

• ffmpeg

  • 需要完整构建，至少支持：

    libass

    （字幕烧录）与

    libx264

    （H.264 编码）

最小安装示例（仅供参考，具体按你的环境调整）：

pip install requests
npm install playwright
npx playwright install chromium

执行目录约定：

• 以下命令默认在

  web-demo-video-synthesis/

  目录内执行（即本

  SKILL.md

  同级目录）。
• 若你从其他目录执行，请自行加上前缀路径。

向人类索要的密钥/Token（必须明确）

该流程可能需要人类提供以下敏感信息（不应提交到代码仓库）：

• 阿里云 ISI（Intelligent Speech Interaction）TTS：

  • Appkey

    （项目级 Appkey）

  • AccessToken

    （短期 token）
  • 保存为

    key.json

    ，字段名兼容：

    appkey/app_key/api_key

    与

    token/access_token/AccessToken/accessToken

• 给人类的参考链接（建议在索要秘钥时一并发给对方；链接可能会变化，若失效请在阿里云文档站内搜索关键词）：
  • 控制台（NLS Portal / 智能语音交互）：

    https://nls-portal.console.aliyun.com/overview

  • RESTful API 文档（语音合成）：

    https://help.aliyun.com/zh/isi/developer-reference/restful-api-3

    • 备注：我在 2026-03-06（Asia/Shanghai）验证过该链接可访问，但页面内部锚点（

      #topic-...

      ）可能不稳定。
  • ISI 文档入口（用于查“Token 获取方式/鉴权说明/参数表”等）：

    https://help.aliyun.com/zh/isi/

推荐优先级（明确，不做静默降级）：

1. 先进的 TTS API（推荐，优先级最高）：例如阿里云 ISI（本 skill 默认实现），或你们自行接入其他更先进的 TTS。
2. 本地替代（仅用于无秘钥快速验证）：例如 macOS

   say

   （无需密钥，但音色/自然度通常弱于先进 TTS）。

也可以替换其他 TTS 服务商，但需要你们自行研究对应 API，并保证输出满足：

• 分段音频可落盘（每段一个文件）
• 可拿到每段时长（用于 timeline）

Workspace 风格（推荐）

目标不是“每次从头跑一个专门的 run”，而是搭建一个可协作的工作目录，然后按顺序维护关键文件：

建议 workspace 目录结构（示例：

temp/web_demo_video_ws/demo01/

）：

• inputs/cues.json

  ：旁白分段文案（锁版本）

• secrets/key.json

  ：TTS 鉴权（不入库）

• segment_audio/

  ：每段音频缓存（可复用）

• timeline/timeline.json

  ：主键时间轴（可编辑）

• audio/timeline_audio.mp3

  ：按 timeline 混出的总音轨（可重建）

• video/video_nocap.webm

  ：按 timeline 录制的无字幕母带（可重录）

• subtitles/captions.srt

  ：由 timeline 导出的字幕（可重建）

• final/final.mp4

  ：最终成片（可重建）

这种布局支持你们迭代：

• 改文案：只重跑 TTS + 生成 timeline
• 改 timeline：只重混音 + 重录屏 + 重合成
• 改字幕样式：只重合成（烧录字幕）

推荐操作顺序（手动可控，便于协作）

1. 初始化 workspace（第一次）

• 准备

  inputs/cues.json

  （锁版本）
• 准备

  secrets/key.json

  （人类提供，不入库）
• 跑一次分段 TTS + timeline（生成器会产出 run 历史）
• 把该次 run 的产物 promote 到 workspace（后续迭代用 workspace 文件为准）

2. 迭代调 timeline（常见）

• 人类/Codex 编辑

  timeline/timeline.json

• 用

  mix_audio_from_timeline.py

  重建

  audio/timeline_audio.mp3

3. 迭代录屏（常见）

• 用

  record_demo_from_timeline.mjs --no-captions true

  生成

  video/video_nocap.webm

• 前提：你的 demo 前端服务必须已启动且

  record_url

  可访问，否则 Playwright 会失败并退出（正确失败）。

• record_url

  对应端口必须可控且唯一，避免被其他本地服务占用后录到错误页面。
• 若出现“滚动就位慢于开声”，优先调大

  scripts/tts_build_workspace.py

  的

  --scroll-lag-sec

  或

  --inter-gap-sec

  （让开声更晚），其次再考虑提高录屏脚本的

  --scroll-settle-ms

  （仅影响录屏等待，不改变音轨时间）。

4. 迭代字幕与合成（常见）

• 用

  build_srt_from_timeline.py

  生成

  subtitles/captions.srt

• 用完整 ffmpeg 合成最终

  final/final.mp4

输入约定（最小集）

• cues.json

  ：最终旁白文案（只含可播报文本，不含导演提示）。

• record_url

  ：demo 页 URL（例如

  http://127.0.0.1:6150/demo

  ）。

• key.json

  ：TTS 鉴权（阿里云 Appkey + AccessToken）。

• seed_video

  ：任意可读取视频（用于时间预算与流水线基准输入）。

输入 schema：

• 旁白 cues：见 references/subtitle_schema.md
• timeline 结构：见 references/steps_schema.md

标准流程（workspace 迭代版）

1. 固化文案（锁版本）

• 文案先冻结，再录制与合成，避免“视频一半后字幕改稿”。

2. 分段 TTS

• 调用

  scripts/tts_build_workspace.py

  ，逐段生成音频并生成

  timeline/timeline.json

  。
• 产物：

  segment_audio/*.wav

  、

  timeline/timeline.json

  、可选

  audio/timeline_audio.mp3

  。

可选：无秘钥的本地 TTS（macOS say）

当你暂时拿不到任何 TTS API 的秘钥/Token，但仍希望先把“网页录屏/字幕/合成”跑通，可以显式改用 macOS

say

：

python3 scripts/tts_build_workspace_macos_say.py \
  --workspace-dir temp/web_demo_video_ws/demo01 \
  --cues-json temp/web_demo_video_ws/demo01/inputs/cues.json \
  --voice Tingting \
  --sample-rate 48000 \
  --inter-gap-sec 2.5 \
  --scroll-lag-sec 1.2 \
  --mix-audio

注意：

• 这是 显式选择 的替代方案，不会在

  tts_build_workspace.py

  里自动 fallback（避免“看起来成功”的静默降级）。

• voice

  的取值与服务商强相关：
  • ISI 的 voice（例如

    emily

    /

    zhida

    ）以服务商文档为准；
  • macOS

    say

    的 voice（例如

    Tingting

    /

    Samantha

    ）用

    say -v '?'

    查询。

3. 基于 timeline 二次录屏（无字幕）

• 使用

  scripts/record_demo_from_timeline.mjs --no-captions true

  。
• 产物：

  video_from_timeline_nocap.webm

  。

4. timeline -> 字幕文件

• 从

  timeline.json

  的

  segments

  生成

  .srt

  （逐段

  start_sec/end_sec/text

  ）。

5. 最终合成（视频 + 语音 + 字幕）

• 使用完整构建的 ffmpeg（系统安装版本即可）。
• 输出高质量 MP4。

一键执行（模板化参数，不建议写死）

WORKSPACE_DIR="temp/web_demo_video_ws/demo01"
RECORD_URL="http://127.0.0.1:6150/demo"
CUES_JSON="$WORKSPACE_DIR/inputs/cues.json"
KEY_JSON="$WORKSPACE_DIR/secrets/key.json"

bash scripts/make_demo_video.sh \
  --workspace-dir "$WORKSPACE_DIR" \
  --cues-json "$CUES_JSON" \
  --key-json "$KEY_JSON" \
  --record-url "$RECORD_URL" \
  --voice auto \
  --record-lang zh \
  --record-viewport 1920x1080 \
  --record-size 3840x2160 \
  --record-device-scale-factor 2 \
  --record-scroll-behavior auto \
  --record-scroll-settle-ms 420 \
  --subtitle-font-name "Arial" \
  --subtitle-font-size 13 \
  --subtitle-margin-v 24 \
  --subtitle-margin-l 48 \
  --subtitle-margin-r 48 \
  --subtitle-auto-wrap true \
  --subtitle-wrap-max-units 42

--voice auto

规则：

• --record-lang en*

  ->

  emily

• --record-lang zh*

  ->

  zhida

• 其他语言默认回退到

  emily

竖屏短视频推荐参数（如小红书）

• 版式建议：关键视觉内容放在“中间偏上”，字幕放在“中间偏下”（避免画面与字幕重叠；也避免顶部/底部 UI 安全区遮挡）。
• 录制：

  --record-viewport 1080x1920 --record-size 1080x1920 --record-device-scale-factor 1

• 字幕安全区（两种常用思路，二选一并迭代调参）：
  • 更大字：

    --subtitle-font-size 13~15 --subtitle-margin-v 72~108 --subtitle-margin-l 72~120 --subtitle-margin-r 72~120

  • 更小字（推荐默认；信息密度更高，且更不遮画面）：

    --subtitle-font-size 10 --subtitle-margin-v 28 --subtitle-margin-l 96 --subtitle-margin-r 96

• 自动换行（推荐默认）：

  --subtitle-auto-wrap true --subtitle-wrap-max-units 38

  （竖屏通常需要更积极的换行与更大的左右安全区）
• 字幕仍越界时，优先顺序：
  1. 增大

     subtitle-margin-l/r

  2. 降低

     subtitle-font-size

  3. 调小

     subtitle-wrap-max-units

  4. 仍不够再拆分过长文案（

     cues.json

     ）

字幕与画面仍重叠时的经验优先级（重要）：

1. 优先把网页“当 PPT 读”的主体上移：在网页里给底部留白（例如每页增加

   padding-bottom

   ），为字幕留出固定安全区。
2. 其次再调字幕（例如降低

   MarginV

   让字幕更靠底部），但不要把字幕压到平台底部 UI 区域里。

竖屏一键参数示例（推荐从这个起步再微调）：

WORKSPACE_DIR="temp/web_demo_video_ws/demo01"
RECORD_URL="http://127.0.0.1:6150/demo"

bash scripts/make_demo_video.sh \
  --workspace-dir "$WORKSPACE_DIR" \
  --record-url "$RECORD_URL" \
  --record-lang zh \
  --voice auto \
  --record-viewport 1080x1920 \
  --record-size 1080x1920 \
  --record-device-scale-factor 1 \
  --record-wait-until domcontentloaded \
  --record-expect-selector "#step-hero" \
  --record-scroll-settle-ms 600 \
  --subtitle-font-name "PingFangSC-Regular" \
  --subtitle-font-size 10 \
  --subtitle-margin-v 28 \
  --subtitle-margin-l 96 \
  --subtitle-margin-r 96 \
  --subtitle-auto-wrap true \
  --subtitle-wrap-max-units 38

备注：

• --subtitle-font-name

  与系统字体有关：macOS 常用

  PingFangSC-Regular

  ；Linux 可用

  Noto Sans CJK SC

  （按你系统已安装字体为准）。

横屏（16:9）推荐参数（如 X / YouTube）

横屏的字幕与竖屏不同点：

• 画面横向空间更大：每行可更长，不需要太激进的换行。
• 常见输出分辨率有 1080p 与 4K：FontSize/Margins 需要跟分辨率成比例调整。

横屏字幕专项经验（这次反复调参后的关键结论）

1. 先区分“硬换行”与“软换行”：
   • 硬换行：SRT 里已经写入

     \n

     （例如

     build_srt_from_timeline.py

     的

     --wrap-max-lines 2

     或偏小的

     --wrap-max-units

     导致）。
   • 软换行：SRT 一行文本，最终由渲染器按可用宽度自动断行。
2. 如果已经“硬换行”过早，后续只改

   MarginL/MarginR

   常常看不出提升，因为可显示宽度已经在 SRT 阶段被锁死。
3. 横屏想“减少频繁换行”，优先使用：

   • --wrap-max-lines 0

     （不强制二行上限）
   • 更大的

     --subtitle-wrap-max-units

     （例如

     140~180

     ）
   • 更小的

     MarginL/MarginR

     （例如

     8~40

     ）
4. 推荐调参顺序（避免反复返工）：
   1. 固定

      FontSize

      到“听感/可读性满意”的值
   2. 逐步减小

      MarginL/R

      扩大显示区
   3. 再增大

      wrap-max-units

      减少预断行
   4. 仍频繁换行时再考虑拆分文案或微降字号
5. 经验上，

   --subtitle-wrap-max-lines 2

   仅适合你明确需要强制两行美观的场景；对长句讲解视频，它更容易制造“没必要的换行”。

推荐起步（1080p，1920×1080）：

• 录制：

  --record-viewport 1920x1080 --record-size 1920x1080 --record-device-scale-factor 1

• 字幕：

  --subtitle-font-size 14~20 --subtitle-margin-v 24~56 --subtitle-margin-l 24~80 --subtitle-margin-r 24~80

• 换行：

  --subtitle-wrap-max-lines 0 --subtitle-wrap-max-units 110~160

  （先让每行吃满，再看是否需要更强约束）

推荐起步（4K，3840×2160；更清晰，适合桌面观看）：

• 录制：

  --record-viewport 1920x1080 --record-size 3840x2160 --record-device-scale-factor 2

• 字幕：

  --subtitle-font-size 13~16 --subtitle-margin-v 18~36 --subtitle-margin-l 8~40 --subtitle-margin-r 8~40

• 换行：建议

  --subtitle-wrap-max-lines 0 --subtitle-wrap-max-units 140~180

  （横屏优先少换行，避免句子被切碎）

横屏一键参数示例（4K）：

WORKSPACE_DIR="temp/web_demo_video_ws/demo01"
RECORD_URL="http://127.0.0.1:6150/demo"

bash scripts/make_demo_video.sh \
  --workspace-dir "$WORKSPACE_DIR" \
  --record-url "$RECORD_URL" \
  --record-lang en \
  --voice auto \
  --record-viewport 1920x1080 \
  --record-size 3840x2160 \
  --record-device-scale-factor 2 \
  --record-wait-until domcontentloaded \
  --record-expect-selector "#step-hero" \
  --record-scroll-settle-ms 520 \
  --subtitle-font-name "Arial" \
  --subtitle-font-size 14 \
  --subtitle-margin-v 24 \
  --subtitle-margin-l 8 \
  --subtitle-margin-r 8 \
  --subtitle-auto-wrap true \
  --subtitle-wrap-max-units 170 \
  --subtitle-wrap-max-lines 0

备注：

• --record-lang

  主要用于录屏脚本的语言设置与

  --voice auto

  的默认音色映射；请按你的视频语言选择（例如中文

  zh

  ，英文

  en

  ）。

常用局部命令（只重跑某一步）

分段TTS + timeline（直接写 workspace，可迭代；默认防止静默复用旧音频）：

python3 scripts/tts_build_workspace.py \
  --workspace-dir temp/web_demo_video_ws/demo01 \
  --cues-json temp/web_demo_video_ws/demo01/inputs/cues.json \
  --key-json temp/web_demo_video_ws/demo01/secrets/key.json \
  --voice emily \
  --sample-rate 48000 \
  --inter-gap-sec 2.5 \
  --scroll-lag-sec 1.2

改了 timeline 后重混音：

python3 scripts/mix_audio_from_timeline.py \
  --timeline temp/web_demo_video_ws/demo01/timeline/timeline.json \
  --output temp/web_demo_video_ws/demo01/audio/timeline_audio.mp3

按 timeline 录无字幕母带：

node scripts/record_demo_from_timeline.mjs \
  --url http://127.0.0.1:6150/demo \
  --timeline-json temp/web_demo_video_ws/demo01/timeline/timeline.json \
  --out temp/web_demo_video_ws/demo01/video/video_nocap.webm \
  --viewport 1920x1080 \
  --record-size 3840x2160 \
  --device-scale-factor 2 \
  --lang en \
  --wait-until networkidle \
  --fail-on-json true \
  --expect-selector "#step-hero" \
  --expect-timeout-ms 12000 \
  --no-captions true

录屏阶段的“正确失败”防护（强烈建议）：

• --fail-on-json true

  （默认 true）：如果

  record_url

  返回

  application/json

  ，会直接失败。
  • 典型原因：端口被占用导致访问到了别的服务，或录到了 API/404 JSON 而不是网页。

• --expect-selector

  /

  --expect-title-includes

  ：对目标页面做最小的存在性校验，避免把错误页面录成“看起来成功”的视频。

• --wait-until domcontentloaded

  ：对 SPA/持续请求的页面更稳（否则

  networkidle

  可能等不到）。

timeline -> SRT：

python3 scripts/build_srt_from_timeline.py \
  --timeline temp/web_demo_video_ws/demo01/timeline/timeline.json \
  --output temp/web_demo_video_ws/demo01/subtitles/captions.srt

最终合成（视频+音轨+字幕）：

ffmpeg -y \
  -i temp/web_demo_video_ws/demo01/video/video_nocap.webm \
  -i temp/web_demo_video_ws/demo01/audio/timeline_audio.mp3 \
  -vf "subtitles=temp/web_demo_video_ws/demo01/subtitles/captions.srt:force_style='Alignment=2,MarginV=24,MarginL=48,MarginR=48,FontName=Arial,FontSize=13,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BorderStyle=3,Outline=1,Shadow=0'" \
  -c:v libx264 -preset medium -crf 18 \
  -c:a aac -b:a 192k \
  -shortest \
  temp/web_demo_video_ws/demo01/final/final.mp4

关键产物

• workspace 内产物（推荐）：

  inputs/ segment_audio/ timeline/ audio/ video/ subtitles/ final/

必读参考

• references/subtitle_schema.md：文案分段输入规范
• references/steps_schema.md：timeline 结构与约束
• references/quality_tuning.md：清晰度和字幕安全区调优
• references/troubleshooting.md：踩坑与排障清单

Legacy（不推荐）

本 skill 目录里保留了旧的“steps 驱动录屏 + subtitles.json”脚本（用于历史兼容与对照）：

• scripts/record_web_demo_with_playwright.mjs

• scripts/build_subtitles_from_json.py

• scripts/transcode_burn_subtitles.sh

• scripts/inspect_video.sh

建议优先使用 workspace + timeline 路线，避免字幕层在录屏阶段受页面重绘/语言切换影响。