If you upgraded Hyprland recently and found that an old wf-recorder command suddenly started printing Failed to copy frame, retrying... until it gave up, you did not hallucinate it. A small but important chunk of the Wayland capture stack has moved on.

The short version is this:

This is one of those annoying Linux desktop moments where a protocol that was “temporary but useful” accidentally became infrastructure. Then the future arrived, and it arrived without asking your shell scripts for permission.

The immediate symptom

The most concrete public report is in wf-recorder issue #273, a thread that started as a question about support for the new protocols and later turned into a bug report in disguise.

A Hyprland user reported that after Hyprland implemented the new image capture protocols, a standard command like this:

wf-recorder -g "$(slurp)" -f screencast-$(date +%Y-%m-%d_%H-%M-%S).mp4

started doing this:

Detected output based on geometry: DP-1
selected region 1490,97 426x528
Failed to copy frame, retrying...
Failed to copy frame, retrying...
...
Failed to copy frame too many times, exiting!

That thread matters because it has three unusually candid data points:

  1. wf-recorder support for the new protocol family was not something the maintainer was rushing toward.
  2. There was an implementation attempt, but it was incomplete.
  3. The person attempting the port eventually pointed users at a different project.

The maintainer, @ammen99, wrote:

“If someone sends a PR, I don’t see why not. However I am not in a hurry…”

Later, collaborator @soreau pointed at an experimental branch for the newer protocol family, and then in the related porting work effectively threw in the towel with this line:

“I have learned there is wl-screenrec now which apparently supersedes this project. Giving up on this attempt.”

That’s not a polished migration guide, but it is about as direct a recommendation as you’ll get from inside the wreckage.

What wlr-screencopy actually was

The protocol being retired here is wlr-screencopy-unstable-v1, one of the old wlroots-family Wayland extensions.

It did one job: let a privileged client ask the compositor to copy pixels from the screen into a client-provided buffer.

At a high level, the flow looked like this:

  1. bind a zwlr_screencopy_manager_v1
  2. request a frame from an output or a region of an output
  3. compositor advertises supported buffer types and dimensions
  4. client allocates a matching wl_buffer
  5. client sends copy or copy_with_damage
  6. compositor replies with ready or failed

The important thing is that the model was fundamentally output-centric:

That was enough for a lot of useful tools:

And to its credit, wlr-screencopy did improve over time. Version 3 added damage reporting and a wait-for-damage mode. That made it less stupid than the first generation of “copy the whole frame every time and pray” tooling.

But it still had the limitations of its origin: it was a wlr unstable protocol, not the long-term standard answer for the wider Wayland ecosystem.

Wayland Explorer now puts the warning directly at the top of the page:

“This protocol is deprecated and not intended for production use. The ext-image-copy-capture-v1 protocol should be used instead.”

That is not subtle.

Why it was replaced instead of extended

The best explanation I found is Andri Yngvason’s write-up, Making a Wayland Screen Capturing Protocol. It is worth reading in full because it explains both the technical motivation and the politics of how Wayland protocols actually get made.

The original draft for the replacement started life as a better screencopy protocol, but over time the design evolved into a more general architecture. The key change was introducing a second protocol layer: image sources.

That is what gave us the split between:

Old model: source and capture are fused

In wlr-screencopy, the protocol more or less bakes in both of these questions at once:

The answer is basically “an output or output region, copied into a buffer.”

That works until you want richer capture targets.

New model: source and capture are separated

The newer architecture says:

That sounds abstract, but it buys three concrete things immediately.

1. Outputs and windows fit the same model

ext-image-capture-source-v1 can represent:

This is a big deal.

With wlr-screencopy, whole-screen capture was natural and window capture was bolted on elsewhere, if at all. With the new model, capturing an output and capturing a toplevel are structurally similar operations.

That matters to compositors because they can stop carrying separate piles of awkward rendering logic for:

Hyprland’s implementation PR literally describes part of the goal as:

“unify all screen/window/region sharing rendering code”

That is the right instinct.

2. Damage tracking got meaningfully better

This is the subtle one, and the one most people never see because the UX of screen recording is “did it work, yes/no”.

wlr-screencopy version 3 can tell the client which parts of the image changed since the previous frame. That helps downstream encoders and lets clients wait for damage.

But the replacement protocol goes further.

With ext-image-copy-capture-v1, the client can tell the compositor:

This matters when clients do double-buffered capture.

Suppose a recorder alternates between buffer A and buffer B.

That means the compositor does not need to recopy the whole frame. It can update only:

This is exactly the kind of boring systems-engineering improvement that pays off in CPU use, memory bandwidth, and latency. It is not sexy, but it is real.

Andri Yngvason calls this out explicitly in his article as one of the motivations for the new protocol.

3. Cursor capture is first-class instead of awkward

The new protocol family also adds proper cursor capture:

That matters for VNC, remote desktop, and mirroring software because it allows the remote side to render the cursor locally. The result is lower perceived latency when you move the mouse.

Again, that is not just a nice extra. For remote desktop it is the difference between “feels sluggish” and “feels plausible”.

4. It is trying to be a Wayland-wide answer, not a wlroots-only one

This is the larger ecosystem point.

wlr-screencopy lives in the wlr unstable namespace. It was useful, but it was never a great long-term center of gravity for everybody.

The replacement lives in wayland-protocols, under the ext / staging path. That is the route toward broader standardization.

This is not just protocol bikeshedding. It changes the incentives:

What Hyprland changed

Hyprland implemented the new protocol pair in PR #11709: implement image-capture-source-v1 and image-copy-capture-v1, merged in February 2026.

