Qt Multimedia GStreamer 백엔드

이 페이지에서는 임베디드 리눅스의 기본 미디어 백엔드인 Qt Multimedia 의 GStreamer 백엔드에 대한 제한 사항과 사용자 정의 사항을 다룹니다.

아키텍처 관련 고려 사항

GStreamer가 임베디드 리눅스의 기본 미디어 백엔드로 사용되는 주된 이유는, 대부분의 임베디드 보드 공급업체들이 하드웨어 가속 미디어 지원을 위해 이 프레임워크를 우선적으로 채택하기 때문입니다. 일부 플랫폼에서는 FFmpeg도 적합할 수 있으므로, 사용자는 두 미디어 백엔드를 모두 시험해 보고 자신에게 가장 적합한 것을 찾아보시기 바랍니다.

Qt Multimedia 는 범용 스트리밍 프레임워크가 아니며, Qt와 함께 GStreamer를 사용하는 데 있어 반드시 아키텍처적으로 최선의 방법은 아닙니다. GStreamer 파이프라인에 대한 높은 수준의 제어가 필요하지만, 비디오 출력을 Qt로만 표시하고자 하는 개발자는 GStreamer의 qml6glsink 사용을 고려해 볼 수 있습니다.

제한 사항 및 알려진 문제

GStreamer는 Qt에 포함되어 있지 않지만, 일반적으로 리눅스 배포판과 함께 제공됩니다.

• 특정 버그는 사용 중인 GStreamer 버전에 기인할 수 있습니다. 해당 플랫폼에서 최신 GStreamer 버그 수정 릴리스를 사용할 것을 권장합니다.
• 일부 버그는 Pulseaudio와 같이 GStreamer에서 사용하는 라이브러리와 관련될 수도 있습니다. 특히 Pulseaudio v16에는 GStreamer 파이프라인이 멈추게 하는 알려진 버그가 있으며, 이 문제를 해결하려면 다음 두 패치의 백포트가 필요합니다:
  • https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/745
  • https://gitlab.freedesktop.org/pulseaudio/pulseaudio/-/merge_requests/764

  이 버그는 현재 Ubuntu 22.04, 23.10, 24.04, Debian 11 및 12, Fedora 39 및 40을 포함한 대부분의 주요 리눅스 배포판에 영향을 미치고 있습니다.

• 녹화 중 카메라 장치 또는 카메라를 전환하는 기능은 지원되지 않습니다.
• 탐색, 재생 속도, 반복 재생, 싱크 전환 기능에는 알려진 버그가 있습니다.
• 오디오 기능을 사용하려면 PulseAudio가 필요합니다. 자세한 내용은 리눅스 플랫폼 참고 사항을 참조하십시오.
• 일부 임베디드 보드의 경우, 파이프라인 협상/연결 문제를 해결하고 성능을 향상시키기 위해 개별적인 구성이 필요합니다. 이러한 문제가 발생할 경우, 개발자는 ‘사용자 지정 사항’에 나열된 환경 변수를 활용하여 테스트해 볼 것을 권장합니다. Qt의 Yocto 메타 레이어 파일에는 특정 보드, BSP 및 Boot to Qt 버전의 조합에 대한 권장 구성이 포함되어 있습니다. 다음은 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
• 일부 NXP i.MX 보드는 imx-capture라는 v4l2 장치를 노출하는데, 이는 GStreamer의 v4l2src와 함께 사용할 때 오류를 일으킬 수 있습니다. Qt Multimedia 가 사용 가능한 카메라 장치 목록에 imx-capture를 추가하지 않도록 하려면, 환경 변수 QT_GSTREAMER_SKIP_IMXCAPTURE=1을 설정하십시오. 이는 비공개 API로 간주되며, NXP 에서 imx-capture 관련 문제가 수정되면 제거될 예정입니다.
• 시스템 메모리 비디오 프레임이나 소프트웨어 변환을 사용하는 비디오 재생 또는 카메라 스트리밍은 CPU 부하가 과도해져 프레임 누락이나 응답 불능 현상을 초래할 수 있습니다. GStreamer 디코더나 카메라 장치가 지원되는 픽셀 형식 중 하나로 DMA-BUF 또는 GLMemory 기반의 비디오 프레임을 출력하는 경우, Qt는 추가적인 변환이나 복사 없이 이를 렌더링할 수 있습니다. GStreamer는 파이프라인 요소의 기능에 따라 형식과 메모리 유형을 선택합니다. 파이프라인에 어떤 요소를 추가할지 제어하는 다양한 방법은 ‘사용자 정의 사항’ 섹션에 설명되어 있습니다. ‘v4l2 카메라의 I/O 모드 지정’ 항목도 참조하십시오.

사용자 정의 지점

Qt Multimedia 는 기본 GStreamer 파이프라인에 접근할 수 있도록 특정 사용자 정의 지점을 제공합니다. 진입점은 ` QGStreamerInterface`입니다. 환경 변수를 설정하여 추가적인 사용자 정의를 수행할 수 있습니다.

외부 OpenGL 텍스처 렌더링

