🎬 video2knowledge

把视频变成带时间戳的字幕 → 结构化知识文档 → HTML / Anki 卡片。三条本地推理路径，全程在本地运行，不上传任何视频/字幕/产出；仓库只跟踪代码与配置变更。

✨ 它能做什么

给它任意一段视频，你会得到：

产物	文件	说明
📝 带时间戳字幕	`subtitles.srt` / `.vtt` / `.json`	词级时间戳，可直接喂播放器或下游处理
📄 知识文档	`knowledge.md`	摘要 / 时间轴 / 核心知识点 / Q&A / 术语表 / 画面要点，支持自定义模板
🌐 HTML	`knowledge.html`	自包含单文件，`[mm:ss]` 时间戳可点跳
🃏 知识卡片 CSV	`cards.csv`	question / answer / tags / timestamp / source
📚 Anki 牌组	`cards.apkg`	稳定 ID，重复导入不重复，开箱即用

三条路径任选或并用：

路径 1 · 多模态：原生多模态小模型（≤4B VLM，经 Ollama）逐帧读视频 → 带时间戳字幕。适合无音轨 / 纯画面 / 屏幕录制 / 演示文稿，能抓 ASR 看不见的屏幕文字和图表。
路径 2 · ASR：faster-whisper 转写音轨 → 带时间戳字幕。适合有清晰语音的视频（讲座/访谈/教程），更快更准。
路径 3 · 音画融合：ASR 抓讲解 + VLM OCR 抓屏幕（表格/公式/举例），按时间戳融合。适合有语音讲解的 PPT/幻灯片视频——把 ASR 听不到的画面内容补回来。

路径 1、2 产出的字幕 schema 一致，第二步（知识加工）对路径无感；路径 3 产出融合的 merged.json，由第二步的 --merged 消费。

🧱 从零开始安装（5 分钟）

假设你是一台干净的系统（没装 ollama / ffmpeg / python），下面四步就能从 0 跑通。

第 0 步 · 克隆仓库

git clone https://github.com/CacinieP/video2knowledge.git
cd video2knowledge

第 1 步 · 安装系统依赖（三件套）

需要三个命令行工具，按你的系统挑一组：

macOS（用 Homebrew）

brew install ffmpeg python@3.11          # ffmpeg + python
brew install ollama                       # 或去 https://ollama.com/download 下 Ollama.app

Linux（apt，Debian/Ubuntu）

curl -fsSL https://ollama.com/install.sh | sh          # ollama 官方脚本
sudo apt update && sudo apt install -y ffmpeg python3 python3-venv

Windows

Ollama：https://ollama.com/download 下载安装包
ffmpeg / python：winget install Gyan.FFmpeg Python.Python.3.11
建议在 Git Bash 或 WSL 里运行下面的命令

检查：ollama --version && ffmpeg -version && python3 --version 三条都有输出即可继续。

第 2 步 · 一键下载模型 + 建虚拟环境

bash scripts/setup_models.sh

这个脚本会做三件事（幂等，可重复执行）：

自动检测你的机型（RAM / GPU / Apple Silicon / NVIDIA），按档位挑模型；
启动 ollama serve 并拉取对应的 VLM（多模态，路径 1 用）；
建一个 venv，装好 faster-whisper + genanki。

跑完会打印一段总结，注意看最后一行 Activate with:，那是要复制的激活命令。

venv 建在哪里，由环境变量 VENV_DIR 决定，两种选法：

# 方式 A（推荐给从 GitHub clone 的用户）：建在仓库内，直观、好找
VENV_DIR=.venv bash scripts/setup_models.sh

# 方式 B（脚本默认）：建在 ~/.zcode/skills/video2knowledge/.venv
#   —— 这是 ZCode skill 场景下的固定路径。直接跑就是它：
bash scripts/setup_models.sh

下面所有示例统一用方式 A（source .venv/bin/activate）；如果你用了方式 B，把激活命令换成 setup_models.sh 末尾打印的那行即可。

