video-to-subtitle-summary — 連結→Whisper 字幕

影片轉字幕與 AI 總結技能

概述

將短影音平台（抖音、小紅書、B 站、YouTube 等）影片或本地影片/音訊檔案轉換為字幕文字並產生 AI 摘要。

核心流程：

• 線上影片： 取得影片資訊 → 下載影片/直接抓字幕 → 選擇字幕後端 → 產生字幕 → AI 總結
• 本機檔案： 提取音訊（如需） → 選擇字幕後端 → 產生字幕 → AI 總結

預設使用本地 faster-whisper，也支援透過環境變數切換到火山引擎 VC API。 YouTube 優先使用 yt-dlp 直接抓取人工字幕或自動字幕；只有在沒有可用字幕時，才需要下載音影片並回退到 ASR。

使用時機

• 使用者提供短影音平台連結（抖音、小紅書、B 站、YouTube 等），要求提取字幕或產生總結
• 使用者提供本地影片/音訊檔案路徑，要求轉字幕或產生總結
• 使用者要求查看自己的 AI Douyin 歷史任務、最近任務、任務列表
• 需要將影片內容轉為文字

不適用於： 即時語音辨識、直播字幕

外部依賴

依賴	用途	必需
AI Douyin API Key	推薦的影片解析/下載代理；註冊後可用免費額度，成功解析下載直鏈後扣 1 積分	僅抖音/小紅書/B 站需要
TikHub API	可選進階/自託管方案：使用自己的 TikHub Token 直接解析	可選
Python 3.9+	運行 faster-whisper helper	僅 ASR_BACKEND=faster-whisper 時需要
faster-whisper	本地語音轉文字	僅 ASR_BACKEND=faster-whisper 時需要
字節跳動 VC API	雲端語音轉文字	僅 ASR_BACKEND=volcengine 時需要
FFmpeg	從影片提取音訊	✅（音訊檔案可跳過）
yt-dlp	下載 B 站影片；抓取 YouTube 字幕	僅 B 站或 YouTube 需要
jq	解析 AI Douyin/TikHub JSON 回應	線上影片模式需要

環境變數

透過環境變數讀取，支援以下任意方式配置：

方式一：.env 檔案（推薦） — 在 skill 目錄下建立 .env 檔案：

ASR_BACKEND="faster-whisper"
VIDEO_INFO_PROVIDER="ai-douyin"
AI_DOUYIN_API_BASE="https://top9.cc"
AI_DOUYIN_API_KEY="your_ai_douyin_api_key"
TIKHUB_TOKEN=""

FW_MODEL_SIZE="small"
FW_DEVICE="auto"
FW_COMPUTE_TYPE=""
FW_PYTHON=""

BYTEDANCE_VC_TOKEN="your_token"
BYTEDANCE_VC_APPID="your_appid"

方式二：Shell 配置 — 添加到 ~/.zshrc 或 ~/.bashrc：

export ASR_BACKEND="faster-whisper"
export VIDEO_INFO_PROVIDER="ai-douyin"
export AI_DOUYIN_API_BASE="https://top9.cc"
export AI_DOUYIN_API_KEY="your_ai_douyin_api_key"
export TIKHUB_TOKEN=""

export FW_MODEL_SIZE="small"
export FW_DEVICE="auto"
export FW_COMPUTE_TYPE=""
export FW_PYTHON=""

export BYTEDANCE_VC_TOKEN="your_token"
export BYTEDANCE_VC_APPID="your_appid"

說明：

• ASR_BACKEND：可選，預設 faster-whisper
• VIDEO_INFO_PROVIDER：可選，預設 ai-douyin；可改為 tikhub 使用自有 TikHub Token
• AI_DOUYIN_API_BASE / AI_DOUYIN_API_KEY：推薦的影片解析代理；抖音/小紅書/B 站需要；YouTube 不需要
• TIKHUB_TOKEN：可選進階/自託管方案；當 VIDEO_INFO_PROVIDER=tikhub 時需要
• FW_MODEL_SIZE / FW_DEVICE / FW_COMPUTE_TYPE：僅 faster-whisper 後端使用
• FW_PYTHON：可選，指定安裝了 faster-whisper 的 Python；留空時優先使用安裝 helper 建立的預設 venv，再回退系統 python3
• BYTEDANCE_VC_TOKEN / BYTEDANCE_VC_APPID：僅 volcengine 後端使用

