
名称	jetson-video-pipeline
开源协议	“Apache-2.0”
描述	>- 在需要执行和验证 Jetson Video Codec SDK 或 PyNvVideoCodec 的编码/解码、转码、分割、容器解码、AV1 或验收工作流并需要精确工件交接时使用。 metadata:
作者	“Vinit Bansal vinitkumarb@nvidia.com” tags: [jetson, video-codec-sdk, pynvvideocodec, pipeline, nvenc, nvdec] languages: [python] data-classification: public

Jetson视频流水线

目的

执行官方示例编解码阶段，并证明每个消费者都使用了前一个阶段产生的精确工件。本技能用于编码后独立解码验证、原生 H.264 到 HEVC 转码、PyNvVideoCodec 分段、容器解码分类、AV1 操作验证，或紧凑的客户验收包。

前提条件

在目标 Jetson 上直接访问 GPU 运行执行。来自 jetson-video-setup 的全新已验证 schema-1.2 nvcodec-environment 身份是可选的。提供时它是权威的，无效或过时的证据在没有本地回退的情况下失败关闭。代理可以从 setup 的公共只读探针中获取它；它不需要在客户的提示中提供。
没有 setup 证据时，仅认证选定的已安装表面。原生路由检查固定的 dpkg 包、包拥有的官方示例源码、构建工具和非存根链接。PyNvVideoCodec 路由需要一个经过认证的 setup 环境或调用方准确绝对路径 pynvc_interpreter；绝不扫描 venv。在询问该路径之前，当该技能已安装时，调用 setup 的公共探针并检查其类型化结果。这些只读检查不安装、修复、注册或冒烟测试任何内容。
带配方的路由需要兄弟技能 jetson-video-recipe 及其一个经过验证的 schema-2 配方。如果存在其规范公共 CLI，则调用它；如果不存在，保留 dependency_required，命名该技能，并告诉用户安装它并重试该阶段。无配方的解码/分割路由不需要该依赖。
capability_report 是编码请求的可选成员，绝不是必需成员。PyNvVideoCodec 编码器能力的既定权威是 schema-1.2 nvcodec-environment 工件的 capabilities 块；省略 capability_report 的编码请求完全受支持并读取该块。当需要能力拥有的新鲜度时，请求可以额外携带由 jetson-video-capability 从相同环境工件生成的 schema-1.0 nvcodec-encoder-capability-report。提供时，该报告成为该检查的选定 Py 编码器 API 证据；它不替换环境工件或其就绪事实。不要仅仅因为可能选择 pynvc 表面而将成员添加到独立构造的请求中。它在任一表面上都是可选的，仅影响 Py 能力分类，并且对于原生应省略；不存在时永远不会失败。
当 setup 已安装时，阅读其共享的视频内容策略，并在任何正常流水线试运行或执行之前应用其输入门。仅凭策略并不需要 setup：没有它时，要求一个确切的用户选择路径或 URL，绝不替换目录或合成媒体，并保留源 URL、许可证、署名、路径、大小和 SHA-256。
PyNvVideoCodec 编码或调用 advanced/decode.py 的路由，包括编码/解码、分割和 Py 容器分类，需要一个单独验证的 full-samples venv。默认的 pynvc-smoke 环境是 setup 就绪证明，必须在创建工作区之前阻止这些路由；返回一个结构化的 jetson-video-setup 依赖并提供一个新的 full-samples venv，而不是原地升级它。如果该技能不存在，告诉用户在重试之前安装它。
直接 encode 控制器有一个更窄的消费者例外：jetson-video-capability 可以绑定 setup 的确定性单帧原始夹具，用于精确的有界能力冒烟操作。该结果仅是操作证据，绝不代表流水线或性能证明。

组合请求的兄弟阶段

