VSS 動画要約

VSS 要約 (VSS Summarize)

Pipeline Manager を介して要約パイプラインを実行します。ドキュメント化された API を自身で呼び出し、観測された応答のみを報告してください。エンドポイントは nginx の /manager プレフィックスを使用します。vss_* MCP ツールが接続されている場合、vss_summarize_video が同じ処理をカバーします。このスキルは REST ルートです。

HOST=http://${HOST_IP:-localhost}:${APP_HOST_PORT:-12345} を設定します。

VSS に到達できない場合の回答契約

ユーザーがデプロイメント環境から離れている、$HOST への接続が拒否される、またはライブ前提条件が失敗する（例：要約モードが無効、指定された動画が存在しない）場合があります。そのような場合でも、処理を停止したり、応答をでっち上げたりしないでください。 観測されたブロッカーを報告し、その後にユーザーが問題を修正して実行できる完全かつ正確な呼び出しシーケンス（完全なエンドポイントパス、リクエスト本文/フォームフィールド、各ステップで前の応答から引き継がれるフィールド、およびステップが完了したことを示す条件）を回答してください。要約フローが実行できなかったという理由だけで、要求されたフローを省略したり短縮したりしないでください。どのコマンドが実行されなかったかを明確に述べてください。回答を「実行しますか？」という問いかけで終わらせないでください。

環境セットアップ（最初に実行）

このスキルは、Video Search & Summarization アプリケーションを実際のソースファイルから操作するため、VSS アプリケーションが存在し、そのアプリケーションルートからコマンドを実行する必要があります。他のすべての前にこれを行ってください。 VSS ソースが既にワークスペースにあるかどうかに関係なく動作します。

バンドルされたブートストラップを実行します。ブートストラップは次の順序でアプリケーションルートを解決し、stdout にそのパスのみを出力します。

1. 現在のディレクトリから上方向に VSS アプリケーションルート（setup.sh、docker/、pipeline-manager/ の3つのマーカーファイルがすべて存在するディレクトリ）を探します。
2. git に問い合わせてリポジトリルート を取得し (git rev-parse --show-toplevel)、それが sample-applications/video-search-and-summarization を含むか、またはそれ自体が VSS アプリケーションルートであるかを確認します。これにより、ユーザー自身のクローンまたはフォークがそのまま動作します。
3. 以前のブートストラップが既に配置したチェックアウト を ${XDG_CACHE_HOME:-$HOME/.cache}/vss-src/edge-ai-libraries で再利用します。

これらのいずれかがヒットした場合、そのチェックアウトは再利用され、クローンは実行されません。3つすべてが失敗した場合のみ、クローンが実行されます。その場合も、sample-applications/video-search-and-summarization のみのshallow (--depth 1)、シングルブランチ、スパースチェックアウトが main から行われます。

# SKILL_DIR はこのスキル自身のディレクトリです（スキル読み込み時に表示されます）。
# リポジトリ内では .github/skills/vss-summarize-video です。
# スキルがスタンドアロンでインストールされていても同様に動作します。
SKILL_DIR=".github/skills/vss-summarize-video"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

以下のすべてのコマンドは、カレントワーキングディレクトリがこの APP_ROOT であることを前提としています。フォーク/ブランチからプルする場合や特定のチェックアウトディレクトリを再利用する場合は、実行前に VSS_REPO_URL、VSS_REPO_BRANCH、または VSS_CLONE_DIR を上書きしてください。ブートストラップは、VSS ではない既存のクローン先を上書きすることを拒否します。

前提条件

1. バックエンドが正常で要約が有効であること - まずプローブします。そうでない場合は、インストールされている vss-troubleshoot または vss-deploy スキルを名前で使用します。

   curl -sf "$HOST/manager/health" >/dev/null && \
   curl -s "$HOST/manager/app/features" | jq -e '(.summary // .) == "FEATURE_ON"'
   

2. 要約する videoId - POST /manager/videos (マルチパート、フィールド video) でアップロードします。応答は { "videoId": "…" } を返します。または、既存のものを一覧表示します - 応答はオブジェクト { "videos": [...] } であり、裸の配列ではありません。また、name は生成されたハッシュです（実際のファイル名は url / dataStore.fileName にあります）。

   curl -s -X POST "$HOST/manager/videos" -F "video=@/path/to/clip.mp4" | jq .
   curl -s "$HOST/manager/videos" | jq '.videos[] | {videoId, file: .dataStore.fileName}'
   

