Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Wayland does not provide one universal screen-capture API. A native client normally uses the staging ext-image-copy-capture-v1 protocol, together with ext-image-capture-source-v1 source objects. Your compositor and its exact version must implement those interfaces; being logged into a Wayland session is not enough. For desktop screen sharing or recording, a PipeWire portal path may be more appropriate than implementing capture buffers yourself.

Which Wayland interface should you use?

Use ext-image-copy-capture-v1 when your application needs compositor-provided pixels in buffers that the application owns. The protocol lets a client capture image sources such as outputs and toplevels. It is still marked testing/staging, so generated bindings and behavior can evolve.

The source and capture layers are deliberately separate. ext-image-capture-source-v1 creates an opaque description of the thing to capture; the capture protocol consumes that description. This design leaves room for additional source types.

Path Best fit Status and caveat
ext-image-copy-capture-v1 Native screenshots or frame acquisition into shared-memory or dma-buf buffers Staging/testing; support varies by compositor and version
wlr-screencopy-unstable-v1 Compatibility with compositors that expose the older wlroots protocol Its documentation calls it experimental and deprecated, and recommends the newer protocol
PipeWire screen-sharing path Portal-mediated screen sharing, conferencing, and recording A media pipeline rather than direct implementation of the Wayland capture protocol; GNOME Shell can provide a framebuffer node for this use

The older protocol’s deprecation notice is a migration signal, not a guarantee that every compositor has implemented the replacement. Select at runtime and keep a fallback or a clear unsupported error.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
#1 Best Overall
Guermok Video Capture Card, 4K USB3.0 HDMI to USB C, 1080P 60FPS & 2K 30FPS
  • 【1080P 60FPS Video Capture Card】 This HDMI game capture card is based on USB3.0 high speed transmission port, input resolution up to 4K@30HZ, output resolution up to 2K@30Hz or 1920×1080@60Hz. Type c and USB interface can meet most of the devices in daily life. Easily meet the online capture, real-time recording, online meetings, live gaming and other functions, so you have a better visual enjoyment. Note: For capture use only; requires capture software to function and is not intended for direct screen casting to a monitor or TV
  • 【Ultra Low Latency Screen Sharing】 HDMI capture card is made of good quality aluminum alloy with strong heat dissipation, allowing you to enjoy ultra low latency while live gaming or video recording or live streaming, avoiding blue screens and lag. This HDMI to USBC capture card supports easy recording of good quality audio or HD video and transferring it to your computer or streaming platform, allowing you to record 60 fps HD video directly on your hard drive and real-time preview
  • 【Plug and Play, Easy to Carry】 This HDMI 1080P video capture card does not require any additional drivers or external power supply, just plug and play for fast capture. The capture card is small and lightweight, so you can put it in your bag for emergencies, making it very portable for outdoor live streaming. It's also a great way to share content in game recording, video conference, video recorder and online teaching
  • 【Wide Compatibility USB Capture Card】 Easily streams to Facebook, Youtube or Twitch. With the connection, this HDMI to USB C/3.0 video capture devices can be working on several Operating Systems and various software: Windows 7/ 8/ 10, Mac OS or above, Linux, Android, Laptop, Xbox One, PS3/PS4/PS5, Camera, DVDs, Set Top Box, Webcame, DSLR, Switch/Switch 2, TV BOX, HDTV, Potplayer/VLC, ZOOM, OBS Studio etc.
  • 【Package Content & Note】 1x HD Audio Capture Card , 1x USB 3.0 to USB C Adapter (A-side 3.0, B-side 2.0), 1x user manual. Please note that you need to restart the OBS Studio software after the audio setup is complete, otherwise it will result in no sound output. When using an adapter, if the device is recognized as USB 2.0, try using the other side with the USB-C port. Simply flip the capture card and reconnect it to be recognized as USB 3.0

Check the compositor before writing capture code