看看它给你选了什么档位：

python3 scripts/hardware_profile.py
# 例：8GB MacBook → profile=mid → whisper-small + minicpm-v4.6

💡 下载慢 / 卡住？ 这些模型从 Ollama / PyPI 拉取，国内网络可设置代理提速：
export HTTPS_PROXY=http://127.0.0.1:7890
bash scripts/setup_models.sh

第 3 步 · 激活 venv（每次新开终端都要做）

# 用了上面的方式 A（仓库内 venv）：
source .venv/bin/activate

# 用了方式 B（脚本默认路径）：
source ~/.zcode/skills/video2knowledge/.venv/bin/activate

不确定自己用了哪种？跑 ls .venv/bin/activate 2>/dev/null —— 有输出就是方式 A，否则就是方式 B。

第 4 步 ·（可选）作为 agent skill 使用

本仓库自带 SKILL.md，可被各类 coding agent 自动加载，让你直接对 agent 说"用 video2knowledge 处理这个视频"即可。把整个仓库放进对应 agent 的 skills 目录即可（任选其一，不互斥）：

Agent	安装目录	安装命令
ZCode	`~/.zcode/skills/video2knowledge/`	`git clone https://github.com/CacinieP/video2knowledge.git ~/.zcode/skills/video2knowledge`
Claude Code	`~/.claude/skills/video2knowledge/`	`git clone https://github.com/CacinieP/video2knowledge.git ~/.claude/skills/video2knowledge`
Cursor	`~/.cursor/skills/video2knowledge/`	`git clone https://github.com/CacinieP/video2knowledge.git ~/.cursor/skills/video2knowledge`

仓库内置的 scripts/setup_models.sh 默认把 venv 建在 ~/.zcode/skills/video2knowledge/.venv（即上表的 ZCode 行）。装到其他 agent 目录时，建议改用方式 A 把 venv 建在仓库内，避免路径错配：
cd ~/.claude/skills/video2knowledge   # 或 ~/.cursor/skills/video2knowledge
VENV_DIR=.venv bash scripts/setup_models.sh
之后在该仓库内处理视频时统一用 source .venv/bin/activate。

仅当不通过 agent、直接在终端用脚本时，可跳过本步——SKILL.md 是给 agent 读的，终端里用不到。

到这里环境就装好了。下面正式处理视频。

🚀 处理第一个视频

A. 路径 2 · ASR（有语音的视频，推荐先试）

source .venv/bin/activate   # 激活 venv（用了方式 B 则换成 setup_models.sh 打印的那行）

# 第一步：视频 → 字幕
python3 scripts/asr_caption.py \
  --video your_video.mp4 --out-dir runs/demo --language zh

# 第二步：字幕 → 知识文档 / HTML / 卡片 CSV
# （首次运行会自动拉取文本模型 openbmb/minicpm5:Q4_K_M，几百 MB，稍等）
python3 scripts/build_knowledge.py \
  --subtitles runs/demo/subtitles.json --out-dir runs/demo --format all

# 2.3：CSV → Anki 牌组
python3 scripts/gen_apkg.py \
  --csv runs/demo/cards.csv --out runs/demo/cards.apkg --deck "我的知识卡"

完成后 runs/demo/ 里就有 subtitles.srt、knowledge.md、knowledge.html、cards.csv、cards.apkg。

英文视频记得在第二步加 --lang en（默认 zh），否则小模型在语言不匹配时容易把示例内容串进产出。

B. 路径 1 · 多模态（无音轨 / 屏幕录制 / 演示文稿）

python3 scripts/mm_caption.py \
  --video screen_recording.mp4 --out-dir runs/demo2 --interval 2.0
# 再走同样的第二步（build_knowledge.py），输出与路径 2 完全一致

