CGDisplayStream仅捕获单帧问题：Swift及macOS开发求助

Hey there! I’ve dealt with this exact issue when switching from AVFoundation to CGDisplayStream for macOS screen capture—super common pitfalls, but easy to fix once you know what to look for. Let’s break down the key issues and a working solution:

Common Reasons for Single-Frame Capture #

The most frequent culprits are:

• Lost strong reference to the CGDisplayStream instance: ARC will immediately deallocate the stream if it’s only stored in a local variable, stopping capture after the first frame.
• Incorrect stream configuration: Wrong pixel format, missing queue setup, or unhandled stream status changes can cause the stream to terminate early.
• Missing permissions: macOS requires explicit screen recording access, which if denied, will silently fail after (or before) the first frame.

Working Swift Implementation #

Here’s a complete example that maintains continuous capture, with comments highlighting critical steps:

import CoreGraphics
import CoreVideo

class ScreenCaptureManager {
    // 🔑 Critical: Strong class-level reference to keep the stream alive
    private var displayStream: CGDisplayStream?
    // Dedicated queue for capture callbacks to avoid blocking the main thread
    private let captureQueue = DispatchQueue(label: "com.yourapp.screencapture.queue", qos: .userInitiated)
    
    func startContinuousCapture() {
        let mainDisplayID = CGMainDisplayID()
        let displayBounds = CGDisplayBounds(mainDisplayID)
        
        // Create the stream with proper configuration
        guard let stream = CGDisplayStream(
            dispatchQueueDisplay: mainDisplayID,
            outputWidth: Int(displayBounds.width),
            outputHeight: Int(displayBounds.height),
            pixelFormat: Int32(kCVPixelFormatType_32BGRA), // Common compatible format
            properties: [
                kCGDisplayStreamMinimumFrameTime: 1.0/60.0 // Maintain 60fps capture
            ] as CFDictionary,
            queue: captureQueue,
            handler: { [weak self] status, timestamp, frameSurface, updateRef in
                // Handle stream status changes first
                switch status {
                case .frameComplete:
                    guard let pixelBuffer = frameSurface as? CVPixelBuffer else {
                        print("Failed to get pixel buffer from frame surface")
                        return
                    }
                    // 🎉 Process your captured frame here!
                    self?.processCapturedFrame(pixelBuffer, timestamp: timestamp)
                case .stopped:
                    print("Display stream stopped unexpectedly")
                    self?.displayStream = nil
                case .error:
                    print("Display stream encountered an error")
                    self?.displayStream = nil
                default:
                    break
                }
            }
        ) else {
            print("Failed to initialize CGDisplayStream")
            return
        }
        
        // Store the stream to keep it alive
        self.displayStream = stream
        
        // Start the stream and validate success
        let startResult = stream.start()
        if startResult != .success {
            print("Failed to start stream: \(startResult.rawValue)")
            self.displayStream = nil
        }
    }
    
    func stopCapture() {
        displayStream?.stop()
        displayStream = nil // Release reference when done
    }
    
    private func processCapturedFrame(_ pixelBuffer: CVPixelBuffer, timestamp: UInt64) {
        // Add your frame processing logic here (e.g., convert to NSImage, encode to video, etc.)
        print("Captured frame at timestamp: \(timestamp)")
    }
}

Key Fixes & Tips #

• Keep a strong reference: Never declare CGDisplayStream as a local variable inside a function—store it as a class property so ARC doesn’t clean it up prematurely.
• Use a dedicated queue: The capture handler runs on the queue you provide; using a serial queue ensures frames are processed in order without thread conflicts.
• Handle stream status: Always check the status parameter in the handler—this will tell you if the stream stopped intentionally or due to an error.
• Permissions: Don’t forget to add the NSScreenRecordingUsageDescription key to your Info.plist with a clear explanation of why your app needs screen access. Without this, macOS will block capture entirely.
• Frame rate control: Use the kCGDisplayStreamMinimumFrameTime property to set your desired capture frame rate (e.g., 60fps as shown above).

Quick Comparison to AVFoundation #

Unlike AVCaptureSession which manages its own lifecycle and state, CGDisplayStream is much lower-level—you’re responsible for maintaining the instance, handling callbacks, and responding to state changes. That’s why the strong reference is such a critical detail here!

内容的提问来源于stack exchange，提问作者brianmario