En esta página

Qt Multimedia Backend de GStreamer

Esta página trata sobre las limitaciones y los aspectos de personalización del backend de GStreamer de Qt Multimedia, el backend multimedia predeterminado en Linux embebido.

Consideraciones arquitectónicas

GStreamer es el backend multimedia predeterminado en Linux embebido, principalmente porque es el marco de trabajo al que la mayoría de los fabricantes de placas embebidas dan prioridad para la compatibilidad multimedia con aceleración por hardware. FFmpeg también puede ser adecuado en algunas plataformas, por lo que se anima a los usuarios a probar ambos backends multimedia para descubrir cuál les funciona mejor.

Qt Multimedia no es un marco de trabajo de streaming de uso general y no es necesariamente la mejor forma, desde el punto de vista arquitectónico, de utilizar GStreamer con Qt. Los desarrolladores que necesiten un alto grado de control sobre el pipeline de GStreamer, pero que solo quieran mostrar la salida de vídeo en Qt, tal vez deban considerar el uso de qml6glsink de GStreamer.

Limitaciones y problemas conocidos

GStreamer no se incluye con Qt, pero suele venir instalado con la distribución de Linux.

  • Algunos errores pueden deberse a la versión de GStreamer que se esté utilizando. Recomendamos utilizar la última versión de GStreamer con correcciones de errores para tu plataforma.
  • Algunos errores también pueden estar relacionados con las bibliotecas que utiliza GStreamer, como Pulseaudio. En particular, Pulseaudio v16 tiene un error conocido que provoca que el canal de GStreamer se cuelgue y requiere la aplicación de estos dos parches:

    Este error afecta actualmente a la mayoría de las distribuciones principales de Linux, incluidas Ubuntu 22.04, 23.10 y 24.04, Debian 11 y 12, así como Fedora 39 y 40.

  • No se admite el cambio de dispositivos de cámara o de cámaras durante la grabación
  • El desplazamiento, las velocidades de reproducción, el bucle y el cambio de destinos presentan errores conocidos.
  • Las funciones de audio requieren PulseAudio. Consulta las notas sobre la plataforma Linux para obtener más detalles.
  • Algunas placas embebidas necesitan configuraciones específicas para resolver problemas de negociación o enlace de canalizaciones y mejorar el rendimiento. Recomendamos a los desarrolladores que prueben con las variables de entorno enumeradas en «Puntos de personalización» cuando se enfrenten a este tipo de problemas. Los archivos de la metacapa Yocto de Qt contienen configuraciones recomendadas para determinadas combinaciones de placas, BSP y versiones de Boot to Qt. A continuación se incluyen enlaces a las versiones de la rama de desarrollo:
  • Algunas placas i.MX de NXP exponen un dispositivo v4l2 denominado «imx-capture», lo que puede provocar errores al utilizarlo con v4l2src en GStreamer. Para evitar que Qt Multimedia añada «imx-capture» a la lista de dispositivos de cámara disponibles, configura la variable de entorno QT_GSTREAMER_SKIP_IMXCAPTURE=1. Ten en cuenta que se trata de una API privada que se eliminará cuando NXP solucione los problemas con «imx-capture».
  • La reproducción de vídeo o la transmisión desde la cámara mediante fotogramas de vídeo de la memoria del sistema o la conversión por software pueden provocar la pérdida de fotogramas y una falta de respuesta debido a una elevada carga de la CPU. Si el decodificador de GStreamer o el dispositivo de cámara genera fotogramas de vídeo respaldados por DMA-BUF o GLMemory en uno de nuestros formatos de píxeles compatibles, Qt puede renderizarlos sin necesidad de conversión ni copia adicionales. GStreamer selecciona un formato y un tipo de memoria en función de las capacidades de los elementos de su canalización. En la sección «Puntos de personalización» se describen diferentes formas de controlar qué elementos se añaden a la canalización. Véase también «Especificación del modo de E/S para cámaras v4l2».

Puntos de personalización

Qt Multimedia ofrece ciertos puntos de personalización que permiten acceder a la canalización subyacente de GStreamer. El punto de entrada es QGStreamerInterface. Se pueden realizar personalizaciones adicionales configurando variables de entorno.

Advertencia: Los puntos de personalización y las variables de entorno específicas de Qt que se enumeran aquí se consideran API privadas y pueden estar sujetas a cambios. Ten en cuenta que, por defecto, los procesos hijos heredan las variables de entorno, lo que puede tener consecuencias no deseadas.

Renderizado de texturas OpenGL externas

Qt importa fotogramas de vídeo respaldados por DMA-BUF al canal gráfico de OpenGL vinculando el búfer subyacente como una imagen EGL y exponiéndolo a los sombreadores como una textura de OpenGL. Por defecto, Qt muestrea estas texturas utilizando el destino de textura GL_TEXTURE_2D y código de sombreador estándar. Algunas placas embebidas ofrecen un mejor rendimiento utilizando en su lugar el destino de textura GL_TEXTURE_EXTERNAL_OES, junto con un sombreador de fragmentos dedicado. Este comportamiento se puede habilitar configurando la siguiente variable de entorno:

