MPV: Testing Custom Video Geometry in Yocto Project

MPV allows precise control over video geometry in the Yocto Project using command-line flags like --geometry. This enables developers to position and resize video windows programmatically, which is essential for custom embedded UI layouts where standard fullscreen playback does not meet design requirements.

Understanding MPV Geometry Flags

When integrating media players into embedded Linux systems built with the Yocto Project, the default behavior of mpv is often to maximize the window or fit it to the screen. However, many embedded interfaces require a specific region of the display to be dedicated to video content. The --geometry flag provides this granular control by accepting a string that defines the width, height, and horizontal/vertical offset from the top-left corner of the screen. The syntax generally follows the pattern +X+Y or WxH+X+Y, where X and Y represent the coordinates from the left and top edges respectively, and W and H define the dimensions. If you omit the dimensions, MPV will use the native resolution of the video file. It is crucial to ensure that the target display configuration in your Yocto image supports the desired resolution and that the compositor (if any) allows window positioning as expected. For more complex video manipulation tasks, such as stabilizing large videos before they are played back, you might need to preprocess the footage. You can learn more about preprocessing techniques in our guide on How to Stabilize a Large Video Using Linux Mint and ffmpeg Software.

Implementing the Test Script

To verify that your Yocto build correctly passes geometry arguments to the MPV binary, you should create a simple shell script. This script isolates the geometry parameters from other potential variables, ensuring that any issues stem from the rendering layer rather than file permissions or codec support. Create a file named test_geometry.sh and make it executable. Inside, define the path to your test video and the specific geometry string. For example, if you want a 640x480 video positioned at 100 pixels from the left and 50 pixels from the top, the argument would be 640x480+100+50.

#!/bin/sh
VIDEO_PATH="/path/to/your/video.mp4"
GEOMETRY="640x480+100+50"

echo "Starting MPV with geometry: $GEOMETRY"
mpv --geometry="$GEOMETRY" "$VIDEO_PATH"

Run this script from the terminal within your Yocto target environment. Observe the window placement carefully. If the video appears in the wrong location, check if the coordinate system origin matches your expectations; some compositors may treat the top-left corner differently depending on multi-monitor setups or scaling factors. If you encounter errors related to output formats when trying to render these geometries, particularly with hardware acceleration, refer to our troubleshooting guide on Troubleshooting: 'v4l2' is not a suitable output format.

Debugging Common Issues

One common pitfall is assuming that the geometry is applied immediately upon startup. In some configurations, especially those using Wayland or specific X11 window managers, there may be a delay between the launch command and the actual window mapping. If the video flashes briefly in fullscreen before moving to the correct geometry, try adding the --no-border and --no-osc flags to reduce visual noise during debugging. Another issue arises when the specified geometry exceeds the physical screen boundaries. MPV will typically clamp the values to fit within the available desktop area, but the exact behavior depends on the window manager. Always test with coordinates well within the safe zone of your display resolution first.

Integrating with Embedded UI Frameworks

In production environments, you rarely run MPV as a standalone application. Instead, it is often launched by a higher-level framework like Qt, GTK, or a custom C++ controller. When launching MPV from code, ensure that environment variables such as DISPLAY are correctly set so the process knows which X server or Wayland socket to connect to. Passing the geometry string via an API call requires careful string escaping. If your UI framework constructs the command line dynamically, ensure that special characters in the geometry string do not interfere with shell interpretation. Using direct library calls or subprocesses with argument arrays is safer than constructing a single command string. For scenarios where you need to generate static frames or manipulate video streams based on specific timing, such as generating a video with an image every few seconds, understanding the underlying FFmpeg pipeline can be beneficial. See how to Generate a video with an image every 5 seconds using ffmpeg to complement your playback strategies.

Verifying Hardware Acceleration Compatibility

Geometry testing is also a good way to verify that your hardware acceleration backend is functioning correctly. Some hardware decoders may not support arbitrary window positioning due to fixed buffer allocations. If the geometry flag is ignored or causes a crash, switch the vo (video output) driver explicitly using --vo=xx (e.g., x11, wayland, or drm) to isolate the problem. Check the MPV log output (-v flag) for warnings about unsupported features. In Yocto images, ensure that the appropriate drivers for your SoC are included in the MACHINE_FEATURES and that the kernel modules are loaded.

Frequently Asked Questions

Does MPV support multiple monitors in Yocto?

Yes, MPV supports multi-monitor setups provided the underlying display server (X11 or Wayland) exposes them. You can specify geometry relative to a specific monitor by knowing its offset coordinates. Ensure your Yocto image includes the necessary display server packages for your hardware.

What happens if the geometry is larger than the screen?

MPV will typically scale down the video or clip the window to fit within the available desktop area, depending on the window manager's rules. It does not automatically scroll the screen. You should always test with dimensions smaller than the primary display resolution to avoid unexpected clipping.

Can I change geometry while the video is playing?

No, the --geometry flag is read only at startup. To change the position or size dynamically, you must send key bindings to MPV, such as pressing f for fullscreen or using OS-specific window management commands. There is no runtime parameter to update the geometry string mid-playback.

Why is my video blurry when resizing?

Blurry video usually results from software scaling algorithms being used instead of hardware-accelerated upscaling or downscaling. Check your MPV configuration for --scale and --cscale settings. Using a sharper scaling algorithm like or enabling hardware decoding can significantly improve quality during geometric transformations.

How do I debug why MPV ignores my geometry flag?

Start by running MPV with the -v verbose flag to see if it reports parsing the geometry correctly. Then, verify that your window manager is not overriding window placements. Try forcing a specific video output driver like --vo=x11 to rule out compositor-specific bugs in your Yocto build.