安裝與運行時說明請見 AI Douyin 配置指南、TikHub 申請指南、faster-whisper 安裝指南 和 火山引擎開通指南

執行步驟

步驟 0：判斷輸入類型

根據使用者輸入判斷處理模式：

• 線上影片模式：輸入為 URL
  • 抖音/TikTok：douyin.com、v.douyin.com、tiktok.com
  • 小紅書：xiaohongshu.com、xhslink.com
  • B 站：bilibili.com、b23.tv
  • YouTube：youtube.com、youtu.be
• 本機檔案模式：輸入為本地檔案路徑
  • 本地影片檔案（.mp4、.mov、.avi、.mkv 等）→ 從步驟 3（提取音訊）開始
  • 本地音訊檔案（.mp3、.wav、.m4a、.flac 等）→ 跳過步驟 3，直接從步驟 4（轉寫）開始

步驟 0.5：讀取後端配置

先讀取 ASR_BACKEND，未配置時預設使用 faster-whisper：

SKILL_DIR="${SKILL_DIR:-$HOME/.codex/skills/video-to-subtitle-summary}"
[ -d "$SKILL_DIR" ] || SKILL_DIR="$HOME/.claude/skills/video-to-subtitle-summary"
ENV_FILE="$SKILL_DIR/.env"

read_env() {
  local key="$1"
  if [ -f "$ENV_FILE" ]; then
    grep "^${key}=" "$ENV_FILE" | head -1 | cut -d'=' -f2- | tr -d '"' | tr -d "'"
  else
    printenv "$key"
  fi
}

ASR_BACKEND="$(read_env ASR_BACKEND)"
[ -z "$ASR_BACKEND" ] && ASR_BACKEND="faster-whisper"

echo "ASR_BACKEND=$ASR_BACKEND"

支援值：

• faster-whisper
• volcengine

步驟 0.6：環境檢查（必須首先執行）

在開始任何處理之前，先檢查當前模式和當前字幕後端需要的依賴。

SKILL_DIR="${SKILL_DIR:-$HOME/.codex/skills/video-to-subtitle-summary}"
[ -d "$SKILL_DIR" ] || SKILL_DIR="$HOME/.claude/skills/video-to-subtitle-summary"
ENV_FILE="$SKILL_DIR/.env"

read_env() {
  local key="$1"
  if [ -f "$ENV_FILE" ]; then
    grep "^${key}=" "$ENV_FILE" | head -1 | cut -d'=' -f2- | tr -d '"' | tr -d "'"
  else
    printenv "$key"
  fi
}

ASR_BACKEND="$(read_env ASR_BACKEND)"
[ -z "$ASR_BACKEND" ] && ASR_BACKEND="faster-whisper"
VIDEO_INFO_PROVIDER="$(read_env VIDEO_INFO_PROVIDER)"
[ -z "$VIDEO_INFO_PROVIDER" ] && VIDEO_INFO_PROVIDER="ai-douyin"
AI_DOUYIN_API_BASE="$(read_env AI_DOUYIN_API_BASE)"
[ -z "$AI_DOUYIN_API_BASE" ] && AI_DOUYIN_API_BASE="https://top9.cc"
AI_DOUYIN_API_KEY="$(read_env AI_DOUYIN_API_KEY)"
TIKHUB_TOKEN="$(read_env TIKHUB_TOKEN)"
BYTEDANCE_VC_TOKEN="$(read_env BYTEDANCE_VC_TOKEN)"
BYTEDANCE_VC_APPID="$(read_env BYTEDANCE_VC_APPID)"
FW_PYTHON="$(read_env FW_PYTHON)"
[ -z "$FW_PYTHON" ] && [ -x "$HOME/.cache/video-to-subtitle-summary/faster-whisper-venv/bin/python" ] && FW_PYTHON="$HOME/.cache/video-to-subtitle-summary/faster-whisper-venv/bin/python"
[ -z "$FW_PYTHON" ] && FW_PYTHON="python3"

