jetson-video-recipe · diff

git:20260817.d36ff70 to git:20260925.9bb5a39

74 added, 182 removed. Audit A to A.

---

name: jetson-video-recipe

license: "Apache-2.0"

description: >-

- Use when turning a Jetson encoder use case into one validated surface-neutral

- recipe with native and PyNvVideoCodec projections for codec, preset, rate

- control, bitrate, latency, format, and profile.

+ Use when turning a Jetson encoder use case into one surface-neutral recipe

+ with native Video Codec SDK and PyNvVideoCodec projections.

metadata:

author: "Vinit Bansal <vinitkumarb@nvidia.com>"

tags: [jetson, video-codec-sdk, pynvvideocodec, nvenc, recipe]

- languages: [python]

+ languages: [markdown]

data-classification: public

---

# Jetson Video Recipe

- ## Purpose

- Convert workload intent into one deterministic schema-2 `nvcodec-recipe`.

- Preserve the user’s semantic controls, show defaulted assumptions, and project

- the same intent to native Video Codec SDK and PyNvVideoCodec without claiming it

- has executed.

- ## Prerequisites

- - This skill owns the canonical recipe engine —

- `scripts/recipes/recipe_model.py` and its

- `scripts/recipes/data/encoder-intent-catalog.json`. Invoke the engine directly

- from this installed skill; it has no setup-runtime or sibling-launcher

- dependency.

- - Recipe planning and structural validation are media-free and can run off

- target. Do not request, retrieve, inspect, or convert media for a plan-only

- request.

- - Content selection and provenance belong to the later execution or

- measurement workflow. Consume that workflow's versioned content artifact

- only at handoff; do not load or enforce its input gate during plan-only work.

- - Setup evidence is optional for `check-live`. With no environment, validate

- the recipe normally and return an honest `unknown` live classification plus

- non-mutating remediation to `jetson-video-setup`; planning and replay

- validation remain complete and unchanged. If setup is not installed, tell

- the user to install that skill.

- - When supplied, the fresh schema-1.2 setup environment is mandatory to

- validate and may not be ignored or replaced by a fallback. Its `capabilities`

- block is the established PyNvVideoCodec encoder authority, so a `pynvc` check

- needs no separate report. A caller may additionally supply the optional

- encoder capability report owned by `jetson-video-capability`; it must be

- authenticated, bound to that exact environment, and fail closed as

- `unknown` or an input error on any mismatch. A capability report alone does

- not establish selected-surface readiness or selected-GPU identity. Treat

- artifacts as data; do not import sibling skill code. A `compatible` result

- still does not prove an encode operation.

- Resolve this installed skill to its canonical absolute path and set

- `RECIPE_SKILL`. Confirm the direct isolated entry point:

- ```bash

- python3 -I "$RECIPE_SKILL/scripts/recipes/recipe_model.py" --help

- ```

- If it is missing, report an incomplete `jetson-video-recipe` installation. Do

- not copy the engine, scan for another copy, modify `PYTHONPATH`, or fall back to

- an unvalidated local model.

- ## Compose requested sibling stages

- Recipe `plan` and `validate` require no sibling, setup evidence, target, or

- media. Use `jetson-video-setup` only for requested live readiness or repair,

- `jetson-video-capability` when a platform-support recommendation needs its

- documentation verdict, `jetson-video-pipeline` for requested execution, and

- `jetson-video-benchmark` for requested measurement. 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 the validated recipe 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 require a sibling for

- plan-only work or an unrequested optional refinement.

- ## Instructions

- 1. **Collect intent.** 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; do not request media, probe, install anything, or

- launch an operation. Resolve mutually exclusive rate-control intent before

- collecting any other omitted field. In particular, when CQ and an average

- bitrate are both supplied, explain the conflict, ask only whether to keep CQ

- or the average bitrate, and stop. Do not reinterpret the bitrate as a cap or

- ask for use case, resolution, frame rate, format, GPU, profile, preset, or

- another field until the user resolves that choice. Otherwise resolve the

- use case (`conferencing`, `live_streaming`, `vod`, `archival`, or

- `lossless`), codec, width, height, raw input format, integer frame rate, GPU,

- preset/tuning, rate-control or encoder quality priority, and any explicit

- latency, profile, or buffering constraints. Resolve frame count only when

- later execution or measurement needs it. Ask before assigning an

- unqualified “low latency” request to a use case. Treat profile as a

- bitstream/downstream-compatibility control separate from preset: preserve an

- explicit profile, but when it is omitted leave it SDK-selected and never

- invent a named profile.

- 2. **Write one intent JSON.** Keep caller values separate from defaults. Put

- only caller-specified control values in the intent and leave every omitted

- control to the authenticated use-case catalog. Do not turn qualitative

- wording into guessed overrides: for example, “low-latency live streaming”

