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は追加の変換やコピーを行うことなくそれらをレンダリングできます。 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 Cameraでv4l2キャプチャデバイスを使用する場合、基盤となるv4l2src GStreamer要素のio-modeプロパティによって、ゼロコピーレンダリングを可能にするDMA-BUFベースのビデオフレームを出力するかどうかが決まります。 場合によっては、カメラドライバが dmabuf モードをサポートしているにもかかわらず、デフォルトの auto モードが mmap モードを選択することがあります。io-mode プロパティの整数値は、以下の環境変数を通じて明示的に設定できます。以下は、列挙型 GST_V4L2_IO_DMABUF を使用して io-mode を dmabuf に設定する例です:

QT_GSTREAMER_V4L2SRC_IOMODE=4

特定の GStreamer 要素の選択

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）はデフォルトでパイプラインに追加されます。これらは必要がない場合に不必要な変換を引き起こす可能性があるため、同じ環境変数を使用して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 のシンクに自動的に接続されます。