智慧平台视频下载（小平老师）
概述
将国家中小学智慧教育平台（basic.smartedu.cn）上教师研修、课程教学等详情页中的视频下载到本地。平台视频采用 HLS（m3u8）分片流，页面为前端动态渲染（SPA），直接抓取 HTML 拿不到视频地址；本技能通过无头浏览器（Playwright + Chromium）真实加载页面、捕获视频元数据，再用并发脚本把未加密的 .ts 切片合并为可直接播放的 MPEG-TS 文件。
何时使用
- 用户提供形如
https://basic.smartedu.cn/teacherTraining/courseDetail?courseId=...&resourceId=...&libraryId=...的链接，要求下载其中视频。 - 用户说"把这个网课/研修视频保存下来""下载这节课的视频""抓取智慧平台的视频"等。
前置依赖
- Python 3.8+
- Playwright + Chromium（无头浏览器，用于捕获真实视频地址）：
python -m pip install playwright && python -m playwright install chromium - （可选）ffmpeg：用于将 .ts 无损重封装为 .mp4，便于双击播放。弱网/沙箱环境下 ffmpeg 安装包较大可能下载失败，此时直接交付 .ts 即可（VLC / PotPlayer / MPV / 智能电视均可播放）。
工作流程
第 1 步：解析链接，提取 resourceId
从用户给出的页面 URL 中提取 resourceId（36 位 UUID），这是定位具体视频的关键。若 URL 中缺少 resourceId，提示用户补充完整链接（包含 resourceId 的那一档视频页）。
第 2 步：无头浏览器捕获元数据
运行：
python scripts/capture_meta.py "<页面URL>" meta.json
脚本会：
- 用 Chromium 无头加载页面，监听网络响应；
- 找到包含 resourceId 的元数据 JSON（通常是 activity_sets/{id}/fulls.json，含该课程下全部资源及其视频地址），保存为 meta.json；
- 同时输出 resolutions.txt（目标视频的各清晰度 m3u8 列表）与 m3u8_urls.txt（页面出现的所有 m3u8）。
若报错"未捕获到元数据"，多为页面未正常加载或链接缺少 resourceId，按提示处理或手动确认视频可播放。
第 3 步：选择清晰度与文件名
打开 resolutions.txt，每行格式 清晰度<TAB>m3u8地址。默认选 1280x720；若需更高清可选 1920x1080，移动端可选 852x480 / 640x360。输出文件名建议取自 meta.json 中该资源的 title 字段（去除 \/:*?"<>| 等非法字符）。
第 4 步：下载并合并切片
运行：
python scripts/download_ts.py "<m3u8地址>" "输出文件名.ts" 16
脚本会：自动识别主播放列表(master)并在未指定具体分辨率时选清晰度、并发（默认 16 线程）下载全部 .ts 切片、严格按序合并为单个 MPEG-TS 文件，并校验首字节 0x47（TS 同步位）。
第 5 步：交付与可选转码
- 交付合并好的
.ts文件，并告知用户可用 VLC / PotPlayer 直接播放。 - 若本机有 ffmpeg，可无损重封装为 mp4（不重新编码、画质不变）：
ffmpeg -i 输出.ts -c copy 输出.mp4 - 若需整个专题（课程下所有视频）批量下载，遍历
meta.json中每个资源的 m3u8 逐一调用 download_ts.py 即可（注意并发与磁盘空间）。
脚本说明
scripts/capture_meta.py：无头浏览器捕获视频元数据，输出meta.json/resolutions.txt/m3u8_urls.txt。scripts/download_ts.py：m3u8 切片并发下载与合并，输出.ts。
已知限制与排查
- 平台部分库内容接口需登录鉴权、内容散列不可推算，因此必须用无头浏览器捕获，静态接口直连会返回 403。
- 若站点改版导致捕获失败，参考
references/api_notes.md中的接口规律重新定位元数据来源。 - 极少数视频切片若加密（含
#EXT-X-KEY），需另行获取密钥，本技能默认处理未加密切片。 - 下载受网络与 CDN 限速影响，失败切片会写入
failed_segs.txt，可重试或降低并发数。
参考资料
references/api_notes.md：平台视频接口反向工程笔记（URL 规律、CDN 域名、静态数据路径、失败路径记录），用于站点改版后的排查。
