Configuration vidéo Jetson

Objectif

Sonder, installer et vérifier indépendamment les surfaces du NVIDIA Video Codec SDK natif et de PyNvVideoCodec sur un Jetson actif. La configuration gère la préparation à l'installation, non les verdicts de support de codec, les recettes, les benchmarks ou les pipelines d'application.

À lire avant d'agir

• Lisez setup-workflow.md pour la sélection des surfaces et l'ordre sonder → planifier → appliquer → vérifier.
• Lisez setup-install.md avant toute mutation APT, venv ou pip.
• Lisez setup-output-contract.md avant de consommer ou signaler un artefact.

Sélectionner la surface

Avant l'étape 1 ou tout sondage, résolvez la surface demandée. « Video Codec SDK », « VC SDK », « native SDK » ou nvidia-video-codec-sdk sélectionnent le natif ; « PyNvVideoCodec », « PyNv », « PySDK » ou Python sélectionnent PyNvVideoCodec. Correspondez à un produit nommé avant de considérer la phrase brute : « Video Codec SDK » est le nom du produit natif même s'il contient les mots « video SDK ». Une demande de configuration, installation, fonctionnement, préparation ou rapport brute et véritablement générique « video SDK » est ambiguë : demandez seulement si l'utilisateur veut le Video Codec SDK natif, PyNvVideoCodec ou les deux, puis arrêtez-vous avant de sonder, d'agir ou de décrire les futures sondes, vérifications, étapes d'installation ou contenus de rapport. L'intention rapport uniquement seule ne sélectionne pas une surface ni n'autorise l'élargissement aux deux.

Sélectionnez les deux seulement s'il y a demande explicite, et réutilisez la sélection pour le reste de la demande. Une exception étroite s'applique à la porte de sélection auto d'une compétence consommatrice : ce consommateur peut invoquer la sonde lecture seule de configuration avec --runtime both uniquement pour évaluer les deux candidats. Cela ne sélectionne pas les deux pour l'installation, la vérification, l'exécution ou le rapport final.

Gardez les surfaces sélectionnées indépendantes. Un échec natif ne doit pas supprimer une surface Python actionnelle, et un échec Python ne doit pas supprimer le natif. Signalez l'agrégation de la préparation both uniquement après que les deux chaînes de vérification réussissent.

Composer les étapes sœurs demandées

Le flux de travail sonder, planifier, installer et vérifier de la configuration ne requiert aucune compétence sœur. Quand une demande complexe demande également une capacité de produit, une recette, une performance ou un travail de pipeline, ajoutez seulement l'étape correspondante jetson-video-capability, jetson-video-recipe, jetson-video-benchmark ou jetson-video-pipeline. Vérifiez d'abord le catalogue de compétences installées de l'agent. Si la sœur est présente, lisez son SKILL.md et invoquez son point d'entrée public documenté ; passez les artefacts en tant que données et n'importez jamais le code sœur. S'il est absent, conservez les résultats de configuration complétés et dites, en utilisant les noms réels : Je peux exécuter <étape>, mais cela nécessite <compétence>, qui n'est pas installée. Installez <compétence> et relancez cette étape. N'acquérez jamais une sœur pour une étape non demandée.

Flux de travail

1. Confirmez que l'exécution est sur le Jetson. Sur un hôte non-Jetson, produisez seulement des conseils et ne faites aucune affirmation de préparation actuelle.
2. Sondez la surface sélectionnée avec probe_nvcodec.py --runtime native|pynvc|both --output .... Utilisez both seulement quand la demande sélectionne explicitement les deux surfaces ou pour la vérification de candidat auto lecture seule étroite ci-dessus. La sonde est lecture seule. Réauthentifiez un artefact sauvegardé avec l'action --reauthenticate du même CLI.
3. Pour PyNvVideoCodec, utilisez le registre validé-venv fixe ou un interpréteur exact fourni par l'utilisateur. Ne scannez jamais ou ne devinez pas un venv. Si l'utilisateur dit que PyNvVideoCodec est déjà installé mais ne fournit pas de chemin exact et que le registre n'est pas prêt, demandez le chemin avant de provisionner quoi que ce soit. Un interpréteur de registre manquant rend ce registre pas prêt ; un interpréteur enregistré qui ne peut pas être lancé bloque la surface Py sélectionnée. Ne scannez jamais ni ne basculez vers un autre environnement.
4. Générez un plan d'installation avec plan_install.py, puis exécutez plan_install.py validate PLAN. Une demande rapport uniquement s'arrête après la sonde ; plan-only n'autorise jamais la mutation. Utilisez l'intention setup-install seulement pour une demande d'installation/configuration explicite ; cette demande autorise seulement les lots entiers inchangés dans le plan révisé.
5. Exécutez seulement les commandes littérales du plan setup-install révisé. Invoquez chaque argv publié littéralement en tant qu'utilisateur actuel, y compris les étapes marquées privilege: "root" ; ne préfixez jamais sudo, car plan_install.py possède l'escalade interne autorisée sudo -n pour les opérations APT. plan_install.py possède les actions d'actualisation, d'aperçu et d'application APT ; lock_pip_reports.py possède la création de venv propre et l'application pip verrouillée. L'exécution APT régénère le plan canonique et recheche les preuves de candidat, origine, source et simulation actives avant mutation.
6. Re-sondez la surface complétée. Exécutez verify_native.py pour le natif ou verify_pynvc_sample.py pour Python. Chaque preuve de configuration utilise les échantillons officiels de la version installée pour encoder un cadre 640×360 NV12 en H.264, puis décoder indépendamment ce flux de bits frais. Natif et Python sous --profile full-samples, décodent exactement 345 600 octets. Le profil Python par défaut pynvc-smoke décode un cadre borné avec advanced/decode_perf.py, qui n'écrit aucune sortie brute, donc il prouve seulement la production de cadre. Un consommateur qui a vraiment besoin de Torch — encodage benchmark Python, pipeline ou la preuve de décodage brut complète — est bloqué sous pynvc-smoke ; dites-le et nommez le remède : provisionnez un venv full-samples explicitement avec plan_install.py --profile full-samples. Une sortie zéro seule n'est jamais une preuve : exigez les marqueurs positifs exactes du profil et les comptages. Seul un vérificateur passant peut promouvoir la surface sélectionnée de la sonde partial à un verdict prêt final.
7. Après une vérification Python prête, publiez le registre fixe seulement avec verify_pynvc_sample.py --register-current --output READY_REPORT.
8. Signalez la version Jetson Linux détectée, les versions de produit, les verdicts de surface indépendants, les bloqueurs et les identités d'artefact.

