video-transcript

動画逐語録抽出エキスパート

動画リンクまたはローカルパスを入力 → 自動検出 → バックグラウンドでダウンロード → 分割 → 圧縮 → 豆包で文字起こし → 厳密な逐語録（stdout + ファイル保存）

フェーズ 0 · skill のルートディレクトリを特定する（最初に行うこと）

トリガーされたら、まず自分の場所を特定する必要があります。次のコマンドを実行してください。

VT_HOME="$(
  for d in "$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
)"
export VT_HOME
echo "VT_HOME=$VT_HOME"

出力が空の場合、skill のインストール先が標準以外の場所にあります。ユーザーにパスを尋ねてから、手動で export VT_HOME=<路径> を実行してください。 以後、すべてのコマンドは "$VT_HOME/scripts/transcript.py" 経由で実行し、相対パスやハードコードした絶対パスは使用しないでください。

フェーズ 1 · 意図の確認と振り分け（必ず最初に行うこと）

ダウンロード／文字起こしコマンドを実行する前に、ユーザーが何を求めているかを判断してください。

ユーザーの意図	対応
「逐語録を抽出」「テキストに変換」「動画の内容」「字幕」と明確に伝えている	この skill の文字起こしフローを続行
「ダウンロードだけ」「動画をダウンロード」「MP4 を保存」「文字起こしは不要」と明確に伝えている	transcript.py は実行せず、video-download を呼び出す
リンクだけを貼っている、「この動画を処理して」と言っている、または希望する結果が明確でない	まず「動画をダウンロードするだけですか、それとも逐語録を抽出しますか？」と尋ねる。ユーザーの確認後に実行

ダウンロードのみの場合は、video-download を特定して呼び出してください。

VD_HOME="$(
  for d in "$HOME/.agents/skills/video-download" \
           "$HOME/.Codex/skills/video-download" \
           "$HOME/.codex/skills/video-download" \
           "$HOME/.claude/skills/video-download" \
           "$(pwd)/skills/video-download"; do
    [ -f "$d/SKILL.md" ] && echo "$d" && break
  done
)"
export VD_HOME
echo "VD_HOME=$VD_HOME"
python3 "$VD_HOME/scripts/download_video.py" "<URL或本地路径>" --json

ダウンロードのみが完了したら、video-download の受け入れ基準に従って、永続保存された MP4 のパス、metadata のパス、再生時間、解像度、動画／音声コーデック、ファイルサイズを返してください。圧縮や豆包での文字起こしには進まないでください。

フェーズ 2 · 依存関係の確認（初回／問題が疑われる場合）

初回の実行時、またはエラーが発生した場合は、まず確認を行ってください。

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

✗ の項目がある場合は、ユーザーに次のように伝えてください。

• ffmpeg／playwright／chromium／API Key などが不足している → ワンクリックインストールガイドを実行：

  bash "$VT_HOME/install.sh"
  

• すべて ✓ であることを確認してから、フェーズ 3 に進みます。

フェーズ 3 · トリガー方法と実行

ユーザーが逐語録を希望すると確認したら、動画リンク（URL またはローカルパス）を受け取り、すぐに次を実行してください。

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

対応する入力：

• B 站：https://www.bilibili.com/video/BVxxx または b23.tv/xxx の短縮リンク
• 抖音：https://www.douyin.com/video/xxx、v.douyin.com/xxx、douyin.com/jingxuan?modal_id=xxx
• 小紅書：xiaohongshu.com/discovery/item/xxx、xiaohongshu.com/explore/xxx、xhslink.com/xxx
• YouTube：youtube.com/watch?v=xxx、youtu.be/xxx
• 微信視頻号：https://weixin.qq.com/sph/xxx、channels.weixin.qq.com/finder-preview/pages/sph?id=xxx
• ローカル動画ファイルのパス

スクリプトが自動で行う処理： 0. 検出 — ヘッドレスブラウザーを起動してタイトル、再生時間、動画／音声の直リンクを取得し、📊 評価表と予想所要時間を出力

1. ダウンロード — 検出時に取得した直リンクを再利用（ブラウザーは再起動しない）。B 站は DASH ストリームを使用（video/audio を個別にダウンロードし、ffmpeg で結合）。その他のプラットフォームは MP4 を直接取得
   • 微信視頻号は、最初に video-download を呼び出してローカル MP4 にダウンロードしてから、圧縮と文字起こしのフローに進みます。解析方法は video-download/.env の WECHAT_RESOLVER で決まります
2. 長尺動画の分割 — 合計再生時間が 8min を超える場合、自動的に 6min ごとに分割し、モデルによる要約を防止
3. 圧縮 — ffmpeg を使用し、目標サイズは 30MB。再生時間に応じて解像度を自動選択し、一度で完了
4. 文字起こし — 豆包動画理解 API と厳密な逐語録用プロンプトを使用（口語表現、ネットスラング、間を維持）
5. 結合 — 長尺動画の各分割分の出力を結合し、各部分の先頭のタイムスタンプのオフセットを自動調整

⚠️ あなた（agent）が必ず行うこと

（1）評価表の共有 — ユーザーに待ち時間の目安を伝える

スクリプトの起動後、stderr の最初に 📊 動画検出評価表が出力されます。必ずすぐにその内容をユーザーに伝え、次の情報を知らせてください。

• 動画のタイトル、再生時間、分割数
• 予想所要時間（ユーザーに待ち時間の目安を伝えることが最も重要です）

文字起こしが終わるまで待ってから伝えるのではなく、まず評価表を共有してから、文字起こしの完了を待ってください。再生時間や所要時間の目安が表示されないと、ユーザーはプログラムが停止したと思う可能性があります。

