The Bug: A Recording That’s Just… Black
I was building a Linux version of Screen Capture — the free screen recorder I’d already shipped for Mac — and the first real test on a Linux machine gave me a video file that opened fine, played fine, and showed absolutely nothing. Just black, start to finish. Audio was there. The window I was trying to record wasn’t.
No error, no crash, no obvious clue. Just a black rectangle where my desktop should have been. That’s a specific kind of frustrating — the tool thinks it worked.
Diagnosing It: Ruled Out at the System Level
My test machine runs Wayland (Ubuntu 26.04, GNOME/Mutter), and the app’s video backend tries the modern, Wayland-native capture path first: PipeWire, via the desktop’s screen-cast portal. That’s the sanctioned way to record a Wayland session — you get a real permission prompt, and it’s what OBS Studio, Firefox, and Chrome all use for screen sharing on Wayland today. It’s supposed to just work.
On this machine, it didn’t. PipeWire capture came back black — and to make sure it wasn’t something dumb in my own code, I tested OBS Studio’s native PipeWire source on the same machine. Same result: solid black. That ruled out the app entirely. Whatever was wrong was below the application layer.
The actual root cause: my GPU is a GTX 1080 — Pascal generation, from 2016 — which is permanently capped at NVIDIA’s 580.xx “Legacy” driver branch. That branch’s DMA-BUF/GPU-buffer-sharing handoff with Mutter has a real bug. The compositor and PipeWire negotiate a buffer, but what actually lands in it is nothing.
This isn’t Wayland refusing to hand over the screen. PipeWire is the sanctioned, working path — it just hit a real bug in an old GPU’s driver branch, several layers below where the app or Wayland itself has any control.
Worth being honest about the outlook here too: NVIDIA’s Legacy branch gets security and critical bug fixes, not new DMA-BUF/buffer-sharing development — and Pascal is thoroughly aged out of their active branch. So this isn’t really a “wait for Wayland” problem. It’s a “wait for NVIDIA to backport a fix to a driver branch they’ve functionally stopped extending” problem, which in practice means it’s unlikely to ever get fixed on this hardware. That’s exactly why the app can’t just assume PipeWire will work — it has to check.
The Real Fix: Try PipeWire First, Validate It, Fall Back When It’s Broken
The app’s backend selection doesn’t just attempt PipeWire and hope. It attempts PipeWire, then actually checks whether real frame content came back — not just whether the pipeline opened without erroring, which is exactly the kind of false-positive that would have shipped a “working” recorder that silently produces black video on hardware like mine.
- If PipeWire delivers real captured content, the app uses it. That’s most people — AMD and Intel graphics, and NVIDIA hardware on a current driver branch, should get Wayland-native capture with zero manual steps.
- If PipeWire’s output validates as black or empty, the app falls back to FFmpeg’s
x11grabinstead — which needs a genuine X11/Xorg session to read from.
One trap worth naming here, because it’s an easy wrong turn once you’re in fallback territory: XWayland being installed does not mean you have a real X11 session. XWayland lets old X11 applications run as individual windows inside Wayland — it doesn’t hand x11grab a copy of the whole desktop. You can have XWayland fully installed and running and x11grab still has nothing usable to capture. I made this assumption myself early on, and it’s wrong.
Getting the X11 Fallback Working, When You Need It
If the app falls back to x11grab — or you just want to check ahead of time — this is how to confirm which session you’re actually running:
echo $XDG_SESSION_TYPEIf that prints wayland and the app has told you PipeWire capture isn’t producing real content, here’s what’s actually confirmed to fix it. Some systems show a “Ubuntu on Xorg” or “GNOME on Xorg” option behind the gear icon on the login screen — worth trying first, it’s the lightest possible fix. On my machine it wasn’t reliably there, so:
- Install Xfce:
sudo apt install xubuntu-desktop - If asked which display manager to keep as default, keep gdm3.
- Reboot.
- On the login screen, click the gear icon and choose Xfce as the session.
- Log back in and re-check
echo $XDG_SESSION_TYPE— it should now sayx11.
Once that says x11, x11grab has a genuine desktop to read from, and the app’s own “Detect Capture Method” button will confirm it’s working.
The Extra Step: I Built an App That Figures This Out For You
Diagnosing a DMA-BUF handoff bug in a legacy NVIDIA driver branch isn’t something I want to hand anyone as “here’s how you record your screen on Linux.” So I built the actual app — a GTK4 interface driving FFmpeg 9 underneath, recording your screen and your microphone and the computer’s sound together into one file, same as the Mac version already did.
A few decisions that came directly out of everything above:
- It tries PipeWire first, automatically — the correct, modern, Wayland-native path that most users on healthy hardware should get with zero manual steps.
- It doesn’t trust that PipeWire “opened successfully” — it validates that real frame content came back before committing to that backend, so a driver-level bug like mine doesn’t silently ship a black recording.
- If validation fails, it falls back to
x11grabautomatically, and a built-in “Detect Capture Method” button tells you right in the window which path is actually active — no terminal commands required to find out. - Everything is bundled into the download — FFmpeg 9, the GTK4 runtime, GStreamer, PulseAudio/PipeWire client libraries — because Linux distros vary too much to assume any of that is already installed. No package manager, no root password, no install script.
- It’s a ~305 MB download because of that bundling. Extract and run:
tar -xzf LinuxScreenRecorder_*.tar.gz, then./run.sh. - Marked Beta, on purpose — it’s newer and less tested than the Mac version, and I’d rather say that upfront than have someone find out the hard way.
Here it is actually recording, on a real Linux machine, x11grab and all:
If your Linux recording comes out black, it’s worth knowing it’s probably not your fault, and it’s probably not even Wayland’s fault — it’s most likely one specific layer, your GPU driver’s buffer handoff, having a bad day. The app checks for that automatically now, so you don’t have to go find it yourself.
In the future should I get a different graphics card, I will try the Pipewire method again, cheers!
