jetson-video-setup

Jetson 视频设置

目的

在运行中的 Jetson 上检查、安装并验证原生 NVIDIA Video Codec SDK 和 PyNvVideoCodec。设置流程负责产品安装和就绪状态检查。 编解码器支持、编码器配置、性能测量和应用程序流水线请使用相关的视频技能。

直接使用标准包管理器、Python 环境工具和已安装的 NVIDIA 示例，然后返回简洁的就绪结果。

操作前请阅读

• 阅读 setup-workflow.md，了解检查和就绪状态检查。
• 在执行 APT、venv 或 pip 更改前，先完整阅读一次 setup-install.md。
• 阅读 setup-output-contract.md，了解需要返回的简洁易读结果。
• 仅当请求同时提供或要求获取媒体时，才阅读 video-content.md。

选择产品

操作目标前，先确定用户请求的产品：

• “Video Codec SDK”、“VC SDK”、“native SDK” 或 nvidia-video-codec-sdk 表示原生产品。
• “PyNvVideoCodec”、“PyNv”、“PySDK”、“Python SDK” 或明确指定 Python 接口，表示 PyNvVideoCodec。
• 仅当用户要求两者时，才同时选择两者。

如果用户只笼统要求设置或检查就绪状态的“video SDK”，则请求存在歧义。询问用户想要原生 Video Codec SDK、PyNvVideoCodec 还是两者，然后停止。“report”一词不能消除这种歧义。

原生和 Python 操作应彼此独立。一方失败不得抹去另一方的成功结果。

工作流程

1. 确认命令将在 Jetson 上运行。检查 /etc/nv_tegra_release、 /etc/os-release 和所请求的 GPU 序号。如果在其他主机上，只提供指导，不得声称已就绪。
2. 仅使用 setup-workflow.md 中的直接命令检查所选产品。对于原生产品，确认已安装的软件包、软件包所属的 Samples 目录、CUDA 工具包和构建工具。对于 Python，使用用户提供或在本次请求期间创建的确切解释器，并检查已安装的发行版和已加载的模块。不得扫描文件系统以查找虚拟环境。
3. 如果用户只要求检查，则报告已安装的内容并停止。软件包或导入项存在表示 installed，而非 ready。
4. 如果所选产品缺失，且用户要求安装或修复，则遵循安装参考。执行任何更改前，先显示准确的软件包或 pip 命令。创建最终 Python 环境路径前，先安装并验证系统前置条件。只更改所选产品及其缺失的前置条件。
5. 安装后，重复直接检查。然后按照 setup-workflow.md 中的说明，运行已安装版本提供的官方单帧编码，再进行独立解码。
6. 分别报告每个所选产品。只有在官方编码和独立解码通过所有可观察检查后，才能使用 ready。否则报告 installed、blocked 或 failed，指出失败的命令或缺失的前置条件，并给出一个具体的后续操作。

如果其他视频技能只要求检查就绪状态，则执行第 1 和第 2 步，并返回准确的软件包/Samples 根目录或 Python 解释器/软件包路径。如果调用方接下来会立即运行自己的认证操作，则不要运行设置冒烟测试。

PyNvVideoCodec 环境选择

解释器优先级如下：用户显式指定的路径、当前对话中已确定的确切路径，然后是常规配置文件路径。 常规 smoke 解释器为 $HOME/.venvs/nvcodec/bin/python；full-samples 解释器为 $HOME/.venvs/nvcodec-full/bin/python。检查这些确切路径之一不属于文件系统扫描。切勿按目录顺序选择 venv，也不要回退到系统 Python。

对于新环境，如果适用的常规路径不存在，则使用该路径；或者使用位于用户拥有的持久位置中的新绝对路径。如果常规路径已存在，则先检查它。若有效，则复用；否则报告其确切缺陷，保持原样，并要求提供其他新路径。返回所选解释器路径，以便下游技能直接使用。

