vss-manage-video-io-storage

目的

VSS の動画入出力およびストレージのワークフロー（センサー、ストリーム、アップロード、スナップショット、クリップ、タイムライン、録画ステータス）に関する VIOS と NvStreamer の API 操作を管理します。

前提条件

• $HOST_IP からアクセス可能なアクティブな VSS デプロイメント（vss-deploy-profile および references/ を参照）。
• イメージの取得に使用する $NGC_CLI_API_KEY および $NVIDIA_API_KEY の NGC 認証情報。
• 呼び出し元が利用できる curl、jq、Docker。

手順

VIOS の操作

VIOS REST API を呼び出して、カメラ／センサー、RTSP ストリーム、録画、スナップショット、ストレージを管理します。カメラの追加、RTSP ストリームの追加、センサー一覧の表示、設定済みのセンサー／カメラ／ストリームの表示、ストリームのステータス確認、スナップショットの取得、クリップのダウンロード、動画ファイルのアップロード、動画ストレージの管理を依頼された場合に使用します。curl を使って VIOS API に直接問い合わせてください。UI は操作しないでください。

アップロードの振り分けルール：

• ユーザーが「<file>.mp4 を VIOS にアップロード」「動画ファイルをアップロード」と依頼した場合、またはローカル動画を VIOS のファイルベースのセンサーとして保存することを意味する場合は、references/api-reference.md のセクション 8 に記載されている VIOS API の PUT /vst/api/v1/storage/file/{filename} を直接使用してください。
• NvStreamer は、ユーザーがライブ／合成 RTSP カメラフィードを明示的に必要としている場合、NvStreamer を指定した場合、または RTSP URL の取得を依頼した場合にのみ使用してください。
• 単純な VIOS MP4 アップロードの依頼に対し、NvStreamer へのアップロード → RTSP URL の取得 → VIOS の /sensor/add への引き渡しを代用しないでください。

このスキルを使用しないでください：

• クリップに対する VLM 推論や、その場限りの視覚的な質疑応答には vss-ask-video を使用してください。
• アーカイブ全体のセマンティック検索や、検索用の動画取り込みには vss-search-archive を使用してください。
• 録画クリップの説明的な要約には vss-summarize-video を使用してください。
• インシデント範囲またはアラート時間帯のレポートには、vss-generate-video-report の Mode B を使用してください。
• 分析指標、インシデント、アラートの参照には vss-query-analytics を使用してください。

このスキルに同梱されている参照契約

このスキルには、references/ の下に4つの参照ファイルが含まれています。目の前のタスクに該当するものを読んでください。

ファイル	目的	対象読者
references/api-reference.md	VIOS REST API の完全なリファレンス（実行時の契約）です。センサー管理、ストレージ、スナップショット、クリップ抽出、WebRTC のライブ再生／リプレイ、RTSP プロキシ、レコーダー、サービス設定、サービスディスカバリーを扱います。VIOS API 操作を実行する際は、これを読んでください。	運用ユーザーおよびこのスキル自体
references/nvstreamer-api-reference.md	NvStreamer REST API のリファレンスです。バージョン、センサーの一覧／情報／ステータス／ストリーム、3つのアップロード方法（PUT v2／PUT v1／POST multipart）と nvstreamer-* カスタムヘッダー、削除、スナップショット（ライブ映像はフレームインデックス指定、ストレージはタイムスタンプ指定）、ストレージ情報、ファイルシステムスキャンを扱います。NvStreamer（vss-vios-nvstreamer、launch_vst の streamer-adaptor バリアント）は、VIOS を起動するものと同じプロファイル（dev-profile-alerts、dev-profile-lvs、dev-profile-search、すべての warehouse プロファイル）によって起動されます。デプロイ側については、integrate-vios-service.md § Topology B を参照してください。テスト用／サンプル動画を合成 RTSP として提供する場合、ファイルに対して NvStreamer が生成した RTSP URL を取得する場合、または標準的な NvStreamer → VIOS のハンドオフを実行する場合（NvStreamer にアップロード → RTSP URL を読み取る → /sensor/add 経由でその URL を VIOS に登録）に読んでください。	運用ユーザー、およびアップロード → RTSP URL → VIOS /sensor/add のフローを構成するスキル作成者
references/integrate-vios-service.md	統合契約です。VIOS を他の VSS マイクロサービスに接続する方法を説明します。必要なピアサービス（RT-VLM、ELK、Kafka、Redis、sdr-controller／SDRC）、vss-build-vision-agent スキルのステップ4で使用される構造化された component_services: ブロック、統合の入力／出力（Kafka トピック、REST エンドポイント、ファイルパス）、環境変数、ネットワーク要件、既知の統合上の制約（例：/url バリアントで http:// が二重になるバグ、VIOS と SDRC のパッチ適用要件）を記載しています。VIOS をピアとして扱うスキルを作成する場合、新しい VSS デプロイを構成する場合、またはキャプションパイプラインの接続をデバッグする場合に読んでください。	スキル作成者、デプロイ構成担当者、ペアファイル保守担当者
references/deploy-vios-service.md	デプロイ契約です。VIOS の起動に必要な要件を説明します。コンテナイメージとタグ（nvcr.io/nvidia/vss-core/vss-vios-*:3.2.0）、GPU／CPU／メモリ／ストレージ要件、起動時の動作とヘルスチェックの調整、必要な環境変数（特に、アップロードの可否を左右する libav の apt インストール手順に必要な VST_INSTALL_ADDITIONAL_PACKAGES=true）、既知のデプロイ上の問題（ボリュームのずれ、libav の欠落、残存コンテナによる502エラー）、前提条件、ドライラン、デプロイの検証、削除の各コマンドを記載しています。VIOS が実行されておらず、単独でデプロイする必要がある場合（または呼び出し元が必要とする場合）、コンテナ起動時の失敗をデバッグする場合、VIOS をラップするデプロイスキルを作成する場合に読んでください。	オペレーター、デプロイスキル作成者

