中文 | English
把课程视频、讲座录屏或已有字幕整理为结构化技术笔记的 Agent Skill。支持长录屏的静音分析、可续跑转写、术语校正、章节切片、配套代码核对和 Markdown 拼装。默认中文笔记，也可以指定其他语言。
这是一个供 Codex 等支持 SKILL.md 的代理使用的技能。脚本处理媒体和检查，代理负责章节划分、理解材料、撰写与回源核对。它不是单独运行就能自动生成完整笔记的应用。
将本仓库克隆到任意位置，然后把整个目录链接或复制到 Codex 的技能目录：
git clone https://github.com/Gaoyuan-0423/lecture-video-to-notes.git
cd lecture-video-to-notes
mkdir -p ~/.codex/skills
ln -s "$(pwd)" ~/.codex/skills/lecture-video-to-notes如果目标目录已有同名技能，先核对现有内容。其他支持 Agent Skills 的工具可以按各自的技能目录规则安装；不依赖 .dsh。
让 Codex 重新发现技能后，使用：
使用 $lecture-video-to-notes，把 /path/to/lecture.mp4 整理成中文技术笔记。
输出到 /path/to/my-lecture-notes；配套代码在 /path/to/course-code。
使用前自动准备缺失的项目依赖。
只有字幕也可以使用，配套代码是可选项。
技能在使用前调用 scripts/bootstrap.py。它检测任务需要的依赖，媒体/转写任务在课程项目里创建 .venv-asr，安装缺失项并验证可用性；纯文本模式直接复用 Python，不创建虚拟环境。模型默认在首次转写时下载，重复使用会复用环境和有效模型缓存。
| 任务模式 | 自动准备的内容 |
|---|---|
text |
处理已有字幕和 Markdown，只用 Python 标准库 |
media |
NumPy、imageio-ffmpeg、可执行的 ffmpeg |
asr |
媒体依赖、平台对应的转写后端、模型下载工具 |
--with-ocr |
macOS 的 ocrmac 和 Pillow；仅按需安装 |
Apple Silicon 默认使用 MLX Whisper，其他平台默认使用 faster-whisper 的 CPU/int8 模式。默认 large-v3 模型较大，CPU 长课程建议根据资源选择较小模型。安装包自带的 ffmpeg 来自 imageio-ffmpeg，无需 Homebrew。
引导前提： 能执行 Python。文本工具支持 Python 3.9+；媒体/转写环境使用 Python 3.10+。引导脚本会寻找已有的合适版本；如果没有，但安装了 uv，会用 uv 准备 Python 3.12。两者都缺失时会给出明确提示。Windows 需要可用的 Python，运行命令可把 python3 换成 python。
所有 Python 包安装在项目虚拟环境中。脚本不会使用 sudo、安装系统包、修改系统 Python 或配置永久代理。首次安装包和模型需要网络、磁盘空间和宿主允许的执行权限；安装失败会返回非零状态并保留诊断信息。
在仓库根目录运行：
# 默认自动选择后端，安装缺失的转写依赖；模型延后下载
python3 scripts/bootstrap.py --project ../my-lecture-notes --profile asr
# 只有字幕：不安装语音识别和媒体依赖
python3 scripts/bootstrap.py --project ../my-lecture-notes --profile text
# 仅检查或查看计划，不安装、不下载
python3 scripts/bootstrap.py --project ../my-lecture-notes --profile asr --check
python3 scripts/bootstrap.py --project ../my-lecture-notes --profile asr --dry-run--check 在缺失必要依赖时返回非零状态。需要提前下载模型、使用 CPU 小模型或指定本地模型时：
python3 scripts/bootstrap.py --project ../my-lecture-notes --download-model
python3 scripts/bootstrap.py --project ../my-lecture-notes \
--backend faster-whisper --model Systran/faster-whisper-small
python3 scripts/bootstrap.py --project ../my-lecture-notes \
--backend mlx --model /absolute/path/to/complete-mlx-model可以用 --python /path/to/python3.12 指定解释器。--model-source modelscope 选择 ModelScope，但模型仓库必须在该源确实存在，并与所选后端兼容；它不会自动转换模型格式。已有完整本地模型可离线复用。
准备完成后，项目的 .lecture-runtime.json 会记录实际解释器、后端、模型和 ffmpeg。后续从课程项目目录执行技能脚本，使用配置中的 python；媒体/转写模式也可直接用 .venv-asr/bin/python（Windows 为 .venv-asr/Scripts/python.exe）。可以设置 LECTURE_NOTES_PROJECT 覆盖项目根目录。完整流程见 workflow.md，可复制命令见 CLI 示例。
- 原始转写、校正后逐字稿与带时间戳字幕。
- 章节笔记、课程术语表、来源说明和待核实项。
- 最终 Markdown，以及可解析的图片引用。
术语表默认没有替换规则，需要按本课程构建。能量阈值会受低声讲话和背景音乐影响，必须抽查被剔除的片段。没有时间戳的文本不能恢复真实视频时间。代码以配套文件或屏幕证据为准，证据不足时明确标注，不补造内容。
语音识别在本机执行，包和模型下载会访问网络；代理读取的文本/画面仍由使用该技能的代理服务处理。代码核对、复听和人工检查是质量的一部分。check_numbers.py 检查改写前后的数字、标识符和代码一致性，不能证明事实本身正确。
当前 OCR 工具使用 macOS Vision，其他平台可使用配套源码、人工抽帧或另选 OCR 工具。GPU/CUDA 后端没有纳入自动安装流程；其他平台以 CPU 路径为默认。
SKILL.md 代理使用的入口
agents/openai.yaml Codex 展示元数据
scripts/ 引导、媒体、转写、字幕及验收工具
references/ 工作流、写作规范与配置模板
requirements*.txt 按任务划分的依赖
tests/ 不下载模型的自动测试
.github/workflows/ Linux/macOS/Windows 离线测试配置
视频、音频、模型、用户代码与笔记放在独立课程项目中。.gitignore 也排除了常见运行产物。上传 GitHub 时只提交仓库源文件。
python3 -m compileall -q scripts tests
python3 -m unittest discover -s tests -vGitHub Actions 配置会在 push/PR 时运行离线测试，测试不下载 ASR 模型。离线测试不能替代真实录音和各平台的完整转写验收。
在 GitHub 创建空仓库，再把本目录作为 Git 仓库提交并推送即可；也可上传源文件。上传前检查文件列表，避免带入课程材料和运行缓存。
源自一个课程笔记工作流，已移除机器专用路径和课程特定默认配置。许可证：MIT。