video-transcript

name	video-transcript
description	视频/播客逐字稿提取 Skill。使用 FunASR 在本机转录（无需 API Key）；视频用 SenseVoice-Small，播客/访谈用 paraformer + CAM++ 区分主持人与嘉宾。支持微信视频号、 抖音、小红书、B站、YouTube、小宇宙及本地音视频。用户说“出文案/提取文案/出逐字稿/ 转文字/视频字幕/主持稿/播客转文字/区分说话人”，粘贴上述平台链接，或提供本地媒体文件时使用。 视频号默认在对话中交付口语逐字稿；“文字PDF”生成同稿文字版；“截图PDF”加入关键帧， 正文不得改写成导读。其他视频平台默认交付整理优化版；播客交付说话人区块版。用户明确说 “只下载/保存MP4”时只下载。ASR 在本机运行，但链接解析需要联网；视频号首次使用需在本机 扫码登录腾讯元宝。
allowed-tools	Read, Write, Edit, Bash, Glob, Grep
metadata	{"display-name":"视频文案提取"}

视频文案提取专家

输入链接 → 解析一次 → 直链提音频(+模型预热并行) → FunASR → 机器预整理 → 按平台交付 视频号:读 skills/weixin-layout.md,默认对话交口语稿;文字PDF / 截图PDF 用 Kami 羊皮纸长文 B站/抖音/小红书/YouTube:LLM 只出 patch → 主持稿/整理优化版 播客:说话人区块成品,直接交付

阶段 0 · 定位 skill 根目录(第一件事)

if [ -z "${VT_HOME:-}" ]; then
  VT_HOME="$(
    for d in "$HOME/.workbuddy/skills/video-transcript" \
             "$HOME/.agents/skills/video-transcript" \
             "$HOME/.Codex/skills/video-transcript" \
             "$HOME/.codex/skills/video-transcript" \
             "$HOME/.claude/skills/video-transcript" \
             "$(pwd)/.Codex/skills/video-transcript" \
             "$(pwd)/.claude/skills/video-transcript" \
             "$(pwd)/skills/video-transcript" \
             "$HOME/.Codex/plugins/video-transcript/video-transcript" \
             "$HOME/.claude/plugins/video-transcript/video-transcript"; do
      [ -f "$d/SKILL.md" ] && echo "$d" && break
    done
  )"
fi
export VT_HOME
echo "VT_HOME=$VT_HOME"

如果输出为空,让用户给出路径后 export VT_HOME=<路径>。 之后所有命令都通过 "$VT_HOME/scripts/transcript.py",不要硬编码路径。

优先用带 funasr 的解释器:

VT_PY="${VT_PY:-$HOME/.workbuddy/binaries/python/envs/default/bin/python}"
[ -x "$VT_PY" ] || VT_PY="/opt/anaconda3/bin/python3.12"
[ -x "$VT_PY" ] || VT_PY="python3"

阶段 1 · 意图分流(贴链接 = 直接转录,不问)

默认规则:用户贴视频/播客链接 → 直接进入转录,不询问。

用户行为	处理
贴微信视频号链接,无其他说明	默认逐字稿:直接转录,对话里交口语稿,不排 PDF。读 skills/weixin-layout.md
贴视频号 + 「逐字稿」/「逐字稿版本」	同上
贴视频号 + 「文字PDF」/「文字版本」	同一份口语稿 → Kami 羊皮纸文字PDF
贴视频号 + 「截图PDF」/「截图版本」	同一份口语稿 + 视频关键帧 → Kami 羊皮纸截图PDF;转录加 --keep-video
贴 B站/抖音/小红书/YouTube 链接,无其他说明	直接转录,不问,走整理优化版
贴播客/音频链接(小宇宙/喜马拉雅/Apple Podcasts)	直接转录,自动带说话人分离
贴链接 + 说「文案/逐字稿/主持稿/转文字」	直接转录;若是视频号,按上一行对应模式
明确说「只下载」「保存MP4」「不用转录」	走 video-download
只说「处理视频」但没附链接	问用户要链接

平台支持分三档,不确定的链接直接试,不要预先劝退:

档位	平台	说明
专门解析	B站(含 b23.tv)、抖音、小红书、YouTube、微信视频号、小宇宙单集	最稳
播客链路	小宇宙单集、喜马拉雅单集、Apple Podcasts	自动说话人分离
yt-dlp 兜底	微博、知乎、西瓜视频、AcFun 等	能跑,默认走视频链路;要区分说话人加 --speakers
不支持	Spotify(DRM)、快手	脚本给出原因+替代做法

常见误贴:小宇宙节目主页(/podcast/)和喜马拉雅专辑页(/album/)都不是单集页, 脚本会明确提示改用单集链接 —— 把提示原样转达给用户,别自己瞎猜别的原因。