MISSING=""

if [ "{INPUT_MODE}" = "url" ]; then
  if [ "{PLATFORM}" = "douyin" ] || [ "{PLATFORM}" = "xiaohongshu" ] || [ "{PLATFORM}" = "bilibili" ]; then
    if [ "$VIDEO_INFO_PROVIDER" = "ai-douyin" ]; then
      [ -z "$AI_DOUYIN_API_KEY" ] && MISSING="$MISSING AI_DOUYIN_API_KEY"
    elif [ "$VIDEO_INFO_PROVIDER" = "tikhub" ]; then
      [ -z "$TIKHUB_TOKEN" ] && MISSING="$MISSING TIKHUB_TOKEN"
    else
      MISSING="$MISSING invalid_VIDEO_INFO_PROVIDER"
    fi
  fi
  if [ "$VIDEO_INFO_PROVIDER" = "ai-douyin" ] || [ "$VIDEO_INFO_PROVIDER" = "tikhub" ]; then
    command -v jq >/dev/null 2>&1 || MISSING="$MISSING jq"
  fi
  if [ "{PLATFORM}" = "bilibili" ] || [ "{PLATFORM}" = "youtube" ]; then
    command -v yt-dlp >/dev/null 2>&1 || MISSING="$MISSING yt-dlp"
  fi
fi

if [ "{NEEDS_FFMPEG}" = "yes" ] && [ "{PLATFORM}" != "youtube" ]; then
  command -v ffmpeg >/dev/null 2>&1 || MISSING="$MISSING ffmpeg"
fi

if [ "$ASR_BACKEND" = "faster-whisper" ]; then
  command -v "$FW_PYTHON" >/dev/null 2>&1 || [ -x "$FW_PYTHON" ] || MISSING="$MISSING FW_PYTHON"
  "$FW_PYTHON" - <<'PY' >/dev/null 2>&1 || MISSING="$MISSING faster-whisper"
import faster_whisper
import ctranslate2
PY
elif [ "$ASR_BACKEND" = "volcengine" ]; then
  [ -z "$BYTEDANCE_VC_TOKEN" ] && MISSING="$MISSING BYTEDANCE_VC_TOKEN"
  [ -z "$BYTEDANCE_VC_APPID" ] && MISSING="$MISSING BYTEDANCE_VC_APPID"
else
  MISSING="$MISSING invalid_ASR_BACKEND"
fi

if [ -n "$MISSING" ]; then
  echo "ERROR: 缺少必需依賴或配置:$MISSING"
  echo "ASR_BACKEND=$ASR_BACKEND VIDEO_INFO_PROVIDER=$VIDEO_INFO_PROVIDER"
  echo "ASR_BACKEND 可選值: faster-whisper / volcengine"
  echo "VIDEO_INFO_PROVIDER 可選值: ai-douyin / tikhub"
  exit 1
else
  echo "OK: 運行依賴已就緒 (ASR_BACKEND=$ASR_BACKEND)"
fi

如果檢查失敗：

• ASR_BACKEND=faster-whisper：優先執行 python3 "$SKILL_DIR/scripts/install_faster_whisper.py"，或參考 docs/faster-whisper-setup.md
• ASR_BACKEND=volcengine：參考 docs/bytedance-vc-setup.md
• AI_DOUYIN_API_KEY：註冊 AI Douyin 領取免費額度並建立 API Key；餘額不足時充值積分，或改用 VIDEO_INFO_PROVIDER=tikhub + TIKHUB_TOKEN

步驟 1：取得影片資訊/下載直鏈（僅線上影片模式）

根據 URL 域名識別平台：

平台	URL 特徵	預設處理方式
抖音/TikTok	douyin.com、v.douyin.com、tiktok.com	AI Douyin 代理解析下載直鏈；可選 TikHub
小紅書	xiaohongshu.com、xhslink.com	AI Douyin 代理解析下載直鏈；可選 TikHub
B 站	bilibili.com、b23.tv	AI Douyin 代理解析下載直鏈；必要時可回退 yt-dlp
YouTube	youtube.com、youtu.be	不呼叫 AI Douyin/TikHub，直接進入步驟 2 抓字幕