デプロイの前提条件 — VIOS が稼働している必要があります

このスキルは主に API クライアントであり、VIOS がすでに起動し、VST のイングレス（デフォルトは http://${HOST_IP}:30888）で到達可能であることを前提としています。このスキル自体は VIOS をデプロイしませんが、VIOS に接続できない場合は、同梱のデプロイ手順書（references/deploy-vios-service.md）を使用してデプロイを調整するか、フルスタックの /vss-deploy-profile スキルに引き継ぎます。作業を始める前に、次の手順を実行してください。

1. VIOS の接続を確認します：

   curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/version" >/dev/null
   

2. 接続確認に失敗した場合、VIOS はデプロイされていません。 次の2つの方法を提示してください。

   "http://${HOST_IP}:30888 で VIOS に接続できません — 現在稼働中のデプロイはありません。次の2つの方法があります： (a) このスキルに同梱の references/deploy-vios-service.md 手順書に従って、VIOS を単独で起動します — イメージタグ、環境変数（特に VST_INSTALL_ADDITIONAL_PACKAGES=true）、ホストディレクトリ、NGC ログイン、起動コマンド、ヘルスチェックのループ、既知のデプロイに関する問題がすべて記載されています。VIOS のみが必要な場合（RT-VLM／ELK などは不要な場合）、またはカスタムプロファイルを構成する場合に適した方法です。 (b) /vss-deploy-profile スキルを使って、VIOS を含むフル VSS プロファイルをデプロイします — base（推奨）、lvs、search、alerts のいずれも、他のコンポーネントとともに VIOS を起動します。完全な VSS スタックが必要な場合に適した方法です。 どちらを希望しますか？"

   • ユーザーが (a) を選んだ場合 → references/deploy-vios-service.md に従って、手順を一つずつ案内します。特に § Environment Variables — Required for Upload-to-Caption Path と § Known Deployment Issues のセクションに注意してください。libav が見つからないエラー（VST_INSTALL_ADDITIONAL_PACKAGES=true）と、ボリュームの不整合によるハング（先に docker compose up --yes または docker volume rm を実行）が、起動を妨げる最も一般的な2つの問題です。デプロイが成功し、手順1の接続確認に合格したら、ここに戻ります。
   • ユーザーが (b) を選んだ場合 → /vss-deploy-profile -p <profile>（デフォルトは base）に引き継ぎます。成功したら、ここに戻ります。
   • ユーザーがどちらも辞退した場合 → 停止します。VIOS の操作には VST バックエンドが稼働している必要があります。応答を捏造したり、機能を制限したモードで処理を続行したりしないでください。

   事前承認済みの自律モード： 呼び出し元から前提条件のデプロイについて明示的な事前承認を得ている場合（たとえば、リクエストに「前提条件のデプロイを事前承認済み」と記載されている場合や、その権限を持つ非対話型の評価ハーネスで実行している場合）は、確認を省略し、方法 (a) を優先してください — このスキルに同梱の references/deploy-vios-service.md を使って VIOS を単独で起動します。ただし、リクエストでフル VSS プロファイルが明示的に指定されている場合は、/vss-deploy-profile -p base を呼び出してください。