使用 pynvc-smoke 进行安装 smoke 验证、解码性能工作，以及常规接口可用性检查。该可用性检查仅检查确切的 smoke 路径；如果该路径不存在或无效，则报告 not_ready。任何使用者编码操作（包括能力可用性验证），以及使用高级原始解码、分割或编码性能示例的工作，都应选择单独的 full-samples 环境及安装指南中所述的依赖项。不涉及媒体的能力清单可使用任一常规配置文件：先检查 smoke；若其不存在，再检查 full-samples，并报告实际响应的确切解释器。仅当整个请求都是不涉及媒体的清单时，才应用这项任一配置文件的许可。如果请求还要求执行操作或验证能力可用性，则使用该请求所绑定的配置文件；若该配置文件尚未就绪，则报告 not_ready，且不要查询另一个常规配置文件。上述接口可用性检查仍绑定到 smoke 路径。

就绪验证

两种产品都使用一个生成的 640×360 8-bit NV12 帧（345,600 字节），进行 H.264 编码，并独立解码新生成的比特流。

产品	所需证据
Native	由软件包提供的 AppEncCuda 报告编码了一个帧；由软件包提供的 AppDec 使用该确切的非空比特流，报告解码了一个帧，并写出 345,600 字节的 NV12 输出。
PyNv full-samples	由 wheel 提供的 basic/encode.py 报告编码了一个 CPU 缓冲区帧；由 wheel 提供的 advanced/decode.py 使用该确切比特流，报告解码了一个帧，并写出 345,600 字节的输出。
PyNv pynvc-smoke	相同的编码器验证；由 wheel 提供的 advanced/decode_perf.py 报告请求解码一个帧且总数为一个，并且没有 worker 错误、警告或回溯。此项验证不声称生成了原始解码文件。

仅有零退出码或文件创建并不足够。必须有预期的标记和数量、新创建的非空比特流，以及独立的使用者。由于 H.264 属于有损压缩，不要求解码后的字节与输入相同。

CPU 缓冲区和设备内存示例模式只能证明确切的就绪操作。它们无法证明外部缓冲区共享、零拷贝，也无法证明其他进程或流水线阶段所用的同步原语。若请求确认进程内或跨阶段的缓冲区契约，请调用 jetson-video-pipeline；必须要求实际下游阶段执行经过验证的操作，以证明共享句柄、格式和布局、所有权与生命周期、信号与等待行为，以及缓冲区安全复用。不要仅凭安装证据回答此类请求。

组合处理相关的同级任务

对于同时询问支持情况、编码器配置、吞吐量或应用工作流的请求，只调用匹配的公开技能：

• jetson-video-capability
• jetson-video-recipe
• jetson-video-benchmark
• jetson-video-pipeline

将所选产品和准确的本地路径作为数据传递。不要读取或导入同级技能的私有文件。如果所需的同级技能不可用，保留已完成的设置结果，并指出缺少的技能。

安全

• 对于仅要求报告的请求，只进行直接的只读检查；绝不构建示例、创建工作区或 venv、启动编解码器操作，或修改软件包及现有 Python 环境。
• 仅使用已经配置且经过签名验证的软件包仓库。NVIDIA SDK 和 CUDA 软件包必须来自已安装版本对应的 Jetson 公共仓库。绝不添加或编辑软件源、密钥，也不绕过信任验证。
• 安装 APT 软件包前，检查候选版本和来源，运行准确的 apt-get -s 模拟，并拒绝会移除或降级软件包，或安装非预期软件包的操作。使用非交互式 sudo -n 执行审核过的命令；如果无法通过该方式授权，则停止，不要使用密码提示、su 或其他提权方式。
• 执行 APT 修改后运行 dpkg --audit，如果输出不为空或命令失败，则停止。
• 将原生安装和 Python 安装分开处理。仅针对 Python 的请求不得安装 nvidia-video-codec-sdk；仅针对原生安装的请求不得创建 venv。
• 不要将凭据写入命令、日志或报告。拒绝符号链接或非预期的安装目标，并使用全新的构建和输出路径。
• 本地安装和冒烟测试结果不能证明产品受支持，也不能证明该版本是最新的兼容版本。要提出此类声明，必须查阅 NVIDIA 当前的官方文档。

对于 PSNR、SSIM、DRM 播放、采集、推理或显示相关工作，应说明设置流程不负责这些工作，并且仅转交用户明确要求的视频编解码部分。