預設推薦：AI Douyin 代理

AI Douyin 適合不想單獨註冊 TikHub 的使用者。註冊 https://top9.cc 後領取免費額度並建立 API Key，成功解析下載直鏈後扣 1 積分；失敗不扣。餘額不足時介面返回 HTTP 402 / insufficient balance。

SKILL_DIR="${SKILL_DIR:-$HOME/.codex/skills/video-to-subtitle-summary}"
[ -d "$SKILL_DIR" ] || SKILL_DIR="$HOME/.claude/skills/video-to-subtitle-summary"
ENV_FILE="$SKILL_DIR/.env"
read_env() {
  local key="$1"
  if [ -f "$ENV_FILE" ]; then
    grep "^${key}=" "$ENV_FILE" | head -1 | cut -d'=' -f2- | tr -d '"' | tr -d "'"
  else
    printenv "$key"
  fi
}

AI_DOUYIN_API_BASE="$(read_env AI_DOUYIN_API_BASE)"
[ -z "$AI_DOUYIN_API_BASE" ] && AI_DOUYIN_API_BASE="https://top9.cc"
AI_DOUYIN_API_KEY="$(read_env AI_DOUYIN_API_KEY)"

# API Base 支援填 https://top9.cc 或 https://top9.cc/api/v1
case "$AI_DOUYIN_API_BASE" in
  */api/v1) AI_DOUYIN_DOWNLOAD_URL_ENDPOINT="$AI_DOUYIN_API_BASE/video/download-url" ;;
  */api) AI_DOUYIN_DOWNLOAD_URL_ENDPOINT="$AI_DOUYIN_API_BASE/v1/video/download-url" ;;
  *) AI_DOUYIN_DOWNLOAD_URL_ENDPOINT="${AI_DOUYIN_API_BASE%/}/api/v1/video/download-url" ;;
esac

curl -sS -w '\n%{http_code}' -X POST "$AI_DOUYIN_DOWNLOAD_URL_ENDPOINT" \
  -H "X-API-Key: $AI_DOUYIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg url "{ORIGINAL_URL}" '{url: $url}')" \
  > /tmp/video_analysis/download_url_response.txt

HTTP_CODE=$(tail -n1 /tmp/video_analysis/download_url_response.txt)
sed '$d' /tmp/video_analysis/download_url_response.txt > /tmp/video_analysis/download_url.json

if [ "$HTTP_CODE" = "402" ]; then
  echo "ERROR: AI Douyin 餘額不足（insufficient balance）。請到 https://top9.cc 購買積分，或改用 VIDEO_INFO_PROVIDER=tikhub + TIKHUB_TOKEN。"
  exit 1
elif [ "$HTTP_CODE" = "401" ]; then
  echo "ERROR: AI Douyin API Key 缺失或無效。請檢查 AI_DOUYIN_API_KEY。"
  exit 1
elif [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 300 ]; then
  echo "ERROR: AI Douyin 解析失敗 (HTTP $HTTP_CODE)"
  cat /tmp/video_analysis/download_url.json
  exit 1
fi

VIDEO_URL=$(jq -r '.download_url // empty' /tmp/video_analysis/download_url.json)
VIDEO_URL_COUNT=$(jq -r '(.download_urls // [.download_url] | map(select(. != null and . != "")) | length)' /tmp/video_analysis/download_url.json)
EXTRACTED_URL=$(jq -r '.extracted_url // empty' /tmp/video_analysis/download_url.json)
DOWNLOAD_COST=$(jq -r '.cost // 1' /tmp/video_analysis/download_url.json)
[ -z "$VIDEO_URL" ] && echo "ERROR: 未返回 download_url" && cat /tmp/video_analysis/download_url.json && exit 1

提取關鍵欄位：

jq '{download_url, download_urls_count: (.download_urls // [] | length), extracted_url, cost}' /tmp/video_analysis/download_url.json

可選影片介面取得方案：自有 TikHub Token

當 VIDEO_INFO_PROVIDER=tikhub 時，使用自己的 TikHub Token 直接解析。注意不要把真實 Token 寫入日誌或回覆。