Wayland clients discover interfaces from the compositor’s registry. Check the exact desktop, compositor build, and package version you intend to support. The Wayland Explorer protocol page includes a compositor/version support table, but it is a snapshot: an unlisted downstream build may behave differently.

  • Confirm that the registry advertises the capture manager and source interfaces you need.
  • Confirm whether your desired source is an output, a toplevel, or another source type exposed by that compositor.
  • Record advertised shared-memory and dma-buf formats, dimensions, modifiers, and stride requirements.
  • Test cursor behavior, damage events, frame timing, and failure events on the exact target version.

Do not infer support merely from XDG_SESSION_TYPE=wayland. A compositor can run Wayland clients while omitting a capture protocol.

The capture lifecycle

1. Bind the managers and obtain a source

Use your language’s Wayland registry bindings to bind the image-capture manager and source manager. Ask the source manager for an opaque descriptor representing the output or toplevel you want. Keep the source object alive until the capture session no longer needs it.

2. Create a session and collect constraints

Create an image-capture session from the source. The compositor then sends a batch of buffer constraints: supported shared-memory formats and/or dma-buf formats, a required buffer size, and a done event terminating that batch. Constraints can be sent again later, so treat them as replaceable state rather than a one-time query.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

3. Allocate a matching buffer

Choose one advertised format and the exact dimensions. Allocate a shared-memory buffer or dma-buf with the required stride, offset, and modifier details. A mismatch is a protocol-level failure; do not silently submit a differently sized buffer.

4. Create one frame and request capture

A session allows at most one live frame object. Create a frame, attach the compatible buffer, report damage, and request capture. For the first frame—or whenever you have no damage history—mark the complete buffer damaged. Damage coordinates start at the buffer’s upper-left corner.

Rank #2
Capture Card, 4K HDMI Video Capture Card, Game Capture Card, 1080P 60FPS Video Capture Device, HDMI to USB 3.0 Capture Card for Streaming, Work with Camera/Xbox/PS4/PS5/PC/OBS
  • 【1080P HD High Quality】Capture resolution up to 1080p for video source and it is ideal for all HDMI devices such as PS4, PS3, Xbox One, Xbox 360, Wii U, DVDs, DSLR, Camera, Security Camera and set top box. Note: Video input supports 4K30/60Hz and 1080p120/144Hz. Does not support 4K120Hz/144Hz. Output supports up to 2K30Hz.
  • 【Plug and Play】No driver or external power supply required, true PnP. Once plugged in, the device is identified automatically as a webcam. Detect input and adjust output automatically. Won't occupy CPU, optional audio capture. No freeze with correct setting.
  • 【Compatible with Multiple Systems】suitable for Windows and Mac OS. High speed USB 3.0 technology and superior low latency technology makes it easier for you to transmit live streaming to Twitch, Youtube, Facebook, Twitter, OBS, Potplayer and VLC.
  • 【HDMI LOOP-OUT】Based on the high-speed USB 3.0 technology, it can capture one single channel HD HDMI video signal. There is no delay when you are playing game live.
  • 【Support Mic-in for Commentary】Rybozen capture card has microphone input and you can use it to add external commentary when playing a game. Please note: it only accepts 3.5mm TRS standard microphone headset.

Damage is an optimization hint, not permission to read stale pixels. The compositor updates at least the union of the area you report and the frame damage it reports, and may copy less when the hint is narrow. It may also wait until source content changes, so a request is not guaranteed to complete immediately.

5. Process metadata and reuse the buffer

On success, process transform, damage, and presentation-time metadata before the ready event. After ready, the buffer may be reused and the frame object should be destroyed. Maintain a queue or back-pressure policy if your encoder or consumer cannot keep up.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

6. Handle failure and changed constraints

Failure events identify conditions such as an unknown runtime error, a buffer-constraint mismatch, or a stopped session. For a mismatch, discard or reallocate the buffer using the latest constraints, create a new frame, and retry. A stopped session requires a new session or a user-visible unsupported-state error, depending on why the source disappeared.

Cursor capture and metadata

Cursor compositing is explicit. Set the session’s paint_cursors option when you want the pointer painted into the captured frame; without that option, the cursor must not be composited into the image. If you need an independent cursor stream, use a cursor-capture session. It reports cursor images and hotspot changes. A hotspot update takes effect with the subsequent frame’s ready event, so do not apply it retroactively to an already delivered frame.

