视频技能 (Video Skill)

视频技能 (Video Skill) 是做什么的？

使用 ffmpeg、Deepgram Nova 3 和 S3/隧道分享来处理和分享视频。

默认：更小的视频，相同分辨率

默认始终以源视频的原始分辨率重新编码为较小的文件。 一个压缩的、相同分辨率的副本几乎总是用户想要的——更快的上传、更轻量的分享、相同的观看体验。将其设为每个流程（静默、交互和 Gemini dev-video 回放编码）的默认值；仅在用户明确要求时才偏离。具体来说：

• 默认优化 = --resolution keep — 使用 libx264 + CRF 重新编码，不添加缩放滤镜，因此分辨率不变，文件只会变小。这是推荐的 Q1 选择，也是静默模式的默认值。
• 仅当源视频明显大于 1080p（≥1440p / 4K）或用户要求时才降分辨率（例如降至 1080p）。绝不升分辨率。
• 仅当用户明确要求不重新编码（例如“保留原始文件”、“不要重新编码”）时，才跳过重新编码（使用未经修改的原始文件 / 流复制）。
• 安全检查： 编码后，将输出文件大小与源文件进行比较。如果大小没有明显减小（罕见情况，例如源视频比特率已经很低），则提高 CRF（26–28）或回退到原始文件。屏幕录制的压缩效果特别好：CRF 24–26 配合 preset slow 通常可以削减 70–80% 的大小，同时保持屏幕文字清晰。
• 下载按钮： 页面默认显示一个**“下载视频”按钮**（指向回放视频）。仅当您确实将未经修改的原始文件按该确切名称上传到输出文件夹时，才添加**“下载原始文件”按钮**——即传递 render_page.py --original-filename <name> 参数；否则该按钮将链接到一个缺失的文件并返回 404。默认的压缩并保留流程不会保留单独的原始文件，因此不要传递 --original-filename。

前提条件

• 必须安装 ffmpeg 和 ffprobe
• 必须安装 Python 3
• 必须安装 aws 命令行工具（用于 S3 上传）
• Deepgram API 密钥 —— 用于音频转录/字幕（默认引擎）
• OpenRouter API 密钥 —— 用于 Gemini 分析引擎（dev-video / transcript-cheap 模式）。可选；仅在选择这些模式时需要。

目录

• 脚本： <skill_dir>/scripts/ —— 所有 Python 脚本和 player.html 模板
• 凭据： ~/.config/video-skill/ —— 在插件更新后持久存在
  • deepgram_token —— 单行 Deepgram API 密钥
  • openrouter_token —— 单行 OpenRouter API 密钥（Gemini 分析引擎）
  • s3_credentials —— key=value 格式（endpoint、bucket、access_key、secret_key）
• 偏好设置： ~/.config/video-skill/preferences.json —— 跨会话保存的用户选择

凭据设置

如果缺少凭据，通过 AskUserQuestion 询问用户：

Deepgram： 检查 DEEPGRAM_API_KEY 环境变量，然后检查 ~/.config/video-skill/deepgram_token 文件。如果两者都不存在，询问用户并将凭据保存到文件。

OpenRouter： 检查 OPENROUTER_TOKEN 环境变量，然后检查 ~/.config/video-skill/openrouter_token 文件。仅 dev-video / transcript-cheap 分析模式需要。如果选择了 Gemini 模式但缺少令牌，询问用户并将凭据保存到文件。

S3： 检查环境变量（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、S3_ENDPOINT、S3_BUCKET），然后检查 ~/.config/video-skill/s3_credentials。如果缺少，询问用户 endpoint、bucket、access_key、secret_key 并保存。

重要： 切勿将凭据作为命令行参数传递。脚本通过 --credential-dir ~/.config/video-skill 从文件内部读取它们。

偏好设置