1. 要約パイプラインを開始する

POST /manager/summary。本文には必須フィールドがあります。title、sampling.*、または evam.evamPipeline のいずれかが欠けていると、400 が返されます。完全なスキーマ、プロンプトオーバーライド、およびオーディオオプションについては、references/summary-request.md を参照してください。

最小限の有効なリクエスト:

curl -s -X POST "$HOST/manager/summary" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Loading dock review",
    "videoId": "<VIDEO_ID>",
    "sampling": { "chunkDuration": 20, "samplingFrame": 5, "frameOverlap": 0, "multiFrame": 5 },
    "evam": { "evamPipeline": "object_detection" },
    "produceFinalSummary": true
  }' | jq .
# → { "summaryPipelineId": "<STATE_ID>" }

サンプリング制約: Pipeline Manager は multiFrame == frameOverlap + samplingFrame を強制します。frameOverlap: 0 の場合、multiFrame == samplingFrame に設定します。不一致があると 400 "Multi frame mismatch" が返ります。 evamPipeline は object_detection | video_ingestion のいずれかです。

クリップの一部だけを要約するには、オプションの sampling.videoStart および sampling.videoEnd (秒) を追加します。例：最初の10分間の場合は "videoStart": 0, "videoEnd": 600。

2. 完了するまでポーリングする

返された summaryPipelineId が stateId です。GET /manager/summary/{stateId} にはトップレベルの status/progress フィールドはありません（/raw のみにあります）。進捗状況はステージごとのフィールドにあります。

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # 文字列、チャンク化完了時は "complete"
  frames:   .frameSummaryStatus,     # COUNTS オブジェクト: {complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # 文字列: "na" → "inProgress" → "complete"  ← 実際の完了シグナル
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ 完了は videoSummaryStatus == "complete" であり、summary が空でないことではありません。 最終的な summary テキストは、videoSummaryStatus がまだ "inProgress" の間にインクリメンタルにストリーミングされるため、"summary length > 0" でポーリングすると途中で切り詰められた要約が返されます。常に videoSummaryStatus でゲートしてください。produceFinalSummary: false の場合、最終ステージはありません。代わりに frameSummaryStatus.inProgress == 0 でゲートしてください。

until curl -s "$HOST/manager/summary/$STATE_ID" \
       | jq -e '.videoSummaryStatus == "complete"' >/dev/null; do sleep 10; done

要約は遅いです（チャンクごとの VLM + LLM マップリデュース）- 秒単位ではなく分単位です。

3. 要約を取得する

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # 最終的なマップリデュース要約
# チャンクごとのキャプションは .frameSummaries[] にあります (各: frameKey, status, summary)。
# .chunks[] にはありません - そこには {chunkId, duration, audioTranscripts} のみが含まれます。
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[{\(.frameKey)}] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # すべて (オーディオ、フレーム、ステータス、…)

最終的な要約テキストを提示し、必要に応じてチャンクごとの詳細も提供します。音声がないオーディオは、audioTranscriptSummary にその旨が示されます - エラーではありません。

最終回答の監査証跡

ツールの引数はユーザーや評価者に見えない場合があります。したがって、最終回答はブートストラップの結果（解決された APP_ROOT、既存のチェックアウトがクローンなしで再利用されたかどうか、そのアプリケーションルートに移動してコマンドが実行されたこと）を報告する必要があります。また、ブートストラップが完全に失敗した場合は、main から VSS アプリのみの shallow (--depth 1)、シングルブランチ、スパースチェックアウトにフォールバックすることも記載します。観測された /manager/health と要約機能の値を報告します。

要約ワークフローについては、使用されたすべてのパブリック Manager 操作（メソッドと /manager/... パス）、重要なリクエストフィールド、観測された応答、および summaryPipelineId から STATE_ID への引き継ぎを明記します。前提条件によって実行がブロックされた場合は、観測されたプローブと未実行のコマンドを明確に区別し、ID や要約内容をでっち上げずに、正確な有効なリクエスト、完了条件、および取得ステップを引き続き示します。

管理

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # すべて一覧表示
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # 1つ削除