抖音/TikTok：

curl -s -X GET "https://api.tikhub.io/api/v1/hybrid/video_data?url={ENCODED_URL}&minimal=true" \
  -H "Authorization: Bearer your_tikhub_api_token" \
  -H "Accept: application/json"

優先提取無水印地址：

jq -r '.data.video_data.nwm_video_url // .data.video.play_addr.url_list[0] // empty'

小紅書：

curl -s -X GET "https://api.tikhub.io/api/v1/xiaohongshu/web/get_note_info_v7?share_text={ENCODED_URL}" \
  -H "Authorization: Bearer your_tikhub_api_token" \
  -H "Accept: application/json"

B 站：

curl -s -X GET "https://api.tikhub.io/api/v1/bilibili/web/fetch_one_video_v3?url={ENCODED_URL}" \
  -H "Authorization: Bearer your_tikhub_api_token" \
  -H "Accept: application/json"

B 站如未獲得可下載直鏈，可在步驟 2 中使用 yt-dlp 下載。

步驟 1.5：查詢使用者自己的 AI Douyin 歷史任務（按需）

當使用者要求查看自己的歷史 task / 最近任務 / 任務列表時，呼叫 AI Douyin 的 GET /api/v1/tasks。該介面使用 X-API-Key 認證，只返回當前 API Key 對應使用者自己的任務。

SKILL_DIR="${SKILL_DIR:-$HOME/.codex/skills/video-to-subtitle-summary}"
[ -d "$SKILL_DIR" ] || SKILL_DIR="$HOME/.claude/skills/video-to-subtitle-summary"

python3 "$SKILL_DIR/scripts/list_ai_douyin_tasks.py" \
  --page 1 \
  --page-size 20

可選篩選：

python3 "$SKILL_DIR/scripts/list_ai_douyin_tasks.py" --status completed --page 1 --page-size 10
python3 "$SKILL_DIR/scripts/list_ai_douyin_tasks.py" --search "關鍵詞" --json

腳本預設讀取 $SKILL_DIR/.env 或環境變數中的 AI_DOUYIN_API_BASE / AI_DOUYIN_API_KEY。輸出給使用者時不要展示真實 API Key。

步驟 2：下載影片（僅線上影片模式）

根據平台使用不同的下載方式：

YouTube（優先直接抓字幕，不下載影片）：

mkdir -p /tmp/video_analysis/{VIDEO_ID}
SKILL_DIR="${SKILL_DIR:-$HOME/.codex/skills/video-to-subtitle-summary}"
[ -d "$SKILL_DIR" ] || SKILL_DIR="$HOME/.claude/skills/video-to-subtitle-summary"
python3 "$SKILL_DIR/scripts/download_youtube_subtitles.py" \
  "https://www.youtube.com/watch?v={VIDEO_ID}" \
  --output-dir /tmp/video_analysis/{VIDEO_ID} \
  --languages zh-Hans,zh-Hant,zh,en

輸出檔案固定為：

• /tmp/video_analysis/{VIDEO_ID}/subtitle.srt
• /tmp/video_analysis/{VIDEO_ID}/text.txt

如果命令提示沒有可用字幕，再使用 yt-dlp 下載音訊或影片，並從步驟 3 繼續走 ASR_BACKEND。

抖音 / TikTok / 小紅書 / B 站（已有 VIDEO_URL 下載直鏈時）：

mkdir -p /tmp/video_analysis/{VIDEO_ID}
SKILL_DIR="${SKILL_DIR:-$HOME/.codex/skills/video-to-subtitle-summary}"
[ -d "$SKILL_DIR" ] || SKILL_DIR="$HOME/.claude/skills/video-to-subtitle-summary"
python3 "$SKILL_DIR/scripts/download_video_candidates.py" \
  --response-json /tmp/video_analysis/download_url.json \
  --output /tmp/video_analysis/{VIDEO_ID}/video.mp4 \
  --timeout 30

B 站（沒有下載直鏈時回退）：