Building a client with generated protocol bindings

The protocol XML is normally converted into language bindings with wayland-scanner (or a language-specific generator). Keep the XML version used at build time alongside your source and regenerate when you upgrade it. A typical C build sequence is:

wayland-scanner client-header ext-image-copy-capture-v1.xml ext-image-copy-capture-v1-client-protocol.h
wayland-scanner private-code ext-image-copy-capture-v1.xml ext-image-copy-capture-v1-protocol.c
cc -std=c11 capture.c ext-image-copy-capture-v1-protocol.c -lwayland-client -o capture

The exact scanner command names and package locations depend on your distribution. Your capture.c event handlers should implement the lifecycle above: registry binding, constraint collection through done, exact buffer allocation, full damage on an initial frame, metadata handling, ready/failed callbacks, and frame destruction.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
Video Capture Card, 4K USB3.0 HDMI to USB C, 1080P60FPS HDMI Capture Card for Streaming, Gaming, Video Recording Compatible with Switch, Xbox, PS4/5, OBS,iPad Mac OS Windows,Camera, Zoom(Silver)
  • 【4K HDMI Input, 2K@30Hz Recording】Powered by a true USB 3.0 high-speed interface, the capture card supports up to 4K@30Hz HDMI input and records at 2K@30Hz or 1080P@60Hz. Perfect for gamers, streamers, and professionals who need crisp, smooth video for live streaming, gameplay recording, or online meetings.
  • 【Ultra Low Latency Screen Sharing】Built with a premium aluminum alloy shell and advanced chipset for stable heat dissipation, ensuring ultra-low latency transmission. Capture high-quality video and dual-channel audio in real time—no lag, no frame drop—ideal for Twitch, YouTube, or OBS streaming.
  • 【Easy Plug and Play, Compact & Portable】No driver or external power required—just plug and play via USB 3.0 or Type-C connection to your Windows or macOS computer. Lightweight and compact design makes it easy to carry for outdoor streaming, live shows, or mobile recording setups.
  • 【Wide Compatibility & Multi-Device Support】Compatible with Windows 7 8 10 11, macOS, Linux,Android and supports most popular software such as OBS, Zoom, VLC, Twitch Studio, and more. Works seamlessly with PS4, PS5, Xbox, Switch, DSLR cameras, TV boxes, and other HDMI-output devices for streaming to YouTube, Twitch, etc.
  • 【What You Get】Includes: HDMI Capture Card, USB 3.0 to USB-C Adapter, User Manual. Tips: Make sure your tablet’s OTG function is enabled before connecting. Test your HDMI device with a monitor first to confirm video and audio output, then connect to the Video Capture Card for recording.

For a production application, isolate protocol code behind an internal interface such as start_capture(source), next_frame(), and stop_capture(). That makes it possible to retain a wlroots compatibility backend or a PipeWire backend while the staging protocol changes.

Choosing between direct capture and PipeWire

Use direct image-copy capture when

  • You need deterministic access to compositor-selected pixels in your own buffers.
  • You control the compositor matrix and can test protocol versions, formats, and failure paths.
  • You need per-frame damage, transform, presentation-time, or explicit cursor-painting behavior.

Use a PipeWire or portal path when

  • Your feature is desktop sharing, conferencing, or recording rather than a low-level screenshot primitive.
  • You want the desktop’s permission and source-selection experience.
  • Your target desktop already exposes a PipeWire video-provider node. PipeWire’s design documentation describes GNOME Shell supplying a node containing framebuffer contents for screen sharing or recording: PipeWire design documentation.

These are different interfaces. A PipeWire node does not mean your application has implemented ext-image-copy-capture-v1, and a direct capture implementation does not automatically provide portal permission UX.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Common failures and fixes

The interface is missing

Cause: the compositor/version does not advertise the manager. Fix: detect it at startup, explain the unsupported compositor, and use a PipeWire or legacy backend where appropriate. Do not bind an interface by assuming its global name.