例：

動画の検出が完了しました：

• プラットフォーム：B 站／タイトル：《xxx》
• 再生時間は 17 分 12 秒です。独立した 3 つのパートに分けて文字起こしします
• 予想所要時間は 3 分 20 秒～5 分 25 秒です。処理中ですので、しばらくお待ちください……

（2）文字起こし完了後、逐語録全文を必ず出力する

スクリプトは最後に、完全な Markdown の逐語録を stdout に出力します。逐語録全体をそのまま会話に表示してください。「xxx.md に保存しました」とだけ伝えるのは、ユーザーに何も見せていないのと同じです。

正しい方法：

1. stdout の # <标题> 以降にある Markdown をすべて取得する
2. タイトル、再生時間、すべての段落を含め、全文をユーザーに伝える
3. 最後に、ユーザーが後から .md ファイルを開けるよう、保存先のパスを1行添える

誤った方法：

• ❌「逐語録を outputs/xxx.md に保存しました。ファイルをご確認ください」
• ❌ 最初の数段落だけを表示して、残りを省略する
• ❌ 内容を要約／短縮する（逐語録は一語一句表示する必要があります）

フェーズ 4 · 出力先

スクリプトは2か所に同時に出力します。

1. stdout に直接出力：完全な Markdown 全文 — agent がユーザーに伝えるため（フェーズ 3 の第 2 項の必須要件を参照）
2. ファイルに保存：$VT_HOME/outputs/<标题>_transcript.md — skill が管理し、すべての成果物を1か所に集約

ファイル保存を無効にする：--no-save 保存先を変更する：--output-dir <path>

評価表の例

═══════════════════════════════════════════════════════
  📊 视频探测
───────────────────────────────────────────────────────
  平台:      B 站
  标题:      在浙江和安徽之间，一座10万人的城市消失了
  时长:      17分12秒
  分段:      3 段(每段 ≤ 6 分钟)
  预估耗时:  3分20秒 ~ 5分25秒
═══════════════════════════════════════════════════════

出力形式の例

# 视频标题

> 时长 5:32 | 来源: <URL或文件名>

## 1. 引入话题 [00:00 - 00:42]
大家好,今天我们要聊的是...

## 2. 核心观点 [00:42 - 02:15]
那么我的看法是这样的,首先...

特徴：

• 意味ごとの分割：テーマに応じて自動的に 3～8 個のパートに分割し、各パートに短い小見出しを付けます
• 段落単位のタイムスタンプ：各パートの先頭に [MM:SS - MM:SS] を付け、位置を簡単に特定できます
• 逐語的な文字起こし：口語表現（「えー」「その」「あー」「つまり」）、ネットスラング、間を維持し、要約や書き換えは行いません
• 音声のないパート：_(此处无人声,XX秒)_ と記載します

フェーズ 5 · エラー処理

状況	対応
--doctor で依存関係の不足が報告される	bash "$VT_HOME/install.sh" を実行
豆包 API Key が見つかりません	$VT_HOME/.env を確認します。未設定の場合は、ユーザーに install.sh を実行して Key を入力するよう案内
API 401／「モデルが許可されていません」	火山方舟のコンソール → モデル広場 → Doubao-Seed-2.0-pro の「有効化」をクリック
抖音の画像・テキスト投稿（note リンク）	画像・テキスト投稿には対応しておらず、動画のみ対応しているとユーザーに伝える
プラットフォームのフロントエンド変更により取得に失敗	$VT_HOME/FALLBACK.md を参照して手動の代替手段を使用
微信視頻号で video-download 不足と表示される	先に video-download skill をインストールするか、video-transcript と同じ階層の skill ディレクトリに配置
微信視頻号で SPH_COOKIE/YUANBAO_COOKIE 不足と表示される	現在 WECHAT_RESOLVER=cookie が使用されています。video-download/.env に Cookie を設定するか、WECHAT_RESOLVER=public-worker に明示的に変更
長尺動画が逐語録ではなくモデルに要約される	自動処理済みです（8min 超の動画を分割）。それでも発生する場合は報告してください
圧縮後も動画が 50MB を超える	スクリプトがビットレート／解像度を自動で繰り返し下げます（最大 4 回）

視頻号の解析方法は video-download/.env で決まります。現在、公共 Worker を選択している場合は、次のように設定してください。

WECHAT_RESOLVER=public-worker

一時的に明示して上書きすることもできます。

VIDEO_DOWNLOAD_WECHAT_RESOLVER=public-worker python3 "$VT_HOME/scripts/transcript.py" "https://weixin.qq.com/sph/xxx"

コマンドラインオプション

パラメーター	説明
input	動画 URL またはローカルファイルのパス（必須。--doctor の場合は省略可能）
--title	動画タイトル（デフォルトは検出したタイトル）
--target-size	圧縮後の目標サイズ（MB）。デフォルトは 30
--no-save	.md ファイルを保存しない（デフォルトでは $VT_HOME/outputs/ に保存）
--output-dir	保存先を変更
--doctor	依存関係と設定の確認モード

Notes

• 豆包原生视频理解,模型直接听视频音频,无需独立 ASR
• 时间戳精度为段落级(不是词级/句级),用于章节定位
• 默认 stdout 直接输出 Markdown 全文(供上层 agent 展示);同时落盘
• 预估耗时模型(基于实测):headless 启动 10s + 下载(0.4s/视频秒) + 每段压缩 12s + 每段 API 30s,给 ±20% 范围
• API Key 配置存在 $VT_HOME/.env(权限 600,gitignore),不会随仓库分发