vss-manage-video-io-storage

## Purpose Manage VIOS and NvStreamer API operations for VSS video input/output and storage workflows: sensors, streams, uploads, snapshots, clips, timelines, and recording status. ## Prerequisites - Active VSS deployment reachable through `VSS_PUBLIC_URL` (Kubernetes Ingress) or `$HOST_IP` (Docker Compose). - NGC credentials in `$NGC_CLI_API_KEY` and `$NVIDIA_API_KEY` for any image pulls. - `curl` and `jq`; Docker is needed only for Compose deployment diagnostics. ## Instructions # VIOS Operations Call the VIOS REST API to manage cameras/sensors, RTSP streams, recordings, snapshots, and storage. Use when asked to: add a camera, add an RTSP stream, list sensors, show configured sensors/cameras/streams, check stream status, get a snapshot, download a clip, upload a video file, or manage video storage. Query the VIOS API directly using curl — do not navigate the UI. **Upload routing rule:** - If the user asks to "upload `<file>.mp4` to VIOS", "upload a video file", or otherwise means storing a local video as a VIOS file-backed sensor, use the direct VIOS API: `PUT /vst/api/v1/storage/file/{filename}` from [`references/api-reference.md`](references/api-reference.md) Section 8. - Use NvStreamer only when the user explicitly needs a live/synthetic RTSP camera feed, asks for NvStreamer, or asks to retrieve an RTSP URL. - Do not substitute the NvStreamer upload -> RTSP URL -> VIOS `/sensor/add` handoff for a plain VIOS MP4 upload request. **Provisioning + fan-out routing rule:** - To register a source and fan it into the perception consumers a build deployed (RT-CV / RT-Embed / RT-VLM) when **no agent tier is present** — e.g. a `vss-build-vision-ai` headless `_builds/<name>` deployment — follow [`references/provision-vios-source.md`](references/provision-vios-source.md) (headless, direct REST; endpoint-parameterized). The recipe fans a source out to RT-CV (detection), RT-Embed (embeddings), and RT-VLM; RT-VLM carries **two independent legs** — dense captioning (free-form prompt) and **VLM tagging** (a controlled JSON-tag prompt that feeds BM25 tag search via `mdx-vlm-captions` → Logstash → `default_<streamId>`). Tagging is provisioned for search builds and is independent of the Alert-Bridge carve-out that governs the dense-captioning leg. - If an agent `/api` tier **is** present, provisioning is agent-owned: defer to `vss-search-archive` (search ingestion) or `vss-manage-alerts` (alert rules), not this recipe. **Do NOT use this skill for:** - VLM inference or ad-hoc visual Q&A about a clip — use `vss-ask-video`. - Semantic search across the archive — use `vss-search-archive`. - **Agent-backed** ingestion for search (full-stack, `/api` agent tier present) — use `vss-search-archive`. (Headless, no-agent provisioning *is* this skill — see the routing rule above.) - Narrative summaries of a recorded clip — use `vss-summarize-video`. - Incident-range or alert-window reports — use `vss-generate-video-report` Mode B. - Reading analytics metrics, incidents, or alerts — use `vss-query-analytics`. ## Reference contracts shipped with this skill This skill bundles five reference files under `references/`. Read whichever applies to the task in front of you: | File | Purpose | Audience | | --- | --- | --- | | [`references/api-reference.md`](references/api-reference.md) | The full VIOS REST API reference (the runtime contract) — sensor management, storage, snapshots, clip extraction, WebRTC live/replay, RTSP proxy, recorder, service configuration, service discovery. **Read this when invoking any VIOS API operation.** | Operational users + this skill itself | | [`references/provision-vios-source.md`](references/provision-vios-source.md) | The **headless (no-agent) write path** — register one VIOS source and fan it out by direct REST to only the consumers a build resolved (RT-CV / RT-Embed / RT-VLM), driven from the retried VIOS live-proxy URL; carries the upload `creation_time` rule, idempotency, and teardown, and defers exact consumer payloads to the deploy-* owner skills. Endpoint-parameterized: the caller injects the loopback consumer URLs. **Read this when provisioning a source into a headless build, or fanning an already-registered source into its perception consumers.** | Runtime operators, `vss-build-vision-ai` callers | | [`references/nvstreamer-api-reference.md`](references/nvstreamer-api-reference.md) | The **NvStreamer REST API reference** — version, sensor list/info/status/streams, the three upload methods (PUT v2 / PUT v1 / POST multipart) with the `nvstreamer-*` custom headers, delete, snapshots (frame-indexed live, timestamp-indexed storage), storage info, filesystem scan. NvStreamer (`vss-vios-nvstreamer`, the streamer-adaptor variant of `launch_vst`) is **brought up by the same profiles that bring VIOS up** — `dev-profile-alerts`, `dev-profile-lvs`, `dev-profile-search`, all warehouse profiles. See `integrate-vios-service.md § Topology B` for the deployment side. **Read this when serving test / sample videos as synthetic RTSP, retrieving the RTSP URL NvStreamer generated for a file, or driving the canonical NvStreamer → VIOS handoff** (upload to NvStreamer → read RTSP URL → register that URL with VIOS via `/sensor/add`). | Operational users + skill authors composing the upload → RTSP URL → VIOS `/sensor/add` flow | | [`references/integrate-vios-service.md`](references/integrate-vios-service.md) | The **integration contract** — how VIOS plugs into other VSS microservices. Documents required peer services (RT-VLM, ELK, Kafka, Redis; `sdr-controller` / SDRC **when `VST_USE_SDRC=true`**), the structured `component_services:` block consumed by the `vss-build-vision-ai` skill's Step 4, integration inputs/outputs (Kafka topics, REST endpoints, file paths), environment variables, network requirements, and known integration constraints (e.g. the `/url`-variant double-`http://` bug, the VIOS + SDRC co-enablement rule for SDRC-routed profiles). **Read this when authoring a skill that talks to VIOS as a peer, when composing a new VSS deployment, or when debugging caption-pipeline wiring.** | Skill authors, deployment composers, pair-file maintainers | | [`references/deploy-vios-service.md`](references/deploy-vios-service.md) | The **deployment contract** — what it takes to bring VIOS up. Documents container images and tags (VIOS core under `nvcr.io/nvidia/vss-core/vss-vios-*`; **SDRC `sdr-mw-l` from [`sdrc/docker-compose.yaml`](../../../deploy/docker/services/infra/sdrc/docker-compose.yaml) `SDR_MW_L_IMAGE` — resolve there before pull/deploy**), GPU / CPU / memory / storage requirements, startup behavior + healthcheck tuning, required environment variables (notably `VST_INSTALL_ADDITIONAL_PACKAGES=true` for the libav apt-install step that gates uploads), known deployment issues (volume drift, libav missing, 502 from leftover containers), prerequisites, dry-run, verify-deployment, and tear-down commands. **Read this when VIOS isn't running and you (or your caller) need to deploy it standalone, when debugging container-startup failures, or when authoring a deploy skill that wraps VIOS.** | Operators, deploy-skill authors | ## Deployment prerequisite — VIOS MUST be running This skill is primarily an API client and assumes VIOS is already up and reachable at the VST ingress. Resolve endpoints once before doing any work. Follow the shared public-Ingress contract in [`../vss-build-vision-ai/references/deployment_resolution.md`](../../vss-build-vision-ai/references/deployment_resolution.md) (`VSS_PUBLIC_URL`, `VSS_VIOS_URL`, `VST_API_BASE`, `VSS_STREAMER_URL`). ```bash if [ -n "${VSS_PUBLIC_URL:-}" ]; then VSS_PUBLIC_URL="${VSS_PUBLIC_URL%/}" VSS_VIOS_URL="${VSS_PUBLIC_URL}/vst" elif [ -n "${HOST_IP:-}" ]; then VSS_VIOS_URL="http://${HOST_IP}:30888/vst" else echo "Provide VSS_PUBLIC_URL for Kubernetes or HOST_IP for Docker Compose." >&2 exit 1 fi VST_API_BASE="${VSS_VIOS_URL}/api/v1" ``` For Kubernetes, do not use `kubectl port-forward`, an in-cluster Service name, a NodePort, or a guessed Helm release name. This skill does not deploy VIOS itself, but when VIOS is unreachable it coordinates a deploy using its bundled deployment runbook ([`references/deploy-vios-service.md`](references/deploy-vios-service.md)) or hands off to the full-stack `/vss-build-vision-ai` skill. Before doing any work: 1. **Probe VIOS:** ```bash curl -sf --max-time 5 "${VSS_VIOS_URL}/api/v1/sensor/version" >/dev/null ``` 2. **If the probe fails, VIOS is not deployed.** Offer the standalone path: > *"VIOS is not reachable at `${VSS_VIOS_URL}` — no deployment is currently up.* > *(a) Bring up VIOS standalone using this skill's bundled [`references/deploy-vios-service.md`](references/deploy-vios-service.md) runbook — image tags, env vars (notably `VST_INSTALL_ADDITIONAL_PACKAGES=true`), host directories, NGC login, bring-up command, healthcheck loop, and known deployment issues are all documented there. This is the right path if you only need VIOS itself (no RT-VLM / ELK / etc.) or if you're composing a custom profile.* > *(b) Deploy a full VSS profile that includes VIOS via the `/vss-build-vision-ai` skill — `base` (recommended), `lvs`, `search`, or `alerts` all bring VIOS up alongside other components. This is the right path if you want a complete VSS stack.* > *Which would you like?"* - If the user picks (a) → walk them through `references/deploy-vios-service.md` step by step. Pay particular attention to its `§ Environment Variables — Required for Upload-to-Caption Path` and `§ Known Deployment Issues` sections — the libav-missing failure (`VST_INSTALL_ADDITIONAL_PACKAGES=true`) and the volume-drift hang (`docker compose up --yes` or `docker volume rm` first) are the two most common bring-up blockers. After deploy succeeds and the probe in step 1 passes, return here. - If the user picks (b) → hand off to `the matching `/vss-build-vision-ai` stock workflow` (default `base`). Return here once it succeeds. - If the user declines both → **stop**. VIOS operations require the VST backend to be up; do not attempt to fabricate responses or proceed with a degraded mode. *Pre-authorized autonomous mode:* if your caller has granted explicit pre-authorization to deploy prerequisites (e.g. the request says "pre-authorized to deploy prerequisites", or you are running in a non-interactive evaluation harness with that permission), skip the confirmation and prefer path (a) — bring up VIOS standalone via this skill's bundled `references/deploy-vios-service.md` — unless the request explicitly asks for a full VSS profile, in which case invoke `the `/vss-build-vision-ai` stock Base workflow`. 3. **If the probe passes, proceed.** VIOS is up; all operations below are safe to execute. --- ## Known limitation — leftover containers from prior deploys `GET /vst/api/v1/sensor/list` and `GET /vst/api/v1/sensor/<sensorId>/streams` can return **HTTP 502 Bad Gateway** or stale results when leftover `*-smc` VST containers from an earlier deploy survive teardown and win the `network_mode: host` port-bind race on `:30000` / `:30888`. **Remediation: re-run `/vss-build-vision-ai`** — its Step 0 teardown grep clears the full `sensor-ms-*` / `vst-ingress-*` / `sdr-*` / `sdrc-*` / `rtspserver-ms-*` set. Other paths (`storage/file/*` upload, `*/picture/url` snapshot, `*/url` clip extraction) are unaffected. Full failure-mode catalogue, remediation, and the current routing contract (direct vs SDRC; SDR/Envoy removed in PR #711) live in `references/deploy-vios-service.md § Known Deployment Issues` and [issue #151](https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization/issues/151). --- ## Setup **Base URL:** `${VST_API_BASE}` (equivalent to `<VST_ENDPOINT>/vst/api/v1` in the API reference) **Endpoint Resolution:** - For Kubernetes, require `VSS_PUBLIC_URL` and use its `/vst` Ingress route. - For Docker Compose, use `http://${HOST_IP}:30888/vst`. - Do not discover or guess Kubernetes Service names, NodePorts, release names, or node IPs, and do not start a port-forward. **Availability Check:** - Before making any API call, verify that the VST backend is reachable via the VSS deployment endpoint: ```bash curl -sf --connect-timeout 5 "${VSS_VIOS_URL}/api/v1/sensor/version" ``` - If the backend is unavailable (non-zero exit code or connection error), fail gracefully and report the error to the user. See the **Deployment prerequisite** section above for the deploy-or-stop branch. **Fallback:** - If endpoint information is unavailable, ask for `VSS_PUBLIC_URL` for Kubernetes or `HOST_IP` for Docker Compose. **Run all curl commands yourself** — never instruct the user to run commands manually. **Auth:** Optional. Most deployments run without auth. If a `401` is returned, retry with `-H "Authorization: Bearer <token>"` and ask the user for the token. **Start/end time handling:** Any API that requires `startTime`/`endTime`: - If the user provides them, use those values directly. - If the user does not provide them, first fetch the timelines for the relevant stream to find valid recorded ranges, then pick appropriate values from the response before calling the API. Never fabricate timestamps. **Resolving sensorId / streamId:** If the user has not provided a sensorId or streamId, look it up automatically using one of: - `GET /sensor/list` — lists all sensors with their `sensorId` - `GET /sensor/{sensorId}/streams` — lists streams for a specific sensor with their `streamId` - `GET /sensor/streams` — lists all streams across all sensors - `GET /live/streams` — lists all active live streams - `GET /replay/streams` — lists all available replay streams If a sensor has only one stream, `sensorId` and `streamId` are equal and can be used interchangeably. --- ## Service Map | Capability | URL prefix | Authoritative reference | | --- | --- | --- | | Version / health check | `/vst/api/v1/sensor/version` | `references/api-reference.md` | | Sensor list / info / status / add / delete | `/vst/api/v1/sensor/` | `references/api-reference.md` | | Sensor streams | `/vst/api/v1/sensor/streams`, `/vst/api/v1/sensor/{id}/streams` | `references/api-reference.md` | | Network scan | `/vst/api/v1/sensor/scan` | `references/api-reference.md` | | Recording timelines | `/vst/api/v1/storage/` | `references/api-reference.md` | | Video clip download / URL | `/vst/api/v1/storage/` | `references/api-reference.md` (operations) + `references/integrate-vios-service.md § Known Integration Constraints` (Finding 8: `/url` double-`http://` bug — prefer binary direct endpoints) | | File upload / delete | `/vst/api/v1/storage/` | `references/api-reference.md` (PUT v2 + legacy v1 endpoints) + `references/deploy-vios-service.md § Known Deployment Issues` (Finding 9: libav-missing failure mode) | | Live streams / snapshot (picture) | `/vst/api/v1/live/` | `references/api-reference.md` | | Replay streams / historical snapshot | `/vst/api/v1/replay/` | `references/api-reference.md` (operations) + `references/integrate-vios-service.md § Known Integration Constraints` (Finding 8) | | **NvStreamer**: file-to-RTSP republisher (upload, retrieve generated RTSP URL, filesystem scan, frame snapshots) | `${VSS_STREAMER_URL}/api/v1/` for Kubernetes; `http://${HOST_IP}:${NVSTREAMER_HTTP_PORT:-31000}/api/v1/` for Compose | `references/nvstreamer-api-reference.md` (the streamer endpoint is **separate** from the VIOS gateway and has **no `/vst` prefix** (`/api/v1/`, not `/vst/api/v1/`), `type: "streamer"` on `/version`) |