QT_MULTIMEDIA_FORCE_GL_TEXTURE_EXTERNAL_OES=1

Especificación del modo de E/S para cámaras v4l2

Al utilizar un dispositivo de captura v4l2 con una cámara « QCamera » o QML, la propiedad «io-mode» del elemento v4l2src de GStreamer subyacente determina si se emiten o no fotogramas de vídeo respaldados por DMA-BUF, lo que permite el renderizado sin copia. En algunos casos, el modo predeterminado «auto» elige el modo «mmap» aunque el controlador de la cámara admita el modo «dmabuf». El valor entero de la propiedad «io-mode» se puede establecer explícitamente mediante la variable de entorno que se indica a continuación. A continuación se muestra un ejemplo de cómo configurar «io-mode» en «dmabuf» con la enumeración GST_V4L2_IO_DMABUF:

QT_GSTREAMER_V4L2SRC_IOMODE=4

Selección de elementos específicos de GStreamer

Una distribución de GStreamer puede incluir varios complementos diferentes que, potencialmente, pueden realizar la misma tarea en la cadena de procesamiento multimedia. GStreamer selecciona automáticamente elementos como decodificadores y demultiplexadores en función de su clasificación de características, que puede anularse mediante una variable de entorno de GStreamer. A continuación se muestra un ejemplo en el que se da mayor prioridad al decodificador de hardware v4l2h264dec que a cualquier decodificador de software H.264, al tiempo que se garantiza que no se seleccione el demultiplexador aiurdemux:

GST_PLUGIN_FEATURE_RANK=v4l2h264dec:MAX,aiurdemux:NONE

Para comprobar qué elementos se crean durante la ejecución, activa el nivel de registro de depuración 4 para GstElementFactory:

GST_DEBUG=GST_ELEMENT_FACTORY:4

Además, puede inspeccionar visualmente toda la cadena de procesamiento de GStreamer especificando una carpeta para los archivos de gráficos de « .dot » que se generarán en diversos eventos, por ejemplo, cambios en el estado de reproducción:

GST_DEBUG_DUMP_DOT_DIR=/root/graphs

Más información sobre estas variables de entorno en la documentación de GStreamer:

Especificación de elementos de conversión por hardware

Si la fuente multimedia de un canal de GStreamer no puede proporcionar búferes de vídeo en un formato de píxeles compatible con Qt Multimedia, el canal utilizará la conversión por software, a menos que contenga un elemento de conversión de vídeo acelerado por hardware adecuado. Para especificar un elemento de conversión por hardware que se vaya a utilizar, configúralo como una descripción del canal de GStreamer en la siguiente variable de entorno:

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT

Algunos elementos de conversión específicos de determinados fabricantes (imxvideoconvert_g2d, nvvidconv) se añaden a la canalización de forma predeterminada si están disponibles. Esto puede provocar conversiones innecesarias si no son necesarias, y se puede desactivar especificando un elemento de identidad de GStreamer mediante la misma variable de entorno:

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=identity

GStreamer también puede realizar conversiones de formato con elementos OpenGL, proporcionando a Qt fotogramas de vídeo respaldados por GLMemory:

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=glupload ! glcolorconvert

Acceso directo a la canalización

Se puede acceder a la « GstPipeline » subyacente a QMediaPlayer y QMediaCaptureSession.

Advertencia: Se tratade una API insegura, ya que el canal sigue siendo gestionado por la implementación de Qt. Se debe tener mucho cuidado al utilizar esta API.

#include <QtMultimedia/spi/qgstreamerinterface.h>

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

Elementos GStreamer personalizados como sumideros y fuentes

Es posible crear elementos de GStreamer a partir de una descripción de canalización de GStreamer y envolverlos dentro de un QGStreamerVideoSource o 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: fuentes personalizadas

El QMediaPlayer acepta una descripción de canalización de GStreamer como URI de fuente:

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

Esto intentará compilar la descripción del pipeline para utilizarla como fuente en el QMediaPlayer y se conectará automáticamente a los sumideros del QMediaPlayer.

Advertencia: ¡Hic sunt dracones! Los pipelines personalizados son una característica experimental: no se adaptan bien a las API de QMediaPlayer, sobre todo en lo que respecta al estado de los medios, las API de metadatos y el estado de transporte. La mayoría de las llamadas se asignarán directamente al pipeline de GStreamer, lo que puede dar lugar a un comportamiento indefinido dependiendo del pipeline. En la mayoría de los casos, es posible que el gstreamer-pipeline: no sea la opción adecuada para el código de la aplicación: para fuentes de vídeo arbitrarias, el QMediaCaptureSession con una cámara personalizada (véase más arriba) es la opción preferida. Para pipelines de complejidad arbitraria que solo quieran dibujar en una Qt GUI, el qml6glsink de GStreamer (véase más abajo) puede ser una opción más robusta.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.