Qt Multimedia GStreamer バックエンド

このページでは、組み込み Linux でのデフォルトのメディアバックエンドであるQt Multimedia の GStreamer バックエンドの制限事項とカスタマイズのポイントについて説明します。

アーキテクチャに関する考察

GStreamer が組み込み Linux のデフォルトのメディアバックエンドである主な理由は、 ほとんどの組み込みボードベンダがハードウェアアクセラレーションによるメディア サポートを優先するフレームワークだからです。プラットフォームによっては FFmpeg も適している場合があるので、ユーザは両方のメディアバックエンドを試してみて、自分に最適なものを見つけることが推奨されます。

Qt Multimedia は汎用的なストリーミングフレームワークではなく、Qt で GStreamer を使用するアーキテクチャ的に最良の方法とは限りません。GStreamer のパイプラインを高度に制御する必要があるが、Qt でのビデオ出力のみを行いたい開発者は、GStreamer のqml6glsink の使用を検討するとよいでしょう。

制限と既知の問題

GStreamer は Qt にバンドルされていませんが、通常 Linux ディストリビューションに同梱されています。

• 特定のバグは、使用されている GStreamer のバージョンに起因している可能性があります。お使いのプラットフォームで最新のGStreamerバグフィックスリリースを使用することをお勧めします。
• バグによっては、PulseaudioのようなGStreamerが使用するライブラリに関連している可能性もあります。特にPulseaudio v16には、GStreamerパイプラインをハングさせる既知のバグがあり、これら2つのパッチのバックポートが必要です：
  • 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を含むほとんどの主流Linuxディストリビューションに影響を及ぼしている。

• 録画中のカメラ・デバイスやカメラの切り替えはサポートされていません。
• シーク、再生レート、ループ、シンクの切り替えには既知のバグがあります。
• オーディオ機能にはPulseAudioが必要です。詳しくはLinuxプラットフォームノートをご覧ください。
• 一部の組み込みボードでは、パイプライン・ネゴシエーション/リンクの問題を解決し、パフォーマンスを向上させるために、個別の設定が必要です。このような問題に直面した場合は、カスタマイズポイントに記載されている環境変数を試してみることをお勧めします。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 がサポートしているピクセルフォーマットで出力する場合、Qt は追加の変換やコピーなしでそれらをレンダリングすることができます。GStreamer は、パイプラインエレメントの能力に基づいてフォーマットとメモリタイプを選択します。どの要素をパイプラインに追加するかを制御するさまざまな方法については、「カスタマイズポイント」で説明します。v4l2カメラのI/Oモードの指定も参照してください。

カスタマイズポイント

Qt Multimedia には、GStreamerパイプラインにアクセスするためのカスタマイズポイントがあります。エントリー・ポイントはclass QGStreamerPlatformSpecificInterface です。環境変数を設定することで、追加のカスタマイズが可能です。

外部 OpenGL テクスチャのレンダリング

Qt は、DMA-BUF バックアップされたビデオフレームを EGL イメージとしてバインドし、OpenGL テクスチャとしてシェーダに公開することで、OpenGL グラフィックパイプラインにインポートします。デフォルトでは、QtはGL_TEXTURE_2Dテクスチャターゲットと標準的なシェーダコードを使用して、これらのテクスチャをサンプリングします。組み込みボードによっては、専用のフラグメントシェーダとともに、代わりに GL_TEXTURE_EXTERNAL_OES テクスチャターゲットを使用した方が、より良いパフォーマンスが得られます。この動作は、以下の環境変数を設定することで有効にできます：

QT_MULTIMEDIA_FORCE_GL_TEXTURE_EXTERNAL_OES=1

v4l2カメラのI/Oモードの指定

QCamera または QML Camera で v4l2 キャプチャデバイスを使用する場合、基礎となる v4l2src GStreamer 要素のio-modeプロパティは、ゼロコピーレンダリングを可能にする DMA-BUF バックのビデオフレームを出力するかどうかに影響します。カメラドライバがdmabufモードをサポートしていても、デフォルトの自動モードがmmapモードを選択する場合があります。io-modeプロパティのint値は以下の環境変数で明示的に設定できます。ここでは、GST_V4L2_IO_DMABUF列挙型でio-modeをdmabufに設定する例を示す：

QT_GSTREAMER_V4L2SRC_IOMODE=4

特定の GStreamer エレメントを選択する

GStreamer ディストリビューションは、メディアパイプラインで同じタスクを実行する可能性のある複数の異なるプラグインを含むことができます。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）は、利用可能であればデフォルトでパイプラインに追加されます。これは不要な変換を引き起こす可能性があり、同じ環境変数を使用して GStreamerID要素を指定することで無効にできます：

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=identity

GStreamer は、OpenGL 要素でフォーマット変換を行うこともでき、Qt に GLMemory でバックアップされたビデオフレームを提供します：

QT_GSTREAMER_OVERRIDE_VIDEO_CONVERSION_ELEMENT=glupload ! glcolorconvert

生のパイプラインアクセス

QMediaPlayer とQMediaCaptureSession の基礎となるGstPipeline にアクセスできます。

#include <QtMultimedia/private/qgstreamer_platformspecificinterface_p.h>

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

シンクおよびソースとしてのカスタム GStreamer 要素

GStreamer のパイプライン記述から GStreamer 要素を作成し、QCamera または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: カスタム・ソース

QMediaPlayer はソースURIとしてGStreamerパイプライン記述を受け入れます：

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

これは、QMediaPlayer のソースとして使用するパイプライン記述のコンパイルを試み、自動的にQMediaPlayer のシンクに接続されます。