--- 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 " 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 , but it requires , which is not installed. Install 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 positive markers and counts. Only a passing verifier may promote the selected surface from probe `partial` to a final ready verdict. 7. After a ready Python verification, publish the fixed registry only with `verify_pynvc_sample.py --register-current --output READY_REPORT`. 8. Report the detected Jetson Linux release, product versions, independent surface verdicts, blockers, and artifact identities. 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.