3. 接続確認に合格した場合は、続行します。 VIOS は稼働中です。以下のすべての操作を安全に実行できます。

---

既知の制限事項 — 過去のデプロイで残ったコンテナ

以前のデプロイの停止後も *-smc VST コンテナが残り、:30000／:30888 で network_mode: host のポートバインド競合に勝った場合、GET /vst/api/v1/sensor/list と GET /vst/api/v1/sensor/<sensorId>/streams は、HTTP 502 Bad Gateway を返すか、古い結果を返すことがあります。対処方法： /vss-deploy-profile を再実行してください — その Step 0 の停止処理にある grep で、sensor-ms-*／vst-ingress-*／sdr-*／sdrc-*／rtspserver-ms-* の一式が削除されます。 その他の経路（storage/file/* によるアップロード、*/picture/url によるスナップショット、*/url によるクリップ抽出）には影響しません。障害モードの全一覧、対処方法、現在のルーティング仕様（直接接続と SDRC の使い分け。PR #711 で SDR／Envoy は削除済み）については、references/deploy-vios-service.md § Known Deployment Issues およびissue #151を参照してください。

---

セットアップ

ベース URL： http://<VST_ENDPOINT>/vst/api/v1

エンドポイントの解決：

• アクティブな VSS デプロイメントに関連付けられた VIOS エンドポイントを使用します。このエンドポイントは、VSS エージェントの実行コンテキストから到達可能な VST バックエンドを示します。
• シェルコマンド、ファイルシステムへのアクセス、静的な設定ファイルを使って、ホスト、IP、ポートを特定しようとしないでください。
• VSS デプロイメントのコンテキストから、VST の正しいネットワークエンドポイントがすでに提供されていることを前提とします。

可用性チェック：

• API を呼び出す前に、VSS デプロイメントのエンドポイントを介して VST バックエンドに到達可能か確認します。

  curl -sf --connect-timeout 5 http://<VST_ENDPOINT>/vst/api/v1/sensor/version
  

• バックエンドが利用できない場合（終了コードがゼロ以外、または接続エラー）、適切に処理し、エラーをユーザーに報告します。デプロイするか停止するかの分岐については、上記のデプロイの前提条件セクションを参照してください。

フォールバック：

• コンテキストからエンドポイント情報を取得できない場合は、VST エンドポイント（ホスト/IP とポート）をユーザーに明示的に尋ねます。

すべての curl コマンドは自分で実行してください — ユーザーに手動でコマンドを実行するよう指示しないでください。

認証： 任意です。ほとんどのデプロイメントでは認証なしで動作します。401 が返された場合は、-H "Authorization: Bearer <token>" を付けて再試行し、トークンをユーザーに尋ねます。

開始時刻／終了時刻の処理： startTime／endTime を必要とする API について：

• ユーザーが値を指定した場合は、その値をそのまま使用します。
• ユーザーが指定していない場合は、まず該当するストリームのタイムラインを取得して、記録済みの有効な範囲を確認してから、API 呼び出し前にレスポンスから適切な値を選びます。タイムスタンプを捏造しないでください。

sensorId／streamId の解決： ユーザーが sensorId または streamId を指定していない場合は、次のいずれかを使って自動的に調べます。

• GET /sensor/list — すべてのセンサーとその sensorId を一覧表示します
• GET /sensor/{sensorId}/streams — 特定のセンサーのストリームとその streamId を一覧表示します
• GET /sensor/streams — すべてのセンサーの全ストリームを一覧表示します
• GET /live/streams — アクティブなすべてのライブストリームを一覧表示します
• GET /replay/streams — 利用可能なすべてのリプレイストリームを一覧表示します

センサーにストリームが 1 つしかない場合、sensorId と streamId は同じ値であり、相互に置き換えて使用できます。

---

サービスマップ