仅下载时定位 video-download 后跑 download_video.py "<URL>" --json,不要再进入转录。

视频号三种交付(先读这个)

识别到 weixin.qq.com/sph 或 channels.weixin.qq.com 时,不要走阶段 4 的「整理优化版 / make_optimized.py」。先读 skills/weixin-layout.md,按三种模式交付。

用户怎么写	交付
什么都不写,或「逐字稿」「逐字稿版本」	默认。 整理过的口语逐字稿,发在对话里。不排 PDF
「文字PDF」(旧称「文字版本」)	同一份口语稿,Kami 羊皮纸纯文字 PDF。文件名 = 官方标题
「截图PDF」(旧称「截图版本」)	同一份口语稿 + 视频关键帧。文件名 = 官方标题

三种共用一份口语正文:补标点、分说话人、改对专有名词。禁止把正文改写成导读 / 概述 / Takeaways。封面最多 2–4 句原话金句。

B 站 / 抖音 / 小红书 / YouTube / 播客不受影响,继续走后面的原流程。

阶段 2 · 依赖体检(首次/可疑时)

已验证过且环境没变化的,跳过体检。首次/换电脑/报错才跑:

"$VT_PY" "$VT_HOME/scripts/transcript.py" --doctor

有 ✗ 项就跑 bash "$VT_HOME/install.sh"。核心依赖没有 ✗ 就可以处理本地文件和其他平台。

--doctor 只检查依赖和视频号认证,不会冒充真实链路验收。需要验证视频号时,用一个可公开测试的分享链接:

"$VT_PY" "$VT_HOME/scripts/transcript.py" --doctor-live "<公开视频号链接>"

阶段 3 · 一条命令跑完下载+转录+预整理

用户给了链接就立刻跑,不要先单独 probe,不要再调一次 download:

"$VT_PY" "$VT_HOME/scripts/transcript.py" "<URL或本地路径>"

视频号「截图PDF」必须留视频文件才能抽帧,加 --keep-video:

"$VT_PY" "$VT_HOME/scripts/transcript.py" "<视频号链接>" --keep-video

可选:

• --force 忽略同 URL 缓存
• --keep-video 额外保存完整 MP4(默认只提音频;截图PDF 必加)
• --no-daemon 不用常驻模型(默认会自动拉起 FunASR daemon)

脚本会自动:

0. 缓存 — 同一 URL 已有预整理稿则秒回;视频号去 skills/weixin-layout.md,其他平台进入阶段 4
1. 解析一次 — 视频号优先 HTTP(元宝 Cookie),失败才开一次浏览器;B 站/抖音/小红书探测时缓存直链
2. 并行 — 后台预热 FunASR daemon,同时 ffmpeg 直链提 16k wav(不下完整 MP4)
3. 转录 — 长视频按 ≤5 分钟切块;有 daemon 则顺序流式写出,无 daemon 则最多 2 进程并行
4. 预整理 — 机器完成切段/合并碎句/候选标题,写出 *_预整理.md + *_polish_brief.json

stderr 会先打 📊 评估表。立刻复述给用户(标题/时长/预估耗时),不要等全部跑完。

长视频还会写 $VT_HOME/outputs/.partial/<hash>/chunk_XX.md 和 progress.json。 转录还没结束时,你可以读已经完成的 chunk,边转边改标题/纠错,最后再合并进一份 patch。

完成后 stderr 有 ----- VT_OUTPUTS ----- 一行 JSON,里面有:

• preorganized_path — 预整理稿(你的主输入)
• polish_brief_path — 增量润色任务书
• transcript_path — 原始逐字稿(对照存档;B站等平台不要在对话里全文展示)
• video_path — 仅 --keep-video 时有,截图PDF 用它抽帧
• stream_dir — 分块流式目录

若是微信视频号:到这里停,去 skills/weixin-layout.md。 不要进入阶段 4,不要跑 make_optimized.py。

视频号失败时按错误码处理,不要把隐私同意误说成技术鉴权:

• WECHAT_AUTH_REQUIRED / WECHAT_AUTH_EXPIRED:让用户在本机运行 sph_resolver.py --login,扫码后重试。
• WECHAT_PARSE_EMPTY / WECHAT_PARSE_TOKEN_MISSING:登录已通过,但该分享链接没有得到可用解析结果;说明可能是链接、内容权限或页面接口变化。
• WECHAT_FEED_FAILED / WECHAT_STREAM_EMPTY:已经进入视频详情阶段,但没有媒体流;可请用户上传本地 MP4/MOV 继续。
• 不要自动改用或请求授权使用 public-worker。该服务当前需要额外服务器凭据,不是公开兜底。

