Qt Multimedia Backend GStreamer

Cette page traite des limitations et des possibilités de personnalisation du backend GStreamer d'Qt Multimedia, le backend multimédia par défaut sur Linux embarqué.

Considérations architecturales

GStreamer est le backend multimédia par défaut sur Linux embarqué, principalement parce qu’il s’agit du framework privilégié par la plupart des fabricants de cartes embarquées pour la prise en charge multimédia accélérée par le matériel. FFmpeg peut également convenir sur certaines plateformes ; les utilisateurs sont donc encouragés à tester les deux backends multimédias afin de déterminer lequel leur convient le mieux.

Qt Multimedia n'est pas un framework de streaming polyvalent et ne constitue pas nécessairement la meilleure approche architecturale pour utiliser GStreamer avec Qt. Les développeurs qui ont besoin d'un haut degré de contrôle sur le pipeline GStreamer, mais qui souhaitent uniquement afficher la sortie vidéo via Qt, peuvent envisager d'utiliser le qml6glsink de GStreamer.

Limitations 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 vous recommandons d’utiliser la dernière version de GStreamer contenant les correctifs de bogues sur votre plateforme.
• Certains bogues peuvent également être liés aux bibliothèques utilisées par GStreamer, comme Pulseaudio. Notamment, Pulseaudio v16 présente un bogue connu qui provoque le blocage du pipeline GStreamer et nécessite l'application 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 courantes, notamment Ubuntu 22.04, 23.10 et 24.04, Debian 11 et 12, ainsi que Fedora 39 et 40.

• Le changement de périphérique de caméra ou de caméra pendant l'enregistrement n'est pas pris en charge
• La recherche, les vitesses de lecture, la lecture en boucle et le changement de périphérique de sortie présentent des bogues connus.
• Les fonctionnalités audio nécessitent PulseAudio. Consultez les notes relatives à la plate-forme Linux pour plus de détails.
• Certaines cartes embarquées nécessitent des configurations spécifiques 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 répertoriées dans la section « Points de personnalisation » lorsqu’ils sont confrontés à 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 d Boot to Qt. Voici les liens vers les versions de la branche de développement :
  • 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. NXP es exposent un périphérique v4l2 nommé imx-capture, ce 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 caméra disponibles, définissez la variable d’environnement QT_GSTREAMER_SKIP_IMXCAPTURE=1. Notez qu’il s’agit d’une API privée qui sera supprimée lorsque NXP aura corrigé les problèmes liés à « imx-capture ».
• La lecture vidéo ou la diffusion en continu depuis une caméra utilisant des images vidéo en mémoire système ou une conversion logicielle peut entraîner des pertes d’images et un manque de réactivité en raison d’une charge CPU importante. Si le décodeur GStreamer ou le périphérique de caméra produit des images vidéo gérées par DMA-BUF ou GLMemory dans l’un de nos formats de pixels pris en charge, Qt peut les afficher sans conversion ni 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 méthodes permettant de contrôler quels éléments sont ajoutés au pipeline sont décrites dans la section « Points de personnalisation ». Voir également « Spécification du mode d’E/S pour les caméras v4l2 ».

Points de personnalisation

Qt Multimedia fournit certains points de personnalisation permettant d’accéder au pipeline GStreamer sous-jacent. Le point d’entrée est QGStreamerInterface. Des personnalisations supplémentaires peuvent être effectuées en définissant des variables d’environnement.

Rendu de textures OpenGL externes

Qt importe des images vidéo basées sur DMA-BUF dans le pipeline graphique OpenGL en liant le tampon sous-jacent en tant qu’image EGL et en l’exposant aux shaders sous forme de texture OpenGL. Par défaut, Qt échantillonne ces textures à l’aide de la cible de texture GL_TEXTURE_2D et d’un code de shader standard. Certaines cartes embarquées offrent de meilleures performances avec la cible de texture GL_TEXTURE_EXTERNAL_OES, associée à 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 d'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 détermine si celui-ci génère ou non des images vidéo basées sur DMA-BUF, ce qui permet un rendu sans copie. Dans certains cas, le mode par défaut « auto » choisit le mode mmap même si le pilote de la caméra prend en charge le mode dmabuf. La valeur entière 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 io-mode sur dmabuf avec l’énumération 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 susceptibles d’effectuer la même tâche dans le pipeline multimédia. GStreamer sélectionne automatiquement des éléments tels que les décodeurs et les démultiplexeurs en fonction de leur classement de fonctionnalités, qui peut être remplacé via une variable d’environnement GStreamer. Voici un exemple qui attribue au décodeur matériel v4l2h264dec un rang supérieur à celui de tout décodeur logiciel H.264, tout en s'assurant que le démultiplexeur aiurdemux ne soit pas sélectionné :

GST_PLUGIN_FEATURE_RANK=v4l2h264dec:MAX,aiurdemux:NONE

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

GST_DEBUG=GST_ELEMENT_FACTORY:4

De plus, vous pouvez inspecter visuellement l’ensemble du pipeline GStreamer en spécifiant un dossier pour les fichiers de gra .dot, qui seront générés lors de divers événements, par exemple lors de changements d’état de 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 les graphiques du pipeline

Spécification des éléments de conversion matérielle

Si la source multimé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 une conversion logicielle, à moins qu'il ne contienne un élément de conversion vidéo accéléré par le matériel adapté. Pour spécifier un élément de conversion matériel à utiliser, définissez-le comme description de pipeline GStreamer dans la variable d'environnement suivante :

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT

Certains éléments de conversion spécifiques à certains fabricants (imxvideoconvert_g2d, nvvidconv) sont ajoutés par défaut au pipeline s'ils sont disponibles. Cela peut entraîner des conversions inutiles s'ils ne sont pas nécessaires, 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 des conversions de format à l’aide d’éléments OpenGL, fournissant ainsi à Qt des images vidéo gérées par GLMemory :

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=glupload ! glcolorconvert

Accès brut au pipeline

Il est possible d’accéder à l’ GstPipeline e sous-jacente à QMediaPlayer et QMediaCaptureSession.

#include <QtMultimedia/spi/qgstreamerinterface.h>

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

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

Il est possible de créer des éléments GStreamer à partir d’une description de pipeline GStreamer et de les intégrer dans un QGStreamerVideoSource ou un QAudioDevice:

#include <QtMultimedia/spi/qgstreamerinterface.h>
#include <QtMultimedia/spi/qgstreamervideosource.h>

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

QGStreamerVideoSource videoSource(QStringLiteral("videotestsrc is-live=true ! gamma gamma=2.0"));
session.setNativeVideoSource(&videoSource);
videoSource.start();

QMediaPlayer : sources personnalisées

L’ QMediaPlayer accepte une description de pipeline GStreamer comme URI de source :

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

Cela tentera de compiler la description du pipeline pour l’utiliser comme source dans l’ QMediaPlayer et sera automatiquement connecté aux récepteurs de l’ QMediaPlayer.