Qt Multimedia Backend GStreamer

Cette page couvre les limitations et les points de personnalisation du backend GStreamer de Qt Multimedia, le backend média par défaut sur Linux embarqué.

Considérations architecturales

GStreamer est le backend média par défaut sur Linux embarqué principalement parce qu'il s'agit du framework que la plupart des vendeurs de cartes embarquées privilégient pour la prise en charge des médias accélérés par le matériel. FFmpeg peut également convenir à certaines plates-formes, et les utilisateurs sont donc encouragés à expérimenter les deux backends médias pour trouver celui qui leur convient le mieux.

Qt Multimedia GStreamer n'est pas un framework de streaming généraliste et n'est pas nécessairement la meilleure façon d'utiliser GStreamer avec Qt. Les développeurs qui ont besoin d'un haut degré de contrôle sur le pipeline GStreamer, mais qui veulent seulement montrer la sortie vidéo Qt, peuvent envisager d'utiliser qml6glsink de GStreamer.

Limites et problèmes connus

GStreamer n'est pas fourni avec Qt, mais il est généralement déployé avec la distribution Linux.

• Certains bogues peuvent être dus à la version de GStreamer utilisée. Nous recommandons d'utiliser la dernière version de GStreamer qui corrige les bogues sur votre plateforme.
• Certains bogues peuvent également être liés aux bibliothèques utilisées par GStreamer, comme Pulseaudio. Pulseaudio v16 a notamment un bogue connu qui provoque le blocage du pipeline GStreamer et nécessite des rétro-portages de ces deux correctifs :
  • https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/745
  • https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/764

  Ce bogue affecte actuellement la plupart des distributions Linux grand public, y compris Ubuntu 22.04, 23.10 et 24.04, Debian 11 et 12, ainsi que Fedora 39 et 40.

• Le changement d'appareil photo ou de caméra pendant l'enregistrement n'est pas pris en charge.
• La recherche, les taux de lecture, la boucle, les puits de commutation ont des bogues connus.
• Les fonctions audio nécessitent PulseAudio. Voir les notes relatives à la plate-forme Linux pour plus de détails.
• Certaines cartes embarquées nécessitent des configurations individuelles pour résoudre les problèmes de négociation/liaison de pipeline et améliorer les performances. Nous recommandons aux développeurs d'expérimenter avec les variables d'environnement listées dans les points de personnalisation lorsqu'ils rencontrent de tels problèmes. Les fichiers de la méta-couche Yocto de Qt contiennent des configurations recommandées pour certaines combinaisons de cartes, de BSP et de versions de Boot to Qt. Voici les liens vers les versions de la branche dev :
  • NXP i.MX 6/8/9 : https://code.qt.io/cgit/yocto/meta-boot2qt.git/tree/meta-boot2qt-distro/dynamic-layers/freescale-layer/recipes-qt/boot2qt-addons/default-qt-envs.bbappend?h=dev
  • Raspberry Pi 4/5 : https://code.qt.io/cgit/yocto/meta-boot2qt.git/tree/meta-boot2qt-distro/dynamic-layers/raspberrypi/recipes-qt/boot2qt-addons/default-qt-envs.bbappend?h=dev

  Certaines cartes i.MX NXP exposent un périphérique v4l2 nommé imx-capture, qui peut provoquer des erreurs lorsqu'il est utilisé avec v4l2src dans GStreamer. Pour empêcher Qt Multimedia d'ajouter imx-capture à la liste des périphériques de caméra disponibles, définissez la variable d'environnement QT_GSTREAMER_SKIP_IMXCAPTURE=1. Notez que ceci est considéré comme une API privée qui sera supprimée lorsque NXP corrigera les problèmes avec imx-capture.

• La lecture vidéo ou le streaming de caméra utilisant des images vidéo de la mémoire système ou une conversion logicielle peut entraîner des chutes d'images et un manque de réactivité en raison d'une forte charge du processeur. Si le décodeur GStreamer ou l'appareil photo émet des images vidéo DMA-BUF ou GLMemory dans l'un de nos formats de pixels pris en charge, Qt peut les rendre sans conversion ou copie supplémentaire. GStreamer sélectionne un format et un type de mémoire en fonction des capacités des éléments de son pipeline. Différentes façons de contrôler les éléments ajoutés au pipeline sont décrites dans les points de personnalisation. Voir aussi Spécification du mode E/S pour les caméras v4l2.

Points de personnalisation

Qt Multimedia fournit certains points de personnalisation pour permettre l'accès au pipeline GStreamer sous-jacent. Le point d'entrée est class QGStreamerPlatformSpecificInterface. Des personnalisations supplémentaires peuvent être effectuées en définissant des variables d'environnement.

Rendu de texture OpenGL externe

Qt importe des images vidéo soutenues par des DMA-BUF dans le pipeline graphique OpenGL en liant le tampon sous-jacent comme une image EGL et en l'exposant aux shaders comme une texture OpenGL. Par défaut, Qt échantillonne ces textures en utilisant la cible de texture GL_TEXTURE_2D et le code de shader standard. Certaines cartes embarquées fonctionnent mieux avec la cible de texture GL_TEXTURE_EXTERNAL_OES, ainsi qu'un shader de fragment dédié. Ce comportement peut être activé en définissant la variable d'environnement suivante :