Qt OpenGL은 기본 버퍼를 EGL 이미지로 바인딩하고 이를 OpenGL 텍스처로 셰이더에 노출함으로써, DMA-BUF 기반의 비디오 프레임을 OpenGL 그래픽 파이프라인으로 가져옵니다. 기본적으로 Qt OpenGL은 GL_TEXTURE_2D 텍스처 타깃과 표준 셰이더 코드를 사용하여 이러한 텍스처를 샘플링합니다. 일부 임베디드 보드의 경우, 전용 프래그먼트 셰이더와 함께 GL_TEXTURE_EXTERNAL_OES 텍스처 타깃을 사용할 때 더 나은 성능을 보입니다. 다음 환경 변수를 설정하여 이 동작을 활성화할 수 있습니다:

QT_MULTIMEDIA_FORCE_GL_TEXTURE_EXTERNAL_OES=1

v4l2 카메라의 I/O 모드 지정

QCamera 나 QML 카메라와 함께 v4l2 캡처 장치를 사용할 때, 기본 v4l2src GStreamer 요소의 io-mode 속성은 제로 카피 렌더링을 허용하는 DMA-BUF 기반 비디오 프레임을 출력할지 여부에 영향을 미칩니다. 경우에 따라 카메라 드라이버가 dmabuf 모드를 지원하더라도 기본값인 auto 모드가 mmap 모드를 선택하기도 합니다. io-mode 속성의 정수 값은 아래 환경 변수를 통해 명시적으로 설정할 수 있습니다. 다음은 enum GST_V4L2_IO_DMABUF를 사용하여 io-mode를 dmabuf로 설정하는 예시입니다:

QT_GSTREAMER_V4L2SRC_IOMODE=4

특정 GStreamer 요소 선택

GStreamer 배포판에는 미디어 파이프라인에서 동일한 작업을 수행할 수 있는 여러 가지 플러그인이 포함될 수 있습니다. GStreamer는 기능 순위(feature rank)에 따라 디코더나 디멀티플렉서와 같은 요소를 자동으로 선택하며, 이는 GStreamer 환경 변수를 통해 재정의할 수 있습니다. 다음은 v4l2h264dec 하드웨어 디코더의 우선순위를 모든 H.264 소프트웨어 디코더보다 높게 설정하고, 동시에 aiurdemux 디멀티플렉서가 선택되지 않도록 하는 예제입니다:

GST_PLUGIN_FEATURE_RANK=v4l2h264dec:MAX,aiurdemux:NONE

실행 중에 어떤 요소가 생성되고 있는지 확인하려면 GstElementFactory에 대해 디버그 로깅 레벨 4를 활성화하십시오:

GST_DEBUG=GST_ELEMENT_FACTORY:4

또한, 재생 상태 변경과 같은 다양한 이벤트 발생 시 덤프되는 .dot 그래프 파일을 저장할 폴더를 지정하여 전체 GStreamer 파이프라인을 시각적으로 확인할 수 있습니다:

GST_DEBUG_DUMP_DOT_DIR=/root/graphs

이러한 환경 변수에 대한 자세한 내용은 GStreamer 문서에서 확인하십시오:

• 환경 변수 - GST_PLUGIN_FEATURE_RANK
• 기본 튜토리얼 - 디버그 로그
• 기본 튜토리얼 - 파이프라인 그래프 가져오기

하드웨어 변환 요소 지정

GStreamer 파이프라인의 미디어 소스가 ` Qt Multimedia`에서 지원하는 픽셀 형식의 비디오 버퍼를 제공할 수 없는 경우, 파이프라인에는 적절한 하드웨어 가속 비디오 변환 요소가 포함되어 있지 않으면 소프트웨어 변환이 사용됩니다. 사용할 하드웨어 변환 요소를 지정하려면 다음 환경 변수에 GStreamer 파이프라인 설명으로 설정하십시오:

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT

사용 가능한 경우 일부 벤더 전용 변환 요소(imxvideoconvert_g2d, nvvidconv)가 기본적으로 파이프라인에 추가됩니다. 이는 필요하지 않은 경우 불필요한 변환을 유발할 수 있으며, 동일한 환경 변수를 사용하여 GStreamer 정체성 요소를 지정함으로써 비활성화할 수 있습니다:

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=identity

GStreamer는 OpenGL 요소를 사용하여 포맷 변환을 수행할 수도 있으며, 이를 통해 Qt에 GLMemory 기반의 비디오 프레임을 제공할 수 있습니다:

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=glupload ! glcolorconvert

파이프라인에 대한 직접 액세스

QMediaPlayer 및 QMediaCaptureSession 의 기반이 되는 ` GstPipeline `에 접근할 수 있습니다.

#include <QtMultimedia/spi/qgstreamerinterface.h>

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

싱크 및 소스로서의 사용자 정의 GStreamer 요소

GStreamer 파이프라인 설명으로부터 GStreamer 요소를 생성하고, 이를 QGStreamerVideoSource 또는 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: 사용자 정의 소스

QMediaPlayer 는 소스 URI로 GStreamer 파이프라인 설명을 받아들입니다:

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

이렇게 하면 파이프라인 설명을 컴파일하여 QMediaPlayer 의 소스로 사용하도록 시도하며, QMediaPlayer 의 싱크에 자동으로 연결됩니다.