对 PPT/幻灯片视频，用 --mode dedup（通用感知去重，无需调场景阈值）+ --prompt-ocr（表格/公式全量转写）：

python3 scripts/mm_caption.py \
  --video slides.mp4 --out-dir runs/demo2 --mode dedup --prompt-ocr

4. 路径 3 · 音画融合（有讲解的 PPT/幻灯片视频）

最适合线上课程、培训录屏这类「嘴在讲、屏上有表」的视频。ASR 抓讲解，VLM 抓屏幕上的表格/公式/举例，按时间戳融合：

source .venv/bin/activate
RUN=runs/$(date +%Y%m%d-%HMMSS)-slides; mkdir -p "$RUN"

# 1a. ASR 抓讲解
python3 scripts/asr_caption.py --video slides.mp4 --out-dir "$RUN" --language zh
# 1b/1c. 感知去重抽帧 + VLM OCR 抓屏幕
python3 scripts/mm_caption.py --video slides.mp4 --out-dir "$RUN" --mode dedup --prompt-ocr
# 2. 按时间戳融合
python3 scripts/merge_visual.py \
  --subtitles "$RUN/subtitles.json" --visual "$RUN/captions.json" --out "$RUN/merged.json"
# 3. 生成知识文档（带"画面要点"小节）
python3 scripts/build_knowledge.py \
  --subtitles "$RUN/subtitles.json" --merged "$RUN/merged.json" \
  --out-dir "$RUN" --format all
python3 scripts/gen_apkg.py --csv "$RUN/cards.csv" --out "$RUN/cards.apkg" --deck "幻灯片知识卡"

默认文本模型为 qwen2.5:3b（8GB 机器实测能读懂融合内容、可推理字幕隐含逻辑）；低配/求快可 --model openbmb/minicpm5:Q4_K_M。详见 references/path3-fusion.md。

🎯 实际效果演示

下面是一段 NASA 公有领域视频（Curiosity 火星车着陆后 Adam Steltzner 的发言，2分25秒，英文，来源，Public Domain）经过完整流水线后的真实产出。

输入字幕（subtitles.srt，faster-whisper small 模型，19 段，前 3 段）：

1
00:00:02,060 --> 00:00:03,580
Say something profound.

2
00:00:06,540 --> 00:00:09,280
I am terribly humbled by this experience.

3
00:00:11,840 --> 00:00:20,600
I forever secretly have felt that I do not deserve to be in the
position of leading the...

生成的知识文档摘要（knowledge.md）：

The video explores the profound humility felt by a scientist who acknowledges his own limitations while recognizing the immense value of working with a diverse team at JPL, highlighting how collective effort and individual contributions can achieve great things together... underscoring the importance of appreciating both the small details of daily tasks and the larger achievements achieved through unity.

核心知识点（自动提炼）：

Leading requires recognizing individual contributions.
Team success depends on diverse skills and perspectives.
Humility is essential for learning from others.
Every great achievement involves collaboration.

知识卡片（cards.csv → cards.apkg，可直接导入 Anki）：

Question	Answer
How does the speaker feel about leading a team?	Expresses humility — "secretly have felt that I do not deserve to be in the position of leading."
What is the significance of the EDL team?	Described as talent at JPL, emphasizing collective skill and mission contribution.
Why does the speaker believe this nation represents humanity?	A "corner of humanity that reaches out and explores," highlighting its role in exploration.

💡 提示：英文视频请加 --lang en（中文视频用默认 --lang zh）。小模型（1B）若语言不匹配会把示例内容串进产出。

🖥️ 硬件适配（自动）

不用手动挑模型大小——scripts/hardware_profile.py 会检测并匹配：