QT_MULTIMEDIA_FORCE_GL_TEXTURE_EXTERNAL_OES=1

Spécification du mode E/S pour les caméras v4l2

Lors de l'utilisation d'un périphérique de capture v4l2 avec une caméra QCamera ou QML, la propriété io-mode de l'élément GStreamer v4l2src sous-jacent affecte la sortie ou non d'images vidéo soutenues par DMA-BUF qui permettent un rendu zéro-copie. Dans certains cas, le mode automatique par défaut choisit le mode mmap même si le pilote de la caméra prend en charge le mode dmabuf. La valeur int de la propriété io-mode peut être définie explicitement via la variable d'environnement ci-dessous. Voici un exemple montrant comment définir le mode io sur dmabuf avec l'enum GST_V4L2_IO_DMABUF :

QT_GSTREAMER_V4L2SRC_IOMODE=4

Sélection d'éléments GStreamer spécifiques

Une distribution GStreamer peut inclure plusieurs plugins différents qui peuvent potentiellement effectuer la même tâche dans le pipeline média. GStreamer sélectionne automatiquement les éléments tels que les décodeurs et les démultiplicateurs en fonction de leur rang de fonctionnalité, qui peut être modifié via une variable d'environnement GStreamer. Voici un exemple qui classe le décodeur matériel v4l2h264dec plus haut que n'importe quel décodeur logiciel H.264, tout en s'assurant que le démultiplexeur aiurdemux n'est pas sélectionné :

GST_PLUGIN_FEATURE_RANK=v4l2h264dec:MAX,aiurdemux:NONE

Pour vérifier quels éléments sont créés pendant l'exécution, activez le niveau 4 de journalisation de débogage pour GstElementFactory :

GST_DEBUG=GST_ELEMENT_FACTORY:4

En outre, vous pouvez inspecter visuellement l'ensemble du pipeline GStreamer en spécifiant un dossier pour les fichiers graphiques .dot qui seront vidés lors de divers événements, par exemple, les changements dans l'état de la lecture :

GST_DEBUG_DUMP_DOT_DIR=/root/graphs

Pour en savoir plus sur ces variables d'environnement, consultez la documentation de GStreamer :

• Variables d'environnement - GST_PLUGIN_FEATURE_RANK
• Tutoriel de base - Le journal de débogage
• Tutoriel de base - Obtenir des graphiques de pipeline

Spécifier les éléments de conversion matérielle

Si la source média d'un pipeline GStreamer ne peut pas fournir de tampons vidéo dans un format de pixels pris en charge par Qt Multimedia, le pipeline utilisera la conversion logicielle à moins qu'il ne contienne un élément de conversion vidéo accélérée matérielle approprié. Pour spécifier un élément de conversion matérielle à utiliser, définissez-le en tant que description du pipeline GStreamer dans la variable d'environnement suivante :

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT

Certains éléments de conversion spécifiques au fournisseur (imxvideoconvert_g2d, nvvidconv) sont ajoutés au pipeline par défaut s'ils sont disponibles. Cela peut entraîner des conversions inutiles, et peut être désactivé en spécifiant un élément d'identité GStreamer à l'aide de la même variable d'environnement :

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=identity

GStreamer peut également effectuer une conversion de format avec des éléments OpenGL, fournissant à Qt des images vidéo soutenues par GLMemory :

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=glupload ! glcolorconvert

Accès au pipeline brut

Il est possible d'accéder à GstPipeline qui sous-tend QMediaPlayer et QMediaCaptureSession.

#include <QtMultimedia/private/qgstreamer_platformspecificinterface_p.h>

[...]
QMediaPlayer player;
GstPipeline *pipeline = QGStreamerPlatformSpecificInterface::instance()->gstPipeline(&player);
[...]
QMediaCaptureSession session;
GstPipeline *pipeline = QGStreamerPlatformSpecificInterface::instance()->gstPipeline(&session);

Éléments GStreamer personnalisés en tant que sources et puits

Il est possible de créer des éléments GStreamer à partir d'une description de pipeline GStreamer et de les envelopper dans un QCamera ou QAudioDevice:

#include <QtMultimedia/private/qgstreamer_platformspecificinterface_p.h>

[...]
QByteArray pipelineString = "videotestsrc is-live=true ! gamma gamma=2.0";

QMediaCaptureSession session;
session.setVideoSink(wid.videoSink());

QCamera *cam = QGStreamerPlatformSpecificInterface::instance()->makeCustomGStreamerCamera(
         pipelineString, &session);
session.setCamera(cam);

QMediaPlayer : sources personnalisées

Le site QMediaPlayer accepte une description de pipeline GStreamer comme URI source :

QMediaPlayer player;
player.setSource(u"gstreamer-pipeline: videotestsrc name=testsrc"_s);

Il essaiera de compiler la description du pipeline pour l'utiliser comme source dans le QMediaPlayer et sera automatiquement connecté aux puits du QMediaPlayer.