jetson-video-pipeline

name	jetson-video-pipeline
license	Apache-2.0
description	Use when executing and verifying Jetson Video Codec SDK or PyNvVideoCodec encode/decode, transcode, segmentation, container decode, AV1, or acceptance workflows with exact artifact handoffs.
metadata	{"author":"Vinit Bansal <[e-mail]>","tags":["jetson","video-codec-sdk","pynvvideocodec","pipeline","nvenc","nvdec"],"languages":["python"],"data-classification":"public"}

Jetson Video Pipeline

Purpose

Execute official-sample codec stages and prove that every consumer used the exact artifact produced by the preceding stage. Use this skill for encode-then-decode verification, native H.264-to-HEVC transcode, PyNvVideoCodec segments, container decode triage, AV1 operation verification, or a compact customer acceptance package.

Prerequisites

• Run execution on the target Jetson with direct GPU access. A fresh validated schema-1.2 nvcodec-environment identity from jetson-video-setup is optional. When supplied it is authoritative, and invalid or stale evidence fails closed without local fallback. The agent may obtain it from setup's public read-only probe; it need not be supplied in the customer's prompt.
• Without setup evidence, authenticate only the selected installed surface. Native routes inspect the fixed dpkg package, package-owned official sample sources, build tools, and non-stub linkage. PyNvVideoCodec routes require an authenticated setup environment or the caller's exact absolute pynvc_interpreter; never scan for a venv. Before asking for that path, invoke setup's public probe when that skill is installed and inspect its typed result. These read-only checks install, repair, register, and smoke-test nothing.
• Recipe-bearing routes require sibling jetson-video-recipe and one of its validated schema-2 recipes. If its canonical public CLI is present, invoke it; if absent, preserve dependency_required, name that skill, and tell the user to install it and retry the stage. Recipe-free decode/segmentation routes do not acquire that dependency.
• capability_report is an optional encode-request member, never a required one. The established authority for PyNvVideoCodec encoder capabilities is the capabilities block of the schema-1.2 nvcodec-environment artifact; an encode request that omits capability_report is fully supported and reads that block. When capability-owned freshness is wanted, a request may additionally carry a schema-1.0 nvcodec-encoder-capability-report produced by jetson-video-capability from the same environment artifact. When supplied, that report becomes the selected Py encoder API evidence for the check; it does not replace the environment artifact or its readiness facts. Do not add the member to an independently constructed request merely because the pynvc surface may be selected. It is optional on either surface, affects Py capability classification only, and should be omitted for native; absence never fails.
• When setup is installed, read its shared video content policy and apply its input gate before any normal pipeline dry run or execution. Setup is not required solely for this policy: without it, require one exact user-selected path or URL, never substitute catalog or synthetic media, and preserve source URL, license, attribution, path, size, and SHA-256.
• PyNvVideoCodec routes that encode or invoke advanced/decode.py, including encode/decode, segmentation, and Py container triage, require a separately validated full-samples venv. The default pynvc-smoke environment is a setup-readiness proof and must block these routes before workspace creation; return a structured jetson-video-setup dependency and provision a new full-samples venv rather than upgrading it in place. If that skill is absent, tell the user to install it before retrying.
• The direct encode controller has one narrower consumer exception: jetson-video-capability may bind setup's deterministic one-frame raw fixture for an exact bounded capability smoke operation. That result is operation evidence only, never representative pipeline or performance proof.

Compose requested sibling stages

Recipe-free decode and segmentation routes require no sibling when the selected SDK prerequisites already exist. Add jetson-video-recipe only for a recipe-bearing stage, jetson-video-benchmark only for requested performance, jetson-video-setup only for installation, repair, or one read-only handoff when registered Python authority is required, and jetson-video-capability only for a requested support verdict or fresh acceptance capability artifact. Use the agent runtime's installed-skill catalog before each stage; do not scan arbitrary directories. 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 stages and artifacts 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 promote a partial workflow to complete or require an optional sibling.

Instructions

