video-to-subtitle-summary

動画の字幕変換と 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 レスポンスの解析	オンライン動画モードで必要

環境変数

環境変数から読み取ります。以下のいずれかの方法で設定できます。

方法 1：.env ファイル（推奨） — スキルのディレクトリに .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"

方法 2：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 Token を使用する場合は tikhub に変更できます
• 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

オプションの動画 API 取得方法：独自の 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"

まず、ウォーターマークのない URL を抽出します。

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"
ENV_FILE="$SKILL_DIR/.env"
if [ -f "$ENV_FILE" ]; then
  BYTEDANCE_VC_TOKEN=$(grep "^BYTEDANCE_VC_TOKEN=" "$ENV_FILE" | cut -d'=' -f2- | tr -d '"' | tr -d "'")
  BYTEDANCE_VC_APPID=$(grep "^BYTEDANCE_VC_APPID=" "$ENV_FILE" | cut -d'=' -f2- | tr -d '"' | tr -d "'")
else
  BYTEDANCE_VC_TOKEN="$BYTEDANCE_VC_TOKEN"
  BYTEDANCE_VC_APPID="$BYTEDANCE_VC_APPID"
fi

curl -s -X POST "https://openspeech.bytedance.com/api/v1/vc/submit?appid=$BYTEDANCE_VC_APPID&language=zh-CN&words_per_line=20&max_lines=2" \
  -H "Content-Type: audio/mpeg" \
  -H "Authorization: Bearer;$BYTEDANCE_VC_TOKEN" \
  --data-binary @/tmp/video_analysis/{VIDEO_ID}/audio.mp3

轮询结果：

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"
if [ -f "$ENV_FILE" ]; then
  BYTEDANCE_VC_TOKEN=$(grep "^BYTEDANCE_VC_TOKEN=" "$ENV_FILE" | cut -d'=' -f2- | tr -d '"' | tr -d "'")
  BYTEDANCE_VC_APPID=$(grep "^BYTEDANCE_VC_APPID=" "$ENV_FILE" | cut -d'=' -f2- | tr -d '"' | tr -d "'")
else
  BYTEDANCE_VC_TOKEN="$BYTEDANCE_VC_TOKEN"
  BYTEDANCE_VC_APPID="$BYTEDANCE_VC_APPID"
fi

curl -s "https://openspeech.bytedance.com/api/v1/vc/query?appid=$BYTEDANCE_VC_APPID&id={TASK_ID}" \
  -H "Authorization: Bearer;$BYTEDANCE_VC_TOKEN"

结果处理：

jq -r '.utterances[].text' subtitle.json | tr '\n' ' ' > /tmp/video_analysis/{VIDEO_ID}/text.txt

生成 SRT：

import json

with open('subtitle.json', 'r') as f:
    data = json.load(f)

def ms_to_srt(ms):
    h, m, s, millis = ms//3600000, (ms%3600000)//60000, (ms%60000)//1000, ms%1000
    return f"{h:02d}:{m:02d}:{s:02d},{millis:03d}"

with open('/tmp/video_analysis/{VIDEO_ID}/subtitle.srt', 'w') as f:
    for i, u in enumerate(data['utterances'], 1):
        f.write(f"{i}\n{ms_to_srt(u['start_time'])} --> {ms_to_srt(u['end_time'])}\n{u['text']}\n\n")

步骤 5：AI 生成总结

直接由 Claude 完成，无需调用第三方总结 API。

读取 text.txt 后生成。

总结时应一并提供以下上下文：

• 原视频标题：如果是在线视频，优先使用平台返回的原始标题字段
  • 抖音/TikTok：优先 desc
  • 小红书：优先 title
  • B 站：优先 title
• 兜底标题：如果没有明确标题，可使用文件名或视频 ID 作为参考标识
• 字幕说明：明确告诉 Claude，正文可能来自 YouTube 字幕、自动字幕或语音识别，可能存在同音字、断句、专有名词识别错误；在不偏离原意的前提下，可以结合原视频标题和上下文做适度修正

推荐直接使用如下提示方式：

以下是一个视频的分析素材，请基于这些信息生成总结：

原视频标题：{ORIGINAL_TITLE}
来源平台：{PLATFORM}
作者：{AUTHOR}
说明：下面的正文来自平台字幕、自动字幕或语音识别，可能存在少量识别误差、断句问题或专有名词错误。请以原视频标题和上下文为参考，在不改变原意的前提下做适度修正，再完成总结。

语音识别文本：
{TEXT_CONTENT}

请输出：
1. AI生成标题：简洁概括，不超过30字；可以参考原视频标题，但不要机械照抄，必要时可根据正文纠正明显错误
2. AI摘要：提炼主要观点和关键信息，200-300字
3. 核心要点：输出3-5条结构化要点

如果原视频标题与正文明显冲突：

• 优先以正文主旨为准
• 保留“可能因语音识别存在误差”的判断，不要凭空补充未出现的信息

1. 标题：简洁概括，不超过 30 字
2. 摘要：主要观点和关键信息，200-300 字
3. 要点：核心观点的结构化列表

输出格式

## 视频分析结果

### 视频信息

| 项目 | 内容 |
| --- | --- |
| 视频ID | xxx |
| 作者 | xxx |
| 时长 | xxx |

### AI生成标题

xxx

### AI摘要

xxx

### 核心要点

1. xxx
2. xxx

### 生成文件

- 视频: /tmp/video_analysis/{ID}/video.mp4
- 音频: /tmp/video_analysis/{ID}/audio.mp3
- SRT字幕: /tmp/video_analysis/{ID}/subtitle.srt
- 纯文本: /tmp/video_analysis/{ID}/text.txt

常见问题

问题	解决方案
缺少环境变量	先确认 ASR_BACKEND；抖音/小红书/B站默认需要 AI_DOUYIN_API_KEY，自有 TikHub 模式需要 TIKHUB_TOKEN；火山后端需要 BYTEDANCE_VC_TOKEN 和 BYTEDANCE_VC_APPID
ASR_BACKEND 无效	只支持 faster-whisper 和 volcengine
faster-whisper 导入失败	执行 python3 "$SKILL_DIR/scripts/install_faster_whisper.py"，安装 helper 会先测速 PyPI 镜像并创建独立 venv；自定义 venv 时设置 FW_PYTHON=/path/to/venv/bin/python
火山 API 认证失败	Authorization 必须是 Bearer;token（分号无空格）
首次运行较慢	faster-whisper 首次会下载模型，等待下载完成后重试
CUDA 环境不可用	FW_DEVICE=auto 会自动回退到 CPU；只有 NVIDIA/CUDA 才走 GPU
视频下载失败	AI Douyin 返回 401 时检查 API Key；402 时充值积分或切换 TikHub；直链下载加 User-Agent；B 站可回退 yt-dlp
FFmpeg 找不到	macOS: brew install ffmpeg / Linux: sudo apt install ffmpeg / Windows: choco install ffmpeg
yt-dlp 找不到	macOS: brew install yt-dlp / 通用: python3 -m pip install -U yt-dlp（B 站 / YouTube 需要）