Video Summary

为在线视频生成转写、校订稿、关键画面与图文总结的 Codex skill
A Codex skill for transcripts, reviewed text, keyframes, and illustrated video summaries

中文 · English

---

中文

Video Summary 将在线视频链接整理为一套可归档的内容包：优先使用页面字幕，没有字幕时再对可访问音频进行 ASR；随后保留原始转写、生成保守校订稿、筛选关键画面，并输出独立可读的 Markdown 与图文 PDF。

这是一份 Codex skill 规范及其配套工具，不是视频下载器。它不会绕过登录、付费墙、DRM、CAPTCHA 或浏览器安全限制。

核心能力

能力	作用
字幕优先、ASR 兜底	尽量使用视频自带字幕，必要时通过 faster-whisper 转写可访问音频
保守校订	保留原始 ASR 文本，只修正确认度高的错词和术语
统一文本格式	转为简体中文，并规范为 [HH:MM:SS.s - HH:MM:SS.s] 时间戳
关键画面规划	按视频时长、章节和主题变化生成候选点，并检查时间覆盖
图文报告	生成包含来源链接、内容脉络、关键画面、原始转写片段和可靠性说明的 Markdown 与 PDF
交付验证	检查文件完整性、字幕格式、来源链接、关键画面覆盖与 PDF 可读性

工作流

在线视频链接 -> 读取页面信息 -> 检查字幕

有字幕：保留原始转写

无字幕：ASR 转写可访问音频 -> 保留原始转写

保守校订与简体化 -> 筛选关键画面 -> 生成 Markdown 与 PDF -> 验证交付包

快速开始

克隆到 Codex skills 目录：

git clone https://github.com/flyjancy/video-summary.git ~/.codex/skills/video-summary

安装脚本依赖：

python3 -m pip install -r requirements.txt

PDF 默认使用系统中文无衬线字体；建议安装 Noto Sans CJK。若只能回退到 STSong-Light，渲染器会明确告警，交付前仍需逐页检查中文显示。

在 Codex 中提供一个在线视频链接：

使用 $video-summary 总结这个视频：https://example.com/video

该 skill 需要 Codex 的 Browser 能力读取页面、定位画面，以及 PDF 能力完成渲染检查。ASR 仅在页面没有可用字幕且浏览器会话能够合法访问音频时使用。

输出

每次任务生成一个以视频标题命名的目录：

<video-title>/
├── transcript.txt
├── transcript-reviewed.txt
├── summary.md
├── summary.pdf
└── build/                 # report.json、选中帧、重建说明

transcript.txt 保留 ASR 原始措辞；transcript-reviewed.txt 只做高置信度修正。最终清单和选中帧保留在 build/，临时音频、候选帧和页面预览在验收后清理。

PDF 提供章节书签、关键帧内部跳转及 Bilibili 时间链接；Markdown 的完整关键帧索引由同一清单生成。可靠性说明紧接末帧，空间不足时自动换页。截图裁剪后必须核对图注，模糊细字不能用于新增精确数值。

配套工具

脚本	用途
scripts/transcribe.py	使用 faster-whisper 转写音频
scripts/normalize_transcript.py	规范时间戳并转换为简体中文
scripts/keyframe_plan.py	规划候选画面并检查最终覆盖率
scripts/render_summary_pdf.py	从 JSON 清单生成图文 PDF
scripts/sync_report_index.py	从同一清单同步 Markdown 完整关键帧索引
scripts/validate_bundle.py	验证最终交付包与 PDF

开发与验证

python3 -m unittest discover -s tests -v

修改输出格式、PDF 清单或验证规则前，请先阅读 references/output-contract.md。

---

English

Video Summary turns an online video URL into an archive-ready bundle. It prefers page-provided subtitles, falls back to ASR only for accessible audio, preserves the raw transcript, creates a conservatively reviewed copy, selects representative keyframes, and produces standalone Markdown and illustrated PDF reports.

This repository contains a Codex skill specification and its supporting tools. It is not a video downloader and does not bypass authentication, paywalls, DRM, CAPTCHAs, or browser safety barriers.

What It Provides

Capability	Purpose
Subtitle-first transcription	Use page subtitles when available and faster-whisper only as a fallback
Conservative review	Preserve raw ASR wording and correct only high-confidence errors and terminology
Normalized text	Convert Chinese text to Simplified Chinese and standardize timestamps
Keyframe planning	Generate candidates from duration, chapters, and topic changes, then check coverage
Illustrated reports	Produce Markdown and PDF with the source, outline, keyframes, raw excerpts, and reliability notes
Bundle validation	Check required files, transcript format, source links, frame coverage, and PDF output

Workflow

Online video URL -> Read page metadata -> Check for subtitles

Available: preserve the raw transcript

Unavailable: transcribe accessible audio -> preserve the raw transcript

Review and normalize -> Select keyframes -> Build Markdown and PDF -> Validate bundle

Quick Start

Clone the skill into your Codex skills directory:

git clone https://github.com/flyjancy/video-summary.git ~/.codex/skills/video-summary

Install the script dependencies:

python3 -m pip install -r requirements.txt

The PDF renderer prefers an installed CJK sans-serif font such as Noto Sans CJK. It emits an explicit warning when it must fall back to STSong-Light; inspect every rendered page before delivery.

Then give Codex an online video URL:

Use $video-summary to summarize this video: https://example.com/video

The skill expects Codex Browser capabilities for page inspection and keyframes, plus PDF capabilities for render verification. ASR is used only when subtitles are unavailable and the browser session can legitimately access the audio.

Output

Each run creates a folder named after the visible video title:

<video-title>/
├── transcript.txt
├── transcript-reviewed.txt
├── summary.md
├── summary.pdf
└── build/                 # report.json, selected frames, rebuild instructions

transcript.txt preserves raw ASR wording. transcript-reviewed.txt contains only high-confidence corrections. Retain the final manifest and selected frames under build/; clean temporary audio, candidates and page previews after acceptance.

PDFs have bookmarks, linked frame indexes and Bilibili playback links. The complete Markdown frame index comes from the same manifest. Reliability follows the last frame and moves to a new page only when needed. Recheck captions after cropping; illegible screenshots cannot support new precise claims.

Included Tools

Script	Purpose
scripts/transcribe.py	Transcribe audio with faster-whisper
scripts/normalize_transcript.py	Normalize timestamps and convert Chinese text to Simplified Chinese
scripts/keyframe_plan.py	Plan candidate frames and validate final coverage
scripts/render_summary_pdf.py	Render an illustrated PDF from a JSON manifest
scripts/sync_report_index.py	Synchronize the complete Markdown frame index
scripts/validate_bundle.py	Validate the final bundle and PDF

Development

python3 -m unittest discover -s tests -v

Read references/output-contract.md before changing the output format, PDF manifest, or validation rules.