skills/piano-lesson-highlight-generator/SKILL.md

name, description

name	description
piano-lesson-highlight-generator	钢琴课精华宣传视频自动生成工具，支持从配套PPT/PDF提取知识点和音乐术语库，自动完成视频剪辑、语音转录、三级字幕纠错、添加标题和转场，生成高质量课程宣传视频。触发词：钢琴课精华、钢琴宣传视频、课程精华剪辑、钢琴课剪精华

钢琴课精华视频生成技能

功能说明

从钢琴课直播/录播视频中提取知识点，自动生成带字幕、标题卡、转场效果的精华宣传视频。

适用场景

• 钢琴课课后精华片段制作
• 钢琴培训机构宣传视频生成
• 课程知识点切片归档
• 同类型音乐/艺术类课程视频剪辑

---

🚨 环境配置（最重要，先看这里）

必须使用的 Python 环境

D:\ProgramData\anaconda3\envs\py312_cuda\python.exe

⚠️ 两个容易混淆的 conda 安装

路径	PyTorch	CUDA	能用吗？
D:\AI\Miniconda3\python.exe	2.11.0+cpu	False	❌ 不能用，转录会超时
D:\ProgramData\anaconda3\envs\py312_cuda\python.exe	2.5.1+cu121	True	✅ 用这个

关键区别：Miniconda 的 PyTorch 是纯 CPU 版本，转录 100 分钟视频会超时（30+ 分钟）。必须用 py312_cuda 环境。

验证环境

"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" -c "import torch; print(torch.cuda.is_available())"
# 必须输出 True

模型路径

D:/AI/LM-Models/faster-whisper/large-v3/

包含 5 个文件：config.json, model.bin, preprocessor_config.json, tokenizer.json, vocabulary.json

完整依赖清单

包	版本	用途
Python	3.12.13	运行时
torch	2.5.1+cu121	GPU 加速
faster-whisper	1.2.1	Whisper 转录
zhconv	1.4.3	繁体转简体
pypinyin	0.55.0	拼音转换（AI 纠错）
pyyaml	6.0.3	配置文件解析

如果环境不存在，重建步骤

# 1. 创建环境
"D:/ProgramData/anaconda3/Scripts/conda.exe" create -n py312_cuda python=3.12 -y

# 2. 安装 CUDA PyTorch
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 3. 安装依赖
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" -m pip install faster-whisper zhconv pypinyin pyyaml

---

调用方式

cd .opencode/skills/piano-lesson-highlight-generator

# 步骤1：知识点提取 + config 生成（含 GPU 转录，约 20-30 分钟）
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" scripts/extract_terms_from_ppt.py <pptx路径> <视频路径> <config输出路径>

# 步骤2：精华视频生成（复用转录，约 2-3 分钟）
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" scripts/generate_highlights.py --config <config路径>

完整示例

cd .opencode/skills/piano-lesson-highlight-generator

# 提取知识点（自动转录视频 + 匹配时间戳 + 生成 config）
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" scripts/extract_terms_from_ppt.py ^
  "D:/F/NewI/opencode/daily-workspace/projects/piano-lesson-highlights/data/lesson3/course.pptx" ^
  "D:/F/yc/课程上架/福田商圈夜校/课程视频/直播回放-03月30日.mp4" ^
  "D:/F/NewI/opencode/daily-workspace/projects/piano-lesson-highlights/cases/lesson3/config.yaml"

# 生成视频
"D:/ProgramData/anaconda3/envs/py312_cuda/python.exe" scripts/generate_highlights.py ^
  --config "D:/F/NewI/opencode/daily-workspace/projects/piano-lesson-highlights/cases/lesson3/config.yaml"

---

项目目录结构

projects/piano-lesson-highlights/
├── data/                    # 原始输入数据（只读）
│   ├── lesson2/
│   │   ├── video.mp4
│   │   └── course.pptx
│   └── lesson3/
│       └── ...
└── cases/                   # 每个案例的工作区（独立）
    ├── lesson2/
    │   ├── config.yaml              # 自动生成的配置
    │   ├── intermediates/
    │   │   └── full_transcript.json # 完整转录（可复用）
    │   └── output/
    │       ├── v1_final.mp4         # 最终视频
    │       ├── subs/
    │       │   ├── v1_original.srt
    │       │   ├── v1_terms.srt
    │       │   └── v1_ai.srt
    │       └── intermediates/
    │           ├── clip1.mp4 ~ clipN.mp4
    │           ├── clip1_fade.mp4 ~ clipN_fade.mp4
    │           ├── clip1.json ~ clipN.json
    │           └── concated.mp4
    └── lesson3/
        └── ...

铁律：每次处理新视频时，必须创建新的独立目录，不得复用旧的 intermediates 或 subs 文件夹。

---

工作流程

步骤1：知识点提取（extract_terms_from_ppt.py）

1. 从 PPT 提取知识点：解析 PPTX XML，找到"本课主要知识点"页面
2. GPU 转录整段视频：每 5 分钟一段，使用 faster-whisper large-v3 + CUDA
   • 转录前自动清理残留 Python 进程，释放 GPU 显存
   • 转录完成后显式释放模型（del model + gc.collect() + torch.cuda.empty_cache()）
