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 <[e-mail]>","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 for surface selection and the probe → plan → apply → verify order.
• Read setup-install.md before any APT, venv, or pip mutation.
• Read 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 ; say so and name the remedy: provision a venv explicitly with . Exit zero alone is never proof: require the profile's exact positive markers and counts. Only a passing verifier may promote the selected surface from probe to a final ready verdict.

Use --fresh-setup only when the user explicitly requests a new setup or reinstall. It never authorizes removing working base packages. A fresh Python setup also requires a unique, previously absent --venv. That --venv must be an absolute path under a durable location, for example /home/ubuntu/.venvs/nvcodec-fresh; never place it in the current working directory or any transient run, session, or evidence tree, because the registry you publish outlives that directory. Relative --output names resolve against the working directory, so write setup reports somewhere equally durable.

Direct setup scripts

Run every public CLI under python3 -I and inspect its --help before building arguments.

File	Public responsibility
scripts/setup/probe_nvcodec.py	Emit or reauthenticate the read-only live nvcodec-environment schema 1.2 artifact.
scripts/setup/plan_install.py	Plan and validate selected components; execute only its own reviewed APT refresh/preview/apply actions.
scripts/setup/lock_pip_reports.py	Create a new venv and materialize/apply the authenticated pip lock.
scripts/setup/verify_native.py	Build package-owned AppEncCuda/AppDec and verify the fixed native encode→decode smoke.
scripts/setup/verify_pynvc_sample.py	Authenticate and run wheel-owned Python encode/decode samples, emit the readiness artifact, and authenticate the validated-venv registry chain.
scripts/setup/setup_contract.py	Private common mechanics for these setup CLIs: strict JSON, bounded commands, and public-APT binding; never invoke it as a CLI.

There is no setup dispatcher. Invoke these five public CLIs directly. Setup must not import Python code from another skill, and another skill must not import setup's private implementation.

Readiness and scope

• Inventory or import presence is not operational proof.
• operation_verified requires both official operations, their positive markers, and a fresh nonempty bitstream. Native and Python full-samples additionally require the exact decoded frame count and raw-output size; Python pynvc-smoke instead requires its two exact one-frame production markers and claims no raw decoded artifact.
• Exit zero or output-file creation alone is insufficient.
• Setup emits only bounded baseline Py API-query observations and raw native sample summaries as supporting readiness evidence. It does not emit the complete decoder tuple matrix or a product-support verdict; use jetson-video-capability for those questions.
• Use jetson-video-recipe, jetson-video-benchmark, and jetson-video-pipeline for configuration, measurement, and handoff work.
• A local probe proves only the detected stack and minimum release gate; it does not prove release currency or the newest release compatible with this target. Call a release latest or newest compatible only when successfully retrieved current official NVIDIA documentation, recorded with URL and retrieval date, establishes both release currency and compatibility with the authenticated target identity. Otherwise report newest-compatible as unknown and point to the official compatibility documentation; local APT state, a failed source, or either fact alone is insufficient.
• For a quality-only request such as PSNR or SSIM, state that setup does not provide it and that a separately authorized quality workflow is required, then stop; do not install, invoke, name, recommend, or offer to set up an external quality tool.

Safety

• Accept native SDK/CUDA packages only from the configured, signature-authenticated stock public NVIDIA Jetson source (repo.download.nvidia.com/jetson/common or /som, exact rNN.N/main). Base prerequisites may use another already configured, signature-authenticated APT origin. Bind every candidate to its exact source record and never add or change a source or key.
• Keep credentials out of argv, logs, artifacts, stdout, and stderr.
• Preserve exact plan, package, interpreter, artifact, and source identities.
• Use fresh output/work/build paths. Never overwrite evidence or reuse it after a reflash, driver/package change, or venv replacement.