auto-subtitlelisted

# auto-subtitle — 音视频自动转写出 SubtitleCue **一条命令出字幕**：音视频文件进，`<同名>.cues.json` + `<同名>.srt` 双产物出。数据契约与 video-motion `SubtitleCue` 逐字对齐：`{start, end, text}`，秒、3 位小数、单行文本（长句已拆条）——`subtitles` 数组可直接进 video-motion 时间轴。 ## Step 1 · 确认素材与语种 - mp4 / wav / flac 皆可（PyAV 直解）。解码报错 → 先转码再喂：`ffmpeg -i in.mp4 -vn -ac 1 -ar 16000 out.wav` - 确认语种并传 `--lang`：`zh`（默认）/ `en` 等 whisper 语种代码 - **纯音乐/音效素材不用跑**：VAD 会滤出空或极短产物（这是特性不是故障） - 素材有已知文本（口播稿 / 台词 / 原文）先留档 UTF-8——Step 3 L2 比对的基准，杜绝基准漂移 ## Step 2 · 跑转写 venv 已随仓库建好（`templates/asr/.venv`）。重建：`python -m venv .venv` + `.venv/Scripts/python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple`。 ```powershell cd skills/auto-subtitle/templates/asr .venv\Scripts\python.exe transcribe.py <输入.mp4|wav> --outdir <输出目录> ``` - 模型默认 `large-v3-turbo`（≈1.6GB 首次自动下载，中文质量线）；快速验证加 `--model small`（≈484MB）。模型缓存在 `~/.cache/huggingface`，下载一次全局复用 - **模型下载失败时设 `HF_ENDPOINT` 换源**：默认官方直连（2026-08 实测通）；备用如 `$env:HF_ENDPOINT="https://hf-mirror.com"`（注意：hub 1.x 下该镜像存在 308 回源兼容问题，优先官方） - stdout 一行英文摘要 `segments=N cues=M total_audio=... model=... lang=... out=...`；exit 0 成功、1 失败 ## Step 3 · 三级核查（必做，不可跳） **L1 程序级**：JSON 可 `json.load`；`subtitles` 是数组且每条恰有 `start`/`end`/`text` 三字段；`start < end` 且跨条单调不减；数值 3 位小数；最后一条 `end` ≤ ffprobe 时长 + 1s。SRT 时间戳行匹配 `HH:MM:SS,mmm --> HH:MM:SS,mmm`，序号从 1 连续。 **L2 准确性**：有已知文本 → `difflib.SequenceMatcher` 比对（双方先去标点去空白规整），整体相似度 ≥0.85、逐句 ≥0.70（对连续 cue 拼接窗口取 max，覆盖切分/合并）；无已知文本 → 抽听首 / 中 / 尾三段核对。 **L2.5 时间轴**（常规检查）：**