There is no single screen-capture API guaranteed by Wayland. For native capture, start with the staging ext-image-copy-capture-v1 protocol, which asks a compositor to copy an output or toplevel into a buffer your client supplies. It works with the separate ext-image-capture-source-v1 source objects. The older wlr-screencopy-unstable-v1 protocol is documented as deprecated, while PipeWire is a separate media-sharing path. In every case, support is compositor- and version-specific, so test the exact desktop build you intend to ship.
What the Wayland screen-capture API actually is
Wayland defines a client/compositor protocol model rather than one universal screenshot function. A client requests capabilities from the compositor, negotiates a compatible buffer, and receives frames through protocol events. The compositor remains in control of which sources can be exposed.
The current direction is ext-image-copy-capture-v1, a staging protocol in the wayland-protocols family. Its documentation describes the purpose directly: “This protocol allows clients to ask the compositor to capture image sources such as outputs and toplevels into user submitted buffers.” Because the protocol is still in testing, its interfaces may evolve. Do not treat a successful bind on one compositor as a promise of long-term compatibility everywhere.
Source selection is deliberately separate. ext-image-capture-source-v1 provides opaque source descriptors that a capture protocol can consume. Outputs and toplevels are examples in the capture documentation, while the source design leaves room for additional source types. Your client therefore has two responsibilities: obtain the right source object and then run the image-copy session against it.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Which capture path should you choose?
| Path | Maturity | What it captures | Important implementation detail | When to use it |
|---|---|---|---|---|
ext-image-copy-capture-v1 |
Staging/testing | Image sources such as outputs and toplevels | Negotiates shared-memory or dma-buf constraints; client submits matching buffers | New native clients when the target compositor implements it |
wlr-screencopy-unstable-v1 |
Experimental and documented as deprecated | wlroots-oriented screen sources | Older protocol; its documentation points to the newer ext protocol | Compatibility with a known compositor that has not migrated |
| PipeWire screen sharing | Separate media path | Streams supplied by desktop portals or shell components | For example, GNOME Shell can provide a node containing framebuffer contents | Recording, conferencing, or media pipelines rather than direct protocol integration |
The replacement recommendation for wlr-screencopy-unstable-v1 is not a universal availability guarantee. Select by the compositor/version matrix you actually support, not by the name of the protocol alone.
Check compositor support before writing capture code
- Identify the exact environment. Record the compositor name, release, distribution package version, session type, and whether the application runs locally or through a remote desktop layer.
- Consult implementation data. The support table on the ext-image-copy-capture-v1 page distinguishes compositor/version pairs that support or do not support the protocol. Treat it as a snapshot: downstream packages and newer releases can differ.
- Verify source types. A compositor may expose an output but not a toplevel, or expose a source with restrictions. Confirm the source your application needs.
- Probe the advertised formats and dimensions. Your client cannot assume a preferred pixel format, stride, or size. The session sends constraints, and those constraints can be updated later.
- Test cursor behavior and errors. Decide whether the cursor should be painted into the frame, and exercise mismatch, stopped-session, and runtime-error paths before release.
A Wayland session by itself is not evidence that capture is available. The exact compositor and its protocol implementation determine the result.
The ext-image-copy-capture-v1 lifecycle
A reliable client follows a strict sequence. Generated client bindings come from the protocol XML; interface and listener names can vary with the version of those generated files, but the state machine is the same.
- Connect and bind the manager. Create a Wayland display connection, enumerate the registry, and bind the compositor’s image-copy-capture manager at the version it advertises. If the global is absent, report that native capture is unavailable instead of attempting an unbound request.
- Obtain an image-capture source. Ask the source-object interface for the output or toplevel descriptor required by your application. Keep this opaque object associated with the capture request.
- Create a capture session. The session represents capture of that source. Register listeners before dispatching events so that every constraint and failure is observed.
- Collect buffer constraints. The compositor advertises supported shared-memory formats and/or dma-buf formats, dimensions, and related requirements. A
doneevent marks the end of the current constraint batch. The compositor may send a later batch, so keep negotiation code able to replace old allocations. - Allocate a compatible buffer. Choose one advertised format and the exact required dimensions, then create the corresponding shared-memory or dma-buf storage. A buffer that is merely similar is not sufficient; mismatches are explicit protocol failures.
- Create one frame object. A session permits at most one live frame object at a time. Do not queue several frame objects against the same session without destroying the previous one at the proper point.
- Attach the buffer and damage. Attach the compatible buffer to the frame. Describe the area that has changed since that buffer was last captured, using coordinates relative to the buffer’s upper-left corner.
- Request capture and dispatch events. The compositor can wait for source content to change before copying a later frame, so a request does not necessarily complete immediately. Keep dispatching the Wayland event queue while waiting.
- Consume metadata before ready. On success, transform, damage, and presentation-time metadata arrive before
ready. Use those values when converting the image, synchronizing timestamps, or updating a damage-aware renderer. - Recycle safely. After
ready, the buffer may be reused. Destroy that frame object, then create the next frame if the session is continuing.
On failure, the compositor supplies a reason. Unknown runtime errors, buffer-constraint mismatches, and stopped sessions are distinct cases; log them separately so an operator can tell whether to retry, reallocate, or stop.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
Buffers, damage, and frame timing
Shared memory and dma-buf
The protocol can advertise shared-memory formats, dma-buf formats, or both. Shared memory is usually the simpler integration for a CPU image pipeline. dma-buf can fit a GPU or zero-copy pipeline, but it still has to match the compositor’s advertised format, dimensions, and modifiers when those are part of the constraints. Build allocation around the received batch rather than hard-coding a format.
Damage is required even when you do not track it
For the first capture, or whenever your application has no reliable history for that buffer, mark the entire buffer damaged. Damage is an optimization hint, not a permission filter. The compositor updates at least the union of the area you report and the frame damage it knows about, and it may reduce copying when your hint is smaller.
Damage coordinates are buffer-relative. If you reuse a pool of buffers, track damage per buffer, not merely per session; a buffer that has been idle may need a full refresh even when the source changed only in a small rectangle.
Do not assume a fixed frame rate
The compositor can defer a capture until source content changes. A caller that expects an immediate reply for every request can appear to hang even though the protocol is behaving normally. Use the presentation-time metadata and your own timeout policy, and continue dispatching events while waiting.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallRank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Cursor capture choices
The session’s paint_cursors option controls whether the pointer is composited into the captured image. When enabled, the cursor is painted onto the frame. When disabled, the cursor must not be composited into that frame.
If your application needs an independently rendered pointer, use the separate cursor-capture session. It reports cursor images and hotspot updates. A hotspot change takes effect with a subsequent frame’s ready event, so apply the new hotspot only when that frame is ready rather than modifying an image already handed to the consumer.
Implementation blueprint for a native client
Because the protocol is staging, generate bindings from the protocol XML version you ship and keep the generated header and XML in lockstep. The following is an implementation sketch, not a substitute for the generated listener signatures:
connect_to_wayland();
bind_ext_image_copy_capture_manager();
source = get_output_or_toplevel_source(target);
session = manager.create_session(source);
wait_for_constraints_done();
while (running) {
constraints = latest_constraints();
buffer = allocate_matching_buffer(constraints);
frame = session.create_frame(); /* one live frame */
frame.attach_buffer(buffer);
frame.damage(has_history(buffer) ? changed_rect(buffer)
: full_buffer_rect(buffer));
frame.request_capture();
dispatch_until_ready_or_failed(frame);
if (frame_failed_reason() == BUFFER_CONSTRAINT_MISMATCH) {
discard(buffer);
continue; /* wait for new constraints */
}
if (frame_failed_reason() != NONE) {
stop_or_report_error();
break;
}
consume_transform_damage_and_presentation_time();
consume_pixels(buffer);
destroy_frame(frame);
recycle(buffer);
}Production code should also handle a new constraint batch while a session is active, source destruction, display I/O errors, and orderly shutdown. Keep buffer allocation, frame scheduling, and pixel consumption separate so a format change does not corrupt an in-flight image.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
When PipeWire is the better architecture
For screen recording, conferencing, and portal-mediated sharing, PipeWire may be a better fit than implementing image-copy capture directly. PipeWire’s design documentation notes that GNOME Shell can supply a node containing framebuffer contents for screen sharing or recording. That node is a media-provider path; it is not the same interface as binding ext-image-copy-capture-v1. Choose PipeWire when you need a stream and the desktop’s sharing stack already provides the source, and choose the Wayland capture protocol when your application needs direct compositor-controlled image buffers.
Troubleshooting common failures
| Symptom | Likely cause | Fix |
|---|---|---|
| No capture manager appears in the registry | The compositor/version does not implement the protocol, or the global is unavailable in this session | Check the exact support entry, offer a PipeWire path where appropriate, or report unsupported capture clearly |
| Session fails with a buffer-constraint mismatch | The allocated format or dimensions no longer match the latest constraints | Discard the buffer, process the newest constraint batch, reallocate, and retry |
| Frames stop arriving | The source has not changed, or the session was stopped | Continue dispatching events; inspect the failure reason and use presentation metadata to distinguish waiting from termination |
| Captured image has no pointer | paint_cursors was not enabled |
Enable cursor painting or implement the separate cursor-capture session |
| Pointer hotspot is one frame behind | The hotspot update was applied before the frame carrying it became ready | Apply hotspot changes on the subsequent ready event |
| Only a partial or stale image appears | Damage was reported incorrectly, or a reused buffer was treated as fully current | Use full-buffer damage when history is unknown and track damage per buffer |
| Code works on one desktop but not another | Protocol support and source exposure differ by compositor and release | Test every target compositor/version and avoid assuming that a Wayland session implies identical behavior |
Performance and reliability practices
- Prefer damage-aware reuse for interactive capture, but fall back to full-buffer damage whenever buffer history is uncertain.
- Keep at least enough buffer management to avoid overwriting pixels that the consumer still reads; the protocol only permits reuse after the frame is ready.
- Do not busy-loop waiting for a frame. Dispatch the Wayland connection and let the compositor decide when changed content is available.
- Record the negotiated format, dimensions, transform, damage, and presentation time with each frame. These fields are essential when diagnosing rotated outputs, dropped updates, or timestamp drift.
- Exercise both shared-memory and dma-buf paths if your product supports both. A compositor can advertise one, the other, or both.
- Pin your generated protocol files to a known revision and retest when upgrading the compositor or wayland-protocols package, because the ext protocol is still in testing.
Or skip the browser setup
If your goal is a screenshot of a website rather than pixels from the local Wayland desktop, ScreenshotNeo is the first service to try: it removes consent banners, popups, and chat widgets before capture, bills only clean shots, and has the lowest paid plan described here.
One GET request returns PNG, JPEG, WebP, or PDF. The API supports full-page capture with lazy images loaded, CSS-selector element capture, device and viewport settings, dark mode, retina scale, custom CSS and JavaScript, click and wait actions, hidden selectors, request/resource blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, and a usage API. Every plan includes the features.
See the ScreenshotNeo documentation for parameter details. cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response identifies the result with X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000, with Growth at $15 for 15,000, Pro at $39 for 60,000, Scale at $99 for 250,000, and Business at $249 for 1,000,000. Yearly billing gives two months free. Create a free ScreenshotNeo account to try it.
FAQ
Is ext-image-copy-capture-v1 stable?
No. The protocol is marked staging/testing, so keep generated bindings and compatibility tests tied to the compositor versions you support.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Can a Wayland client capture any window?
Not automatically. The compositor decides which source objects it exposes; outputs and toplevels are examples, not a universal promise for every application or desktop.
Does PipeWire implement the same capture API?
No. PipeWire is a separate media path in which desktop components can provide stream nodes for sharing or recording.
Frequently Asked Questions
Is ext-image-copy-capture-v1 stable?
No. It is a staging/testing protocol, so compatibility must be checked against the compositor versions you support.
Can a Wayland client capture any window?
No. Source availability is controlled by the compositor; outputs and toplevels are examples rather than a universal guarantee.
Does PipeWire implement the same capture API?
No. PipeWire is a separate media-sharing and recording path.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Recommended Free Tools
