Skip to content

README.md

Latest commit

 

History

History
94 lines (70 loc) · 2.96 KB

README.md

File metadata and controls

94 lines (70 loc) · 2.96 KB
Raw

icon ThatCapture

NuGet

Small cross-platform screen capture library for .NET

Platform support

Platform Support Method Dependency
Windows ✅ Graphics.CopyFromScreen System.Drawing.Common
macOS ✅ CGWindowListCreateImage CoreGraphics (system)
Linux (X11) ✅ XGetImage libX11 (system)
Linux (Wayland) ✅ xdg-desktop-portal Screenshot Tmds.DBus.Protocol

Wayland note: the first capture will show a system permission prompt from the desktop portal. This is a Wayland security requirement and cannot be bypassed.

Usage

var capture = new ScreenCapture();
var result = await capture.CaptureAreaAsync(x, y, width, height);

if (result is CaptureResult.Ok(var frame))
{
    // frame.Pixels - raw bytes
    // frame.Width  - pixels wide
    // frame.Height - pixels tall
    // frame.Stride - bytes per row (may include padding — always use Stride, not Width * 4)
    // frame.Format - e.g. PixelFormat.Bgra8888
}

ScreenCapture automatically picks the right backend for the current platform. The active backend is exposed via the Platform property:

Console.WriteLine(capture.Platform);

To override the auto-detected platform, pass a CapturePlatform value to the constructor:

var capture = new ScreenCapture(CapturePlatform.X11);

The returned CapturedFrame always contains raw pixel data.

Encoding to an image format

Extension methods are available to encode a captured frame to PNG, JPEG, or WebP:

byte[] png  = frame.ToPng();
byte[] jpeg = frame.ToJpeg(); // default quality: 85
byte[] jpeg = frame.ToJpeg(quality: 60);
byte[] webp = frame.ToWebp(); // lossy by default
byte[] webp = frame.ToWebp(lossless: true);

To save directly to a file:

await File.WriteAllBytesAsync("screenshot.png", frame.ToPng());

Error handling

CaptureAreaAsync returns a CaptureResult, which is either Ok or Err. Match on it to handle failures:

switch (result)
{
    case CaptureResult.Ok(var frame):
        // use frame
        break;
    case CaptureResult.Err(var err):
        var message = err switch
        {
            CaptureError.PermissionDenied => "screen recording permission was denied",
            CaptureError.SessionBusUnavailable => "D-Bus session bus is unavailable",
            CaptureError.Timeout => "portal request timed out",
            CaptureError.CaptureFailed { Message: var msg } => msg ?? "native capture call failed",
        };
        break;
}

Development

Run the test script:

dotnet run --project scripts/TestEncoding/TestEncoding.csproj