阶段 4 · 你(agent)必须做的事:只出 patch,不要重写全文

本阶段只给 B 站 / 抖音 / 小红书 / YouTube 等非视频号视频。视频号看 skills/weixin-layout.md。

核心交付仍是「整理优化版 / 主持稿」。但机器已经做完分段和合并,禁止再把全文抄进 content.json,也禁止在对话里把同一篇稿子重写两遍。

正确流程(必须按此执行)

1. 读 preorganized_path 全文(以文件为准,stdout 可能截断)
2. 读 polish_brief_path
3. 只写一份很小的 patch.json,字段:
   • title: 可选,润色后的大标题
   • headings: 与章节顺序对齐的语义化小标题(可只改需要改的)
   • fixes: [{"from":"原词","to":"修正词","confidence":"high|low"}]（high 会自动替换全文对应词）
   • paragraph_edits: 仅当整段结构都要改时才给 {"section":1,"para":0,"replace":"..."}
4. 渲染(一次即可):

"$VT_PY" "$VT_HOME/scripts/make_optimized.py" \
  --from-md "<preorganized_path>" \
  --patch "<patch.json>" \
  --filename "YYYY-MM-DD_标题30字内_整理优化版" \
  --output-dir "$VT_HOME/outputs"

5. 读取生成的 *_整理优化版.md,在对话里完整输出整理优化版全文(纯 Markdown,不要用代码块包裹)
6. 需要预览时 present_files 只传整理优化版 .html(第一位) + .md
7. 末尾附一行落盘路径

章节很多时的并行润色

polish_brief.json 里 sections 超过 4 个时:

• 按 4 章一组拆成多个小 patch(只要 headings 切片 + 该段 fixes / paragraph_edits)
• 可以并行想、但最后必须合成一个 patch.json 再跑 make_optimized.py
• 仍然不要输出多份全文

绝对不要做

• ❌ 把原始无标点逐字稿贴进对话
• ❌ --dump-template 再把全文填进 content.json(旧流程已废弃)
• ❌ 只展示前几段、总结或改写观点
• ❌ 缓存命中后还重新下载/转录(除非用户说「重跑」/--force)

缓存命中

脚本打印 [OK] 缓存命中 时:直接用已有 预整理.md 做 patch → 渲染整理优化版。用户明确要求重跑才加 --force。

播客/说话人分离模式

触发:小宇宙 episode 链接自动启用;其他输入(本地音频/任意 URL)加 --speakers 强制启用。

# 小宇宙链接:自动说话人分离,无需额外参数
"$VT_PY" "$VT_HOME/scripts/transcript.py" "https://www.xiaoyuzhoufm.com/episode/xxxx"

# 本地音频/其他来源:强制说话人分离,可手动指定人名
"$VT_PY" "$VT_HOME/scripts/transcript.py" 访谈.m4a --speakers --host 张三 --guest 李四

# 只重跑后处理(调版式/改人名),复用已有转录,不重跑 ASR、不重新下载
"$VT_PY" "$VT_HOME/scripts/transcript.py" <同一输入> --reformat --host 张三 --guest 李四

版式不满意/人名认错时用 --reformat,不要用 --force。 --force 会连十几分钟的 ASR 一起重跑； --reformat 复用 outputs/.partial/<hash>/transcription.json,1 小时单集约 1 分钟出新版。

小宇宙以外的播客平台(喜马拉雅/Apple Podcasts)没有音频直链,自动用 yt-dlp 取音频, 拿不到 Shownotes,所以说话人会回退成「说话人 A/B」,想要真名就手动传 --host / --guest。

产物:*_逐字稿.md(说话人区块,成品)、*_逐字稿.srt(带说话人前缀、句级时间轴,可直接压字幕)、 *_outputs.json、.partial/<hash>/transcription.json(原始转录,--reformat 的输入)。

转录期间每 30 秒打一行 [转录中] 已跑 x 分,约 y%,预计还需 z 分。 进度是按音频时长估的,不是真实完成度;转录本身是一次不可中断的推理, 中途失败只能重跑(不切块是有意的:CAM++ 的说话人编号只在单次推理内一致,切块会让同一个人在不同块里换编号)。

ASR 一落盘就删掉临时 wav(1 小时单集约 115MB);要留音频排查加 --keep-audio。

与视频链路的区别:

	视频链路	播客链路
引擎	SenseVoice-Small(快,~6x 实时)	paraformer + CAM++(慢,约音频时长 25%,1 小时单集约 15 分钟)
说话人	无	自动分离 + 主持人/嘉宾映射
输出	*_预整理.md(需 agent patch 润色)	*_逐字稿.md(成品,直接交付,不走 patch 流程)+ *_逐字稿.srt
首次模型	SenseVoice 234M	paraformer/CAM++/VAD/punc 约 1GB