That PR is more informative than most because the author documented actual test procedures and real tools used to exercise the new stack.

The test matrix included:

The PR description also noted this command for testing the new backend directly with wl-screenrec:

./target/debug/wl-screenrec -o HDMI-A-1 -capture-backend=ext-image-copy-capture

And, notably, the author wrote that the Arch package at the time had broken transforms and recommended building from source for that test.

That detail matters because it shows what Hyprland’s capture work was being validated against in practice:

Hyprland’s own wiki is also pretty clear about where the preferred capture path lives now. The page on Screen sharing says:

And in a Hyprland forum thread about portal startup, Vaxry suggested using OBS via PipeWire as the way to verify that the stack works.

That does not mean “everything must be OBS now.” It does mean the center of gravity has shifted:

Why wf-recorder in particular got stranded

wf-recorder was not abandoned in a general sense. The repository is still active, and there have been unrelated fixes as recently as 2026.

But the capture backend it relies on is the wrong one for the direction the ecosystem is moving.

The key issue is still wf-recorder #273, which reads almost like a compressed postmortem:

There was also a porting PR, wf-recorder #322, titled Switch to ext-copy-capture protocols instead of wlr-screencopy protocol. The title says exactly what needed to happen.

The comments in that PR are revealing because they show there is real protocol complexity here, not just a boring rename:

That is why “just add support for the new protocol” turns out not to be a one-line patch.

It also explains why wf-recorder is not automatically the right horse to bet on for the future, even if it technically could be made to work.

The protocol details that actually matter

If you maintain a capture tool, or just like understanding where the pain comes from, these are the useful differences.

wlr-screencopy

The old protocol is centered around a single frame object:

Conceptually, the compositor owns the capture state and tells the client about damage.

ext-image-copy-capture

The new protocol is organized around a session and explicit frame objects:

This buys several improvements:

So when a legacy client built around wlr-screencopy talks to a compositor that has moved its implementation strategy toward the newer protocols, you are not dealing with a cosmetic mismatch. You are dealing with a different capture model.

What to use now on Hyprland

There are really two answers, depending on what kind of user you are.

If you want the mainstream, least-surprising path

Use OBS Studio via PipeWire.

That is the boring answer, which is usually the right one.

It is what Hyprland documentation and forum guidance orbit around. It is also the answer that is least entangled with wlroots-era assumptions.

On Arch, obs-studio is in the official repositories:

If you want the thing closest in spirit to wf-recorder

Use wl-screenrec.

This is the project that keeps coming up when people working through the transition ask: “fine, but what is the new CLI-ish recorder?”

It matters that:

On Arch, wl-screenrec is not in the official repos at the time of writing, but it is on the AUR:

If you are on Hyprland and liked wf-recorder because it was small, scriptable, and not a giant streaming suite, this is the most natural successor.

If you care about low overhead and hardware encode paths

There is also GPU Screen Recorder, which is in the official Arch repos:

This is less “the canonical protocol transition answer” and more “a very practical recorder that performs well.” It is still a good option, just not the one that emerged directly from the wf-recorder breakage discussion.

If you just want a GUI button

Kooha remains a perfectly decent simple GUI recorder:

It is not a replacement for the old wf-recorder shell-script niche, but not everybody needs every tool to be a shrine to Unix composability.

Official Arch repo vs AUR

For Arch users, the split is simple.

Official repos

AUR

If you want the most future-aligned CLI replacement for wf-recorder, the annoying answer is still the real one: the good option is in the AUR.

What this says about Wayland in 2026

A lot of “Wayland is immature” commentary is stale. Most of it has been stale for years. But this kind of breakage is the sort of thing that still makes the desktop feel more provisional than people want to admit.

The irony is that the new protocol direction is technically better.

It gives us:

That is all good.

What still feels rough is the migration layer:

This is very Wayland. The architecture gets better. The user gets punched in the face by a missing compatibility story.

What to do if your old workflow was wf-recorder -g "$(slurp)"

If your old habit looked like this:

wf-recorder -g "$(slurp)" -f clip.mp4

the practical advice is:

  1. stop expecting wf-recorder to be the long-term answer on Hyprland
  2. install wl-screenrec if you want the closest conceptual successor
  3. keep obs-studio around as the reliable fallback and for any workflow involving PipeWire, scenes, multiple sources, or just wanting the thing to work
  4. if performance and long-running recordings matter more than protocol purity, evaluate gpu-screen-recorder

In other words:

If you want the shortest possible path through the evidence, read these in order:

  1. wlr-screencopy-unstable-v1 protocol page — note the deprecation warning
  2. Andri Yngvason: Making a Wayland Screen Capturing Protocol — explains the design and rationale for the replacement
  3. ext-image-capture-source-v1 protocol page
  4. ext-image-copy-capture-v1 protocol page
  5. Hyprland PR #11709 — implementation of the new protocols
  6. wf-recorder issue #273 — where the user-facing failure becomes visible
  7. wf-recorder PR #322 — attempted migration off wlr-screencopy
  8. Hyprland wiki: Screen sharing
  9. Hyprland forum thread about portal startup / OBS via PipeWire
  10. wl-screenrec repository

Bottom line

Nothing “mystical” happened here.

A deprecated wlroots-era protocol reached the end of its useful life. A better protocol family replaced it. Hyprland moved. wf-recorder did not keep up cleanly enough. Users noticed because the easiest old commands stopped working.

That does not mean Hyprland broke screen recording out of spite. It means the capture stack is being rebuilt on a better foundation and one of the old clients got stranded between eras.

Which, to be fair, is still a breakage. It is just a breakage with a decent technical case behind it.