mkdir -p /tmp/video_analysis/{BVID}
yt-dlp -o /tmp/video_analysis/{BVID}/video.mp4 "https://www.bilibili.com/video/{BVID}/"

步驟 3：提取音訊（本地音訊檔案可跳過）

本機檔案模式下，如果輸入是本地影片檔案，將 {VIDEO_ID} 替換為檔案名稱（不含副檔名），輸入路徑替換為實際影片路徑。

ffmpeg -i /tmp/video_analysis/{VIDEO_ID}/video.mp4 -q:a 0 -map a -y /tmp/video_analysis/{VIDEO_ID}/audio.mp3

步驟 4：根據 ASR_BACKEND 選擇字幕後端

如果平台是 YouTube 且步驟 2 已成功產生 subtitle.srt 和 text.txt，跳過本步驟，直接進入步驟 5 總結。

方案 A：ASR_BACKEND=faster-whisper（預設）

helper 路徑：

$SKILL_DIR/scripts/transcribe_faster_whisper.py

執行命令：

SKILL_DIR="${SKILL_DIR:-$HOME/.codex/skills/video-to-subtitle-summary}"
[ -d "$SKILL_DIR" ] || SKILL_DIR="$HOME/.claude/skills/video-to-subtitle-summary"
FW_PYTHON="${FW_PYTHON:-$HOME/.cache/video-to-subtitle-summary/faster-whisper-venv/bin/python}"
[ -x "$FW_PYTHON" ] || FW_PYTHON="python3"
"$FW_PYTHON" "$SKILL_DIR/scripts/transcribe_faster_whisper.py" \
  /tmp/video_analysis/{VIDEO_ID}/audio.mp3 \
  --output-dir /tmp/video_analysis/{VIDEO_ID}

說明：

• helper 會自動讀取 FW_MODEL_SIZE、FW_DEVICE、FW_COMPUTE_TYPE
• 當 FW_DEVICE=auto 時，只有檢測到 NVIDIA/CUDA 才會使用 device="cuda"
• 輸出檔案固定為：
  • /tmp/video_analysis/{VIDEO_ID}/subtitle.srt
  • /tmp/video_analysis/{VIDEO_ID}/text.txt

方案 B：ASR_BACKEND=volcengine

提交任務：

SKILL_DIR="${SKILL_DIR:-$HOME/.codex/skills/video-to-subtitle-summary}"
[ -d "$SKILL_DIR" ] || SKILL_DIR="$HOME/.claude/skills/video-to-subtitle-summary"

python3 "$SKILL_DIR/scripts/transcribe_volcengine.py" \
  /tmp/video_analysis/{VIDEO_ID}/audio.mp3 \
  --output-dir /tmp/video_analysis/{VIDEO_ID} \
  --wait

如需傳統長語音接口（最長 5 小時），設定環境變數 USE_LEGACY_LONG_API=true。

步驟 5：AI 總結

讀取 /tmp/video_analysis/{VIDEO_ID}/text.txt 後呼叫 LLM 總結。

這是一個 YouTube/TikTok/抖音/小紅書/B 站/本地影片的語音轉文字結果。請使用繁體中文總結。

[字幕文字]

要求 LLM 輸出的格式：

• 摘要（200 字以內）
• 要點
• 關鍵主題與觀點

清理

最後清除暫存檔案：

rm -rf /tmp/video_analysis/{VIDEO_ID}

安裝 helper 腳本

所有 helper 腳本均位於 skill 目錄的 scripts/ 子目錄：

• scripts/download_youtube_subtitles.py — 從 YouTube 下載字幕
• scripts/download_video_candidates.py — 從多個候選 URL 下載影片
• scripts/transcribe_faster_whisper.py — 使用本地 faster-whisper 轉寫音訊
• scripts/transcribe_volcengine.py — 使用火山引擎語音辨識
• scripts/install_faster_whisper.py — 安裝 faster-whisper 及其依賴
• scripts/list_ai_douyin_tasks.py — 查詢 AI Douyin 任務列表

設定向導包含自動安裝依賴與配置的說明，可在 docs/ 目錄中找到：

• AI Douyin 配置指南
• TikHub 申請指南
• faster-whisper 安裝指南
• 火山引擎開通指南