En esta página

Configuración avanzada de FFmpeg

Esta página enumera las características configurables del backend multimedia de FFmpeg. Todas las características forman parte de la API privada y pueden modificarse o eliminarse en el futuro sin previo aviso. Ten en cuenta que, por defecto, las variables de entorno se heredan en los procesos hijos y pueden tener consecuencias no deseadas.

Habilitar el registro de FFmpeg y del backend multimedia Qt FFmpeg

Puedes configurar la salida avanzada de registros de FFmpeg mediante variables de entorno.

  • QT_FFMPEG_DEBUG=1 activa el registro adicional de la biblioteca FFmpeg y puede ayudarte a comprender los problemas relacionados con dicha biblioteca.
  • QT_LOGGING_RULES="*.ffmpeg.*=true" activa los registros de desarrollo de Qt Multimedia en el complemento de FFmpeg. Las categorías de registro en el complemento de FFmpeg suelen denominarse «qt.multimedia.ffmpeg.XXX». Para habilitar los registros de desarrollo de todo Qt Multimedia, configura QT_LOGGING_RULES="*.multimedia.*=true"
  • Si configura tanto QT_FFMPEG_DEBUG como QT_LOGGING_RULES, se mostrarán todos los códecs de FFmpeg disponibles la primera vez que se utilice la funcionalidad de codificación o decodificación desde QMediaPlayer, QAudioDecoder o QMediaRecorder. Esta información puede ayudarle a comprender situaciones en las que Qt Multimedia no encuentra un decodificador o codificador de FFmpeg adecuado. Recomendamos adjuntar el volcado de códecs a los informes de errores de Qt si se encuentran problemas específicos relacionados con los códecs.

Habilitar códecs experimentales de FFmpeg

FFmpeg ofrece algunos códecs, como Opus o Vorbis, en calidad de experimentales. Los códecs experimentales no siguen estrictamente el estándar y pueden resultar inestables. Están desactivados por defecto. Para activarlos, configura la variable de entorno ` QT_ENABLE_EXPERIMENTAL_CODECS=1`.

Configuración de los protocolos de red permitidos

Por motivos de seguridad, la biblioteca FFmpeg restringe el uso de protocolos anidados, es decir, protocolos utilizados por otros protocolos; consulta la documentación sobre protocolos de FFmpeg. Puedes anular explícitamente los protocolos permitidos mediante la variable de entorno ` QT_FFMPEG_PROTOCOL_WHITELIST`, por ejemplo:

export QT_FFMPEG_PROTOCOL_WHITELIST=file,crypto,rtp,udp

Advertencia: Ten en cuenta que los protocolos anidados pueden introducir vulnerabilidades de seguridad cuando se utilizan con datos no fiables. Permite únicamente los protocolos que se ajusten a tus requisitos de seguridad y empresariales.

Configuración del transporte RTSP

Las secuencias de entrada RTSP se pueden abrir con un transporte inferior RTSP específico de FFmpeg configurando la variable de entorno ` QT_FFMPEG_RTSP_TRANSPORT `. El valor se pasa a la opción de entrada ` rtsp_transport ` de FFmpeg para las URL de tipo ` rtsp:// `. Por ejemplo, utilice el entrelazado TCP dentro del canal de control RTSP:

export QT_FFMPEG_RTSP_TRANSPORT=tcp

Entre los valores habituales se incluyen udp, tcp, udp_multicast, http y https; consulta la documentación del protocolo RTSP de FFmpeg. Esta opción no está activada por defecto y se ignora para fuentes multimedia que no sean RTSP.

Configurar la aceleración por hardware en los backends

  • Backends explícitos de aceleración por hardware para la decodificación y la codificación.

    El complemento de FFmpeg elige el backend de aceleración por hardware para la decodificación y la codificación en función de la disponibilidad, la estabilidad, la eficiencia y los detalles de implementación. Si el backend de hardware seleccionado no funciona como se espera, puedes intentar establecer una lista de prioridades personalizada o desactivar todos los backends de hardware mediante las variables de entorno QT_FFMPEG_DECODING_HW_DEVICE_TYPES y QT_FFMPEG_ENCODING_HW_DEVICE_TYPES. Los backends de hardware disponibles incluyen:

    • cuda
    • drm
    • dxva2
    • d3d11va
    • d3d12va,
    • OpenCL
    • QSV
    • VAAPI
    • vdpau
    • videotoolbox
    • mediacodec
    • vulkan

    Sin embargo, la disponibilidad de los backends de hardware depende del sistema operativo, de los controladores instalados, de la versión de FFmpeg y de la configuración. Es importante tener en cuenta que los responsables del mantenimiento de Qt no han probado algunos tipos de dispositivos con Qt Multimedia, por lo que es posible que no funcionen como se espera. En el momento de redactar este documento, estos backends incluyen:

    • drm
    • opencl
    • qsv
    • vdpau
    • Vulkan

    Ejemplos:

    # Set vdpau or cuda encoding hardware backends
    export QT_FFMPEG_ENCODING_HW_DEVICE_TYPES=vdpau,cuda
    
    # Set only d3d12va decoding hardware backend
    export QT_FFMPEG_DECODING_HW_DEVICE_TYPES=d3d12va
    
    # Disable decoding hw backends (set an empty list)
    export QT_FFMPEG_DECODING_HW_DEVICE_TYPES=,
  • Conversión de texturas de hardware.

    El uso de la conversión basada en la GPU para los fotogramas de vídeo descodificados y renderizados puede reducir significativamente el uso de la CPU. Nuestro objetivo es aprovechar esta característica con el mayor número posible de backends de hardware. Si detectas algún problema de renderizado, prueba a realizar el renderizado sin la conversión de texturas por GPU para identificar la causa. Puedes desactivar la conversión de texturas por GPU utilizando la variable de entorno ` QT_DISABLE_HW_TEXTURES_CONVERSION `: QT_DISABLE_HW_TEXTURES_CONVERSION=1. Con el backend de hardware ` VAAPI `, la conversión de texturas por hardware está desactivada por defecto. Establece ` QT_XCB_GL_INTEGRATION=xcb_egl ` para activarla.

  • Permitir la incompatibilidad de perfiles de códec.

    Si el perfil del códec no coincide con las capacidades indicadas del hardware, puede ignorar la discrepancia y permitir la decodificación por hardware mediante QT_FFMPEG_HW_ALLOW_PROFILE_MISMATCH=1. Configurar esta opción puede resultar útil, por ejemplo, cuando se utiliza la decodificación acelerada por hardware para el perfil básico H.264 con el backend de hardware VAAPI, ya que la mayoría de estas secuencias cumplen las restricciones del decodificador de hardware H.264 existente.

    Advertencia: Si la secuencia no es compatible, la decodificación por hardware forzada puede provocar una salida de vídeo totalmente incorrecta.

© 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.