Buffer-constraint mismatch

Cause: stale dimensions, format, stride, or dma-buf modifier, often after the compositor sent updated constraints. Fix: stop submitting frames, replace your cached constraints, reallocate an exact match, and retry.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Frames appear cropped, stale, or torn

Cause: incorrect damage coordinates, an incomplete first-frame damage report, or reuse before ready. Fix: mark the full buffer damaged initially, use coordinates relative to the upper-left, and recycle only after the ready event.

Capture never returns

Cause: the compositor is waiting for source content to change, or your event loop is not dispatching Wayland events. Fix: keep dispatching the display queue, treat capture as asynchronous, and add an application timeout that reports a stalled source rather than blocking forever.

Rank #4
Capture Card, USB Video Capture Card Device, Audio Video Converter Grabber for RCA to USB-Convert VHS Mini DV VCR Hi8 DVD to Digital, for PC TV Tape Player Camcorder, MAC Windows Vista Compatible
  • AV TO USB Converter: Capture videos and audios from VHS, VCR, Hi8, DV tapes to a PC, with the help of our USB Video Converter. Save room while digitizing your favorite old memories
  • Quality Capture Card: Our USB Video Capture Card converting anolog RCA composite input into HD 720P USB output and capturing audio without any sound card. Advanced signal processing technology provides you with great precision, colors, resolutions, and details.
  • Plug and Play: Automatically install the driver once you hook up this RCA to USB Converter to a PC. No external power is needed. User-friendly and easy to operate
  • Wide Compatibility: The Video Capture Card can work with video devices with RCA connector or S-Video connector, such as VHS, VCR, Hi8, camcorder, compatible with Windows and Mac OS. Support video formats like NTSC, PAL, and support brightness, contrast, hue, and saturation control
  • Note: The Video Converter is used with acquisition software. We recommend OBS Studio or PotPlayer for Windows, and QuickTime Player for Mac. They can be downloaded for free online. Please operate according to the steps in User Manual or contact us if you have any questions

The pointer is absent or duplicated

Cause: cursor painting was disabled when you expected compositing, or you composited a separate cursor stream twice. Fix: choose one mode—session cursor painting or a separate cursor session—and test hotspot updates.

The source disappears

Cause: an output was unplugged, a window closed, or a session stopped. Fix: handle the stopped-session failure, destroy dependent frame and buffer objects safely, refresh source descriptors, and ask the user to select a new source.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Performance, reliability, and security considerations

  • Buffer choice: shared memory is simple and portable; dma-buf can avoid extra copies when your renderer or encoder accepts the advertised format and modifier.
  • Damage tracking: track what your consumer has already seen, but fall back to full damage whenever history is uncertain.
  • Back pressure: limit outstanding frames because the protocol permits only one live frame per session; queue encoded work outside the Wayland dispatch thread.
  • Timing: preserve presentation-time metadata when synchronizing recordings or correlating frames with input.
  • Privacy: capture only the selected source, release buffers promptly, and treat screenshots as sensitive data. A compositor may intentionally deny or stop capture.
  • Versioning: test upgrades and downstream patches; staging protocols can change before becoming stable.

Or skip the browser setup

If your goal is a screenshot of a website rather than the Wayland desktop, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF; it is not a replacement for compositor-level desktop capture.

Example using the documented API (full API documentation):

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

It removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

Frequently Asked Questions

Can an X11 screenshot library capture a Wayland desktop?

Not reliably. Wayland compositors control screen contents; use a compositor capture protocol or the desktop’s PipeWire/portal path instead of assuming X11 access.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Is ext-image-copy-capture-v1 stable?

No. Its protocol documentation labels it testing/staging. Pin and test the protocol version and compositor builds you support.

Can I capture a window without capturing the whole output?

Only if the compositor exposes that source type. The protocol supports opaque source descriptors, with outputs and toplevels given as examples; availability is compositor-specific.

Why does a capture request not produce a frame immediately?

The compositor may wait for source content to change, and delivery is asynchronous. Continue dispatching Wayland events and handle the ready or failed event.

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.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.