Profile	触发	ASR 模型	VLM	典型机型
`tiny`	RAM < 6 GB	tiny	moondream	树莓派 / 4G 老笔记本
`low`	6–8 GB 无独显	base	minicpm-v4.6	上网本
`low-mac`	6–8 GB Apple Silicon	small	minicpm-v4.6	M1 MacBook Air
`mid`	8–16 GB	small	minicpm-v4.6	主流笔记本
`high`	16–32 GB	medium	qwen2.5vl:3b	M2/M3 Pro、16G PC
`high-gpu`	NVIDIA ≥ 8 GB 显存	large-v3	qwen2.5vl:7b	RTX 3060/4060/3090（CUDA+float16 全速）
`max`	RAM > 32 GB	large-v3	qwen2.5vl:7b	工作站 / 服务器

NVIDIA 有短路逻辑：≥8GB 显存直接走 CUDA，不受总内存限制。全部可用环境变量（ASR_DEFAULT_MODEL=、VLM_MODEL=）或 CLI flag 覆盖。完整说明见 references/hardware-profiles.md。

📐 自定义知识文档模板

内置默认模板（assets/default-template.md）用 {{占位符}} 渲染。写任意 .md 放进你想要的占位符即可：

# {{title}} — 课程笔记
> {{date}} · {{duration}} · {{source}}

## 本节目标
{{summary}}

## 时间轴
{{timeline}}

## 必背知识点
{{key_points}}

## 自测题
{{qa}}

可用占位符：{{title}} {{source}} {{duration}} {{date}} {{summary}} {{timeline}} {{key_points}} {{qa}} {{glossary}} {{meta}}。内置课程笔记 / 会议纪要 / 技术教程三套示例见 references/templates.md。

python3 scripts/build_knowledge.py \
  --subtitles runs/demo/subtitles.json --out-dir runs/demo \
  --template ./my-lecture-template.md --format knowledge

❓ 常见问题（从零开始最容易踩的坑）

Q: 激活 venv 的命令到底是什么路径？

由 setup_models.sh 的 VENV_DIR 决定：

仓库内（方式 A，推荐）：跑 VENV_DIR=.venv bash scripts/setup_models.sh，之后 source .venv/bin/activate。
固定路径（方式 B，脚本默认）：source ~/.zcode/skills/video2knowledge/.venv/bin/activate。

始终以 setup_models.sh 末尾 Activate with: 打印的那行为准。

Q: 跑 build_knowledge.py 卡很久 / 报模型找不到？

第二步会调用一个文本模型 openbmb/minicpm5:Q4_K_M（用于摘要/知识点/Q&A），首次运行时 Ollama 会自动拉取，几百 MB，需要联网和等待。提前手动拉可避免等待意外：ollama pull openbmb/minicpm5:Q4_K_M。想换更大的模型提升质量：--model qwen2.5:7b。

Q: 报错 ollama not found / ffmpeg not found？

回【第 1 步】把对应工具装上并确认在 PATH 里：ollama --version && ffmpeg -version。Ollama 装好后若未常驻，setup_models.sh 会自动 ollama serve 拉起；若仍失败，手动开一个终端跑 ollama serve。

Q: 模型 / pip 下载很慢或超时？

国内网络建议挂代理：export HTTPS_PROXY=http://127.0.0.1:7890（端口换成你自己的）。pip 可换镜像：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple。

Q: Windows 上能跑吗？

可以，建议在 Git Bash 或 WSL 里运行（脚本依赖 bash）。Ollama 用官方安装包，ffmpeg/python 用 winget 安装，venv 激活路径同样以 setup_models.sh 输出为准。

🔒 隐私与留痕

全程本地：视频文件、抽帧、字幕、知识产物始终留在你机器上的 runs/<时间戳>-<视频名>/，绝不上传，不联网调用云 API。
仓库只跟代码：本仓库是 skill 本身（脚本/文档/模板）的版本管理，不包含任何视频或处理产出——runs/ 已在 .gitignore 中忽略。代码与配置的修改都有 git 历史可追溯。
本地复现：要复现某次结果，在本地 runs/<...>/ 里查看当次用的参数和产出即可（按需自行写 manifest.json 记录，但默认不入库）。

