GStreamer添加textoverlay后覆盖整个视频流问题求解

核心原因 #

该问题绝大多数场景是视频颜色格式不兼容导致的：textoverlay依赖Pango库渲染文字，对输入视频帧的颜色空间、位深要求比gdkpixbufoverlay严格，格式不匹配时会出现渲染异常，覆盖整个画布。

解决方案 #

按以下优先级排查修正：

• 在textoverlay前后补充格式转换和显式caps约束，修正后的测试管道如下：

gst-launch-1.0 tcamsrc ! xvideo/x-bayer,width=1920,height=1080,framerate=15/1  ! tcamautoexposure ! tcamwhitebalance ! bayer2rgb ! videoconvert ! video/x-raw,format=RGBx,width=1920,height=1080 ! textoverlay font-desc="Sans 24" text="test string" valignment=top halignment=left shaded-background=true ! videoconvert ! xvideosink

这里显式指定输入textoverlay的帧格式为RGBx、分辨率和源一致，同时在textoverlay输出后再加一层videoconvert适配xvideosink的输入格式要求，避免输出格式不兼容。如果RGBx格式无效，可尝试替换为ARGB、RGB等格式测试。

• 如果上述修改后依然异常，先关闭阴影背景测试：将shaded-background=true改为shaded-background=false，部分旧版本GStreamer的textoverlay存在阴影背景尺寸计算错误的bug，关闭后可验证是否是该问题导致。如果确认是背景问题，可以额外给textoverlay指定width=1920 height=1080参数强制匹配视频尺寸。
• 如果以上方案都无效，可先替换textoverlay为clockoverlay做测试，如果clockoverlay也出现全画布覆盖的问题，说明你本地的gst-plugins-base版本存在兼容性问题，可升级插件包到1.16及以上稳定版本重试。

Qt集成注意事项 #

Qt侧集成时排查逻辑和gst-launch完全一致，确保textoverlay的输入输出格式匹配上下游的插件/Qt视频接收组件的格式要求即可。

内容的提问来源于stack exchange，提问作者user3583535