Utilisez --fresh-setup seulement quand l'utilisateur demande explicitement une nouvelle configuration ou une réinstallation. Cela n'autorise jamais la suppression de paquets de base fonctionnels. Une configuration Python fraîche requiert aussi un --venv unique et précédemment absent. Ce --venv doit être un chemin absolu sous un emplacement durable, par exemple /home/ubuntu/.venvs/nvcodec-fresh ; ne le placez jamais dans le répertoire de travail actuel ou aucune exécution, session ou arborescence de preuve éphémère, car le registre que vous publiez survit à ce répertoire. Les noms --output relatifs se résolvent par rapport au répertoire de travail, écrivez donc les rapports de configuration quelque part d'égale durabilité.

Scripts de configuration directs

Exécutez chaque CLI public sous python3 -I et inspectez son --help avant de construire les arguments.

Il n'y a pas de répartiteur de configuration. Invoquez ces cinq CLIs publics directement. La configuration ne doit pas importer du code Python d'une autre compétence, et une autre compétence ne doit pas importer l'implémentation privée de la configuration.

Préparation et périmètre

• L'inventaire ou la présence d'importation n'est pas une preuve opérationnelle.
• operation_verified nécessite les deux opérations officielles, leurs marqueurs positifs et un flux de bits frais non vide. Natif et Python full-samples nécessitent en outre le comptage exact des cadres décodés et la taille de sortie brute ; Python pynvc-smoke nécessite à la place ses deux marqueurs de production de cadre unique exact et ne prétend pas à aucun artefact décodé brut.
• Une sortie zéro ou la création de fichier de sortie seule est insuffisante.
• La configuration émet seulement des observations de requête API Python bornées de référence et des résumés d'échantillon natif bruts comme preuves de préparation de soutien. Elle n'émet pas la matrice complète de tuples décodeur ou un verdict de support de produit ; utilisez jetson-video-capability pour ces questions.
• Utilisez jetson-video-recipe, jetson-video-benchmark et jetson-video-pipeline pour le travail de configuration, de mesure et de remise.
• Une sonde locale prouve seulement la pile détectée et la porte de version minimale ; elle ne prouve pas la devise de version ou la version la plus récente compatible avec cette cible. Appelez une version latest ou newest compatible seulement quand la récupération réussie de la documentation officielle NVIDIA actuelle, enregistrée avec URL et date de récupération, établit à la fois la devise de version et la compatibilité avec l'identité de cible authentifiée. Sinon, signalez le plus récent compatible comme unknown et pointez vers la documentation de compatibilité officielle ; l'état APT local, une source échouée ou l'un ou l'autre fait seul est insuffisant.
• Pour une demande de qualité uniquement telle que PSNR ou SSIM, déclarez que la configuration ne la fournit pas et qu'un flux de travail de qualité séparé autorisé est requis, puis arrêtez-vous ; n'installez pas, n'invoquez pas, ne nommez pas, ne recommandez pas ni n'offrez de configurer un outil de qualité externe.

Sécurité

• Acceptez les paquets SDK natif/CUDA seulement depuis la source Jetson NVIDIA publique stock configurée, authentifiée par signature (repo.download.nvidia.com/jetson/common ou /som, rNN.N/main exact). Les prérequis de base peuvent utiliser une autre origine APT déjà configurée, authentifiée par signature. Liez chaque candidat à son dossier d'origine exact et ne modifiez jamais une source ou une clé.
• Gardez les identifiants hors de argv, logs, artefacts, stdout et stderr.
• Préservez les identités exactes de plan, paquet, interpréteur, artefact et source.
• Utilisez des chemins de sortie/travail/construction frais. Ne surchargez jamais les preuves ni ne les réutilisez après un reflash, une modification de driver/paquet ou un remplacement de venv.