vss-summarize-video

VSS Summarize

Pipeline Manager を介して要約パイプラインを実行します。curl コマンドは自分で実行し、結果を伝えてください。エンドポイントでは nginx の /manager プレフィックスを使用します。

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

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

このスキルは、実際のソースファイルを通じて Video Search & Summarization アプリを操作するため、VSS アプリが存在し、アプリのルートディレクトリからコマンドを実行する必要があります。何よりも先に実行してください。VSS のソースがすでにワークスペースにあるかどうかにかかわらず、動作します。

同梱のブートストラップを実行します。まず、現在のディレクトリから上位へたどり、親となる git リポジトリを調べて既存の VSS チェックアウトを探します。見つかった場合は、再クローンせずに再利用します。チェックアウトが見つからない場合に限り、main から sample-applications/video-search-and-summarization のみを浅く、単一ブランチでスパースチェックアウトします。解決されたアプリのルートディレクトリを標準出力に表示します。

# SKILL_DIR is THIS skill's own directory (shown to you when the skill loads);
# in-repo it is .github/skills/vss-summarize-video. Works the same if the skill is installed standalone.
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 をオーバーライドしてください。

前提条件

1. バックエンドが正常で、要約が有効になっていること — まずプローブで確認します。正常でない場合は、vss-troubleshoot／vss-deploy を使用します。

   curl -sf "$HOST/manager/health" >/dev/null && \
   curl -s "$HOST/manager/app/features" | jq '.summary // .'   # confirm summary capability
   

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 のいずれかです。

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

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

STATE_ID=<STATE_ID>
curl -s "$HOST/manager/summary/$STATE_ID" | jq '{
  chunking: .chunkingStatus,         # string, "complete" when chunked
  frames:   .frameSummaryStatus,     # COUNTS object: {complete, inProgress, na, ready}
  video:    .videoSummaryStatus,     # string: "na" → "inProgress" → "complete"  ← real done signal
  audio:    .audioTranscriptSummaryStatus,
  summary_len: (.summary | length)
}'

⚠️ 完了の判定条件は videoSummaryStatus == "complete" です。summary が 空でないことではありません。 最終的な summary テキストは、 videoSummaryStatus がまだ "inProgress" の間に少しずつストリーミングされるため、 「summary の長さ > 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 の MapReduce 処理のため、数秒ではなく数分です）。

3. 要約を取得する

curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.summary'   # final map-reduced summary
# Per-chunk captions live in .frameSummaries[] (each: frameKey, status, summary).
# NOT in .chunks[] - those only carry {chunkId, duration, audioTranscripts}:
curl -s "$HOST/manager/summary/$STATE_ID" | jq -r '.frameSummaries[] | "[\(.frameKey)] \(.summary)"'
curl -s "$HOST/manager/summary/$STATE_ID/raw" | jq .   # everything (audio, frames, status, …)

最終的な要約テキストを提示し、必要に応じてチャンクごとの詳細も提示してください。音声に発話が含まれない場合は、その旨を示す audioTranscriptSummary が返されます。これはエラーではありません。

管理

curl -s "$HOST/manager/summary" | jq '.[] | {stateId, title}'   # list all
curl -s -X DELETE "$HOST/manager/summary/$STATE_ID"             # delete one