GStreamer + waylandsink on MediaTek Genio: display output setup

On MediaTek Genio running IoT Yocto, waylandsink is the correct GStreamer element for sending video to a display. It integrates with the Weston Wayland compositor that runs by default in the BSP. Getting it working requires the right environment variables, a correct pipeline, and knowing how to target a specific physical output when your board has both DSI and HDMI active.

Key Insights

• waylandsink only works when Weston is running — it is a Wayland client, not a DRM/KMS sink
• WAYLAND_DISPLAY must be set in the environment where gst-launch-1.0 runs — SSH sessions do not inherit this automatically
• Use the display property to target a specific output (HDMI-A-1, DSI-1) — without it, Weston picks the output
• kmssink bypasses Weston and writes directly to the framebuffer — use it only when running without a compositor
• Running two pipelines to two outputs simultaneously is supported on Genio 720 and 1200

What is waylandsink and why does Genio use it?

waylandsink is a GStreamer element that renders video frames as a Wayland surface. It communicates with the running Weston compositor over the Wayland socket, and Weston handles compositing the surface onto the physical display.

IoT Yocto starts Weston by default on boot. Because Weston owns the display hardware, any application that wants to show video must go through Weston — which means using waylandsink, not kmssink or autovideosink (which tries X11 first and fails on a Wayland-only system).

The MediaTek-specific waylandsink in IoT Yocto is not the same as the upstream GStreamer waylandsink from gstreamer1.0-plugins-bad. It is a proprietary plugin that integrates with the MTK multimedia stack for zero-copy buffer handling between the decoder and the display. For the full list of GStreamer packages available in the Yocto build, see adding GStreamer plugins to Genio IoT Yocto.

How do you set up a basic display pipeline?

The minimal working pipeline:

export WAYLAND_DISPLAY=wayland-0
gst-launch-1.0 videotestsrc ! videoconvert ! waylandsink

With a V4L2 camera source:

export WAYLAND_DISPLAY=wayland-0
gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! waylandsink

With hardware-decoded video:

export WAYLAND_DISPLAY=wayland-0
gst-launch-1.0 filesrc location=test.mp4 ! qtdemux ! h264parse ! mtkvdec ! waylandsink

The WAYLAND_DISPLAY variable points to the Weston socket. On IoT Yocto it is typically wayland-0 and the socket lives at /run/user/0/wayland-0. If you run as a non-root user, check /run/user/<uid>/ for the socket path.

How do you target a specific display output?

Boards with both DSI and HDMI outputs need explicit output targeting. Without it, Weston puts the surface on whichever output it considers primary, which may not be what you want.

First, list available outputs:

weston-info | grep "output"

Output names follow the DRM connector convention: DSI-1 for the MIPI DSI panel, HDMI-A-1 for HDMI. Then specify the target:

gst-launch-1.0 videotestsrc ! videoconvert ! waylandsink display=HDMI-A-1

For two simultaneous outputs, run two pipelines:

# Terminal 1 — DSI panel
gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! waylandsink display=DSI-1 &

# Terminal 2 — HDMI monitor
gst-launch-1.0 filesrc location=video.mp4 ! qtdemux ! h264parse ! mtkvdec ! waylandsink display=HDMI-A-1 &

Both pipelines are independent Wayland clients. Weston composites them to their respective outputs.

waylandsink vs kmssink: which to use?

	waylandsink	kmssink
Requires Weston	Yes — Weston must be running	No — talks to DRM directly
Conflicts with Weston	No	Yes — will fail if Weston is active
Compositor overhead	One vsync (~16ms at 60fps)	None
Zero-copy support	Yes (MTK implementation)	Yes
Multi-window/overlay	Yes — Weston composites	No — single plane
Use case	Standard IoT Yocto application	Kiosk / bare framebuffer / headless

Use waylandsink for any application running on the standard IoT Yocto image with Weston. Use kmssink only if you have stopped Weston and are building a system that owns the display hardware directly.

To stop Weston before using kmssink:

systemctl stop weston
gst-launch-1.0 videotestsrc ! videoconvert ! kmssink

What are the common waylandsink failures?

“Could not connect to Wayland display” — WAYLAND_DISPLAY is not set or points to a non-existent socket. Check ls /run/user/0/ for the actual socket name and export it.

“No element waylandsink” — The MTK waylandsink plugin is not installed. It comes from the NDA BSP layer (meta-mediatek-bsp-private). The public build includes a fallback but it lacks hardware acceleration.

Black window appears but no video — Pipeline is running but videoconvert is producing a format waylandsink cannot handle. Add ! video/x-raw,format=NV12 ! before waylandsink to force a compatible format.

Video appears on wrong output — display property is not set and Weston chose the other output. Use waylandsink display=HDMI-A-1 explicitly.

Tearing on HDMI — Weston’s frame sync is not aligned with your source. Add sync=true to waylandsink to force timestamp-based synchronization.

---

Building on MediaTek Genio and need help with GStreamer pipelines, display bringup, or Yocto BSP work? ProventusNova specializes in embedded Linux on Genio. See our GStreamer pipeline service or get in touch.