3. 定位教学锚点：找到知识点首次出现时间，作为教学开始
4. 定位作业锚点：用"作业"词密度定位，而非固定引导语
5. 匹配知识点到时间戳：
   • 使用完整关键词 + 核心子词 + 相关词映射 + 数字归一化
   • 评分综合考量：出现次数、文本量、讲解密度、孤立程度
   • 排除导读区（无讲解特征 + segment ≤ 2 个 → 跳过）
   • 排除回顾区（靠近作业时间惩罚 + 回顾性语言检测）
6. 匹配作业片段：
   • 模糊匹配 30+ 种口语化结束表达
   • 检测到结束语言后 +30s 兜底
   • 无结束语言时用 45s 间隔截断
7. 生成 config.yaml

步骤2：精华视频生成（generate_highlights.py）

1. 提取视频片段：按 config 时间点截取，添加 1s 淡入淡出
   • 自动修复重叠：调整前一个片段的 end 使其等于后一个的 start
2. 转录片段：优先复用 full_transcript.json，按时间切片映射
   • 时间戳限制在 clip 实际时长范围内
   • 内容验证：先应用术语纠正再匹配关键词
3. 三级字幕：
   • v1_original：原始转录 + 繁简转换
   • v1_terms：术语库纠正（黑剑→黑键、副点→附点等）
   • v1_ai：AI 上下文纠错（语义异常 + 拼音推断 + 专有名词补全）
4. 视频合成：标题卡 + 字幕烧录 + 片段合并

---

配置文件格式（YAML）

video_src: "视频文件路径.mp4"
output_dir: "输出目录路径"

# 知识点片段
clips:
  - title: "八分音符"
    start: 2332
    end: 2362
  - title: "作业"
    start: 6515
    end: 6997

# 术语纠正表
term_corrections:
  黑剑: 黑键
  负点: 附点
  副点: 附点
  实质: 时值
  演音: 延音
  言音: 延音
  阅历: 乐理

# 视频参数
video_params:
  fade_duration: 1
  title_duration: 3
  title_fontsize: 90
  title_color: FFFF00
  subtitle_fontsize: 24
  subtitle_color: FFFFFF
  whisper_model: large
  use_fast_whisper: true
  whisper_model_path: "D:/AI/LM-Models/faster-whisper/large-v3"

---

知识点匹配架构

相关度评分

匹配类型	分数	示例
完整关键词	3.0	"附点音符" 匹配 "附点音符"
数字归一化	2.5	"十六分音符" 匹配 "16分音符"
核心子词	2.0	"双音的支撑" 匹配 "双音支撑"
相关词映射	1.5	"升降记号" 匹配 "升号"/"降号"
前缀匹配	1.5	"附点音符" 匹配 "附点"
核心词	1.0	3-4 字核心词匹配

教学特征识别

特征	检测方式
实际教学	讲解词占比高（因为/所以/就是/什么意思/为什么/怎么/弹/按/练）
导读提及	无讲解特征 + segment ≤ 2 个 → 跳过
回顾总结	靠近作业时间 + "刚才"/"今天学了" → 降权
推迟预告	"等下再说"/"后面讲" → 大幅降权

作业结束检测（模糊匹配 30+ 种表达）

类型	匹配模式	示例
明确下课	下课、拜拜、再见	"下课"
作业完成	作业.*就这样、作业.*就这些、作业.*讲到这里	"今天的作业就这样"
通用结束	就到这里、就这样了、说完了、没什么.*说的	"就这些了"
群发通知	发群、到时候.*发	"到时候我发群里"

---

验证标准

• GPU 加速下，转录 100 分钟视频约 20-30 分钟
• 最终视频总时长建议 < 15 分钟
• 每个知识点开头显示 3 秒黄色标题卡（90 号字，黑边，居中）
• 字幕为简体中文，24 号白字黑边，位于底部
• 片段间有 1 秒淡入淡出转场
• 输出文件真实存在且可播放

---

已知限制

1. Python 版本：必须 3.12，3.13 不支持 CUDA 版 PyTorch
2. GPU 依赖：必须 GPU 加速，CPU 转录 100 分钟视频需要 100+ 分钟
3. 转录精度：Whisper 对专业音乐术语可能有识别误差（如"附点"→"副点"），依赖术语纠正表修正
4. 数字识别：Whisper 可能将中文数字识别为阿拉伯数字（"十六"→"16"），已内置数字归一化匹配
5. 中文字体：标题卡需要 Windows 系统字体 C:/Windows/Fonts/msyh.ttc（微软雅黑）

---

重新生成机制

如果用户发现字幕错误：

1. 告知具体错误内容 + 需要基于哪个版本修改
2. 直接修改对应的 srt 文件
3. 使用 ffmpeg 重新烧录：ffmpeg -i concated.mp4 -vf "subtitles=修改后的.srt:force_style='...'" -c:a copy new_version.mp4