For one still image, use SCScreenshotManager.captureImage(contentFilter:configuration:). First obtain shareable displays or windows with SCShareableContent, scope the source with an SCContentFilter, configure the capture with SCStreamConfiguration, then try await the capture. The method returns a CGImage; you can display it, process it, or encode it as PNG, JPEG, or another image format.
Use an SCStream only when you need continuing video frames or audio. For screenshot-specific output controls, use the separate captureScreenshot API with SCScreenshotConfiguration.
What you need before writing code
- A macOS app target with ScreenCaptureKit imported.
- An
NSScreenCaptureUsageDescriptionentry in the target’s Info settings. Explain why the app needs to capture the screen. - Screen Recording permission in System Settings > Privacy & Security > Screen Recording.
- A deployment target and SDK where the API you call is available. Apple’s “Capturing screen content in macOS” sample lists macOS 15 or later and Xcode 16 or later; treat those as sample-project requirements, not a complete availability matrix for every ScreenCaptureKit symbol.
On the sample’s first run, macOS presents the permission prompt. After granting access, the sample requires a restart before capture works. Your app should still handle denial and other failures rather than assuming that permission is available immediately.
The minimal one-frame workflow
- Query
SCShareableContentfor displays, applications, and windows. - Choose the display or window you want.
- Create an
SCContentFilterfor that source. - Create an
SCStreamConfigurationand set the dimensions or other stream settings you need. - Call the async throwing
SCScreenshotManager.captureImagemethod. - Use the returned
CGImageor encode it to a file.
A complete display capture in Swift
import ScreenCaptureKit
import ImageIO
import UniformTypeIdentifiers
@main
struct OneFrameCapture {
static func main() async {
do {
let content = try await SCShareableContent.excludingDesktopWindows(
false,
onScreenWindowsOnly: true
)
guard let display = content.displays.first else {
throw CaptureError.noDisplay
}
// Include every window on the selected display.
let filter = SCContentFilter(display: display, excludingWindows: [])
let configuration = SCStreamConfiguration()
configuration.width = 1920
configuration.height = 1080
configuration.showsCursor = false
let image = try await SCScreenshotManager.captureImage(
contentFilter: filter,
configuration: configuration
)
let outputURL = URL(fileURLWithPath: "/tmp/screencapturekit-shot.png")
guard let destination = CGImageDestinationCreateWithURL(
outputURL as CFURL,
UTType.png.identifier as CFString,
1,
nil
) else {
throw CaptureError.cannotCreateDestination
}
CGImageDestinationAddImage(destination, image, nil)
guard CGImageDestinationFinalize(destination) else {
throw CaptureError.writeFailed
}
print("Saved to \(outputURL.path)")
} catch {
fputs("Screenshot failed: \(error)\n", stderr)
}
}
enum CaptureError: Error {
case noDisplay
case cannotCreateDestination
case writeFailed
}
}The fixed 1,920×1,080 values are an example. Set them to the pixel dimensions your output requires, or leave the configuration at its SDK defaults when you do not need a specific size. A Retina display and a logical-point window can have different pixel dimensions, so decide whether your downstream code expects points or pixels.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
- AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
- FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
- FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
- UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
- A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.
Capturing a particular window
Use the same sequence but select a window from content.windows and build the filter for that window. Apple’s sample enumerates running applications and windows so the user can choose a source. Keep the filter narrow: a display filter includes its permitted windows, while a window filter avoids accidentally recording unrelated content. Re-query shareable content when the window may have closed or moved before the capture starts.
Why the content filter matters
SCContentFilter is the boundary of the capture. It determines whether the result represents a display, a specific window, or a display with exclusions. Selecting the first display is convenient for a demo but is not a reliable product behavior on a multi-monitor Mac. Present the available displays and windows to the user, retain the selected identifier, and handle the case where that source disappears.
Filtering also helps with privacy. Exclude windows that should never appear in an image, and do not treat a successful API call as proof that every visible application is safe to publish.
Choosing the right ScreenCaptureKit API
| API path | Result or lifecycle | Use it when |
|---|---|---|
captureImage(contentFilter:configuration:) |
One CGImage, using SCStreamConfiguration |
You need a single frame and ordinary stream configuration controls. |
captureScreenshot |
One screenshot with SCScreenshotConfiguration |
You need screenshot-oriented format, cropping, cursor, or window-rendering controls. |
captureSampleBuffer |
One CMSampleBuffer |
Your pipeline already consumes sample buffers. |
SCStream |
Ongoing video (and, when configured, audio) sample buffers | You are recording, previewing, or analyzing a continuing session. |
Do not pass an SCScreenshotConfiguration to captureImage; the two one-frame methods use different configuration types.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #2
- BUILT FOR COLLEGE. AND BEYOND — MacBook Air with the M5 chip packs blazing speed and powerful AI capabilities into an incredibly portable design. And with up to 18 hours of battery life,* this thin and light powerhouse is ready to take on almost any major, just about anywhere.
- TEAR THROUGH TOUGH ASSIGNMENTS — With its faster CPU and unified memory, the M5 chip delivers even more performance and fluidity across apps, making multitasking and creative workflows smooth and responsive. A powerful Neural Engine and next-generation GPU with Neural Accelerators give you a powerful platform for AI.
- MAKE QUICK WORK OF YOUR TO-DO LIST — Apple Intelligence helps you write, express yourself, and get things done effortlessly — whether it’s for school or everyday life. With groundbreaking privacy protections, it gives you peace of mind that no one else can access your data — not even Apple.*
- UP TO 18 HOURS OF BATTERY LIFE — MacBook Air delivers incredible battery life with amazing performance, so you can power through a full day of classes without worrying about plugging in.
- A BRILLIANT 13.6-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Air supports 1 billion colors, making photos and videos pop with rich contrast and sharp detail, and text appears supercrisp. So everything — from class presentations to movies to games — looks truly stunning.
When to use SCScreenshotConfiguration
The screenshot-specific path is useful when the output itself, rather than a stream pipeline, is the main concern. The SDK exposes controls for:
- Output content type: HEIC, JPEG, or PNG.
- Pixel width and height.
- Standard or high-dynamic-range output.
- Display intent.
- Source and destination rectangles for cropping and scaling.
- Cursor visibility.
- Window shadow and clipping behavior.
Create an SCScreenshotConfiguration, set only the properties supported by the SDK in your deployment target, and pass it to captureScreenshot with the same SCContentFilter. Because property availability can change with the SDK, compile against the macOS SDK you ship and check availability before using newer controls.
Encoding and handling the CGImage
CGImage is an in-memory image, not a file. For PNG or JPEG output, use Image I/O’s CGImageDestination, as in the example. Add metadata only when you have a clear reason; screenshots can contain window names, document text, or location-sensitive information. If you display the image in AppKit, create an NSImage with the image’s pixel size rather than assuming a 1× scale.
Permission and privacy behavior
Declare the purpose
Add NSScreenCaptureUsageDescription to the app’s Info settings with a user-facing explanation. Apple’s framework guidance explicitly requires requesting screen recording permission before capturing content.
Recommended Free Tools
Rank #3
- AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
- FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
- FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
- UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
- A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.
Ask at the right time
Request access as part of the flow that begins a capture, not on an unrelated first launch. Explain which display or window will be captured and what you will do with the image. If the user denies access, show a recovery path to System Settings instead of repeatedly retrying.
Expect a restart in the documented sample flow
The Apple sample reports that the app must be restarted after permission is granted on its initial run. Design your state machine so a failed first attempt can be retried after relaunch, and continue to handle errors on every call.
Troubleshooting common failures
No displays or windows are returned
There may be no eligible on-screen source, the query may have been made while a window was closing, or the app may not have the required permission. Re-query SCShareableContent, verify the permission toggle, and show an explicit “no source available” state.
The call throws after permission was granted
Check that the app was relaunched if you followed the sample’s first-run flow. Also verify that the selected window still exists and that the filter was created from a current content query.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #4
- AN AMAZING MAC AT A SURPRISING PRICE — With an incredibly portable and durable aluminum design, up to 16 hours of battery life,* and the A18 Pro chip, MacBook Neo is ready to go wherever school takes you.
- FOUR STUNNING COLORS. ONE DURABLE DESIGN — Choose from four beautiful colors — Silver, Blush, Citrus, or Indigo — each with a color-coordinated keyboard. And MacBook Neo is made with a durable recycled aluminum enclosure that helps it reach 60 percent recycled content by weight — the most ever in any Apple product.*
- FLY THROUGH EVERYDAY ASSIGNMENTS — Whether you’re cramming for finals, using Apple Intelligence* to summarize class notes, creating presentations, or even playing the latest Apple Arcade game,* MacBook Neo delivers the performance and AI capabilities you need to get things done.
- UP TO 16 HOURS OF BATTERY LIFE — MacBook Neo delivers all day battery life, so you can power through from early morning classes to late night study sessions without worrying about plugging in.
- A VIBRANT 13-INCH DISPLAY* — The gorgeous Liquid Retina display on MacBook Neo supports 1 billion colors, so photos and videos pop and text is crisp for easy reading.
The image is blank or unexpectedly cropped
Inspect the filter first, then inspect width, height, source rectangles, and destination rectangles. A window filter cannot capture content outside that window, and a display filter with exclusions can intentionally remove windows.
The output looks soft on a Retina display
Request pixel dimensions appropriate for the destination instead of copying logical screen points. Keep the image at native or deliberately chosen dimensions until the final resize.
PNG writing fails
Ensure the destination URL is writable, the Image I/O destination was created, and CGImageDestinationFinalize returned true. A successful capture does not guarantee that the subsequent file operation will succeed.
The app captures more than intended
Do not default to the first display in a production workflow. Let the user select a window or display, use exclusions, and log the filter choice for support diagnostics without logging sensitive image contents.
Best Value
- FAST RUNS IN THE FAMILY — The 16-inch MacBook Pro with the M5 Pro or M5 Max chip brings next-generation speed and powerful on-device AI to personal, professional, and creative tasks. With all-day battery life, double the starting storage,* and a breathtaking Liquid Retina XDR display, it’s pro in every way.*
- BUCKLE UP — Along with a next-generation CPU, faster unified memory, and up to 2x faster SSD storage,* M5 Pro and M5 Max feature a more powerful GPU with a Neural Accelerator built into each core, delivering faster AI performance and on-device training capabilities. So you can blaze through demanding workloads at mind-bending speeds.
- BUILT FOR AI — Apple silicon, and every major component that powers it, is designed to run demanding on-device AI workloads like LLM inference and training. And Apple Intelligence helps you write, express yourself, and get things done effortlessly with groundbreaking privacy protections at every step.*
- ALL-DAY BATTERY LIFE — MacBook Pro delivers the same exceptional performance whether it’s running on battery or plugged in.*
- MACOS RUNS APPS FAST — All your go-to apps run lightning fast in macOS, including built-in apps like FaceTime and Messages. Plus, built-in virus protection and free software updates help keep your Mac running smoothly and securely.
Performance, reliability, and cost considerations
- A one-frame API avoids the memory and scheduling overhead of maintaining an
SCStreamwhen no ongoing capture is required. - Large dimensions and high-dynamic-range output increase memory use and encoding time. Resize after capture when a smaller delivery image is sufficient.
- Keep capture off the main actor when encoding or uploading the result. Update UI state on the main actor after the image is ready.
- Cache the selected source identifier, but revalidate it before every capture because displays and windows can change.
- There is no per-shot ScreenCaptureKit charge. Your practical costs are app development, storage, processing, and any service you add for distribution or remote capture.
Or skip the browser setup
If you need a hosted screenshot rather than a Mac-local capture, ScreenshotNeo is the first service to try: it removes consent banners, popups, and chat widgets before capture, bills only clean shots, and has a $5 paid plan for 3,000 shots.
One GET request returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for all options.
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}`);ScreenshotNeo can load lazy images, capture a CSS-selected element, emulate dark mode and device presets, use custom viewport and retina settings, run JavaScript or clicks, wait for selectors, delays, or network idle, block ads and trackers, set headers, cookies, authorization, timezone, and geolocation, create PDFs, resize images, cache with a chosen TTL, sign public image links, run asynchronous jobs with signed webhooks, capture up to 100 URLs per bulk call, and expose usage and OpenAPI endpoints. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing result. The free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
Pre-release checklist
- Confirm the deployment target supports the symbols you use.
- Add and explain
NSScreenCaptureUsageDescription. - Test denied, granted, and newly granted permission states.
- Query current shareable content and validate the chosen source.
- Use
captureImagewithSCStreamConfiguration, or use the separate screenshot configuration path when its controls are needed. - Choose pixel dimensions and output encoding deliberately.
- Handle thrown errors and file-encoding failures.
- Review captured content for private windows before saving or uploading it.
Frequently Asked Questions
Can ScreenCaptureKit capture a single application without showing the rest of the desktop?
Yes. Enumerate the available windows, select the application’s window, and create the content filter for that window instead of using a whole-display filter.
Should I use ScreenCaptureKit for screenshots taken from a website URL on a server?
No. ScreenCaptureKit captures content available to a permitted macOS app. A hosted URL-to-image workflow is better handled by a screenshot service such as ScreenshotNeo.
What should I log when a capture fails?
Log the operation, selected source identifier, configuration dimensions, permission state, and thrown error. Avoid logging the screenshot pixels or sensitive window titles.
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.
