The Life of a Programmer

Creating a local screen overlay for streaming (OBS, Linux)

My new computer has a larger screen than the last one. It’s great, except it no longer matches the typical 1920×1080 streaming dimensions. I can’t adjust those dimensions without suffering scaling issues on Twitch and YouTube. I can broadcast only a part of my stream, but I can’t see the dimensions of that area. I need a local overlay that shows me what is going on.

I explored several options before I found something that worked.

First I tried display from ImageMagick. This toolkit usually has everything one wants with basic image manipulation, provided you can figure out the incredibly complex command line interfaces. Alas, I was unable to find any option that displayed the image as I wanted.

Thinking that compositing is part of the desktop, I looked into the widgets. There is a media panel in KDE. Despite being awkward to get working, it does display the image correctly: no background and properly blended. Unfortunately, it can’t be placed above other windows, since it’s a widget on the desktop.

Moving on, I find a program called qiv, a simple image viewer. I played with this a while since it seemed like it might work, but perhaps I had the options wrong. It seemed to have proper shaping of the window (ignore mouse input), but it was not compositing. Compositing refers to doing full alpha blending with the other windows on the desktop. Instead, it was doing blending against a checkerboard background, thresholding to either a fully opaque or transparent pixel for the window manager.

I gave up in frustration for a while. I assumed what I wanted was simple, but it was looking to be impossible. I wanted a cross-section of features, all which I knew where possible, but no program exposed.

I tried a few alternative approaches. I’ve used wmctrl to move windows around. It allows keeping a window above others, but there was no option to alter input handling.

xprop is general X protocol property tool. One setting, called WM_HINTS includes the input control. It was a bit difficult to figure out how to even modify this field. For reference:

xprop -id 0x08a00003 -f WM_HINTS 32i WM_HINTS
xprop -id 0x08a00003 -f WM_HINTS 32i -set WM_HINTS "67, 1, 1, 0, 0, 0, 0, 0, 144703489"

I have no idea what all those values are and could not find a combination that turned off the input handling. There may not be one.

I stumbled upon yet another program, called pqiv. This one did the full-screen compositing, but the input handling was still a problem. Before finding this, I saw another program written in Python. It turned off handling via the X Shape system but was missing the compositing. With that in mind, I searched the issues of pqiv and found something I wanted: issue 125.

That linked to another issue which had some code in it. I pulled it together, added some command line options, and created a small branch.

It does exactly what I want.

pqiv --click-through --keep-above --transparent-background --hide-info-box /projects/Current/

That composites my stream overlay and disables mouse handling.

There is also the --position option, which for some reason didn’t support negative values. It turns out, the window manager API is being stupid since wmctrl also couldn’t set a negative value for the position. It smells like some clever code from the past.

Please join me on Discord to discuss, or ping me on Mastadon.

Creating a local screen overlay for streaming (OBS, Linux)

A Harmony of People. Code That Runs the World. And the Individual Behind the Keyboard.

Mailing List

Signup to my mailing list to get notified of each article I publish.

Recent Posts