/jetson-video-setup

name: jetson-video-setup
license: "Apache-2.0"
description: >-
  Use when installing, repairing, probing, or verifying native NVIDIA Video
  Codec SDK or PyNvVideoCodec on Jetson with official encode-to-decode samples,
  including registered-environment recovery.
metadata:
  author: "Vinit Bansal <vinitkumarb@nvidia.com>"
  tags: [jetson, video-codec-sdk, pynvvideocodec, setup, nvenc, nvdec]
  languages: [python]
  data-classification: public

Jetson Video Setup

Purpose

Probe, install, and independently verify the native NVIDIA Video Codec SDK and PyNvVideoCodec surfaces on a live Jetson. Setup owns installation readiness, not codec-support verdicts, recipes, benchmarks, or application pipelines.

Read before acting

• Read [setup-workflow.md](references/setup-workflow.md) for surface selection

and the probe → plan → apply → verify order.

• Read [setup-install.md](references/setup-install.md) before any APT, venv, or

pip mutation.

• Read [setup-output-contract.md](references/setup-output-contract.md) before

consuming or reporting an artifact.

Select the surface

Before step 1 or any probe, resolve the requested surface. "Video Codec SDK", "VC SDK", "native SDK", or `nvidia-video-codec-sdk` selects native; "PyNvVideoCodec", "PyNv", "PySDK", or Python selects PyNvVideoCodec. Match a named product before considering the bare phrase: "Video Codec SDK" is the native product name even though it contains the words "video SDK". A genuinely bare "video SDK" setup, install, operation, readiness, or report-only request is ambiguous: ask only whether the user wants native Video Codec SDK, PyNvVideoCodec, or both, then stop before probing, acting, or describing future probes, checks, installation steps, or report contents. Report-only intent alone does not select a surface or authorize broadening to both.

Select both only when explicitly requested, and reuse the selection for the rest of the request. One narrow exception applies to a consumer skill's `auto` selection gate: that consumer may invoke setup's read-only probe with `--runtime both` solely to evaluate both candidates. This does not select both for installation, verification, execution, or the final report.

Keep the selected surfaces independent. A native failure must not suppress an actionable Python surface, and a Python failure must not suppress native. Report aggregate `both` readiness only after both verification chains pass.

Compose requested sibling stages

Setup's probe, plan, install, and verification workflow requires no sibling skill. When a complex request also asks for product capability, recipe, performance, or pipeline work, add only the corresponding `jetson-video-capability`, `jetson-video-recipe`, `jetson-video-benchmark`, or `jetson-video-pipeline` stage. Check the agent's installed skill catalog first. If the sibling is present, read its `SKILL.md` and invoke its documented public entry point; pass artifacts as data and never import sibling code. If it is absent, preserve completed setup results and say, using the actual names: `I can run <stage>, but it requires <skill>, which is not installed. Install <skill> and retry this stage.` Never acquire a sibling for an unrequested stage.

Workflow

1. Confirm execution is on the Jetson. On a non-Jetson host, produce guidance only and make no live readiness claim. 2. Probe the selected surface with `probe_nvcodec.py --runtime native|pynvc|both --output ...`. Use `both` only when the request explicitly selects both surfaces or for the narrow read-only consumer `auto` candidate check above. The probe is read-only. Reauthenticate a saved artifact with the same CLI's `--reauthenticate` action. 3. For PyNvVideoCodec, use the fixed validated-venv registry or an exact user-supplied interpreter. Never scan for or guess a venv. If the user says PyNvVideoCodec is already installed but supplies no exact path and the registry is not ready, ask for the path before provisioning anything. A missing registered interpreter makes that registry not ready; a registered interpreter that cannot be launched blocks the selected Py surface. Never scan or fall back to another environment. 4. Generate an install plan with `plan_install.py`, then run `plan_install.py validate PLAN`. A report-only request stops after the probe; `plan-only` never authorizes mutation. Use `setup-install` intent only for an explicit install/setup request; that request authorizes only the complete unchanged batches in the reviewed plan. 5. Execute only literal commands from the reviewed `setup-install` plan. Invoke every published `argv` verbatim as the current user, including steps marked `privilege: "root"`; never prefix `sudo`, because `plan_install.py` owns the authorized internal `sudo -n` escalation for APT operations. `plan_install.py` owns APT refresh, preview, and apply actions; `lock_pip_reports.py` owns clean-venv creation and the locked pip apply. APT execution regenerates the canonical plan and rechecks live candidate, origin, source, and simulation evidence before mutation. 6. Re-probe the completed surface. Run `verify_native.py` for native or `verify_pynvc_sample.py` for Python. Each setup proof uses the installed release's official samples to encode one 640×360 NV12 frame to H.264, then independently decode that fresh bitstream. Native, and Python under `--profile full-samples`, decode to exactly 345,600 bytes. The default Python profile `pynvc-smoke` decodes one bounded frame with `advanced/decode_perf.py`, which writes no raw output, so it proves frame production only. A consumer that genuinely needs Torch — Python encode-benchmark, pipeline, or the full raw-decode proof — is blocked under `pynvc-smoke`; say so and name the remedy: provision a `full-samples` venv explicitly with `plan_install.py --profile full-samples`. Exit zero alone is never proof: require the profile's exact p