機能	URL プレフィックス	正式な参照先
バージョン／ヘルスチェック	/vst/api/v1/sensor/version	references/api-reference.md
センサー一覧／情報／ステータス／追加／削除	/vst/api/v1/sensor/	references/api-reference.md
センサーのストリーム	/vst/api/v1/sensor/streams, /vst/api/v1/sensor/{id}/streams	references/api-reference.md
ネットワークスキャン	/vst/api/v1/sensor/scan	references/api-reference.md
録画タイムライン	/vst/api/v1/storage/	references/api-reference.md
ビデオクリップのダウンロード／URL	/vst/api/v1/storage/	references/api-reference.md（操作）+ references/integrate-vios-service.md § Known Integration Constraints（Finding 8：/url の http:// 二重付加バグ — バイナリの直接エンドポイントを優先）
ファイルのアップロード／削除	/vst/api/v1/storage/	references/api-reference.md（PUT v2 とレガシー v1 エンドポイント）+ references/deploy-vios-service.md § Known Deployment Issues（Finding 9：libav がない場合の障害モード）
ライブストリーム／スナップショット（画像）	/vst/api/v1/live/	references/api-reference.md
リプレイストリーム／過去のスナップショット	/vst/api/v1/replay/	references/api-reference.md（操作）+ references/integrate-vios-service.md § Known Integration Constraints（Finding 8）
NvStreamer：ファイルから RTSP への再配信（アップロード、生成された RTSP URL の取得、ファイルシステムスキャン、フレームスナップショット）	http://${HOST_IP}:${NVSTREAMER_HTTP_PORT:-31000}/vst/api/v1/	references/nvstreamer-api-reference.md（ストリーマーのエンドポイントは VIOS ゲートウェイとは別です — ポートが異なり、/version では type: "streamer" が返されます）

---

操作

センサー管理、ストレージ、スナップショット、クリップ抽出、WebRTC のライブ／リプレイ、RTSP プロキシ、レコーダー、サービス設定、サービスディスカバリーを含む、VIOS REST API の完全なリファレンスは references/api-reference.md にあります。操作を実行する際は、このファイルを参照してください。

ディスク上の動画ファイルを合成 RTSP カメラとして配信するリクエスト（サンプルを NvStreamer にアップロードし、自動生成された RTSP URL を取得して、その URL を VIOS に登録する）では、NvStreamer エンドポイントを参照し、references/nvstreamer-api-reference.md に従ってください。NvStreamer は、これを同梱する VIOS 利用プロファイルとともに自動的に起動します。個別にデプロイする必要はありません。

VIOS と他のマイクロサービスとの連携方法や、VIOS の起動方法に関する統合時およびデプロイ時の質問については、それぞれ references/integrate-vios-service.md および references/deploy-vios-service.md を参照してください（各ファイルの内容については、上記の リファレンスの範囲 テーブルを参照してください）。

---

ワークフロー：センサー名／IP -> クリップまたはスナップショット

ユーザーがセンサー名または IP を指定しており、クリップまたはスナップショットが必要な場合：

0. VST に接続できることを確認します（セットアップ — 可用性チェックを参照）：

   curl -sf --connect-timeout 5 "http://<VST_ENDPOINT>/vst/api/v1/sensor/version"
   

1. センサーを一覧表示して sensorId を確認します：

   curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/list" | jq .
   

2. そのセンサーのストリームを取得して streamId を確認します（isMain: true を優先）：

   curl -s "http://<VST_ENDPOINT>/vst/api/v1/sensor/<sensorId>/streams" | jq .
   

3. タイムラインを確認し、指定された範囲に録画があることを確認します：

   curl -s "http://<VST_ENDPOINT>/vst/api/v1/storage/<streamId>/timelines" | jq .
   

4. streamId を使ってクリップまたはスナップショットをダウンロードします。/url の JSON エンベロープ形式のバリアントよりも、バイナリ直接エンドポイント（/storage/file/<streamId>?startTime=...&endTime=...、/replay/stream/<streamId>/picture?startTime=...、/storage/stream/<streamId>/picture?startTime=...）を優先してください。/url バリアントは 3.2.0 で http:// が二重に付いた URL を返し、クライアント側での除去が必要です。詳細は references/integrate-vios-service.md § Known Integration Constraints Finding 8 を参照してください。

---

レスポンス

データありの成功： JSON オブジェクトまたは配列です。

データなしの成功： null — null レスポンスは、API 呼び出しが成功したものの、返すデータがないことを意味します（例：スケジュールが設定されていない、スキャンで結果が見つからなかった）。エラーではありません。

ブール値による成功： 一部のエンドポイントは、成功時に true を返します（例：DELETE /sensor/{sensorId}）。

エラー： error_code と error_message を含む JSON オブジェクトです：

{
  "error_code": "VMSInternalError",
  "error_message": "VMS internal processing error"
}

一般的なコード：VMSInternalError、VMSNotFound、VMSInvalidParameter。

PUT アップロード時に InvalidParameterError: Failed to get media information が表示された場合、これは libav がない場合の失敗です。VIOS が VST_INSTALL_ADDITIONAL_PACKAGES=true なしでデプロイされています。修正方法については、references/deploy-vios-service.md § Known Deployment Issues Finding 9 を参照してください。

