录屏讲解视频

零、何时用我 / 何时用别人（区隔，先读这段）

已废弃、不要再用：product-video-generator（能力已被本 skill 完整覆盖，且本机路径失效）；book-video-factory / hsf-shipintuiguang（已被 hsf-book-video 超集包含）。

一、功能与能力范围

能做的事

输入一段竖屏手机录屏，自动走：抽帧 → 功能识别 → 聚类切分 → 写旁白 → 配音 → 切段 → 合成竖屏成品。 真正卖点：录屏无需人工标时间窗——讲到哪个功能，画面自动停在那个功能的操作/结果页。

• 录屏 → 讲解视频全流程（主推，A 线）

输出句子级旁白脚本（每句绑定录屏时间窗 src），可单独审阅/修改后再合成。

• 讲解脚本产出

edge-tts 配音，支持换声（XiaoyiNeural 女清亮 / YunjianNeural 男沉稳 等）、调速（Rate=-15% 放慢）； 字幕由音频驱动、词级高亮，句间自然停顿无长静音。

• 配音 + 字幕（自带）

fork 内联为自带 scripts/compose_video.py，不引用、不依赖 原版 book-video-generator。 单独拷贝到任意机器即可运行（需隔离 venv 装 edge_tts / Pillow / imageio-ffmpeg）。

• 合成引擎独立可部署

产出 segments.json（改文案/换声重合成）、各段 mp3 + words.json、最终 MP4。

• 可重跑的交付物

书名+作者 → 写稿 → AI插图 → 配音 → 横屏16:9合成。本 skill 仅复用 compose 引擎， 写稿/生图环节需外部 LLM + 图像生成（参考 book-video-generator 原流程）。

• 图书解说线（B 线，复用引擎）

• 60 秒混剪模式（C 线，投放浓缩液）

把内容体系多形态素材（场景种草镜头、试用体验录屏、背书件用户画面、FAQ 痛点句）压成一条 60 秒投放短视频。方法论见 references/60s-mix-edit.md：标准时间轴（钩子→痛点→产品→卖点→ 证据→CTA）、四套语言（镜头/字幕/声音/节奏）、分镜脚本格式（一镜一行→segments.json）、 五问质量底线、数据闭环。合成复用 compose_video.py 多分镜（segments/segment_chapters/ cover/keywords/transition_interval 已支持），无需新开发。

能力边界（不做 / 限制）

三、A 线流程（操作视频 → 讲解视频）

自动模式（推荐，已验证）

无需人工标时间窗——脚本自动抽帧、按功能聚类切分、写旁白、配音、出片：

PY scripts/auto_build.py --raw "<录屏路径>" --out "<输出目录>"   # 全流程
PY scripts/compose_video.py < <输出目录>/segments.json           # 合成竖屏成品

auto_build.py 内部流程：

• 抽帧（每 5s 一帧）→ frames/ + manifest.json

• 多模态识别：当前由 AI 用 Read 逐帧看，把每帧 {秒: 画面描述} 回填进 FRAME_CAPTIONS

• cluster_segments() 按功能聚类自动切分时间窗（连续同功能帧聚成一段）

• SCRIPT 模板按功能段生成句子级旁白（每句 src 取段首秒），真实环境可换 LLM 生成

• edge-tts 配音 + -ss/-t 切视频段 + 写 segments.json（含竖屏字段）

参数化：--raw 录屏路径（或环境变量 HSF_RAW_VIDEO）、--out 输出目录（或 HSF_WORKDIR）。 默认 RAW 回退到 心宠2.mp4 示例，换产品必须传 --raw。

手动模式（Option B，精细化）

• 用 Read 逐帧看录屏，人工标"功能节点时间窗"表

• 在 gen_voiceover_cut.py 的 SEGMENTS 里，每条短句配 src（录屏秒数）

• PY gen_voiceover_cut.py → 配音 + 切段 + 写 segments.json

• PY scripts/compose_video.py < segments.json → 合成

参数速查（gen_voiceover_cut.py / auto_build.py 顶部）

• VOICE：音色。zh-CN-XiaoyiNeural(女清亮) zh-CN-XiaoxiaoNeural(女温柔,默认) zh-CN-YunjianNeural(男沉稳) zh-CN-YunyangNeural(男讲述)

• RATE：语速。-15% 放慢，+10% 加快

• video_width/video_height：竖屏 576/1280（或 720/1280）；横屏 1920/1080

• max_chars：字幕每行字数，竖屏 14，横屏 16

四、B 线流程（图书 → 视频，简述）

• LLM 根据书名+作者写解说文案 → 2. 拆分镜 → 3. AI插图生成 → 4. TTS配音 → 5. compose_video.py 合成（横屏1920×1080）

五、已知坑（必看）

• segments.json 必须含 video_width/video_height —— 不显式传则回退 1920×1080 横屏，竖屏录屏被压扁+黑边。

• 音频驱动时长 —— 视频段时长由音频决定（-shortest），别在 segments 写虚高 duration（会拖尾静音）。

• edge-tts 词级时间戳 —— Communicate(..., boundary="WordBoundary") 才能拿逐词时间，否则字幕整段同时出现。

• ffprobe 不存在 —— 用 ffmpeg -i 解析或 imageio_ffmpeg 路径。

• Windows 沙箱无 /tmp —— 落盘用工作区绝对路径。

• heredoc 引号转义易错 —— 长脚本写成 .py 文件再跑，别 inline。

六、输入参数（调用时向用户确认）

• 录屏路径（必需）：本地视频文件

• 画幅：默认竖屏（产品录屏）；横屏仅图书线

• 音色：默认 XiaoyiNeural 女清亮；可换

• 语速：默认 -15% 放慢

• 模式：自动（推荐）/ 手动精细化

七、交付物

• 成品 MP4（竖屏讲解视频）

• segments.json（可重跑）

• 各段 mp3 + words.json（可换声重合成，不必重新切视频）

• 录屏指南（发合作方）：references/录屏指南.md

八、独立性说明（重要）

合成引擎 scripts/compose_video.py 已 fork 内联，不引用原版 book-video-generator 任何文件。 单 skill 拷贝到任意机器（装好 venv 依赖）即可运行。自动模式 auto_build.py 的录屏源通过 --raw / 环境变量 HSF_RAW_VIDEO 传入，不写死示例路径。

常见问题