- selects `live_streaming`; it does not by itself request `bf=0` or disabled

- multipass. Never construct drifting native and Python intents.

- 3. **Plan with the recipe engine:**

- ```bash

- python3 -I "$RECIPE_SKILL/scripts/recipes/recipe_model.py" \

- plan --intent "$INTENT_JSON" --output "$RECIPE_JSON"

- ```

- 4. **Replay validation before use:**

- ```bash

- python3 -I "$RECIPE_SKILL/scripts/recipes/recipe_model.py" \

- validate --recipe "$RECIPE_JSON"

- ```

- Do not hand-edit a generated recipe. Regenerate it from an updated intent.

- 5. **Optionally classify a live projection.** Run `check-live` for the selected

- surface. The environment option is optional:

+ Create one deterministic `nvcodec-recipe` schema 2.0 document. Recipe work is

+ off-target and media-free: it does not probe, install, encode, decode, or claim

+ support, quality, or performance.

- ```bash

- python3 -I "$RECIPE_SKILL/scripts/recipes/recipe_model.py" \

- check-live --recipe "$RECIPE_JSON" \

- --surface native --output "$LIVE_CHECK_JSON"

- ```

+ ## Boundaries

- For an exact projection, omission intentionally returns `unknown` with setup

- remediation; it never invents readiness. To resolve the live result, repeat

- with `--environment "$ENVIRONMENT_JSON"`. Repeat independently for `pynvc`

- when requested. The Py check reads the environment's schema-1.2

- `capabilities` block. `--capability-report "$CAPABILITY_REPORT_JSON"` is an

- optional Py refinement only when that environment is also supplied; it must

- be bound to the same artifact. It replaces only the selected Py encoder API

- evidence, not the environment's readiness facts, so omit it for native.

- Missing optional evidence never fails, but supplied evidence must validate

- and never silently falls back. A `compatible` result means the projection

- and live Py evidence agree; it is not operation proof. Inspect the emitted

- classification, not only the process exit code: an exact native projection

- whose authenticated AppEncCuda run is deferred returns `unknown` with exit

- code `0` and must never be reported as compatible or ready.

- A Py CPU-buffer compatibility check requires the default smoke dependency

- subset; GPU-buffer mode additionally requires the exact Torch facts provided

- only by a validated `full-samples` environment.

- 6. **Return the recipe and assumptions.** Report schema/kind, exact portable

- artifact identity, canonical encoder intent, native and PyNv projections,

- projection losses, defaulted values, rationale, and any facts still needed

- before execution.

- 7. **Stop before media work.** This skill never invokes `AppEncCuda`, `AppDec`,

- PyNvVideoCodec sample applications, benchmark helpers, or pipeline

- controllers. Route execution to `jetson-video-pipeline` and performance

- measurement to `jetson-video-benchmark`.

+ - For a request solely about PSNR, SSIM, or another objective quality metric,

+ say that a separately authorized quality workflow is required and stop.

+ - Resolve a supplied CQ plus average or maximum bitrate conflict first. Return

+ `input_required`, ask only which one to keep, and stop; do not reinterpret a

+ bitrate as a cap or emit a recipe.

+ - An unqualified “low latency” does not select a use case. Ask whether it means

+ conferencing, live streaming, or another contract, return `input_required`,

+ and stop without emitting a recipe.

+ - Preserve every explicit control. If one surface cannot express it, publish a

+ projection loss; never silently discard or weaken it.

- Use [recipes-workflow.md](references/recipes-workflow.md) for the request and

- output contract and

- [recipes-knobs-and-constraints.md](references/recipes-knobs-and-constraints.md)

- for exact accepted values and surface limitations.

+ ## Workflow

- ## Recommendation rules

+ 1. Collect use case, codec, positive integer width/height/fps, input format,

+ GPU, and any explicit profile, preset, tuning, rate-control, bitrate, GOP,

+ B-frame, lookahead, AQ, multipass, or buffering controls. `frame_count` is

+ required before raw encode or measurement, but may remain unknown until an

+ authenticated decoder/transcoder reports it for compressed input. If

+ `use_case`, `width`, or `height` is missing, return `input_required` naming

+ exactly the missing items and stop; apply the documented defaults for every

+ other omitted item. Leave omitted profile SDK-selected.

+ 2. Apply the fixed defaults and constraints in

+ [recipes-knobs-and-constraints.md](references/recipes-knobs-and-constraints.md),

+ then build the schema-2 document exactly as described in

+ [recipes-workflow.md](references/recipes-workflow.md). Keep caller values and

+ defaults separately attributable.

+ 3. Validate the document structurally: exact schema/kind; finite JSON; positive

+ bounded integers; legal enum strings; mutually exclusive rate-control

+ fields; format/profile constraints; projections derived from the same