{
  "language": "en",
  "last_folder": "/Users/example/screencasts",
  "share_folder": "/Users/example/screencasts",
  "sharing_method": "s3",
  "optimization": "compress-keep",
  "crf": 23,
  "preset": "medium",
  "audio": "aac-128k",
  "subtitles": "track",
  "subtitle_style": "modern",
  "subtitle_font": "Helvetica Neue",
  "target_language": "ru",
  "download_button": true,
  "passcode": true,
  "mode": "subtitles"
}

optimization：回放视频的编码方式。默认 compress-keep = 在源分辨率下重新编码以减小文件大小（--resolution keep）。其他值：web-1080p（降分辨率至 1080p —— 用于 ≥1440p/4K 的源），custom，keep-original（不重新编码 —— 仅在用户明确要求时）。请参阅上方 “默认：更小的视频，相同分辨率”。

mode：决定转录/分析引擎的单个字段。四个值之一（旧的 analysis_mode + developer_analysis 对合并为此）：

mode	引擎	字幕	开发者分析	使用场景
subtitles（默认）	Deepgram	精确	否	普通分享，仅需要字幕
dev-audio	Deepgram	精确	是（来自转录文本）	工具/反馈，也需要清晰字幕
dev-video	Gemini 视频	粗略	是 + 截图	最丰富的工具/用户体验反馈（读取屏幕）
transcript-cheap	Gemini 音频	粗略	否	便宜快速转写，时间精度要求不高

内部：subtitles/dev-audio 运行 process_and_share.py（后者使用 --developer-analysis 参数）；dev-video/transcript-cheap 运行 Gemini 引擎（gemini_analyze.py）。“开发者分析” = 页面内分析块 加上 分析 Markdown 制品（参见该部分）。引擎指南（研究于 2026-06）：保持 Deepgram 用于精确字幕；使用 Gemini-video 用于分析，Gemini-audio 用于便宜快速转写。对于 dev-video，如果精确字幕也很重要，则额外运行一次 Deepgram 以生成音频轨道。

保存： 每次交互选择后，更新 preferences.json。每次运行后始终保存 last_folder。 加载： 启动时读取。使用保存的值作为“（推荐）”默认值。在静默模式下，直接使用。

脚本参考

所有脚本位于 <skill_dir>/scripts/。它们接受 --credential-dir 参数用于凭据，并打印 [PROGRESS] 行用于状态跟踪。

