Libusb-UVC : une bibliothèque Python pure pour les caméras USB Video Class

Le protocole UVC (USB Video Class) définit la façon dont une caméra expose ses flux vidéo et ses contrôles à travers l’USB.
Il s’agit d’un protocole standardisé par l’USB-IF, utilisé par la quasi-totalité des webcams modernes : caméras internes de portables, modules USB, microscopes numériques, etc.
Sur Linux, c’est habituellement le module noyau uvcvideo qui gère ces périphériques et fournit une interface /dev/video* à travers V4L2.

Mais dans certains cas, on a besoin d’un accès plus bas-niveau, directement via libusb :
pour expérimenter des contrôles propriétaires, récupérer des images fixes (still image capture), inspecter les descripteurs, ou encore gérer des flux compressés que V4L2 ne supporte pas encore (H.265, VP8, AV1…).

C’est dans ce contexte qu’est née Libusb-UVC.

Objectif du projet

Libusb-UVC vise à fournir une implémentation Python pure du protocole UVC :

indépendante du pilote noyau (uvcvideo peut rester chargé),
pilotable entièrement en espace utilisateur via libusb,
avec une API orientée objet et un outillage d’inspection complet.

Le but n’est pas de remplacer V4L2, mais de comprendre et explorer le protocole depuis l’espace utilisateur, pour le contrôle, le streaming et l’expérimentation.

Ce que fait la bibliothèque aujourd’hui

Streaming complet en userspace
Le module gère les flux YUYV et MJPEG en temps réel, avec reconstruction des trames, gestion de l’isochronisme et du changement d’alt-setting.
Les flux compressés (H.264, H.265, VPx, AV1…) sont également pris en charge en mode pass-through : la bibliothèque ne les décode pas, mais fournit les paquets bruts aux décodeurs en espace utilisateur (par exemple PyAV ou GStreamer).
Contrôles vidéo complets (VC)
Les unités standard (Input Terminal, Processing Unit) et les Extension Units propriétaires sont découvertes dynamiquement et peuvent être interrogées ou modifiées (GET_CUR, SET_CUR, etc.).
Un système de fichiers quirks JSON permet de documenter les GUIDs connus et de donner des noms explicites aux sélecteurs (par exemple les GUID Quanta ou Microsoft XU).
Gestion des images fixes (Still Image Capture)
Le protocole UVC 1.1 introduit la possibilité pour une caméra de capturer une image unique à la demande, avec éventuellement une résolution différente du flux vidéo.
Cette fonctionnalité a été implémentée : la bibliothèque sait envoyer la commande STILL_IMAGE_TRIGGER et récupérer la trame correspondante.
En pratique, aucune caméra testée jusqu’ici ne semble exposer de vrai mode still image, même si beaucoup déclarent les descripteurs correspondants.
Cela reste donc surtout une partie exploratoire du protocole, mais elle est fonctionnelle côté code.
Mode hybride avec le pilote du noyau
Si uvcvideo est chargé, la bibliothèque peut détacher uniquement l’interface de contrôle (VC) pour lire ou écrire les paramètres sans perturber les applications utilisant /dev/video*.
Le flux vidéo reste alors accessible via les outils classiques, ce qui permet un diagnostic fin sans avoir à décharger de module.
Inspection et génération de profils (quirks)
L’outil pyusb_uvc_info.py permet d’afficher toutes les interfaces, formats, résolutions et contrôles d’une caméra.
Il peut aussi générer un fichier JSON décrivant la structure de ses XU, utile pour la documentation ou le débogage.

Particularités et différences avec pyuvc

Contrairement à pyuvc (qui repose sur le pilote V4L2 et sur libjpeg-turbo pour le décodage MJPEG),
Libusb-UVC ne s’appuie sur aucun pilote noyau.
Tout est géré via les transferts USB, en Python pur, ce qui permet de manipuler des flux que V4L2 ignore encore (par exemple des flux compressés modernes).

Pour le décodage, la bibliothèque peut déléguer à :

PyAV (binding FFmpeg) pour le décodage logiciel ou matériel,
GStreamer (via appsrc) pour des pipelines plus complexes, tout en restant agnostique sur le backend.

Ce choix rend la bibliothèque beaucoup plus flexible que pyuvc, notamment pour des usages d’analyse ou de recherche.

Perspectives

Les prochaines étapes concernent :

la validation de nouveaux GUIDs d’Extension Units (Quanta, Realtek, Microsoft),
et la consolidation de la documentation technique (schémas des descripteurs, exemples de commandes GET_LEN et GET_INFO).

Avec Libusb-UVC, on a un outil libre et reproductible pour explorer le protocole UVC, comprendre les caméras, et permettre à d’autres de bâtir dessus.

Code et documentation

Code source : github.com/jeffwitz/Libusb-UVC
Licence : MIT
Langage : Python ≥ 3.8
Dépendance principale : libusb1
Exemples fournis : inspection, capture d’image, capture vidéo, génération de quirks

Conclusion

Libusb-UVC offre un regard complet sur le protocole UVC depuis l’espace utilisateur.
C’est un outil utile pour les chercheurs, makers ou développeurs qui veulent comprendre comment une caméra dialogue réellement sur le bus USB —
et un bon point de départ pour aller au-delà de ce que propose V4L2.