当选定 SDK 前提已存在时，无配方的解码和分割路由不需要兄弟技能。仅为带配方阶段添加 jetson-video-recipe，仅为请求的性能添加 jetson-video-benchmark，仅为安装、修复或在注册的 Python 权威需要时的一次只读交接收取 jetson-video-setup，并且仅为请求的支持裁决或新的验收能力工件添加 jetson-video-capability。在每个阶段之前使用代理运行时的已安装技能目录；不要扫描任意目录。如果兄弟存在，读取其 SKILL.md 并调用其文档化的公共入口点；将工件作为数据传递，绝不导入兄弟代码。如果不存在，保留完成的阶段和工件，并使用实际名称说：我可以运行<阶段>，但它需要<技能>，该技能未安装。请安装<技能>并重试此阶段。 切勿将部分工作流升级为完整，也不要要求可选的兄弟技能。

说明

应用范围边界。对于仅请求客观质量指标（包括 PSNR 或 SSIM）的请求，仅说明本技能不提供这些指标，且需要单独授权的质量工作流，然后停止。不得命名或推荐外部工具，也不得提供配置或运行比较。对于仅限于采集、传输、 AI、显示或玻璃到玻璃延迟的请求，说明这些阶段不在本编解码技能范围内并停止，而不命名、推荐或提供其他工具或工作流。否则立即进入步骤2的媒体门；仅在该门通过后选择 encode_decode、native_transcode、pynvc_segments、 container_triage、av1_verify 或 acceptance。
对于所有剩余的规划、试运行或执行流水线路由的请求，包括“仅计划”或“不运行”，在路由选择以及前提、兄弟技能、参考或脚本检查之前应用此门。请勿将媒体门控的流水线请求分解为无媒体的配方子任务。如果缺少媒体，返回 input_required，并在目标探测、浏览、检索、认证、试运行或操作启动之前停止。在此门处仅询问缺少的媒体；不要同时检查控制器帮助、描述或规划路由、列出未来阶段或交接、或请求解释器、环境、配方或后期阶段字段。此终止门的完整响应仅包含 input_required 和对精确目标本地媒体路径或用户提供的 HTTP(S) URL 的一个请求。绝不选择替代媒体。上述能力冒烟例外仅适用于直接 encode 控制器，不得提升为流水线完成。
规范化并哈希确切的本地输入。对于 URL 输入，保留用户提供的确切 URL，然后在目标资格、授权和运行时权威门通过后才进行检索、规范化和哈希。
保留显式的 native、pynvc 或 both。将“whichever”、“best available”、“choose for me”和其他未指定表面措辞视为 auto，绝不视为 both。将 both 保留给显式要求运行或比较两个表面的请求。
在输入门和表面分类之后，为每个选定表面精确选择一个运行时权威。如果调用方提供 setup 环境身份，则验证该确切工件并将其绑定到试运行和执行；绝不忽略它或替换为本地回退。如果 PyNvVideoCodec 可能参与，并且未提供环境或确切解释器，通过其公共只读 probe_nvcodec.py 调用已安装的 jetson-video-setup：对显式 Python 使用 --runtime pynvc，对 both/auto 使用 --runtime both，使用新的 --output，绝不使用 --setup-candidate。检查新工件；只有选定 Py 表面已安装且其 pynvc.identity.status 为 verified 的实时工件才可用。将该确切文件快照为控制器的可移植 environment 身份，恰好包含 schema_version、kind、规范的绝对 path、size_bytes 和小写 sha256；不要导入兄弟代码或将阻塞的探针作为权威传递。如果 setup 不存在或报告任何未就绪、不可读、过期、绑定或启动失败，仅为显式 pynvc/both 询问并提供确切的 pynvc_interpreter。对于 auto，将 Py 保持为 not_evaluated，并仅继续合格的原生表面。控制器派生私有本地绑定，绝不接受来自请求的绑定，并在启动前重新验证它。如果本地认证失败，仅在已安装时对该确切表面使用 setup。
仅使用选定的运行时权威应用 auto 门：零个合格表面则阻止，一个则运行，两个则返回 selection_required；在此门中绝不排序表面。对于两个合格表面，此门是无条件的：不要搜索旧结果或基准来做出选择。请求确切的 native、 pynvc 或 both，然后在试运行或启动前停止。绝不信任提示中关于表面就绪的声明：从提供或新探测的权威建立资格。没有 setup 证据或确切本地 pynvc_interpreter 时，将 PyNvVideoCodec 记录为 not_evaluated 并带重试操作；不要让该可选对等方阻止其他方面合格的原生 auto 路由。显式 pynvc 或 both 仍需要这两个权威之一。
在任何编解码器启动之前，认证来自已安装 Video Codec SDK 包的每个选定可执行文件，或来自选定 wheel 和解释器的每个 Python 示例。仅使用这些经过认证的 NVIDIA 示例路由；如果无法满足某个阶段，报告该阶段阻塞。
对于多阶段 pipeline 请求，仅组合所需的兄弟技能。如果请求的性能阶段需要 jetson-video-benchmark，调用其已安装的公共控制器；如果不存在，保留已完成的流水线阶段并报告基准阶段为 dependency_required 并附安装并重试操作。运行流水线 dry_run，检查完整配方和示例参数，然后使用新的结果和工作区路径运行 execute。直接调用本技能的公共控制器：
```
python3 -I {baseDir}/scripts/pipeline_controller.py \
  --request request.json --workspace fresh-workspace \
  --output result.json
```
单个编码后独立解码请求调用 scripts/encode_controller.py，使用相同的三个参数。该控制器仅执行：首先验证并检查其配方和请求信封，然后使用新的输出和工作区路径调用一次；不要声称它执行了内部试运行。
要求确切的正标记和计数，无显式失败标记，且输出为新的非空文件。重新打开并重新哈希每个原始交接。独立解码器必须消耗确切的生产者路径、大小和 SHA-256，并产生预期的帧。
对于原生转码，仅接受一个经认证的 AppTrans 完成标记，采用任一发布形式：旧版 (#totFrames=N) 或当前 Total frame transcoded: N。拒绝缺失、重复或混合标记。
独立保留每个分段或表面结果。失败的对等方产生诚实的部分结果，而不是摘要级完成。
对于验收，让控制器验证并写入其九个物理预密封文件并返回 seal_pending: true；这些文件与参考键和阶段行不同。将大型媒体/构建工件保留在外部，然后由代理最后创建校验和清单——控制器不创建它。

参考

流水线工作流定义路由、验收、密封以及仅流水线使用的紧凑内容证据和验证器契约。
Setup 的共享视频内容策略定义确切的用户输入门和常见内容证据。
官方示例契约定义允许的路由和操作证明。

可用脚本

在隔离模式下直接调用每个公共脚本：

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

脚本	用途	参数
`scripts/encode_controller.py`	执行一个配方绑定编码，随后进行独立解码。	`--request`、`--workspace` 和 `--output`。
`scripts/pipeline_controller.py`	试运行或执行六条多阶段流水线路由。	`--request`、`--workspace` 和 `--output`。
`scripts/validate_representative_content_summary.py`	在不修改外部媒体的情况下重新哈希外部媒体并验证紧凑内容元数据。	检查 `--help` 以获取摘要/输入参数。

限制

本技能涵盖 NVIDIA 编解码阶段及其工件交接，不包括采集、网络传输、AI 推理、显示或玻璃到玻璃延迟。
它不实现 PSNR 或 SSIM 质量测量。
能力查询、退出码为零或创建输出文件绝不代表操作证明。
仅允许通过认证的已发布 NVIDIA 示例中嵌入的 libavformat 进行容器解复用。

故障排除

返回确切失败的阶段门、生产者、消费者、工件路径和原因。
保留 input_required、selection_required、blocked、partial 和 failed，而不是声称完整流水线。
拒绝过时输出、禁止位置的符号链接、路径/大小/SHA 漂移、格式错误的请求或证据 JSON、错误的帧计数和重复完成标记。
最多重试一次，且仅在证据标识了变化的条件后，如已修复依赖、新提供的工件或更改的路径/大小/SHA-256 绑定。重复未更改的失败命令是被禁止的。