简体中文 | English

视频脚本提取 Skill

一个面向 Codex 的视频拆解 Skill：将本地视频、公开视频直链或可公开取得媒体的网页，整理为带起止时间码、便于理解和复刻的视频脚本。

它会先读取媒体元数据，再要求用户明确选择解析程度、输出格式和是否嵌入代表帧。确认完成后，才会分析画面、台词、画面文字、声音、配乐、镜头调度与打光。

功能

• 支持单个或多个本地视频、公开视频直链，以及无需登录即可取得媒体的网页。
• 区分恒定帧率与可变帧率，分别使用帧时间码或原始时间戳与帧号定位。
• 按镜头切换和有意义的持续变化分段；连续速切按整体汇总，避免无效膨胀。
• 从同一份 VIDEO_SCRIPT_RESULT 渲染 Markdown、Excel 和 Word，避免多格式内容漂移。
• 可按用户选择嵌入代表帧，并检查图片、表格锚点、字体和分页等交付质量。
• 支持媒体预处理、结果缓存、失败恢复、阶段计时和多格式并行渲染。
• 对听不清、看不清或无法验证的内容使用明确的不确定性标记，不把推测写成事实。

本仓库是 Codex Skill，不是一个内置视觉、OCR 或语音识别模型的独立全自动 CLI。实际分析能力取决于当前 Codex 运行时可用的工具和模型。

解析程度

三个程度逐级累积：程度 2 包含程度 1，程度 3 包含程度 1 和程度 2。

程度	主要内容
程度 1	人物、场景、动作、大致镜头类型；全部台词；重要画面文字；配乐起止与变化点
程度 2	增加重要的互动、情绪、表情、动作细节、镜头调度和打光；记录全部画面文字、重要音效与环境音变化，以及配乐特征
程度 3	记录所有持续至少 1 秒且有意义的画面、动作、镜头和灯光变化；记录全部可辨识音效、环境音与更完整的配乐特征

详细规则见 references/analysis-rules.md。

输出格式

• Markdown：适合阅读、版本管理和继续编辑。
• Excel：适合按时间码筛选、排序和批量检查，可嵌入代表帧。
• Word：适合正式交付，包含中文字体映射和片段分页控制。

用户可选择一个或多个格式。是否嵌入代表帧必须单独确认，没有默认值。所有格式都由同一份结构化结果生成，字段规范见 references/output-formats.md。

运行要求

基础要求：

• 支持用户级 Skills 的 Codex 环境。
• Python 3.9 或更高版本。
• ffmpeg 和 ffprobe。

按功能需要：

• Pillow：生成联系表并检查图片。
• python-docx：生成和检查 Word 文件。
• Node.js 与 @oai/artifact-tool：生成 Excel 文件；Codex 桌面运行时通常已提供。
• yt-dlp 或同等工具：读取无需登录的公开网页媒体。
• 可用的视觉检查、OCR 和语音识别能力：完成对应内容分析。
• 中文字体和可用的 DOCX 渲染器：执行 Word 逐页验收。

Skill 不会自动安装缺失工具，也不会在未获授权时把视频、帧、音频、转写或 OCR 内容上传到外部服务。

安装

全新安装：

git clone https://github.com/Stupides9169/video-script-extraction-skill.git \
  ~/.codex/skills/video-script-extraction

更新通过 Git 克隆安装的版本：

git -C ~/.codex/skills/video-script-extraction pull --ff-only

若目标目录已经存在且不是此仓库的 Git 克隆，请先克隆到另一个目录并检查差异，不要直接覆盖本地修改。重启或刷新 Codex 后即可使用。

使用方式

在 Codex 中提供视频文件或公开链接，并说明要提取可复刻的时间码脚本。例如：

提取这个视频的脚本。程度 1，输出 Excel，嵌入代表帧。

拆解这三个视频，我想复刻。先读取元数据，再让我逐个选择解析程度。

如果请求中没有明确给出全部选项，Skill 会先展示元数据并询问：

1. 解析程度 1、2 或 3。
2. 输出 Markdown、Excel、Word，或它们的组合。
3. 是否嵌入代表帧。

单个视频达到 10 分钟时，还需要选择完整分析、按 10 分钟分段，或指定时间区间。

工作流程

1. 验证视频来源，并用 ffprobe 读取时长、分辨率、帧率、编码和 CFR/VFR 信息。
2. 收集本次任务的解析程度、输出格式和代表帧选择。
3. 检查视觉、OCR、语音识别与文档生成能力；缺失时明确暂停。
4. 复用缓存或通过 scripts/prepare_media.py 一次性准备帧、音频和场景数据。
5. 建立并验证唯一的 VIDEO_SCRIPT_RESULT。
6. 通过 scripts/render_outputs.py 渲染所选格式。
7. 通过 scripts/qa_outputs.py 检查产物，再返回文件和诊断路径。

性能、缓存和恢复细节见 references/performance-workflow.md。

隐私与边界

• 不绕过登录、DRM、Cookie、反爬或访问控制；受限来源应由用户提供可读取文件。
• 未明确确认解析程度、输出格式和代表帧选项前，只读取元数据，不分析内容。
• 不自动安装工具，不擅自调用外部服务，不上传用户媒体或派生内容。
• 不覆盖源视频或已有输出；中间文件放在任务专用目录，结束时按规则清理。
• 听不清标记为 [听不清]，可能台词标记为 [可能是：…]，看不清文字标记为 [无法辨认]，其他不确定判断标记为 [不确定]。
• 本 Skill 用于时间码复刻脚本，不用于纯字幕转写、影视评论、创意改编、视频生成、剪辑、转码或发布。

开发与测试

运行完整测试：

python3 -B -m unittest discover -s tests -p 'test_*.py' -v

验证 Skill 结构：

python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py .

部分媒体与渲染测试需要 FFmpeg、Pillow、python-docx，以及 Codex 运行时提供的 Node.js 和 @oai/artifact-tool。结构校验脚本还要求执行它的 Python 环境已安装 PyYAML。

项目结构

.
├── SKILL.md          # 触发条件、确认门禁和主工作流
├── agents/           # Codex UI 元数据
├── references/       # 解析、输出和性能规则
├── scripts/          # 预检、预处理、缓存、渲染与 QA 工具
├── assets/           # Excel 与 Word 模板
└── tests/            # Python 单元与集成测试

许可证

本项目采用 MIT License。