自动化处理:小宇宙页 __NEXT_DATA__ 解析标题/音频直链/Shownotes → 从 Shownotes 提取主持人/嘉宾姓名(取不到回退「说话人 A/B」) → 半截词缝合 → ct-punc 补标点 → 语义分段 → 通用 AI 术语纠错。

输出版式(说话人区块):

## 说话人
- **主持人** 曲凯:约 30% 时长
- **嘉宾** 孟繁青:约 70% 时长

## 逐字稿
### 00:22 – 00:30　主持人 · 曲凯
因为这块也很热嘛,所以今天很开心请到…

播客专属词表扩展:在 $VT_HOME/.podcast_glossary.json 写 [["错误词","修正词"], ...],会叠加在内置通用 AI 术语表之上。

agent 拿到播客 *_逐字稿.md 后:直接在对话里输出全文(或按用户要求摘要),不要再跑 make_optimized.py。

阶段 5 · 异常处理

场景	处理
--doctor 报缺依赖	bash "$VT_HOME/install.sh"
funasr 未安装	pip install funasr torchaudio
首次运行联网失败	首次需下载 SenseVoice-Small(约 234M)
播客模式首次很慢	首次自动下载 paraformer/CAM++/VAD/punc 模型(约 1GB),之后走本地缓存
播客版式/人名要改	用 --reformat(秒级),别用 --force(会重跑 ASR)
播客转录中途中断	只能重跑,ASR 不支持续跑(切块会打乱说话人编号);已完成的单集看 .partial/<hash>/transcription.json
某节目专有名词老是错	写 $VT_HOME/.podcast_glossary.json: [["错词","对词"]],优先于内置词表
小宇宙解析失败	页面结构变化;可先下载音频再 --speakers 转本地文件
抖音图文笔记	提示仅支持视频
平台前端改版	看 $VT_HOME/FALLBACK.md
视频号缺登录态	"$VT_PY" "$VT_HOME/scripts/sph_resolver.py" --login
WECHAT_AUTH_REQUIRED / WECHAT_AUTH_EXPIRED	在本机运行 sph_resolver.py --login,扫码后重试
WECHAT_PARSE_EMPTY / WECHAT_STREAM_EMPTY	登录不等于链接可解析;保留错误码,可让用户上传本地 MP4/MOV
视频号公共 Worker 401 / 1042	不再作为公开兜底;使用 yuanbao-login
要保留 MP4	给脚本加 --keep-video,或走 video-download

视频号解析默认 yuanbao-login。sph_resolver.py 先抽 Cookie 走 HTTP,失败才开一次浏览器。

"$VT_PY" "$VT_HOME/scripts/sph_resolver.py" --check
"$VT_PY" "$VT_HOME/scripts/sph_resolver.py" --login
"$VT_PY" "$VT_HOME/scripts/asr_daemon.py" --status

命令行选项

参数	说明
input	视频 URL 或本地路径
--title	覆盖标题
--no-save	不落盘
--output-dir	改保存路径
--doctor	体检
--doctor-live <视频号链接>	在体检基础上验证认证→解析→媒体流,不下载/转录
--force / --no-cache	忽略同 URL 缓存
--keep-video	额外保存 MP4(视频号截图PDF 必加)
--no-daemon	不使用常驻模型
--speakers	强制说话人分离模式(小宇宙链接自动启用)
--host / --guest	说话人分离模式手动指定主持人/嘉宾姓名
--reformat	复用已有转录只重跑后处理(调版式/改人名,不重跑 ASR)
--keep-audio	播客模式转录后保留临时 wav(默认清理)

Notes

• 视频引擎 FunASR SenseVoice-Small:中文 CER 7.81%,模型 234M,CPU 约 6x 实时
• 播客引擎 paraformer-zh + fsmn-vad + ct-punc + CAM++:带说话人分离,约 0.15x 实时
• 视频号不再 probe+download 各解析一遍;默认也不下完整视频
• FunASR daemon 常驻后,后续任务跳过 15~30s 模型加载;空闲 30 分钟自动退出
• 时间戳是段落级,用于章节定位
• 预估耗时:时长/8 + 15s(直链音频 + 已预热模型)
• 热词:$VT_HOME/.env 里 FUNASR_HOTWORD=词1 词2
• ASR 转录在本地运行,不需要 API Key;链接解析和首次模型下载需要联网
• 微信视频号三种交付见 skills/weixin-layout.md:默认对话逐字稿;文字PDF / 截图PDF 用 Kami 羊皮纸长文;文件名用视频原标题