For new macOS apps, use Apple’s ScreenCaptureKit: request shareable content, select an SCWindow or SCDisplay, apply an SCContentFilter, and capture a still image with the screenshot API available in your target SDK. Use an SCStream when you need a continuing sequence of frames. Your app must request Screen Recording permission and explain the need with NSScreenCaptureUsageDescription.
Choose a still screenshot or a stream
The correct API depends on the job:
| Need | Recommended approach |
|---|---|
| One image of a window or display | ScreenCaptureKit screenshot interface available in the target SDK, using a content filter and screenshot configuration. |
| Repeated frames, recording, live processing or streaming | SCStream with stream configuration and an output handler. |
| User chooses what to share for an ongoing session | Apple’s system content-sharing picker, rather than a custom source picker. |
ScreenCaptureKit exposes shareable displays, applications, windows, filters, stream configuration and screenshot-related types. Check the SDK documentation for the exact availability annotation and Swift signature of the screenshot method you select; the available overloads do not all have the same deployment target.
Prepare the macOS project
Add the framework
- In Xcode, open the macOS target.
- Add
ScreenCaptureKitto the target’s linked frameworks if it is not already available through the project settings. - Import it in the Swift file.
import ScreenCaptureKit
import AppKit
Explain permission in Info.plist
Add the NSScreenCaptureUsageDescription key in the target’s Info pane (or Info.plist) with a plain-language reason, such as “This app captures the selected window to create an image.” Apple’s guidance is to request screen-recording permission before capturing. This is separate from camera and microphone authorization; do not add camera or microphone keys unless your app actually uses those devices.
Enumerate windows and displays
Ask ScreenCaptureKit for content the user is allowed to share. Apple’s sample uses the asynchronous call below with desktop windows included and only on-screen windows returned.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
let content = try await SCShareableContent.excludingDesktopWindows(
false,
onScreenWindowsOnly: true
)
let displays = content.displays
let windows = content.windows
Always handle an empty result. A window can close between enumeration and capture, and a window identifier alone does not guarantee that a later capture will succeed.
Capture one window
Select a real SCWindow, create a window-specific filter, then pass that filter to the screenshot interface supported by your deployment target. The following structure shows the selection and validation logic; verify the final screenshot call and return type against the SDK installed in your Xcode version.
import ScreenCaptureKit
import AppKit
func selectWindow(containing titlePart: String) async throws -> SCWindow {
let content = try await SCShareableContent.excludingDesktopWindows(
false,
onScreenWindowsOnly: true
)
guard let window = content.windows.first(where: {
($0.title ?? "").localizedCaseInsensitiveContains(titlePart)
}) else {
throw CaptureError.windowNotFound
}
return window
}
enum CaptureError: Error {
case windowNotFound
case displayNotFound
case noContent
}
func makeWindowFilter(_ window: SCWindow) -> SCContentFilter {
SCContentFilter(desktopIndependentWindow: window)
}
For a one-shot image, create the appropriate SCScreenshotConfiguration, set output width, height and image quality as needed, and invoke the screenshot manager method exposed by your SDK. Convert the returned image to PNG, JPEG or another representation using the return type documented for that SDK, then write the data to disk. Because Apple’s API signatures and availability vary by SDK, do not copy a method name from a different Xcode release without checking its declaration.
Capture an entire display
Choose an SCDisplay and create a display filter. A display capture includes content visible on that display rather than an individual application window.
Recommended Free Tools
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
func selectDisplay(index: Int = 0) async throws -> SCDisplay {
let content = try await SCShareableContent.excludingDesktopWindows(
false,
onScreenWindowsOnly: true
)
guard content.displays.indices.contains(index) else {
throw CaptureError.displayNotFound
}
return content.displays[index]
}
func makeDisplayFilter(_ display: SCDisplay) -> SCContentFilter {
SCContentFilter(display: display, excludingApplications: [], exceptingWindows: [])
}
Configure the output dimensions deliberately. A Retina display can produce a much larger pixel image than its point size. Match the configuration to the image size your application actually needs rather than assuming the display’s logical dimensions are the desired output. Apple’s update history records support for screenshots across multiple displays in June 2024; confirm that capability and its availability for your deployment target.
When a stream is the better choice
Use SCStream for recording, repeated screenshots, OCR over time, computer-vision processing or live transmission. Configure the stream with a content filter and stream configuration, attach an output handler, and consume video sample buffers. If you only need one frame, a stream adds lifecycle and buffering work that a screenshot interface avoids.
Stream code also needs cancellation and back-pressure handling. Stop the stream when the window closes or the task is cancelled, and release output handlers so a long-running capture does not retain the view controller or other application state.
Permission and first-run behavior
- Explain the capture purpose in your own UI before starting the request.
- Trigger the Screen Recording permission flow before attempting capture.
- Handle denial by showing how the user can enable the app in macOS Privacy & Security settings, then offer a retry.
- After a permission change, account for the possibility that the current process must be restarted. Apple’s ScreenCaptureKit sample specifically tells the user to restart its sample after granting permission; design and test your own app’s flow rather than assuming every app behaves identically.
Do not promise success merely because the app has a visible window. Permission, source availability, protected content, window lifetime and configuration validity all affect the result.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Save and represent the image
The screenshot API’s exact return type is SDK-dependent. Common macOS image pipelines use CGImage, NSImage or an image representation object. Once you have the documented image type:
- Use PNG for lossless UI, text and transparency.
- Use JPEG when a smaller photographic file matters more than lossless edges.
- Validate the destination URL and create parent directories before writing.
- Move encoding off the main actor for large full-display captures.
Keep the capture and encoding errors separate in logs. A successful capture followed by a failed file write should not be reported as a permission problem.
Legacy Core Graphics code
CGWindowListCreateImage is deprecated in Apple’s Core Graphics reference. For new desktop capture work, start with ScreenCaptureKit instead of building a new dependency on that API. The sources available for this guide do not establish a one-for-one migration for every legacy option, so test behavior such as window exclusions, off-screen windows and protected content on the macOS versions you support.
Troubleshooting
The content list is empty
Check Screen Recording permission, confirm that a display or target window is actually on screen, and verify that you are not filtering out every eligible source. Retry enumeration after the user changes permission.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
The window was found but capture fails
The window may have closed, moved off screen or become ineligible. Enumerate again immediately before capture, recreate the filter, and report a specific “window no longer available” state instead of retrying indefinitely.
The permission prompt never appears
Verify that NSScreenCaptureUsageDescription is present in the app bundle and that you are running the signed app target you edited. A previously decided permission can also suppress a new prompt; direct the user to Privacy & Security and provide a retry or restart path.
The screenshot API is unavailable at your deployment target
Read the symbol’s availability in the target SDK. If the still-image method is unavailable, use a validated SCStream-and-frame route for that target or raise the minimum macOS version. Do not assume that the minimum version of one ScreenCaptureKit type applies to every screenshot overload.
The result is the wrong size
Inspect the screenshot configuration’s width, height and image-quality settings, and account for Retina scaling. Decide whether your product wants logical points or physical pixels before choosing values.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Or skip the browser setup
If you need a website image rather than a macOS desktop frame, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
See the complete parameter reference in the ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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}`);One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Does ScreenCaptureKit capture camera or microphone input automatically?
No. Desktop screen-recording authorization is distinct from camera and microphone authorization; add and request those capabilities only when your app uses them.
Can I silently capture any window by its window ID?
No. Enumerate eligible shareable content, verify the window still exists, obtain permission and apply a current content filter before capturing.
Should I build my own source-selection picker?
For ongoing sharing workflows, Apple recommends the system content-sharing picker. A one-shot app-directed capture can select a previously chosen window or display directly.
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.