脚本	用途	关键参数
process_and_share.py	主要工作流：优化 + 转录 + 渲染 + 上传	` --output-dir --share-folder --share s3
share_existing.py	分享已处理的文件夹	` --share-folder --share s3
upload_s3.py	将文件夹上传到 S3	<folder> --key <key> --credential-dir
render_page.py	从模板生成 index.html	--output-dir --template --metadata
manage_registry.py	注册表 CRUD（添加/移除/列出/获取/迁移）	<subcommand> --share-folder
partial_update.py	重新渲染并上传已分享的文件夹（从注册表解析 key，转发密码）	<output_folder> [--key]
font_name.py	打印 TTF 字体的内部系列名称（用于 ASS Fontname）	<font.ttf>
transcribe.py	Deepgram 转录 → SRT + VTT	<video> --credential-dir [--language]
gemini_analyze.py	Gemini 引擎：音频转录 或 视频分析 + 截图	` --mode audio
burn_subtitles.py	将字幕烧录到视频中	<video> <srt> [--font --fontsize ...]
share_server.py	用于隧道分享的本地 HTTP 服务器	<share_root> [--port]

工作流

步骤 0：解析参数并检测模式

命令：

• /video → 交互模式（步骤 1-5）
• /video process <path> → 针对特定文件的 交互模式
• /video share → 静默模式：处理最新视频 + 分享
• /video share <path> → 静默模式：处理特定文件 + 分享
• /video share <path> "context" → 带有额外元数据上下文的 静默模式
• /video start → 启动分享服务器 + 隧道
• /video stop → 停止分享
• /video status → 列出已分享的视频
• /video copy <key_or_name> → 将链接 + 密码复制到剪贴板
• /video remove <key_or_name> → 从注册表中移除

---

分享命令（直接处理，无需处理视频）

分享注册表： <share_folder>/.share_registry.json —— 由 manage_registry.py 管理。

start 命令：

1. 读取偏好设置 → share_folder。如果未设置，询问用户。
2. 检查 pgrep -f share_server.py。如果正在运行，显示状态。
3. 启动服务器：python3 "<scripts>/share_server.py" "<share_folder>" --port 8080 &
4. 启动隧道：ssh -p 443 -R0:localhost:<port> -o StrictHostKeyChecking=no a.pinggy.io 2>&1 &
5. 解析隧道 URL。显示：“服务器运行在 <base_url>”
6. 使用完整 URL（<base_url>/v/<key>）列出已有视频。

stop 命令： pkill -f share_server.py; pkill -f "ssh.*pinggy"; pkill -f "ngrok http"

status 命令：

1. 运行 python3 "<scripts>/manage_registry.py" list --share-folder "<share_folder>"
2. 检查 pgrep -f share_server.py 以获取隧道状态。
3. 显示表格：key、标题、S3 URL、隧道 URL、密码、创建时间。

copy 命令：

1. 运行 python3 "<scripts>/manage_registry.py" get --share-folder "<share_folder>" --key "<query>"
2. 格式化：<title>\n<url>\nPasscode: <code> → pbcopy

remove 命令： 运行 python3 "<scripts>/manage_registry.py" remove --share-folder "<share_folder>" --key "<query>"

---

静默模式（/video share）

一次确认，一次脚本执行，最少交互。

流程：

1. 识别视频（参数路径或 last_folder / CWD 中的最新文件）

2. 创建输出文件夹 <share_folder>/<video_name>/

3. 生成密码（随机 6 位数字或保存的偏好设置）

4. 显示确认信息：

   快速分享：demo.mov
   → 相同分辨率 · 压缩（CRF 23）· AAC 128k
   → 转录 + 字幕（轨道）
   → 通过 S3 分享（永久链接）
   → 密码：482910
   继续？
   

   选项：继续（推荐） / 切换到交互模式

   如果 mode 是 dev-video 或 transcript-cheap，则不运行 process_and_share.py —— 而是按照“Gemini 分析引擎”部分执行（静默模式，使用保存的偏好设置），然后仍然上传并注册分享。

5. 运行主工作流脚本。当 mode 为 dev-audio 时，传递 --developer-analysis 参数：

   python3 "<scripts>/process_and_share.py" "<video_path>" \
       --output-dir "<output_folder>" \
       --share-folder "<share_folder>" \
       --credential-dir ~/.config/video-skill \
       --resolution keep --crf 23 --preset medium --audio aac-128k \
       --subtitles track \
       --share s3 \
       --passcode "<passcode>" \
       [--developer-analysis] \
       [--context "<user_context>"]
   

   默认 --resolution keep（压缩，保持相同分辨率）。仅当源视频 ≥1440p/4K 时才使用 --resolution 1080p，或者如果用户明确想要未修改的文件，则处理 keep-original 的情况。

6. 监视 stdout 中的 METADATA_READY: 标记 —— 当脚本打印此标记时： a. 读取其之前的 TRANSCRIPT_PREVIEW: 和 METADATA_INFO:。 b. 从转录预览生成标题、描述和 4-8 个章节。 c. 如果 mode 是 dev-audio（启用了开发者分析）：从完整转录（读取输出目录中的 SRT/VTT，而不是截断的预览）构建分析块和分析 Markdown。有关确切的格式和约定，请参阅 “metadata.json 参考” 和 “分析 Markdown” 部分。匹配页面语言（RU / DE / EN）。 d. 根据 metadata.json 参考 将 metadata.json 写入输出目录。 e. 脚本检测到 metadata.json 并自动继续。

7. 脚本完成。显示结果。

...（已截断）