1. Apply the scope boundary. For a request solely for objective quality metrics, including PSNR or SSIM, state only that this skill does not provide them and that a separately authorized quality workflow is required, then stop. Do not name or recommend an external tool, and do not offer to configure or run the comparison. For a request limited to capture, transport, AI, display, or glass-to-glass latency, state that those stages are outside this codec skill and stop without naming, recommending, or offering another tool or workflow. Otherwise proceed immediately to the media gate in step 2; choose encode_decode, native_transcode, pynvc_segments, container_triage, av1_verify, or acceptance only after that gate clears.

2. For every remaining request to plan, dry-run, or execute a pipeline route, including “plan only” or “do not run”, apply this gate before route selection and before prerequisite, sibling, reference, or script inspection. Do not decompose a media-gated pipeline request into a media-free recipe subtask. If media is missing, return input_required and stop before target probing, browsing, retrieval, authentication, dry run, or operation launch. Ask only for the missing media at this gate; do not also inspect controller help, describe or plan the route, list future stages or handoffs, or request an interpreter, environment, recipe, or later-stage field. The complete response at this terminal gate consists only of input_required and one request for an exact target-local media path or user-supplied HTTP(S) URL. Never choose substitute media. The capability-smoke exception above applies only to the direct encode controller and must not be promoted to pipeline completion.

3. Canonicalize and hash an exact local input. For URL input, preserve the exact user-supplied URL, then retrieve, canonicalize, and hash it only after target eligibility, authorization, and runtime-authority gates pass.

4. Preserve explicit native, pynvc, or both. Treat “whichever”, “best available”, “choose for me”, and other unspecified-surface wording as auto, never as both. Reserve both for an explicit request to run or compare both surfaces.

5. After the input gate and surface classification, select exactly one runtime authority for each selected surface. If the caller supplies a setup environment identity, validate and bind that exact artifact to dry-run and execute; never ignore it or substitute a local fallback. If PyNvVideoCodec may participate and neither an environment nor exact interpreter was supplied, invoke installed through its public read-only : use for explicit Python or for /, a fresh , and never . Inspect the fresh artifact; only a live artifact whose selected Py surface is installed and whose is is usable. Snapshot that exact file as the controller's portable identity with exactly , , canonical absolute , , and lowercase ; do not import sibling code or pass a blocked probe as authority. If setup is absent or reports any not-ready, unreadable, stale, binding, or launch failure, ask for and supply the exact only for explicit /. For , keep Py and continue only an eligible native surface. The controller derives a private local binding, never accepts that binding from a request, and revalidates it before launch. If local authentication fails, use setup for only that exact surface when installed.

References

• Pipeline workflow defines routes, acceptance, sealing, and the pipeline-only compact content-evidence and validator contract.
• Setup's shared video content policy defines the exact user-input gate and common content evidence.
• Official sample contract defines allowed routes and operation proof.

Available Scripts

Invoke each public script directly in isolated mode:

python3 -I {baseDir}/scripts/encode_controller.py --help
python3 -I {baseDir}/scripts/pipeline_controller.py --help
python3 -I {baseDir}/scripts/validate_representative_content_summary.py --help

Script	Purpose	Arguments
scripts/encode_controller.py	Execute one recipe-bound encode followed by independent decode.	--request, --workspace, and --output.
scripts/pipeline_controller.py	Dry-run or execute the six multi-stage pipeline routes.	--request, --workspace, and --output.
scripts/validate_representative_content_summary.py	Rehash external media and validate compact content metadata without modifying it.	Inspect --help for summary/input arguments.

Limitations

• This skill covers NVIDIA codec stages and their artifact handoffs, not capture, network transport, AI inference, display, or glass-to-glass latency.
• It does not implement PSNR or SSIM quality measurement.
• A capability query, exit zero, or output-file creation is never operation proof.
• Container demux is allowed only through libavformat embedded in an authenticated released NVIDIA sample.

Troubleshooting

• Return the exact failed gate, producer, consumer, artifact path, and reason.
• Preserve input_required, selection_required, blocked, partial, and failed rather than claiming a complete pipeline.
• Reject stale outputs, symlinks where forbidden, path/size/SHA drift, malformed request or evidence JSON, wrong frame counts, and duplicate completion markers.
• Retry at most once and only after evidence identifies a changed condition, such as a repaired dependency, a newly supplied artifact, or a changed path/size/SHA-256 binding. Repeating an unchanged failed command is forbidden.