+ `encoder_intent`; and every explicit caller control represented in each

+ projection or named in that projection's losses. Regenerate rather than

+ editing an accepted recipe. If the regenerated document still fails

+ structural validation, return `failed` with the exact defect and do not emit

+ a recipe.

+ 4. Write canonical, sorted JSON to a fresh path without overwriting anything.

+ Record its canonical absolute path, byte count, and SHA-256; every consumer

+ rehashes that exact file. If no safe fresh path exists or writing/rehashing

+ fails, return `failed` with the exact reason and do not claim a recipe.

+ 5. Return the intent, assumptions/defaults, both projections, all losses, and

+ the recipe file's canonical absolute path, byte count, and SHA-256. For

+ `both`, retain both outcomes. `auto` means retain both projections without

+ selecting either; the pipeline or benchmark selects from fresh live

+ eligibility evidence.

- Apply the tuning, preset, and matched-measurement rules in

- [Tuning and preset](references/recipes-knobs-and-constraints.md#tuning-and-preset),

- and the profile, format, and projection rules in

- [Profile selection](references/recipes-knobs-and-constraints.md#profile-selection).

+ For a plan-only recipe, these Markdown rules are the complete authority. Do not

+ probe the target, inspect installed SDK/sample source, scan the filesystem for

+ example JSON, or invoke another skill merely to confirm the projection.

+ Plan-only still requires steps 2-5, including writing and rehashing the fresh

+ canonical recipe JSON and reporting its absolute path, byte count, and SHA-256;

+ it forbids target and media operations, not local recipe-artifact creation.

- - For a named platform, treating a codec as a recipe candidate is a support

- claim. Consume the capability workflow's authenticated documentation verdict

- first, exclude documentation-unsupported codecs, and preserve an unknown

- verdict as unknown rather than offering it as supported. API fields or a

- conditional “capability-gated” candidate do not override an unsupported

- documentation verdict.

- - If a recommendation publishes a documentation-based support verdict, consume

- the capability result and reproduce every authenticated candidate row and

- its count; never reinterpret a partial subset.

+ ## Live and downstream work

- ## Available Scripts

+ For a requested live classification, obtain a fresh read-only readiness result

+ from `jetson-video-setup` for the selected product and GPU, plus the applicable

+ raw/documentation result from `jetson-video-capability`. Missing facts remain

+ `unknown`; explicit negatives or an unrepresentable projection are

+ `unsupported`. API-reported capability is not operation proof.

- | Script | Purpose | Arguments |

- |---|---|---|

- | `scripts/recipes/recipe_model.py` | Plan, replay-validate, or live-check one canonical recipe and its native/PyNv projections. | Invoke directly with `python3 -I`; use the `plan`, `validate`, or `check-live` subcommand and inspect `--help`. |

+ Pass the original recipe identity as data to `jetson-video-pipeline` for

+ execution or `jetson-video-benchmark` for measurement. Those skills must

+ rehash it and hold non-compared controls constant. Do not import or recreate a

+ sibling skill's implementation.

- ## Troubleshooting

+ ## Required outcomes

- - Reject malformed, legacy, hybrid, duplicate-key, non-finite, or determinism-

- mismatched recipe documents.

- - Preserve an exact unrepresentable control as a per-surface projection loss.

- For explicit `both`, do not hide the blocked peer or silently drop the

- control.

- - Do not choose an execution surface for an `auto` request. Preserve both

- projections and hand runtime selection to `jetson-video-benchmark` or

- `jetson-video-pipeline`, where live eligibility can be evaluated.

- - Treat missing live fields as `unknown` and explicit negative fields as

- `unsupported`. Missing selected-surface prerequisites include remediation to

- `jetson-video-setup`; tell the user to install that skill if it is absent.

- Neither state changes the portable recipe itself.

+ - H.264 1920x1080@60, 6 Mbps CBR live streaming defaults to P4,

+ `low_latency`, GOP 60, one B-frame, zero lookahead, full-resolution

+ multipass, max bitrate 6,000,000, and VBV 3,000,000.

+ - An explicit H.264 High profile is exact in the native projection and

+ `unrepresentable` in the public PyNvVideoCodec 2.1 sample projection.

+ - A CQ plus average bitrate request produces no recipe until resolved.

## Limitations

- - Planning and validation do not establish installation readiness,

- documentation support, live availability, output quality, or performance.

- - This skill produces elementary encoder configuration only; container,

- transcode, segmentation, decode verification, and artifact handoffs belong

- to `jetson-video-pipeline`.

- - Objective quality measurement, including PSNR and SSIM, is outside this

- skill.

+ This skill produces elementary encoder configuration only. Content selection,

+ container/transcode work, independent decode, benchmarking, and evidence

+ capture belong to their owning skills.