example/ 目录提供一份用 ffmpeg 合成视频跑通的示例产出（无真实数据，仅供演示结构与字段）。

📂 项目结构

video2knowledge/
├── SKILL.md                       # 主控文档（流程编排 + 留痕规范）
├── scripts/
│   ├── hardware_profile.py        # 机型检测 → 配置档（单一真相源）
│   ├── setup_models.sh            # 幂等：检测机型 + 拉模型 + 建 venv
│   ├── asr_caption.py             # 路径 2：faster-whisper → 字幕
│   ├── mm_caption.py              # 路径 1：VLM 逐帧 → 字幕
│   ├── extract_frames.py          # ffmpeg 抽帧 → frames.json
│   ├── build_knowledge.py         # 第二步：字幕 → 知识文档/HTML/CSV
│   └── gen_apkg.py                # 2.3：CSV → Anki .apkg
├── references/                    # 详细文档（按需加载）
│   ├── hardware-profiles.md
│   ├── path1-multimodal.md
│   ├── path2-asr.md
│   ├── templates.md
│   └── outputs.md
├── assets/default-template.md     # 内置默认知识文档模板
└── example/                       # 合成视频的示例产出（无真实数据）

处理真实视频时，产出会写到本地 runs/（已 gitignore，不入库）。

🧠 设计取舍

全本地推理：用 Ollama 跑 VLM/文本模型、faster-whisper 跑 ASR，视频内容不离开本机，隐私可控、留痕可复现。
小模型优先：默认档位（mid）用 1B 级模型，8GB 机器跑得动；模型小→摘要/时间轴/知识点质量好，但 Q&A 在 1B 模型上偶有偏差。换更大的本地文本模型（build_knowledge.py --model qwen2.5:7b）即可显著改善。
CLI 优先，可被 skill 调用：所有脚本带 --help、不硬编码路径、幂等。

📜 License

MIT © CacinieP

Navigation Menu

Repository files navigation

🎬 video2knowledge

✨ 它能做什么

🧱 从零开始安装（5 分钟）

第 0 步 · 克隆仓库

第 1 步 · 安装系统依赖（三件套）

第 2 步 · 一键下载模型 + 建虚拟环境

第 3 步 · 激活 venv（每次新开终端都要做）

第 4 步 ·（可选）作为 agent skill 使用

🚀 处理第一个视频

A. 路径 2 · ASR（有语音的视频，推荐先试）

B. 路径 1 · 多模态（无音轨 / 屏幕录制 / 演示文稿）

4. 路径 3 · 音画融合（有讲解的 PPT/幻灯片视频）

🎯 实际效果演示

🖥️ 硬件适配（自动）

📐 自定义知识文档模板

❓ 常见问题（从零开始最容易踩的坑）

🔒 隐私与留痕

📂 项目结构

🧠 设计取舍

📜 License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
agents		agents
assets		assets
example		example
references		references
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SKILL.md		SKILL.md

Folders and files

Latest commit

History

Repository files navigation

🎬 video2knowledge

✨ 它能做什么

🧱 从零开始安装（5 分钟）

第 0 步 · 克隆仓库

第 1 步 · 安装系统依赖（三件套）

第 2 步 · 一键下载模型 + 建虚拟环境

第 3 步 · 激活 venv（每次新开终端都要做）

第 4 步 ·（可选）作为 agent skill 使用

🚀 处理第一个视频

A. 路径 2 · ASR（有语音的视频，推荐先试）

B. 路径 1 · 多模态（无音轨 / 屏幕录制 / 演示文稿）

4. 路径 3 · 音画融合（有讲解的 PPT/幻灯片视频）

🎯 实际效果演示

🖥️ 硬件适配（自动）

📐 自定义知识文档模板

❓ 常见问题（从零开始最容易踩的坑）

🔒 隐私与留痕

📂 项目结构

🧠 设计取舍

📜 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages