jiawood2006/hermes-skills

Video-to-Text — 抖音/本地视频 → 文字 → 内容情报（一条命令闭环）

抖音分享链接 → 自动下载 → 语音转写 → 结构化 Markdown → 爆款拆解，一条命令跑完。 不用手动存视频、不用第三方 API key、隐私不出本机（默认本地 faster-whisper）。

📁 安装：hermes skills install jiawood2006/hermes-skills/skills/video-to-text 或 ./install.sh（一键装+全局命令 vtt）→ 脚本在 ~/.hermes/skills/utilities/video-to-text/scripts/。

触发条件

用户发送以下内容时使用本技能：

• 抖音分享链接（v.douyin.com / www.douyin.com/video/…），要"转文字/提取文案/拆解/分析爆款/看内容"
• B站链接，要"看视频信息"
• 本地视频文件（.mp4/.mov/.m4a），要"语音转文字/字幕/摘要/分析"

使用步骤

1. 抖音链接 → 全自动闭环（默认行为）

# 一条命令：元数据 + 自动下载 + 本地转写
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py "https://v.douyin.com/xxxx/"

# 全流程 + LLM 摘要 + 爆款结构拆解
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py "https://v.douyin.com/xxxx/" --all

# 只要元数据（不下不转）
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py "https://v.douyin.com/xxxx/" --meta-only

# 转写引擎换硅基 SenseVoice（中文口语/带噪更准，需 SILICONFLOW_API_KEY，失败自动回退本地）
SILICONFLOW_API_KEY=sk-xxx python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py "https://v.douyin.com/xxxx/" --engine sensevoice

技术链路：curl 短链取真实视频 ID → Playwright 监听 aweme/detail API 拿元数据+无水印 play_url → 自动下载 → 提取音频 → 转写。

2. 本地视频文件 → 转写 + 内容情报

python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 视频.mp4                 # 只转写
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 视频.mp4 --summary       # + 内容摘要
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 视频.mp4 --analyze       # + 爆款结构拆解
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 视频.mp4 --engine sensevoice  # 换 SenseVoice

3. B站链接 → 元数据（零依赖公开 API）

python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py "https://www.bilibili.com/video/BV1..."

输出标题/作者/时长/播放/点赞/简介；转写请下载后走本地文件。

4. 输出产物（结构化 Markdown）

默认保存 <标题>_transcript.md，可直接进 Obsidian/知识库：

---
platform: douyin
url: https://v.douyin.com/xxx
title: 视频标题
author: 作者名
duration_s: 42
digg: 12345
date: 2026-09-04
tags: ["话题1", "话题2"]
---

# 视频标题

| 字段 | 值 |
|:---|:---|
| duration_s | 42 |
...

## 转写全文

[00:00] 大家好今天给大家…
[00:05] 这款产品…

5. 输出字幕文件（SRT / VTT，带真实时间戳）

想剪视频、上传 YouTube/B站字幕、或做逐句校对时，直接出字幕文件：

# 文字稿 + 附带 SRT 字幕（最常用）
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 视频.mp4 --subtitles srt

# 同时出 SRT 和 VTT
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 视频.mp4 --subtitles srt,vtt

# 只要字幕，不要文字稿
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 视频.mp4 --format srt

• 输出 <标题>_transcript.srt（剪映/Premiere/YouTube 通用）或 .vtt（网页播放器通用）
• 中文默认输出简体 + 标点，并按句切分（不会一条字幕横跨十几秒）
• 切分阈值可用环境变量调：VTT_MAX_CHARS=18（每条约多少字）、VTT_MAX_DUR=7（每条最长秒数）

6. 指定转写语言

python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 英文视频.mp4 --asr-lang en

缺省 zh（普通话）。中文字幕会额外注入提示词引导简体输出。

7. 对已有转写文本做分析

python3 ~/.hermes/skills/utilities/video-to-text/scripts/analyze.py 转写.md --all

• --summary 输出：一句话概括/核心要点/金句/目标受众/可借鉴点
• --analyze 输出：开头钩子(0-10s)/节奏结构占比/情绪曲线/卖点/CTA/可复用套路
• --format txt 输出纯文本（旧格式兼容）；--out-dir 指定目录

验证（安装后自测）

# 本地文件快速自测：没有视频？用 macOS 自带语音合成一段
say -v "Ting-Ting" "大家好，这是一段测试语音" -o /tmp/t.m4a   # Linux 可跳过
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py /tmp/t.m4a --out-dir /tmp/vtt_test
# 期望：/tmp/vtt_test 出现 *_transcript.md 且含"测试语音"附近文本

# 字幕功能自测（应得到简体带标点、按句切分的 SRT）
python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py /tmp/t.m4a --subtitles srt --out-dir /tmp/vtt_test
# 期望：/tmp/vtt_test 出现 *_transcript.srt，含 --> 时间戳行

依赖（首次使用时安装）

pip3 install faster-whisper        # 默认本地转写（首次下载 tiny 模型 ~75MB）
# macOS 自带 avconvert；Linux 需 ffmpeg
# 抖音解析需 playwright + chromium（douyin_extract 内部使用）
# 内容摘要/爆款拆解需 LLM key（LLM_API_KEY 环境变量 或 ~/.deai_writer.conf）
# SenseVoice 引擎可选：SILICONFLOW_API_KEY（硅基流动，有免费额度）

已知陷阱

• duration_ms=0 假阴性：SSR 元数据时长可能为 0 但实际是视频。有下载 URL 先下载验证，勿直接判图文。
• play_addr URL 过期：SSR 解析出的视频 URL 可能 404，此时下载失败会提示手动提供文件（自动降级不中断）。
• 图文内容：duration=0 且下载文件 <1MB 是图文（无音频），只输出元数据，不编造内容。
• whisper 转写慢：Intel Mac 3 分钟视频约 5 分钟；已自动 language='zh' + VAD 过滤静音。要更快/更准用 --engine sensevoice。
• 中文默认输出繁体（已修）：whisper 对中文常输出繁体、且几乎不加标点。本技能已默认注入 initial_prompt 引导简体 + 标点；如需自定义，设环境变量 WHISPER_INITIAL_PROMPT（置空则关闭该引导）。
• 准确率取决于模型大小：默认 WHISPER_MODEL=tiny（~75MB，快但易错字）。要可用的转写质量就换 small/medium：

  WHISPER_MODEL=small python3 ~/.hermes/skills/utilities/video-to-text/scripts/vtt.py 视频.mp4 --subtitles srt
  

  首次会下载模型（国内网络建议 export HF_ENDPOINT=https://hf-mirror.com）。
• 字幕切分粒度可调：默认按标点/18 字/7 秒切条。要更碎或更整用 VTT_MAX_CHARS、VTT_MAX_DUR 环境变量。
• SenseVoice 路径无真实时间戳：该引擎不返回时间信息，时长按语速估算，字幕时间轴仅供参考——要精确字幕请用 faster-whisper。
• 分析需 LLM key：--summary/--analyze 需 LLM_API_KEY；未配置时只转写不分析（明确降级不报错）。