/url バリアントのレスポンスにある imageUrl または videoUrl フィールドで、http:// が二重に付いたプレフィックスが見られる場合、これは Finding 8 に該当します。クライアント側で先頭の http:// を除去するか、バイナリ直接エンドポイントに切り替えてください。

---

例

操作プロンプトの例：

• 「アクティブな VIOS センサーを一覧表示して、ストリームの状態を表示してください。」
• 「このサンプル動画を VIOS にアップロードして、生成されたストリーム ID を返してください。」
• 「このセンサーの録画タイムラインから 2 秒間のクリップをダウンロードしてください。」
• 「NvStreamer を使ってファイルをアップロードし、生成された RTSP URL を取得してください。」

制限事項

• VIOS の操作には、接続可能な VST バックエンドが必要です。ヘルスプローブに失敗する場合は、前提条件となるサービスを停止するか、デプロイしてください。
• ほとんどのデプロイでは認証は不要ですが、外部の認証レイヤーを追加することもできます。
• 例に記載されているコンテナー側のパスでは、コンテナー内の VST インストールルートを示す中立的なプレースホルダーとして ${VST_CONTAINER_ROOT} を使っています。パスの例を使う前に、アクティブなデプロイから実際のパスを確認してください。
• API キー、ベアラートークン、生成された認証情報をログや最終応答に出力しないでください。

トラブルシューティング

• エラー：ヘルスプローブに失敗します。原因：VIOS がデプロイされていないか、エンドポイントが間違っています。解決策：デプロイの前提条件に関する手順に従うか、正しい VST エンドポイントを確認してください。
• エラー：アップロードが Failed to get media information で失敗します。原因：VIOS コンテナに libav パッケージがインストールされていません。解決策：VST_INSTALL_ADDITIONAL_PACKAGES=true を設定し、再デプロイしてください。
• エラー：/url のレスポンスに http://http://... が含まれます。原因：既知の URL 構築不具合です。解決策：バイナリの直接エンドポイントを使用するか、重複したプレフィックスを削除してください。

---

ヒント

• **jq：**すべての JSON レスポンスは、読みやすくするために jq . にパイプされます。バイナリレスポンス（クリップのダウンロード、スナップショット）は対象外で、代わりに -o <file> を使用します。
• **時刻の形式：**常に ISO 8601 UTC を使用します。例：2026-04-10T10:30:00Z または 2026-04-10T10:30:00.000Z。
• **streamId ヘッダー：**ライブ／リプレイ／レコーダーのエンドポイントでは、パスパラメーターとリクエストヘッダーの両方に streamId が必要です。両方を指定してください。
• **大きなクリップ：**直接ストリーミングするには、バイナリの直接エンドポイント /storage/file/<id>?...&container=mp4 を -o clip.mp4 とともに使用してください。/url のエンベロープ形式には Finding 8 の二重 http:// 不具合があるため、上流で修正されるまでは避けるか、クライアント側でプレフィックスを削除してください。
• センサーとストリーム ID：sensorId はカメラを識別し、streamId はそのカメラの特定のビデオストリームを識別します（センサーにはメインストリームとサブストリームがある場合があります）。
• センサーの種類（RTSP 対アップロードファイル）の識別：GET /sensor/<sensorId>/streams を呼び出し、各ストリームの url フィールドを確認してください。url が rtsp:// で始まる場合、ライブ RTSP/IP カメラストリームです。url がファイルパス（例："${VST_CONTAINER_ROOT}/streamer_videos/TruckAccident.mp4"）の場合、アップロードファイルのセンサーです。これにより使用する削除手順が決まります。セクション 8 を参照してください。
• 録画タイムラインではアップロード時刻が反映されます：PUT /vst/api/v1/storage/file/<filename>?timestamp=<iso> でファイルをアップロードすると、GET /storage/<streamId>/timelines が返すタイムラインの基準は、アップロード時の実時刻ではなく、指定されたタイムスタンプになります。その後のスナップショット／クリップのクエリでは、この範囲内のタイムスタンプを必ず使用してください。まずタイムラインを取得してください。正式な仕様については、references/api-reference.md § 8 および references/integrate-vios-service.md § Integration Interfaces > Inputs > Upload video file を参照してください。
• **エンドポイントの解決：**VST エンドポイントは VSS のデプロイコンテキストから提供されます。IP／ポートを手動で特定しようとしないでください。利用できない場合は、ユーザーに確認してください。すべての curl の例では <VST_ENDPOINT> をプレースホルダーとして使用しています。実行前に、解決したエンドポイントに置き換えてください。